1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
|
Adding and configuring options
==============================
Options can be added using ``:option(name, description, default, convert, args, count)`` method. It returns an Option instance, which can be configured in the same way as Parsers. The ``name`` property is required. An option can have several aliases, which can be set as space separated substrings in its name or by continuously setting ``name`` property.
.. code-block:: lua
:linenos:
-- These lines are equivalent:
parser:option "-f" "--from"
parser:option "-f --from"
.. code-block:: none
$ lua script.lua --from there
$ lua script.lua --from=there
$ lua script.lua -f there
$ lua script.lua -fthere
.. code-block:: lua
{
from = "there"
}
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 ``local args = parser:parse()`` has been executed.
======================== ==============================
Option's aliases Location of option's arguments
======================== ==============================
``-o`` ``args.o``
``-o`` ``--output`` ``args.output``
``-s`` ``--from-server`` ``args.from_server``
======================== ==============================
As with arguments, the index can be explicitly set using ``target`` property.
Flags
-----
Flags are almost identical to options, except that they don't take an argument by default.
.. code-block:: lua
:linenos:
parser:flag("-q --quiet")
.. code-block:: none
$ lua script.lua -q
.. code-block:: lua
{
quiet = true
}
Control characters
------------------
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.
Setting number of consumed arguments
------------------------------------
Just as arguments, options can be configured to take several command line arguments.
.. code-block:: lua
:linenos:
parser:option "--pair"
:args(2)
parser:option "--optional"
:args "?"
.. code-block:: none
$ lua script.lua --pair foo bar
.. code-block:: lua
{
pair = {"foo", "bar"}
}
.. code-block:: none
$ lua script.lua --pair foo bar --optional
.. code-block:: lua
{
pair = {"foo", "bar"},
optional = {}
}
.. code-block:: none
$ lua script.lua --optional=baz
.. code-block:: lua
{
optional = {"baz"}
}
Note that the data passed to ``optional`` 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.
Setting argument choices
------------------------
The ``choices`` property can be used to specify a list of choices for an option argument in the same way as for arguments.
.. code-block:: lua
:linenos:
parser:option "--format"
:choices {"short", "medium", "full"}
.. code-block:: none
$ lua script.lua --format foo
.. code-block:: none
Usage: script.lua [-h] [--format {short,medium,full}]
Error: argument for option '--format' must be one of 'short', 'medium', 'full'
Setting number of invocations
-----------------------------
For options, it is possible to control how many times they can be used. argparse uses ``count`` property to set how many times an option can be invoked. The value of the property is interpreted in the same way ``args`` is.
.. code-block:: lua
:linenos:
parser:option("-e --exclude")
:count "*"
.. code-block:: none
$ lua script.lua -eFOO -eBAR
.. code-block:: lua
{
exclude = {"FOO", "BAR"}
}
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.
As a special case, if an option can be used more than once and it consumes no arguments (e.g. it's a flag), than the number of invocations is stored in the associated field of the result table.
.. code-block:: lua
:linenos:
parser:flag("-v --verbose", "Sets verbosity level.")
:count "0-2"
:target "verbosity"
.. code-block:: none
$ lua script.lua -vv
.. code-block:: lua
{
verbosity = 2
}
|
