Spec for parser flag definitions

Flag definition consists of a list of blocks. Blocks are separated by block separator - \t, except first one. There are no separator before first block and after last block.

This are defined blocks (in order):

• Option identifier (will be used as a long flag option).
• Short option name (optional).
• Metadata block. Described in Metadata section.
• Description (in theory optional, code does not check its length).

First separator (after ID) could be one of theese:

• \t - This will be flag with long and short variants
• \n - This will be a flag with long option only. Short option block should be ommited.

Also, flag definition could be used to specify command to parser internals. This commands start from - character.

List of commands:

• separator -> Using this will push -- separator (if found) into a list of positional arguments. By defulat it is not pushed into that list.
• alias -> Allow to add long option aliases to already existing options. Arguments format is :<option identifier>:<alias name>,<another alias name>,.... Traling comma is not required but supported.
• group -> Allows to add custom help message for a flags group. Arguments format is :<group name>:<help message>. Message will be treated as a raw string and printed using printf("%s\n", message);, so you can omit trailing newline.

This block consistsi of key=value pairs. They are separated by metadata pair separator - ;. Last pair is terminated by ablock separator. For any ommited key default value will be used. This section could be left.

Supported keys:

• arg - Specifies type of argument expected for this flag. Default value is no argument. ? could be used at the end of arument type to mark arguments as optional. Allowed arguments:
  • arg - Single argument expected
  • list - List of arguments expected. List will terminate on first word starting from -.
  • tlist - Terminated list. List will terminate only on terminator symbol.
• len - Set expected number of arguments for list and tlist argument types. 0 indicates any number of arguments.
• thint - Type hint. Optional string. Will be shown to user in help message.
• tdelim - Delimeter character for a tlist argument type.
• group - Allows to group related flags. Used purely by help message formatter, grouped flags will be put together. Takes one argument as a string.

TList delimeter could be 1 character only.

TList and List maximum expected length could only be 255. More arguments could be parsed, but only on 0 expected length of a list (value provided by a user in metadata is truncated to a byte).

Define an option that does not take any aruments:

arg\a\t\tSimple flag with long and short variants and without arguments.

Define an option that takes one argument (integer):

arg\ta\targ=arg;thint=integer\tFlag with long and short variants that takes one argument.

Define a long option that can take a list with 4 elements (file paths):

arg\narg=list;len=4;thint=file\tFlag with long option only that take list with 4 elements.

Make library push -- to a list of long options:

-separator