[Proposal] Diagramming

[KathleenDollard]

The ability to understand how a command line would be handled by the parser is useful in at least these scenarios:

• To display how things would be parsed to aid in understanding it
• To explore issues/bugs
• To allow rich display in typo correction or other error message output
• To display examples

In several of these, the parser understanding may be displayed as color or other text markings.

To handle all of these, the understanding, or the ability to recreate that understanding, needs to be passed out of the parser, not just a string.

Note: arg in the following paragraph is a member of the args array passed to main, or an equivalent.

One approach would be to include the arg position, and the number of arguments absorbed by any value result. For example, a collection of ints would absorb the arg for each int. By implication, the arg location of each item in the collection is its position relative to the start position (the second item in the collection would be at start + 1, assuming zero based)

CliOption is a little more complicated. The option id itself is an arg and it may or may not contain the first item in the collection depending on which of these forms are used:

... -x 42
... -x=42

Question: Assuming that -x is a collection of ints (Arity > 1), how is the following parsed?

... -x=42 43 44

Does the equals sign change this being interpreted as a collection if the type of -x is int[]?

This proposal is to add a Location property on all symbol results (CommandResult, OptionResult and ArgumentResult) that would be a record with these properties:

int ArgStartPosition // `arg` start location
int ArgCount  // total count of args
int ArgCollectionOffset // one if space is used to delimit, otherwise zero
int ArgCollectionDelimterPosition // If a non-space delimiter is used, where in the first `arg` does the delimiter appear

I'm not crazy about this resolution of the fact a split may or may not occur.

Also, something probably needs to record whether the exe name was entered so that either a consistent output could be rendered (examples, for example ;) or the user-entered string.

The actual display of diagramming would be via a diagramming subsystem.