-
Notifications
You must be signed in to change notification settings - Fork 9
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat: add parsed meta-data to returned properties #129
Conversation
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as outdated.
This comment was marked as resolved.
This comment was marked as resolved.
…ernals to match node layout.
* `kind` {string} One of 'option', 'positional', or 'option-terminator'. | ||
* `index` {number} Index of element in `args` containing token. So the | ||
source argument for a token is `args[token.index]`. | ||
* option tokens |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
To improve the readability I would explain that we mean the kind=option
token
* option tokens | |
* 'option' tokens |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
rather than quotes, which i find confusing, how about linking the term to the appropriate section?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, that works too.
I use the same syntax in the kind
description to be homogeneous
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The compact POJO description is a bit subtle to read. How about an expanded version with all the properties listed?
Proposed expanded
A returned token has two properties which are always defined,
and some other properties which vary depending on the kind
:
kind
{string} One of 'option', 'positional', or 'option-terminator'.index
{number} Index of element inargs
containing token. So the
source argument for a token isargs[token.index]
.
An option token has additional parse details
for an option detected in the input args
:
kind
='option'
index
{number} Index of element inargs
containing token.name
{string} Long name of option.rawName
{string} How option used in args, like-f
of--foo
.value
{string | undefined} Option value specified in args.
Undefined for boolean options.inlineValue
{boolean | undefined} Whether option value specified inline,
like--foo=bar
.
A positional token has just one additional property with the positional value:
kind
='positional'
index
{number} Index of element inargs
containing token.value
{string} The value of the positional argument in args (i.e.args[index]
).
An option-terminator token has only the base properties:
kind
='option-terminator'
index
{number} Index of element inargs
containing token.
Old compact
The returned tokens have properties describing:
- all tokens
kind
{string} One of 'option', 'positional', or 'option-terminator'.index
{number} Index of element inargs
containing token. So the
source argument for a token isargs[token.index]
.
- option tokens
name
{string} Long name of option.rawName
{string} How option used in args, like-f
of--foo
.value
{string | undefined} Option value specified in args.
Undefined for boolean options.inlineValue
{boolean | undefined} Whether option value specified inline,
like--foo=bar
.
- positional tokens
value
{string} The value of the positional argument in args (i.e.args[index]
).
- option-terminator token
(Also asked in: nodejs/node#43459 (comment))
Undefined for boolean options. | ||
* `inlineValue` {boolean | undefined} Whether option value specified inline, | ||
like `--foo=bar`. | ||
* positional tokens |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
* positional tokens | |
* 'positional' tokens |
like `--foo=bar`. | ||
* positional tokens | ||
* `value` {string} The value of the positional argument in args (i.e. `args[index]`). | ||
* option-terminator token |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
* option-terminator token | |
* 'option-terminator' token |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
👍 assuming this has been synced with the upstream Node.js PR.
Congrats on the contribution to Node 🥳
@shadowspawn may I merge this? |
Yes, it is up to date with upstream. (I'll get to it this weekend otherwise.) |
Problem
We don't wish to offer extensive configuration knobs and dials for modifying
parseArgs
behaviour, but we don't currently return rich information for authors to implement features themselves.See #84.
Solution
Return a property which contains an array of the parsed tokens detected in the args. This allows the author to inspect the meta-data to add additional checks to throw for repeated options (say), or reprocess the tokens entirely to add auto-arrays for repeated options (say).
The internal implementation uses the tokens to do the error checking and generate the
values
andpositionals
. "Eating our own dog food."The extra details are opt-in and not returned by default.
Closes: #84
This includes some minor lint in the existing (upstream) documentation, including one which was independently fixed:
Example
Examples Folder Experimental Only
I am not planning to commit the examples other than
tokens.js
in this PR. I'll submit them in separate PRs. I'll leave them in the PR until last minute as examples of using the tokens for custom processing.