.\" Man page generated from reStructuredText.
.
.TH "ARGPARSE" "1" "Jun 21, 2018" "0.6.0" "argparse"
.SH NAME
argparse \- argparse tutorial
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.sp
Contents:
.SH CREATING AND USING PARSERS
.sp
The \fBargparse\fP module is a function which, when called, creates an instance of the Parser class.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\- script.lua
local argparse = require "argparse"
local parser = argparse()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
\fBparser\fP is now an empty parser which does not recognize any command line arguments or options.
.SS Parsing command line arguments
.sp
\fB:parse([argv])\fP method of the Parser class returns a table with processed data from the command line or \fBargv\fP array.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local args = parser:parse()
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
After this is executed with \fBlua script.lua\fP, \fBargs\fP is an empty table because the parser is empty and no command line arguments were supplied.
.SS Error handling
.sp
If the provided command line arguments are not recognized by the parser, it will print an error message and call \fBos.exit(1)\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua foo
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua [\-h]
Error: too many arguments
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If halting the program is undesirable, \fB:pparse([args])\fP method should be used. It returns boolean flag indicating success of parsing and result or error message.
.sp
An error can raised manually using \fB:error()\fP method.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:error("manual argument validation failed")
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua [\-h]
Error: manual argument validation failed
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Help option
.sp
As the automatically generated usage message states, there is a help option \fB\-h\fP added to any parser by default.
.sp
When a help option is used, parser will print a help message and call \fBos.exit(0)\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-h
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua [\-h]
Options:
\-h, \-\-help Show this help message and exit.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Typo autocorrection
.sp
When an option is not recognized by the parser, but there is an option with a similar name, a suggestion is automatically added to the error message.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-\-hepl
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua [\-h]
Error: unknown option \(aq\-\-hepl\(aq
Did you mean \(aq\-\-help\(aq?
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Configuring parsers
.sp
Parsers have several properties affecting their behavior. For example, \fBdescription\fP and \fBepilog\fP properties set the text to be displayed in the help message after the usage message and after the listings of options and arguments, respectively. Another is \fBname\fP, which overwrites the name of the program which is used in the usage message (default value is inferred from command line arguments).
.sp
There are several ways to set properties. The first is to chain setter methods of Parser object.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local parser = argparse()
:name "script"
:description "A testing script."
:epilog "For more info, see http://example.com"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The second is to call a parser with a table containing some properties.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local parser = argparse() {
name = "script",
description = "A testing script.",
epilog "For more info, see http://example.com."
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Finally, \fBname\fP\&. \fBdescription\fP and \fBepilog\fP properties can be passed as arguments when calling a parser.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local parser = argparse("script", "A testing script.", "For more info, see http://example.com.")
.ft P
.fi
.UNINDENT
.UNINDENT
.SH ADDING AND CONFIGURING ARGUMENTS
.sp
Positional arguments can be added using \fB:argument(name, description, default, convert, args)\fP method. It returns an Argument instance, which can be configured in the same way as Parsers. The \fBname\fP property is required.
.sp
This and the following examples show contents of the result table returned by \fIparser:parse()\fP when the script is executed with given command\-line arguments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:argument "input"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua foo
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
input = "foo"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The data passed to the argument is stored in the result table at index \fBinput\fP because it is the argument\(aqs name. The index can be changed using \fBtarget\fP property.
.SS Setting number of consumed arguments
.sp
\fBargs\fP property sets how many command line arguments the argument consumes. Its value is interpreted as follows:
.TS
center;
|l|l|.
_
T{
Value
T} T{
Interpretation
T}
_
T{
Number \fBN\fP
T} T{
Exactly \fBN\fP arguments
T}
_
T{
String \fBA\-B\fP, where \fBA\fP and \fBB\fP are numbers
T} T{
From \fBA\fP to \fBB\fP arguments
T}
_
T{
String \fBN+\fP, where \fBN\fP is a number
T} T{
\fBN\fP or more arguments
T}
_
T{
String \fB?\fP
T} T{
An optional argument
T}
_
T{
String \fB*\fP
T} T{
Any number of arguments
T}
_
T{
String \fB+\fP
T} T{
At least one argument
T}
_
.TE
.sp
If more than one argument can be consumed, a table is used to store the data.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:argument("pair", "A pair of arguments.")
:args(2)
parser:argument("optional", "An optional argument.")
:args "?"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua foo bar
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
pair = {"foo", "bar"}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua foo bar baz
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
pair = {"foo", "bar"},
optional = "baz"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH ADDING AND CONFIGURING OPTIONS
.sp
Options can be added using \fB:option(name, description, default, convert, args, count)\fP method. It returns an Option instance, which can be configured in the same way as Parsers. The \fBname\fP property is required. An option can have several aliases, which can be set as space separated substrings in its name or by continuously setting \fBname\fP property.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
\-\- These lines are equivalent:
parser:option "\-f" "\-\-from"
parser:option "\-f \-\-from"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-\-from there
$ lua script.lua \-\-from=there
$ lua script.lua \-f there
$ lua script.lua \-fthere
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
from = "there"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
For an option, default index used to store arguments passed to it is the first "long" alias (an alias starting with two control characters, typically hyphens) or just the first alias, without control characters. Hyphens in the default index are replaced with underscores. In the following table it is assumed that \fBlocal args = parser:parse()\fP has been executed.
.TS
center;
|l|l|.
_
T{
Option\(aqs aliases
T} T{
Location of option\(aqs arguments
T}
_
T{
\fB\-o\fP
T} T{
\fBargs.o\fP
T}
_
T{
\fB\-o\fP \fB\-\-output\fP
T} T{
\fBargs.output\fP
T}
_
T{
\fB\-s\fP \fB\-\-from\-server\fP
T} T{
\fBargs.from_server\fP
T}
_
.TE
.sp
As with arguments, the index can be explicitly set using \fBtarget\fP property.
.SS Flags
.sp
Flags are almost identical to options, except that they don\(aqt take an argument by default.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:flag("\-q \-\-quiet")
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-q
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
quiet = true
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Control characters
.sp
The first characters of all aliases of all options of a parser form the set of control characters, used to distinguish options from arguments. Typically the set only consists of a hyphen.
.SS Setting number of consumed arguments
.sp
Just as arguments, options can be configured to take several command line arguments.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:option "\-\-pair"
:args(2)
parser:option "\-\-optional"
:args "?"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-\-pair foo bar
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
pair = {"foo", "bar"}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-\-pair foo bar \-\-optional
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
pair = {"foo", "bar"},
optional = {}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-\-optional=baz
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
optional = {"baz"}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Note that the data passed to \fBoptional\fP option is stored in an array. That is necessary to distinguish whether the option was invoked without an argument or it was not invoked at all.
.SS Setting number of invocations
.sp
For options, it is possible to control how many times they can be used. argparse uses \fBcount\fP property to set how many times an option can be invoked. The value of the property is interpreted in the same way \fBargs\fP is.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:option("\-e \-\-exclude")
:count "*"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-eFOO \-eBAR
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
exclude = {"FOO", "BAR"}
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If an option can be used more than once and it can consume more than one argument, the data is stored as an array of invocations, each being an array of arguments.
.sp
As a special case, if an option can be used more than once and it consumes no arguments (e.g. it\(aqs a flag), than the number of invocations is stored in the associated field of the result table.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:flag("\-v \-\-verbose", "Sets verbosity level.")
:count "0\-2"
:target "verbosity"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-vv
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
verbosity = 2
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SH MUTUALLY EXCLUSIVE GROUPS
.sp
A group of arguments and options can be marked as mutually exclusive using \fB:mutex(argument_or_option, ...)\fP method of the Parser class.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:mutex(
parser:argument "input"
:args "?",
parser:flag "\-\-process\-stdin"
)
parser:mutex(
parser:flag "\-q \-\-quiet",
parser:flag "\-v \-\-verbose"
)
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If more than one element of a mutually exclusive group is used, an error is raised.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-qv
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua ([\-q] | [\-v]) [\-h] ([] | [\-\-process\-stdin])
Error: option \(aq\-v\(aq can not be used together with option \(aq\-q\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua file \-\-process\-stdin
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua ([\-q] | [\-v]) [\-h] ([] | [\-\-process\-stdin])
Error: option \(aq\-\-process\-stdin\(aq can not be used together with argument \(aqinput\(aq
.ft P
.fi
.UNINDENT
.UNINDENT
.SH ADDING AND CONFIGURING COMMANDS
.sp
A command is a subparser invoked when its name is passed as an argument. For example, in \fI\%git\fP CLI \fBadd\fP, \fBcommit\fP, \fBpush\fP, etc. are commands. Each command has its own set of arguments and options, but inherits options of its parent.
.sp
Commands can be added using \fB:command(name, description, epilog)\fP method. Just as options, commands can have several aliases.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:command "install i"
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
If a command it used, \fBtrue\fP is stored in the corresponding field of the result table.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua install
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
install = true
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
A typo will result in an appropriate error message.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua instal
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua [\-h] ...
Error: unknown command \(aqinstal\(aq
Did you mean \(aqinstall\(aq?
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Getting name of selected command
.sp
Use \fBcommand_target\fP property of the parser to store the name of used command in a field of the result table.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:command_target("command")
parser:command("install")
parser:command("remove")
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua install
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
install = true,
command = "install"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Adding elements to commands
.sp
The Command class is a subclass of the Parser class, so all the Parser\(aqs methods for adding elements work on commands, too.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local install = parser:command "install"
install:argument "rock"
install:option "\-f \-\-from"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua install foo \-\-from=bar
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
install = true,
rock = "foo",
from = "bar"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
Commands have their own usage and help messages.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua install
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua install [\-f ] [\-h]
Error: too few arguments
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua install \-\-help
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua install [\-f ] [\-h]
Arguments:
rock
Options:
\-f , \-\-from
\-h, \-\-help Show this help message and exit.
.ft P
.fi
.UNINDENT
.UNINDENT
.SS Making a command optional
.sp
By default, if a parser has commands, using one of them is obligatory.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local parser = argparse()
parser:command "install"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua [\-h] ...
Error: a command is required
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
This can be changed using \fBrequire_command\fP property.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
local parser = argparse()
:require_command(false)
parser:command "install"
.ft P
.fi
.UNINDENT
.UNINDENT
.SH DEFAULT VALUES
.sp
For elements such as arguments and options, if \fBdefault\fP property is set to a string, its value is stored in case the element was not used (if it\(aqs not a string, it\(aqll be used as \fBinit\fP property instead, see actions).
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
parser:option("\-o \-\-output", "Output file.", "a.out")
\-\- Equivalent:
parser:option "\-o" "\-\-output"
:description "Output file."
:default "a.out"
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
{
output = "a.out"
}
.ft P
.fi
.UNINDENT
.UNINDENT
.sp
The existence of a default value is reflected in help message, unless \fBshow_default\fP property is set to \fBfalse\fP\&.
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
$ lua script.lua \-\-help
.ft P
.fi
.UNINDENT
.UNINDENT
.INDENT 0.0
.INDENT 3.5
.sp
.nf
.ft C
Usage: script.lua [\-o