-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
50513fc
commit 3f057c1
Showing
2 changed files
with
149 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,2 +1,149 @@ | ||
# util-parseargs | ||
Polyfill of future proposal for `util.parseArgs()` | ||
|
||
### Links & Resources | ||
|
||
* [Initial Tooling Issue](https://github.com/nodejs/tooling/issues/19) | ||
* [Initial Proposal](https://github.com/nodejs/node/pull/35015) | ||
|
||
---- | ||
|
||
## `process.mainArgs` Proposal | ||
|
||
> Note: This can be moved forward independently of the `util.parseArgs()` proposal/work. | ||
### Implementation: | ||
|
||
```javascript | ||
process.mainArgs = process.argv.slice(process._exec ? 1 : 2) | ||
``` | ||
|
||
--- | ||
|
||
## `util.parseArgs([argv][, options])` Proposal | ||
|
||
* `argv` {string[]} (Optional) Array of argument strings; defaults | ||
to [`process.mainArgs`](process_argv) | ||
* `options` {Object} (Optional) The `options` parameter is an | ||
object supporting the following properties: | ||
* `withValue` {string[]} (Optional) An `Array` of argument | ||
strings which expect a value to be defined in `argv` (see [Options][] | ||
for details) | ||
* `multiples` {string[]} (Optional) An `Array` of argument | ||
strings which, when appearing multiple times in `argv`, will be concatenated | ||
into an `Array` | ||
* `short` {Object} (Optional) An `Object` of key, value pairs of strings which map a "short" alias to an argument; When appearing multiples times in `argv`; Respects `withValue` & `multiples` | ||
* `strict` {Boolean} (Optional) A `Boolean` on wheather or not to throw an error when unknown args are encountered | ||
* Returns: {Object} An object having properties: | ||
* `args` {Object}, having properties and `Boolean` values corresponding to parsed options passed | ||
* `values` {Object}, have properties and `String` values corresponding to parsed options passed | ||
* `positionals` {string[]}, containing [Positionals][] | ||
|
||
--- | ||
|
||
## Examples w/ Output | ||
|
||
```js | ||
const { parseArgs } = require('util') | ||
``` | ||
|
||
```js | ||
// default | ||
const argv = ['-f', '--foo=a', '--foo', 'b'] | ||
const options = {} | ||
const { args, values, positionals } = parseArgs(argv, options) | ||
args // { f: true, foo: true} | ||
values // { f: [undefined], foo: [undefined] } | ||
positionals // ['b'] | ||
``` | ||
```js | ||
// withValue | ||
const argv = ['-f', '--foo=a', '--foo', 'b'] | ||
const options = { | ||
withValue: ['foo'] | ||
} | ||
const { args, values, positionals } = parseArgs(argv, options) | ||
args // { f: true, foo: true} | ||
values // { f: [undefined], foo: ['b'] } | ||
positionals // [] | ||
``` | ||
```js | ||
// withValue & multiples | ||
const argv = ['-f', '--foo=a', '--foo', 'b'] | ||
const options = { | ||
withValue: ['foo'], | ||
multiples: ['foo'] | ||
} | ||
const { args, values, positionals } = parseArgs(argv, options) | ||
args // { f: true, foo: true} | ||
values // { f: [undefined], foo: ['a','b'] } | ||
positionals // [] | ||
``` | ||
```js | ||
// shorts | ||
const argv = ['-f', '--foo=a', '--foo', 'b'] | ||
const options = { | ||
short: { f: 'foo' } | ||
} | ||
const { args, values, positionals } = parseArgs(argv, options) | ||
args // { foo: true} | ||
values // { foo: [undefined] } | ||
positionals // ['b'] | ||
``` | ||
|
||
### F.A.Qs | ||
|
||
- Is `cmd --foo=bar baz` the same as `cmd baz --foo=bar`? | ||
- Yes, if `withValue: ['foo']`, otherwise no | ||
- Does the parser execute a function? | ||
- no | ||
- Does the parser execute one of several functions, depending on input? | ||
- no | ||
- Can subcommands take options that are distinct from the main command? | ||
- no (this might be a problem? at least it's a more definitive "opinion") | ||
- Does it output generated help when no options match? | ||
- no | ||
- Does it generated short usage? Like: `usage: ls [-ABCFGHLOPRSTUWabcdefghiklmnopqrstuwx1] [file ...]` | ||
- no (no usage/help at all) | ||
- Does the user provide the long usage text? For each option? For the whole command? | ||
- no | ||
- Do subcommands (if implemented) have their own usage output? | ||
- no | ||
- Does usage print if the user runs `cmd --help`? | ||
- no | ||
- Does it set `process.exitCode`? | ||
- no | ||
- Does usage print to stderr or stdout? | ||
- N/A | ||
- Does it check types? (Say, specify that an option is a boolean, number, etc.) | ||
- no | ||
- Can an option have more than one type? (string or false, for example) | ||
- no | ||
- Can the user define a type? (Say, `type: path` to call `path.resolve()` on the argument.) | ||
- no | ||
- Does a `--foo=0o22` mean 0, 22, 18, or "0o22"? | ||
- `"0o22"` | ||
- Does it coerce types? | ||
- no | ||
- Does `--no-foo` coerce to `--foo=false`? For all flags? Only boolean flags? | ||
- no, it sets `{args:{'no-foo': true}}` | ||
- Is `--foo` the same as `--foo=true`? Only for known booleans? Only at the end? | ||
- no, `--foo` is the same as `--foo=` | ||
- Does it read environment variables? Ie, is `FOO=1 cmd` the same as `cmd --foo=1`? | ||
- no | ||
- Do unknown arguments raise an error? Are they parsed? Are they treated as positional arguments? | ||
- no, they are parsed, not treated as positionals | ||
- Does `--` signal the end of flags/options? | ||
- **open question** | ||
- If `--` signals the end, is `--` included as a positional? is `program -- foo` the same as `program foo`? Are both `{positionals:['foo']}`, or is the first one `{positionals:['--', 'foo']}`? | ||
- Does the API specify whether a `--` was present/relevant? | ||
- no | ||
- Is `-foo` the same as `--foo`? | ||
- yes <-- ! kind of a blocker for shortopts ! | ||
- Recommend: "No, -foo is shortopts form of --f --o --o" (assuming none are defined, or withValues) | ||
- Is `---foo` the same as `--foo`? | ||
- no | ||
- the first flag would be parsed as `'-foo'` | ||
- the second flag would be parsed as `'foo'` | ||
- Is `-` a positional? ie, `bash some-test.sh | tap -` | ||
- no |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters