Argument Processor

`loop.compiler.Arguments`

Class of objects that work as functions that takes string arguments passed as varargs and process them as command-line arguments to extract possible command-line options that may precede the actual arguments. This class is useful to process command-line arguments passed to a Lua script.

Each object is created as a table that maps the name of each valid command-line option to its default value. The type of the default value also defines which values are valid for each command-line option. For example, a command-line option with a numeric default value will only accepts values that denote numbers. These objects behave like functions that take as parameter a sequence of strings and process them as command-line options.

Behavior

Initialization

Arguments([object]): Creates an argument processor from object that accepts options which names that are defined in the object.

Fields

_alias

Optional table that maps command-line option name aliases to the actual command-line option name. These aliases may be used as command-line option names but the value is stored using the actual option name. By default this field is not defined.

_badnumber

String that defines the format of the error message generated when an command-line option cannot be converted to a number. The default value for this field is "invalid value for option '%s', number excepted but got '%s'".

_boolean

Table that maps strings that are alias of boolean values to its corresponding boolean value. These aliases may be used as the value of boolean command-line options. If the value of a boolean command-line option is not defined in this table then it is registered in the processor under the boolean option's name. The default value for this field is a table that defines "true" and "yes" as aliases of true and "false" and "no" as aliases if false.

_missing

String that defines the format of the error message generated when an command-line option is provided without value. The default value for this field is "no value defined for option '%s'".

_norepeat

String that defines the format of the error message generated when a same command-line option is provided more than once. If this field evaluates to false then repeated command-line option are processed and the last value is the one that remains in the processor. The default value for this field is "option '%s' was already defined".

_optpat

String that defines the pattern that command-line option must match. The pattern must define three captures, in the following order:

name: name of the command-line option.
assign: assignment expression that indicates the value of the option was provided with the option name. If this capture contains any character then the following capture is used as the option's value, otherwise the next argument is used as the option value if necessary.
value: command-line option value. This capture is only processed if the previous capture evaluates to a non-empty string.

The default value for this field is "^%-(%w+)(=?)(.-)$".

_unknown

String that defines the format of the error message generated when an command-line option is provided that is not defined in the processor. If this field evaluates to false then any command-line option provided that match the option pattern (see field _optpat) and is not defined is processed as a string option. The default value for this field is "unknown option '%s'".

Meta-Fields

__call: Receives as arguments a sequence of string values that shall be processed as command-line options by the processor. The values of the processed options are stored in the processor using the option name as key thus replacing the default values initially provided. This function returns the index of the last string processed or nil and an error message if some error was detected during the command-line option processing.

Remarks

Option names shall not match the name of members defined by this class.
Options which default value are boolean never get their value from a following argument like in --boolopt true. The only way to explicitly set the value of a boolean option is using the assignment expression defined by the second capture of pattern defined by field _optpat like in --boolopt=false. When the assignment expression is not present in the definition of a boolean option then the option received the value true by default.
Options which default value are tables may appear many times (even when field _norepeat is defined) and each option's value is inserted in the table thus resulting in a array of all values provided for the option.
Options which default value are functions may also appear many times (even when field _norepeat is defined). In such case, the function is invoked for each time the option is processed and receives as parameters the processor object, the option's name, and option's value. If the function returns a value then the options processing fails and the returned value is used as error message.

Examples

Server with Command-Line Options

local Arguments = require "loop.compiler.Arguments"
local Verbose = require "loop.debug.Verbose"
local verbose = Verbose()
local args = Arguments{
 _optpat = "^%-%-(%w+)([=:]?)(.-)$"
 port = 0
 verb = {}
}
function args:log(optname, optvalue)
 local file, errmsg = io.open(optvalue, "w")
 if file
 then verbose:output(file)
 else return errmsg
 end end print("Fake Server 1.0 Copyright (C) 0000")
local argidx, errmsg = args(...)
if not argidx or argidx >= select("#", ...) then
 io.stderr:write([[
ERROR: ]],errmsg,[[ 
Usage: fakeserver.lua [options] <files>
Options:
 --verb <flag>
 --log <file>
 --port <number>
]])
 os.exit(1)
end for _, flag in ipairs(args.verb) do
 verbose:flag(flag, true)
end if args.port == 0 then
 args.port = nil -- no port was defined end initserver(args, select(argidx, ...))