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
172
173
174
175
176
177
178
179
180
181
182
|
Adding and configuring commands
===============================
A command is a subparser invoked when its name is passed as an argument. For example, in `git <http://git-scm.com>`_ CLI ``add``, ``commit``, ``push``, etc. are commands. Each command has its own set of arguments and options, but inherits options of its parent.
Commands can be added using ``:command(name, description, epilog)`` method. Just as options, commands can have several aliases.
.. code-block:: lua
:linenos:
parser:command "install i"
If a command it used, ``true`` is stored in the corresponding field of the result table.
.. code-block:: none
$ lua script.lua install
.. code-block:: lua
{
install = true
}
A typo will result in an appropriate error message.
.. code-block:: none
$ lua script.lua instal
.. code-block:: none
Usage: script.lua [-h] <command> ...
Error: unknown command 'instal'
Did you mean 'install'?
Getting name of selected command
--------------------------------
Use ``command_target`` property of the parser to store the name of used command in a field of the result table.
.. code-block:: lua
:linenos:
parser:command_target("command")
parser:command("install")
parser:command("remove")
.. code-block:: none
$ lua script.lua install
.. code-block:: lua
{
install = true,
command = "install"
}
Adding elements to commands
---------------------------
The Command class is a subclass of the Parser class, so all the Parser's methods for adding elements work on commands, too.
.. code-block:: lua
:linenos:
local install = parser:command "install"
install:argument "rock"
install:option "-f --from"
.. code-block:: none
$ lua script.lua install foo --from=bar
.. code-block:: lua
{
install = true,
rock = "foo",
from = "bar"
}
Commands have their own usage and help messages.
.. code-block:: none
$ lua script.lua install
.. code-block:: none
Usage: script.lua install [-h] [-f <from>] <rock>
Error: too few arguments
.. code-block:: none
$ lua script.lua install --help
.. code-block:: none
Usage: script.lua install [-h] [-f <from>] <rock>
Arguments:
rock
Options:
-h, --help Show this help message and exit.
-f <from>, --from <from>
Making a command optional
-------------------------
By default, if a parser has commands, using one of them is obligatory.
.. code-block:: lua
:linenos:
local parser = argparse()
parser:command "install"
.. code-block:: none
$ lua script.lua
.. code-block:: none
Usage: script.lua [-h] <command> ...
Error: a command is required
This can be changed using ``require_command`` property.
.. code-block:: lua
:linenos:
local parser = argparse()
:require_command(false)
parser:command "install"
Command summaries
-----------------
The description for commands shown in the parent parser help message can be set
with the ``summary`` property.
.. code-block:: lua
:linenos:
parser:command "install"
:summary "Install a rock."
:description "A long description for the install command."
.. code-block:: none
$ lua script.lua --help
.. code-block:: none
Usage: script.lua [-h] <command> ...
Options:
-h, --help Show this help message and exit.
Commands:
install Install a rock.
.. code-block:: none
$ lua script.lua install --help
.. code-block:: none
Usage: script.lua install [-h]
A long description for the install command.
Options:
-h, --help Show this help message and exit.
|
