anchor.diff:  Remko Popma <rpopma@apache.org>
   v0.2.0, 2017-02-11
   :toc: left
  +:toclevels: 1
   :toc-title: Features
   
   A CLI framework in a single file, designed to be easy to include in your application _in source form_:
   allowing you to parse command line arguments without dragging in an external dependency.
   
   How it works: annotate your class and picoCLI initializes it from the command line arguments,
  -converting the input to strongly typed data. Any option prefix style works,
  -with special support for POSIX-style short groupable options.
  -Generates online "usage" help. Can be configured to make option matching case-insensitive,
  +converting the input to strongly typed values in the fields of your class. Any option prefix style works,
  +with special support for POSIX-style clustered short options.
  +Easily customizable online "usage" help. Can be configured to make option matching case-insensitive,
   and supports abbreviated options when unambiguous. Works with Java 5 or higher.
   
   == Example
  
positive.code: }
  ----
  
  == Standalone Options are Booleans
  == Options with Parameters
  == parameters are strongly typed
  == built-in type converters
  
  Converters for byte, short, int and long (and their wrapper classes) use the https://docs.oracle.com/javase/7/docs/api/java/lang/Integer.html#decode(java.lang.String)[`decode`] method to convert String values, so you can specify hexadecimal and even octal values in additional to the normal decimal values.
  
  == registering custom type converters
  == option short form
  
  == Short options can be grouped
  Single-character options preceded with a '-', like `-v` or `-r`, can be grouped, so `-vxr` is equivalent to `-v -x -r`.
  
  // TODO ambiguous short options: ambiguity with the -f FILE and -fFILE notation.
  // TODO ambiguous options: writing --input ARG (as opposed to --input=ARG) is ambiguous,
  // TODO document that if arity>1 and args="-opt=val1 val2", arity overrules the "=": both values are assigned
  
  == Ambiguity
  [source,java]
  ----
  class TextOption {
      @CommandLine.Option(names = "-t") int[] number;
      @CommandLine.Option(names = "-f") File file;
  }
  TextOption opt = CommandLine.parse(new TextOption(), "-t", "123", "-f", "path/to/file");
  ----
  Above example with throw a `ParameterException: Could not convert '-f' to int[] for option '-t' parameter[1]`. PicoCLI finds that the number field is an array, and since no `arity` is specified, it assumes you want to assign all arguments that follow the `-f` option to this field.
  
  TODO: How can users work around this? Do they need to rely on their users specifying -f last? Can we use varargs? What if varargs=false is also specified?
  
  == Download
  
  NOTE: Here is the source. Copy and paste it into a file called `CommandLine.java`, add it to your project, and enjoy!
  
  [source,java]
  ----
  include::../src/main/java/picocli/CommandLine.java[]
  ----
negative.code: [source,java]
  ----
  import picocli.CommandLine.Option;
  import picocli.CommandLine.Parameters;
  import java.io.File;
  
  public class Example {
      @Parameters(description = "Specifies the input file(s).")
      private File[] inputFiles;
  
      @Option(names = { "--out", "-o" }, description = "Specifies the output file.", required = true)
      private File outputFile;
  
      @Option(names = { "--verbose", "-v" }, description = "Be verbose.")
      private boolean verbose = false;
  
      @Option(names = { "--help", "-h" }, help = true, description = "Displays this help message and quits.")
      private boolean helpRequested = false;
      ...
  }
  ----
  