formats.cli - ICE 0.1 API documentation

ICE 0.1 API documentation

# formats.cli

Command line parser.

struct CLIOption;

  Command line option.

  Methods of this struct are used to specify parameters of the option. The option is then added to a CLI using its addOption() method.

  this(const(immutable(char)[]) name);

    Construct a CLIOption with specified name.

    Parameters:

    const(immutable(char)[]) name | Long name of the option. (Will automatically be prefixed with "--" .) Must not be parsable as a number.

  pure @property ref CLIOption shortName(const char name);

    Set short name of the option. (Will be prefixed by "-" .)

    Parameters:

    char name | Short name (one character). Must be from the alphabet.

  pure @property ref CLIOption help(const string help);

    Set help string of the option.

  CLIOption target(T)(T* target);

    Set value target.

    Parse single argument of the option as target type and write it to the target.
    Target must be specified (by any of the target() methods)
    Target type must be a bool, number or a string.

    Parameters:

    target | Target variable to write option argument to.

  CLIOption target(T)(T target);

    Set setter function target.

    Parse single argument of the option as target type and pass it to specified function.
    Target must be specified (by any of the target() methods).
    Target type must be function taking single bool, number or a string.

    Parameters:

    target | Target setter to pass option argument to.

  CLIOption target(T)(ref T[] target);

    Set array target.

    Parse arguments of the option as target type and write them to specified array. If the option is specified more than once, arguments from all instances of the option are written to the array.
    Target must be specified (by any of the target() methods).
    Target type must an arrao of bools, numbers, strings.

    Parameters:

    target | Target array to write option arguments to.

  CLIOption target(T)(T target, const int argCount = -1);

    Set function target.

    Pass arguments of the option to specified function without any parsing. Optionally, required number of arguments can be specified.
    Target must be specified (by any of the target() methods).
    Target must be a void function taking an array of strings as its parameter.

    Parameters:

    target | Target function to pass option arguments to.

  ref CLIOption defaultArgs(string[] args...);

    Specify default arguments for this option.

    Option's action will be executed with specified arguments if the option is not present. If default arguments are not specified, and the option is not present, option's action will not be executed.

    Parameters:

    string[] args | Default arguments for the option.

    Returns:
    Resulting CLIOption.
class CLI;

  Command line parser.

  Options are specified using the Option struct and added using the addOption() method.
  Each option has a long, GNU-style name automatically prefixed by "--" and optionally a short, one character name automatically prefixed by "-". Long option names can be abbreviated as long as the abbreviation uniquely identifies an option.
  Short options can be chained; Option arguments can be separated from options by spaces or '='; Array options accept comma separated arguments; Boolean flags can have optional argument, e.g. "-f0" will set flag -f to false.
  A help option (-h, --help) is automatically generated from help info specified for each option.

  Examples:

       void main(string[] args)
       {
           CLI cli = new CLI();
           cli.description = "Example 1.0\n Written in D by E. Xample";
           cli.epilog = "Find more info at www.example.com";

           bool flag;
           int val;
           int setter_val;
           void setter(int i){setter_val = i;}
           int[] array;

           //bool flag
           cli.addOption(CLIOption("flag").target(&flag).shortName('f'));
           //value, with defaults
           cli.addOption(CLIOption("value").target(&flag).shortName('v').defaultArgs("1"));
           //setter
           cli.addOption(CLIOption("setter").target(&setter).shortName('s');
           //array
           cli.addOption(CLIOption("array").target(array).shortName('a');
           //custom function
           cli.addOption(CLIOption("custom")
                              .target((string[] args){foreach(arg; args){writeln(arg);}})
                              .shortName('c');

           //parse arguments
           if(!cli.parse(args)){return;}

           ...

       }

  this();

    Construct a CLI.

  pure @property void description(const string text);

    Set program description (start of the help text).

  pure @property void epilog(const string text);

    Set epilog of the help text.

  pure void addOption(CLIOption option);

    Add a command line option.

    Every option must have an unique long (and short, if any) name.

    Parameters:

    CLIOption option | Option to add.

  bool parse(string[] args);

    Parse command line arguments.

    Command line options' targets are written to/executed as the options are parsed. If an error occurs, parsing is aborted and false is returned.

    Parameters:

    string[] args | Command line arguments to parse. Must be at least one (program name).

    Returns:
    False in case of error or if help was requested. False otherwise.
string[] storeAction(T)(string[] args, void delegate(T) target);

  Action that parses the first argument and passes it to a delegate.

  Parameters:

  args | Option arguments.
  target | Target delegate to pass parsed argument to.

  Returns:
  Arguments that were not parsed.
  Throws:
  CLIException if there weren't enough arguments. ConvOverflowException on a parsing overflow error (e.g. to large int). ConvException on a parsing error.
string[] arrayStoreAction(T)(string[] args, ref T[] target);

  Action that parses any number of arguments and saves them in an array.

  Parameters:

  args | Option arguments.
  target | Target array to add parsed arguments to.

  Returns:
  Empty array.
  Throws:
  ConvOverflowException on a parsing overflow error (e.g. to large int). ConvException on a parsing error.

Copyright © Ferdinand Majerech 2011. | Page generated by AutoDDoc and Ddoc.