anchor.diff:  
   • `CalledAs()` method indicates what alias was used to call the option on the command line.
   
  +• Simple synopsis and option list automated help.
  +
   • Boolean, String, Int and Float64 type options.
   
   • Negatable Boolean options.
  
positive.code: 
  toc::[]
  
  == Introduction
  
  NOTE: For a <<quick_overview>>, jump to that section in the TOC or review the http://godoc.org/github.com/DavidGamba/go-getoptions[GoDoc Documentation].
  
  Option parsing is the act of taking command line arguments and converting them into meaningful structures within the program.
  
  An option parser should support, at least, the following:
  
  Boolean options::
  `True` when passed on the command line.
  For example:
  +
  `ls --all`
  +
  In `go-getoptions` this is accomplished with:
  +
  - `ptr := opt.Bool(name, default_value)`.
  - `opt.BoolVar(&ptr, name, default_value)`.
  - Additionally, if all you want to know is if the option was passed you can use: `opt.Bool(name, default_value)` (without capturing its return value) and then check `opt.Called(name)`.
  
  Options with String arguments::
  The option will accept a string argument.
  For example:
  +
  `grepp --ignore .txt`
  +
  Additionally, arguments to options can be passed with the `=` symbol.
  +
  `grepp --ignore=.txt`
  +
  In `go-getoptions` this is accomplished with:
  +
  - `ptr := opt.String(name, default_value)`.
  - `opt.StringVar(&ptr, name, default_value)`.
  
  The features listed above are enough to create basic programs but an option parser should do better:
  
  Options with Integer arguments::
  Parse an option string argument into an Integer and provide an user error if the string provided is not an integer.
  For example:
  +
  `grepp --contex-lines 3`
  +
  and:
  +
  `grepp --context-lines string`
  +
    Error: 'string' is not a valid integer.
  +
  In `go-getoptions` this is accomplished with:
  +
  - `ptr := opt.Int(name, default_value)`.
  - `opt.IntVar(&ptr, name, default_value)`.
  
  Options with Floating point arguments::
  Parse an option string argument into a Floating point value and provide an user error if the string provided is not a valid floating point.
  For example:
  +
  `command --approximation 3.5`
  +
  and:
  +
  `command --approximation string`
  +
    Error: 'string' is not a valid floating point value.
  +
  In `go-getoptions` this is accomplished with:
  +
  - `ptr := opt.Float64(name, default_value)`.
  - `opt.Float64Var(&ptr, name, default_value)`.
  
  The features listed above relieve the programmer from the cumbersome task of converting the option argument into the expected type.
  
  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.
  
  `go-getoptions` has only implemented these two features for string.
  
  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("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("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.
  
  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("warn")`.
  
  Option aliases::
  Options should be allowed to have different aliases.
  For example, the same option could be invoked with `--address` or `--hostname`.
  +
  In `go-getoptions`, pass `opt.Alias("my-alias")` to any option.
  For example:
  +
  `opt.BoolVar(&flag, "flag", false, opt.Alias("alias", "alias-2"))`
  +
  Finally, to know with what alias an option was called with used `opt.CalledAs(<name>)`.
  
  Required options::
  Mark an option as required.
  Return an error if the option is not called.
  +
  In `go-getoptions`, pass `opt.Required()` to any option.
  For example:
  +
  `opt.BoolVar(&flag, "flag", false, opt.Required())`
  +
  Optionally, override the default error message with `opt.Required(msg)`.
  For example:
  +
  `opt.BoolVar(&flag, "flag", false, opt.Required("Missing --flag!"))`
  
  Incremental option::
  Some options can be passed more than once to increment an internal counter.
  For example:
  +
  `command --v --v --v`
  +
  Could increase the verbosity level each time the option is passed.
  +
  In `go-getoptions` this is accomplished with:
  +
  - `ptr := opt.Increment(name, default_value)`.
  - `opt.IncrementVar(&ptr, name, default_value)`.
  
  Additional types::
  The option parser could provide converters to additional types.
  The disadvantage of providing non basic types is that the option parser grows in size.
  +
  Not yet implemented in `go-getoptions`.
  
  Options with optional arguments::
  With regular options, when the argument is not passed (for example: `--level` instead of `--level=debug`) you will get a _Missing argument_ error.
  When using options with optional arguments, If the argument is not passed, the option will set the default value for the option type.
  For this feature to be fully effective in strong typed languages where types have defaults, there must be a means to query the option parser to determine whether or not the option was called or not.
  +
  In `go-getoptions` this is accomplished with:
  +
    - `ptr := opt.StringOptional(name, default_value)`.
    - `ptr := opt.IntOptional(name, default_value)`.
    - Not yet implemented for `float64`.
    - The above should be used in combination with `opt.Called(name)`.
  +
  For example, for the following definition:
  +
  `ptr := opt.StringOptional("level", "info")`
  +
  * If the option `level` is called with just `--level`, the value of `*ptr` is the default `"info"` and querying `opt.Called("level")` returns `true`.
  * If the option `level` is called with `--level=debug`, the value of `*ptr` is `"debug"` and querying `opt.Called("level")` returns `true`.
  * Finally, If the option `level` is not called, the value of `*ptr` is the default `"info"` and querying `opt.Called("level")` returns `false`.
  
  Option flags that call a method internally::
  If all the flag is doing is call a method or function when present, then having a way to call that function directly saves the programmer some time.
  +
  Not yet implemented in `go-getoptions`.
  
  Notice how so far only long options (options starting with double dash `--`) have been mentioned.
  There are 3 main ways to handle short options (options starting with only one dash `-`), see the <<operation_modes>> section for details.
  
  [[operation_modes]]
  == Operation Modes
  
  The behaviour for long options (options starting with double dash `--`) is consistent across operation modes.
  The behaviour for short options (options starting with only one dash `-`) depends on the _operation mode_.
  The sections below show the different operation modes.
  
  === Normal Mode (default)
  
  |===
  |Given argument |Interpretation
  
  |--opt
  a|option: `"opt"`,  argument: `nil`
  
  |--opt=arg
  a|option: `"opt"`, argument: `"arg"` footnote:[Argument gets type casted depending on option definition.]
  
  |-opt
  a|option: `"opt"`, argument: `nil`
  
  |-opt=arg
  a|option: `"opt"`, argument: `"arg"` footnote:[Argument gets type casted depending on option definition.]
  
  |===
  
  === Bundling Mode
  
  Set by defining `opt.SetMode("bundling")`.
  
  |===
  |Given option |Interpretation
  
  |--opt
  a|option: `"opt"`,  argument: `nil`
  
  |--opt=arg
  a|option: `"opt"`, argument: `"arg"` footnote:[Argument gets type casted depending on option definition.]
  
  |-opt
  a|option: `"o"`, argument: `nil` +
  option: `"p"`, argument: `nil` +
  option: `"t"`, argument: `nil`
  
  |-opt=arg
  a|option: `"o"`, argument: `nil` +
  option: `"p"`, argument: `nil` +
  option: `"t"`, argument: `"arg"` footnote:[Argument gets type casted depending on option definition.]
  
  |===
  
  === Enforce Single Dash Mode
  
  Set by defining `opt.SetMode("singleDash")`.
  
  |===
  |Given option |Interpretation
  
  |--opt
  a|option: `"opt"`,  argument: `nil`
  
  |--opt=arg
  a|option: `"opt"`, argument: `"arg"` footnote:[Argument gets type casted depending on option definition.]
  
  |-opt
  a|option: `"o"`, argument: `"pt"` footnote:[Argument gets type casted depending on option definition.]
  
  |-opt=arg
  a|option: `"o"`, argument: `"pt=arg"` footnote:[Argument gets type casted depending on option definition.]
  
  |===
  
  == Biggest option parser misfeature - Automatically generate help
  
  The biggest misfeature an option parser can have is to automatically generate the help message for the programmer.
  This seemingly helpful feature has caused most scripts not to have proper man pages anymore and to have all options descriptions mixed in the help synopsis.
  
  Don't be lazy, write a man page for your program and create the program's synopsis yourself.
  
  If you are looking for options, link:http://asciidoctor.org/[asciidoctor] has a manpage backend that can generate manpages written in the Asciidoc markup.
  
  [[quick_overview]]
  == Quick overview
  
  
negative.code: • Require order: Allows for subcommands. Stop parsing arguments when the first non-option is found.
  When mixed with Pass through, it also stops parsing arguments when the first unmatched option is found.
  
  == How to install it
  
  . Get it from github:
  +
  `go get github.com/DavidGamba/go-getoptions`
  
  . Then import it:
  +
  `import "github.com/DavidGamba/go-getoptions" // As getoptions`
  
  . Enjoy!
  
  == Dependencies
  
  Go 1.5+
  
  [[roadmap]]
  == ROADMAP
  
  * Create new error description for errors when parsing integer ranges (`1..3`).
  
  