CommandLine.Notes.txt

CommandLine Parser Extensions
=============================

Problems with CommandLine:
- Help screen not consistent between invoked automatically on error or via HelpBuilder
- Help text not customisable enough (doesn't show command line structure)
- Parser customisation done inline away from Arguments classes and the defaults are not ideal
- --help/--version interception to display help screen other than the default


Links
-----
https://github.com/gsscoder/commandline/wiki/Latest-Version#usage-attribute
https://github.com/gsscoder/commandline/wiki/Display-A-Help-Screen


Usage
-----

Parser.Default
    returns a Parser instance


Configuration
-------------

var parser = new Parser(config => config.HelpWriter = Console.Out);


Single Options
--------------

var result = parser.ParseArguments<T>(args);
    returns a ParserResult<T>
    which is really a Parsed<T> or NotParsed<T>

or can do

var result = parser.ParseArguments<T>(args)
    .WithParsed(options => ...)     // Type T
    .WithNotParsed(errors => ...)   // IEnumerable<Error>

or even

var returnCode = parser.ParseArguments<T>(args)
    .MapResult(
        options => RunAndReturnExitCode(options),
        _ => 1
    );


Verbs
-----

var result = parser.ParseArguments<T1, T2, T2>(args)
    .WithParsed<T1>(opts => ...)
    .WithParsed<T2>(opts => ...)
    .WithParsed<T3>(opts => ...)
    .WithNotParsed(errors => ...)

or

var returnCode = parser.ParseArguments<T1, T2, T3>(args)
    .MapResult(
        (T1 options) => RunT1AndReturnExitCode(options),
        (T2 options) => RunT2AndReturnExitCode(options),
        (T3 options) => RunT3AndReturnExitCode(options),
        errs => 1
    );


Built in Commands
-----------------

--help      triggers help output
--version   triggers version output

only via the default configured HelpWriter though











Sample Output
-------------

----------------------------------------------------------------------------------------------------
Default output from ParseArguments<>

CommandLine 2.0.275-beta
Copyright (c) 2005 - 2015 Giacomo Stelluti Scala

ERROR(S):
  Required option 'p, position' is missing.
  A required value not bound to option name is missing.
USAGE:
Default:
  CommandLine [filename]

  -p, --position       Required. Where to start from

  -l, --lines          (Default: 5) How many lines to process

  --help               Display this help screen.

  --version            Display version information.

  FileName (pos. 0)    Required. The filename to process


----------------------------------------------------------------------------------------------------
Customising via HelpText.AutoBuild

CommandLine 2.0.275-beta
Copyright (c) 2005 - 2015 Giacomo Stelluti Scala
 
USAGE:
Default:
  CommandLine [filename]

  -p, --position       Required. Where to start from Valid values: Above, Below
  -l, --lines          (Default: 5) How many lines to process
  --help               Display this help screen.
  --version            Display version information.
  FileName (pos. 0)    Required. The filename to process


----------------------------------------------------------------------------------------------------
Templated help from DNX.Helpers.CommandLine

Test.DNX.Helpers.CommandLine v1 - 
Copyright © 2017 DNX Solutions Ltd

Usage:
Test.DNX.Helpers.CommandLine.dll [FileName] { [options] }

Options:
-p, --position  Where to start from
-l, --lines  How many lines to process
-?, --help  Display this Help page