anchor.diff:  :idprefix:
   :name: go-getoptions
   :toc: macro
  +:toclevels: 4
   
   Go option parser inspired on the flexibility of Perl’s GetOpt::Long.
   
  
positive.code: 
  Another feature a better option parser should have is the ability to set a flag to `False`.
  
  Negatable boolean options::
  `True` when passed on the command line without any modifier and `False` when the `--no-` modifier is prefixed.
  For example:
  +
  `command --verbose`
  +
  and:
  +
  `command --no-verbose`, or `command --noverbose`
  +
  In `go-getoptions` this is accomplished with:
  +
  - `ptr := opt.NBool(name, default_value)` which automatically defines `no-name` and `noname`.
  - `opt.NBoolVar(&ptr, name, default_value)` which automatically defines `no-name` and `noname`.
  
  That covers the most basic set of features, but still it is not enough to get past a basic program.
  The following features will allow for a more complete interface.
  
  Options with array arguments::
  This allows the same option to be used multiple times with different arguments.
  The list of arguments will be saved into a Slice inside the program.
  For example:
  +
  `list-files --exclude .txt --exclude .html --exclude .pdf`
  +
  In `go-getoptions` this is accomplished with:
  +
  - `ptr := opt.StringSlice(name, 1, 1)`.
  
  Options with Key Value arguments::
  This allows the same option to be used multiple times with arguments of key value type.
  For example:
  +
  `rpmbuild --define name=myrpm --define version=123`
  +
  In `go-getoptions` this is accomplished with:
  +
  - `strMap := opt.StringMap(name, 1, 1)`.
  
  Both features above should support the basic types listed before: string, integer and floating point.
  
negative.code: The features above are useful when you have a variable amount of arguments, but it becomes cumbersome for the user when the number of entries is always the same.
  The features described below are meant to handle the cases when each option has a known number of multiple entries.
  
  === Options with array arguments and multiple entries
  
  This allows the user to save typing.
  For example:
  
  Instead of writing: `color --r 10 --g 20 --b 30 --next-option` or `color --rgb 10 --rgb 20 --rgb 30 --next-option`
  
  The input could be: `color --rgb 10 20 30 --next-option`.
  
  The setup for this feature should allow for the user to continue using both versions of the input, that is passing one argument at a time or passing the 3 arguments at once, or allow the setup to force the user to have to use the 3 arguments at once version.
  This is accomplished with the minimum and maximum setup parameters.
  
  The minimum setup parameter indicates the minimum amount of parameters the user can pass at a time.
  For the example above, the parameter could be set to 3 to force the user to have to pass the 3 arguments at once.
  When set to 1, the user will be able to pass a single parameter per option call.
  
  The maximum setup parameter indicates the maximum amount of parameters the user can pass at a time.
  The option parser will leave any non option argument after the maximum in the `remaining` slice.
  
  In `go-getoptions` this is accomplished with:
  
  - `strSlice := opt.StringSlice(name, minArgs, maxArgs)`.
  - `intSlice := opt.IntSlice(name, minArgs, maxArgs)`.
  
  Additionally, in the case of integers, positive integer ranges are allowed.
  For example:
  
  Instead of writing: `csv --columns 1 2 3` or `csv --columns 1 --columns 2 --columns 3`
  
  The input could be: `csv --columns 1..3`.
  
  In `go-getoptions` this is currently enabled by default when using:
  
  `intSlice := opt.IntSlice(name, minArgs, maxArgs)`
  
  === Options with key value arguments and multiple entries
  
  This allows the user to save typing.
  For example:
  
  Instead of writing: `connection --server hostname=serverIP --server port=123 --client hostname=localhost --client port=456`
  
  The input could be: `connection --server hostname=serverIP port=123 --client hostname=localhost port=456`
  
  In `go-getoptions` this is accomplished with:
  
  - `strMap := opt.StringMap(name, minArgs, maxArgs)`.
  
  That covers a complete user interface that is flexible enough to accommodate most programs.
  The following are advanced features:
  
  === Stop parsing options when `--` is passed
  
  Useful when arguments start with dash `-` and you don't want them interpreted as options.
  
  In `go-getoptions` this is the default behaviour.
  
  === Stop parsing options when a subcommand is passed
  
  A subcommand is assumed to be the first argument that is not an option or an argument to an option.
  When a subcommand is found, stop parsing arguments and let a subcommand handler handle the remaining arguments.
  For example:
  
  `command --opt arg subcommand --subopt subarg`
  
  In the example above, `--opt` is an option and `arg` is an argument to an option, making `subcommand` the first non option argument.
  
  This method is useful when both the command and the subcommand have option handlers for the same option.
  
  For example, with:
  
  `command --help`
  
  `--help` is handled by `command`, and with:
  
  `command subcommand --help`
  
  `--help` is not handled by `command` since there was a subcommand that caused the parsing to stop.
  
  Additionally, when mixed with _pass through_, it will also stop parsing arguments when it finds the first unmatched option.
  
  In `go-getoptions` this is accomplished with:
  
  - `opt.SetRequireOrder()`.
  
  And can be combined with:
  
  - `opt.SetUnknownMode(getoptions.Pass)`.
  
  === Allow passing options and non-options in any order
  
  Some option parsers force you to put the options before or after the arguments.
  That is really annoying!
  
  In `go-getoptions` this is the default behaviour.
  
  === Allow pass through
  
  Have an option to pass through unmatched options.
  Useful when writing programs with multiple options depending on the main arguments.
  The initial parser will only capture the help or global options and pass through everything else.
  Additional argument parsing calls are invoked on the remaining arguments based on the initial input.
  
  In `go-getoptions` this is accomplished with:
  
  - `opt.SetUnknownMode(getoptions.Pass)`.
  
  === Fail on unknown
  
  The opposite of the above option.
  Useful if you want to ensure there are no input mistakes and force the application to stop.
  
  In `go-getoptions` this is the default behaviour.
  
  It can be explicitly set with:
  
  `opt.SetUnknownMode(getoptions.Fail)`.
  
  === Warn on unknown
  
  Less strict parsing of options.
  This will warn the user that the option used is not a valid option but it will not stop the rest of the program.
  
  In `go-getoptions` this is accomplished with:
  
  - `opt.SetUnknownMode(getoptions.Warn)`.
  
  === Option aliases
  
  Options should be allowed to have different aliases.
  For example, the same option could be invoked with `--address` or `--hostname`.
  +
  