refactor!: rework results to have parsedOptions property and store true in values for boolean options

[shadowspawn]

See #70 for longer description.

In parse results, minor code changes:

• rename flags to parsedOptions
• store true in values for boolean options (rather than undefined)

In README, more churn:

• as above
• update result property descriptions
• show all options found in args in parsedOptions, not just boolean options
• update -- description to match current implementation
• fix one example that got broken in a previous refactor
• replace "withValue" with "type:string"
• replace "flag" with "option" or " boolean option" as appropriate
• other small tweaks to wording

Added the examples in the README to a file so can confirm actual behaviour!

[ljharb]

This seems wrong; — means “stop parsing options”; everything after it should be untouched.

[shadowspawn]

I'm not sure what you mean.

The QA don't include an example storing an (otherwise) option as a positional, is that what you were expecting?

[ljharb]

What i mean is, program a b c should have three positionals (a, b, and c) - but program -- a b c should only have one positional, the string "a b c", so it can be passed verbatim to something else.

[shadowspawn]

No, combining the strings like that would lose the information about the separate arguments and require another interpretation step to split them up again.

This might be too opaque, but imagine implementing subcommands:

// utility --option1 -- dispatch --option2
const result1 = parseArgs({ options: mainOptions );
if (result1.positionals[0] === 'dispatch') {
   const result2 = parseArgs({ args: result1.positionals.slice(1), options: dispatchOptions });
}

A different example. The -- turns off option processing and the remaining arguments end up untouched and treated as positionals, so these three examples all have the same result. There isn't anything special about the handling of arguments after the -- than before the -- other than no option processing.

utility foo bar -- --unprocessed-option
utility foo -- bar --unprocessed-option
utility -- foo bar --unprocessed-option

[ljharb]

Yes, that's the idea. They're going to be passed to another program, so THAT program will be interpreting them on its own - perhaps with different rules than the current one.

[shadowspawn]

Normally that other program will be interpreting an array of arguments, not a single string?

The -- stops option detection. It is not a marker for separate collection of arguments into another structure.

(There are some programs that treat -- as a marker for separate processing, but in my experience that is unusual. It is easy to form the impression programs work that way though, since for easy reading the -- is often put before the passthrough arguments!)

[shadowspawn]

One way of thinking about -- is that it is another user-level intervention. No author action required.

• suppress shell interpretation of special characters in arguments: quote argument
• suppress utility interpretation of arguments as options: --

[shadowspawn]

Example behaviours of reference implementations added to: #58 (comment)

[shadowspawn]

Closing in favour of #83