embedded Argument parser

The embedded Argument parser is needed when you have repeating groups of arguments. Do not confuse this with --multiple since that allows for multiple values for the same argument. There is a good example in Funnel - or more generally, keys for a sort program.

For this discussion we will have a positional argument for input file and an embedded Argument parser for the --keys. This embedded parser will be invoked once for every key. A command-line like this should be possible.

sort myFile.txt --keys (1 10) (15 3)

This will invoke our program (sort) and sort the file myFile.txt on two --keys. The first key starts in position 1 and is 10 long, and the second key starts in position 15 and is 3 long.

Embedded parsers are always indicated with brackets around them on the command-line. () and [] are both valid.

This --begin and --end isolate the embedded parser. Any arguments between these bookends are part of the embedded parser. The positional filename argument is not between the --begin/--end markers so it is not part of the embedded parser. And that makes sense since the filename is not part of each key. The indentation in the example is just for readability.

CmdLine.create(
    "--type file --key filename --position",
    "--type begin --key key",
    "--type     integer --key offset --positional --required",
    "--type     integer --key length --positional --required",
    "--type end   --key key"
    );

--begin and --end

The --begin type indicates the beginning of the embedded parser. The parser is named, in this example, key, so that it can be referenced in the --end type. Embedded parsers can be embedded within other embedded parsers. That is why they are named; so the --end can indicate which --begin it is for.