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 ifoptarg
is not recognised.Parameters:
Returns:
-
bool
true
orfalse
- std.optparse:file (opt, optarg)
-
Report an option parse error unless
optarg
names an existing file.Parameters:
Returns:
-
`optarg`
- std.optparse:finished (arglist, i)
-
Finish option processing
Usually indicated by
--
atarglist[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:
- msg string error message
- 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:
- 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
withopt
.Parameters:
- opt string option name
- value option argument value
- std.optparse:version ()
- Option should display version text, then exit.