Class std.optparse

Parse and process command line options.

 local OptionParser = require "std.optparse"
 local parser = OptionParser (spec)
 _G.arg, opts = parser:parse (_G.arg)

The string spec passed to OptionParser must be a specially formatted help text, of the form:

 any text VERSION
 Additional lines of text to show when the --version
 option is passed.

 Several lines or paragraphs are permitted.

 Usage: PROGNAME

 Banner text.

 Optional long description text to show when the --help
 option is passed.

 Several lines or paragraphs of long description are permitted.

 Options:

   -h, --help               display this help, then exit
       --version            display version information, then exit
   -b                       a short option with no long option
       --long               a long option with no short option
       --another-long       a long option with internal hypen
       --true               a Lua keyword as an option name
   -v, --verbose            a combined short and long option
   -n, --dryrun, --dry-run  several spellings of the same option
   -u, --name=USER          require an argument
   -o, --output=[FILE]      accept an optional argument
   --                       end of options

Footer text.  Several lines or paragraphs are permitted.

Please report bugs at bug-list@yourhost.com

Most often, everything else is handled automatically. After calling parser:parse as shown above, _G.arg will contain unparsed arguments, usually filenames or similar, and opts will be a table of parsed option values. The keys to the table are the long-options with leading hyphens stripped, and non-word characters turned to _. For example if --another-long had been found in _G.arg then opts would have a key named another_long. If there is no long option name, then the short option is used, e.g. opts.b will be set. The values saved in those keys are controlled by the option handler, usually just true or the option argument string as appropriate.

On those occasions where more complex processing is required, handlers can be replaced or added using parser:on.

Functions

std.optparse.OptionParser (spec) Instantiate a new parser.

Tables

std.optparse.boolvals Map various option strings to equivalent Lua boolean values.
std.optparse.opts Parsed options table, with a key for each encountered option, each with value set by that option's on_handler.
std.optparse.parser Customized parser for your options.

Methods

std.optparse:boolean (opt[, optarg="1"]) Return a Lua boolean equivalent of various optarg strings.
std.optparse:file (opt, optarg) Report an option parse error unless optarg names an existing file.
std.optparse:finished (arglist, i) Finish option processing Usually indicated by -- at arglist[i].
std.optparse:flag (arglist, i[, value]) Option at arglist[i] is a boolean switch.
std.optparse:help () Option should display help text, then exit.
std.optparse:normalise (arglist) Normalise an argument list.
std.optparse:on (name, handler, value) Add an option handler.
std.optparse:on_handler (arglist, i[, value=nil]) Function signature of an option handler for on.
std.optparse:opterr (msg) Report an option parse error, then exit with status 2.
std.optparse:optional (arglist, i[, value=true]) Option at arglist[i] can take an argument.
std.optparse:parse (arglist) Parse arglist.
std.optparse:required (arglist, i[, value]) Option at arglist[i} requires an argument.
std.optparse:set (opt, value) Store value with opt.
std.optparse:version () Option should display version text, then exit.


Functions

std.optparse.OptionParser (spec)
Instantiate a new parser. Read the documented options from spec and return a new parser that can be passed to parse for parsing those options from an argument list.

Parameters:

  • spec string option parsing specification

Returns:

    parser a parser for options described by spec

Tables

std.optparse.boolvals
Map various option strings to equivalent Lua boolean values.

Fields:

  • false false
  • 0 false
  • no false
  • n false
  • true true
  • 1 true
  • yes true
  • y true
std.optparse.opts
Parsed options table, with a key for each encountered option, each with value set by that option's on_handler.
std.optparse.parser
Customized parser for your options.

Methods

std.optparse:boolean (opt[, optarg="1"])
Return a Lua boolean equivalent of various optarg strings. Report an option parse error if optarg is not recognised.

Parameters:

Returns:

    bool true or false
std.optparse:file (opt, optarg)
Report an option parse error unless optarg names an existing file.

Parameters:

  • opt string option name
  • optarg string option argument, must be an existing file

Returns:

    `optarg`
std.optparse:finished (arglist, i)
Finish option processing Usually indicated by -- at arglist[i].

Parameters:

  • arglist table list of arguments
  • i int index of last processed element of arglist

Returns:

    int index of next element of arglist to process
std.optparse:flag (arglist, i[, value])
Option at arglist[i] is a boolean switch.

Parameters:

  • arglist table list of arguments
  • i int index of last processed element of arglist
  • value either a function to process the option argument, or a value to store when this flag is encountered

Returns:

    int index of next element of arglist to process
std.optparse:help ()
Option should display help text, then exit.
std.optparse:normalise (arglist)
Normalise an argument list. Separate short options, remove = separators from --long-option=optarg etc.

Parameters:

  • arglist table list of arguments to normalise

Returns:

    table normalised argument list
std.optparse:on (name, handler, value)
Add an option handler.

Parameters:

  • name opts of the option, or list of option names
  • handler on_handler function to call when any of opts is encountered
  • value additional value passed to on_handler
std.optparse:on_handler (arglist, i[, value=nil])
Function signature of an option handler for on.

Parameters:

  • arglist table list of arguments
  • i int index of last processed element of arglist
  • value additional value registered with on (default nil)

Returns:

    int index of next element of arglist to process
std.optparse:opterr (msg)
Report an option parse error, then exit with status 2.

Parameters:

std.optparse:optional (arglist, i[, value=true])
Option at arglist[i] can take an argument. Argument is accepted only if there is a following entry that does not begin with a '-'.

Parameters:

  • arglist table list of arguments
  • i int index of last processed element of arglist
  • value either a function to process the option argument, or a default value if encountered without an optarg (default true)

Returns:

    int index of next element of arglist to process
std.optparse:parse (arglist)
Parse arglist.

Parameters:

  • arglist table list of arguments

Returns:

  1. table a list of unrecognised arglist elements
  2. opts parsing results
std.optparse:required (arglist, i[, value])
Option at arglist[i} requires an argument.

Parameters:

  • arglist table list of arguments
  • i int index of last processed element of arglist
  • value either a function to process the option argument, or a forced value to replace the user's option argument.

Returns:

    int index of next element of arglist to process
std.optparse:set (opt, value)
Store value with opt.

Parameters:

  • opt string option name
  • value option argument value
std.optparse:version ()
Option should display version text, then exit.
generated by LDoc 1.4.0