-
Notifications
You must be signed in to change notification settings - Fork 7
/
index.html
353 lines (260 loc) · 13.5 KB
/
index.html
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
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<title>docopt—language for description of command-line interfaces</title>
<link rel="stylesheet" href="normalize.css" media="screen">
<link rel="stylesheet" href="style.css" media="screen">
<link rel="stylesheet" href="printable.css" media="print">
</head>
<body>
<a href="https://github.com/docopt/"><img style="position: absolute; top: 0; right: 0; border: 0;" src="https://s3.amazonaws.com/github/ribbons/forkme_right_darkblue_121621.png" alt="Fork me on GitHub"></a>
<h1>docopt</h1>
<script>
document.getElementsByTagName('h1')[0].className =
['dashdash', 'ellipsis', 'brackets', 'angular', 'parens', 'upper', '']
[Math.floor(Math.random() * 7)];
</script>
<h2>Command-line interface description language</h2>
<iframe width="800" height="450"
src="http://www.youtube.com/embed/pXhcPJK5cMc?rel=0"
frameborder="0" allowfullscreen></iframe>
<p><code>docopt</code> helps you:</p>
<ul>
<li>define the interface for your command-line app, and</li>
<li>automatically generate a parser for it.</li>
</ul>
<p><code>docopt</code> is based on conventions that have been used for decades in help messages and
man pages for describing a program's interface. An interface description
in <code>docopt</code> <em>is</em> such a help message, but formalized. Here is an example:</p>
<pre><code>Naval Fate.
Usage:
naval_fate ship new <name>...
naval_fate ship <name> move <x> <y> [--speed=<kn>]
naval_fate ship shoot <x> <y>
naval_fate mine (set|remove) <x> <y> [--moored|--drifting]
naval_fate -h | --help
naval_fate --version
Options:
-h --help Show this screen.
--version Show version.
--speed=<kn> Speed in knots [default: 10].
--moored Moored (anchored) mine.
--drifting Drifting mine.
</code></pre>
<p>The example describes the interface of executable <code>naval_fate</code>, which can be
invoked with different combinations of <em>commands</em> (<code>ship</code>, <code>new</code>, <code>move</code>,
etc.), <em>options</em> (<code>-h</code>, <code>--help</code>, <code>--speed=<kn></code>, etc.) and positional
arguments (<code><name></code>, <code><x></code>, <code><y></code>).</p>
<p>The example uses brackets "<code>[ ]</code>", parens "<code>( )</code>", pipes "<code>|</code>" and ellipsis
"<code>...</code>" to
describe <em>optional</em>, <em>required</em>, <em>mutually exclusive</em>, and <em>repeating</em>
elements. Together, these elements form valid <em>usage patterns</em>, each starting
with program's name <code>naval_fate</code>.</p>
<p>Below the usage patterns, there is a list of options with descriptions.
They describe whether an option has short/long forms (<code>-h</code>, <code>--help</code>), whether
an option has an argument (<code>--speed=<kn></code>), and whether that argument has a
default value (<code>[default: 10]</code>).</p>
<p>A <code>docopt</code> implementation will extract all that information and generate a
command-line arguments parser, with the text of the interface description as the
help message shown when the program is invoked with
the <code>-h</code> or <code>--help</code> options.</p>
<h2>Usage patterns</h2>
<p>Text occuring between keyword <code>usage:</code> (case-<em>in</em>sensitive) and a <em>visibly</em>
empty line is interpreted as list of usage patterns. The first word after
<code>usage:</code> is interpreted as the program's name. Here is a minimal example for
program that takes no command-line arguments:</p>
<pre><code>Usage: my_program
</code></pre>
<p>Program can have several patterns listed with various elements used to
describe the pattern:</p>
<pre><code>Usage:
my_program command --option <argument>
my_program [<optional-argument>]
my_program --another-option=<with-argument>
my_program (--either-that-option | <or-this-argument>)
my_program <repeating-argument> <repeating-argument>...
</code></pre>
<p>Each of the elements and constructs is described below.
We will use the word "<em>word</em>" to describe a sequence of characters delimited
by either whitespace, one of "<code>[]()|</code>" characters, or "<code>...</code>".</p>
<h3><argument> ARGUMENT</h3>
<p>Words starting with "<code><</code>", ending with "<code>></code>" and upper-case words are
interpreted as positional arguments.</p>
<pre><code>Usage: my_program <host> <port>
</code></pre>
<h3>-o --option</h3>
<p>Words starting with one or two dashes (with exception of "<code>-</code>", "<code>--</code>"
by themselves) are interpreted as short (one-letter) or long options,
respectively.</p>
<ul>
<li>Short options can be "stacked" meaning that <code>-abc</code> is equivalent to
<code>-a -b -c</code>.</li>
<li>Long options can have arguments specified after space or equal "<code>=</code>" sign:<br>
<code>--input=ARG</code> is equivalent to <code>--input ARG</code>.</li>
<li>Short options can have arguments specified after <em>optional</em> space:<br>
<code>-f FILE</code> is equivalent to <code>-fFILE</code>.</li>
</ul>
<p>Note, writing <code>--input ARG</code> (as opposed to <code>--input=ARG</code>) is ambiguous, meaning
it is not possible to tell whether <code>ARG</code> is option's argument or a positional
argument. In usage patterns this will be interpreted as an option with argument
<em>only</em> if a description (covered below) for that option is
provided. Otherwise it will be interpreted as an option and separate
positional argument.</p>
<p>There is the same ambiguity with the <code>-f FILE</code> and <code>-fFILE</code> notation. In the latter
case it is not possible to tell whether it is a number of stacked short
options, or an option with an argument. These notations will be interpreted as an
option with argument <em>only</em> if a description for the option is provided.</p>
<h3>command</h3>
<p>All other words that do <em>not</em> follow the above conventions of <code>--options</code> or
<code><arguments></code> are interpreted as (sub)commands.</p>
<h3>[optional elements]</h3>
<p>Elements (options, arguments, commands) enclosed with square brackets "<code>[ ]</code>"
are marked to be <em>optional</em>. It does not matter if elements are enclosed
in the same or different pairs of brackets, for example:</p>
<pre><code>Usage: my_program [command --option <argument>]
</code></pre>
<p>is equivalent to:</p>
<pre><code>Usage: my_program [command] [--option] [<argument>]
</code></pre>
<h3>(required elements)</h3>
<p><em>All elements are required by default</em>, if not included in brackets "<code>[ ]</code>".
However, sometimes it is necessary to mark elements as required explicitly
with parens "<code>( )</code>".
For example, when you need to group mutually-exclusive elements (see next
section):</p>
<pre><code>Usage: my_program (--either-this <and-that> | <or-this>)
</code></pre>
<p>Another use case is when you need to specify that <em>if one element is present,
then another one is required</em>, which you can achieve as:</p>
<pre><code>Usage: my_program [(<one-argument> <another-argument>)]
</code></pre>
<p>In this case, a valid program invocation could be with either no arguments,
or with 2 arguments.</p>
<h3>element|another</h3>
<p>Mutually-exclusive elements can be separated with a pipe "<code>|</code>" as follows:</p>
<pre><code>Usage: my_program go (--up | --down | --left | --right)
</code></pre>
<p>Use parens "<code>( )</code>" to group elements when <em>one</em> of the mutually exclusive
cases is required. Use brackets "<code>[ ]</code>" to group elements when <em>none</em> of the
mutually exclusive cases is required:</p>
<pre><code>Usage: my_program go [--up | --down | --left | --right]
</code></pre>
<p>Note, that specifying several patterns works exactly like pipe "<code>|</code>", that is:</p>
<pre><code>Usage: my_program run [--fast]
my_program jump [--high]
</code></pre>
<p>is equivalent to:</p>
<pre><code>Usage: my_program (run [--fast] | jump [--high])
</code></pre>
<h3>element...</h3>
<p>Use ellipsis "<code>...</code>" to specify that the argument (or group of arguments)
to the left could be repeated one or more times:</p>
<pre><code>Usage: my_program open <file>...
my_program move (<from> <to>)...
</code></pre>
<p>You can flexibly specify the number of arguments that are required.
Here are 3 (redundant) ways of requiring zero or more arguments:</p>
<pre><code>Usage: my_program [<file>...]
my_program [<file>]...
my_program [<file> [<file> ...]]
</code></pre>
<p>One or more arguments:</p>
<pre><code>Usage: my_program <file>...
</code></pre>
<p>Two or more arguments (and so on):</p>
<pre><code>Usage: my_program <file> <file>...
</code></pre>
<h3>[options]</h3>
<p>"<code>[options]</code>" is a shortcut that allows to avoid listing all options
(from list of options with descriptions) in a pattern. For example:</p>
<pre><code>Usage: my_program [options] <path>
--all List everything.
--long Long output.
--human-readable Display in human-readable format.
</code></pre>
<p>is equivalent to:</p>
<pre><code>Usage: my_program [--all --long --human-readable] <path>
--all List everything.
--long Long output.
--human-readable Display in human-readable format.
</code></pre>
<p>This can be useful if you have many options and all of them are applicable
to one of patterns. Alternatively, if you have both short and long
versions of options (specified in option description part),
you can list either of them in a pattern:</p>
<pre><code>Usage: my_program [-alh] <path>
-a, --all List everything.
-l, --long Long output.
-h, --human-readable Display in human-readable format.
</code></pre>
<p>More details on how to write options' descriptions will follow below.</p>
<h3>[--]</h3>
<p>A double dash "<code>--</code>", when not part of an option, is often used as a convention
to separate options and positional arguments, in order to handle cases when,
e.g., file names could be mistaken for options. In order to support this
convention, add "<code>[--]</code>" into your patterns before positional arguments.</p>
<pre><code>Usage: my_program [options] [--] <file>...
</code></pre>
<p>Apart from this special meaning, "<code>--</code>" is just a normal command, so you can
apply any previously-described operations, for example, make it required
(by dropping brackets "<code>[ ]</code>")</p>
<h3>[-]</h3>
<p>A single dash "<code>-</code>", when not part of an option, is often used by convention
to signify that a program should process <code>stdin</code>, as opposed to a file.
If you want to follow this convention add "<code>[-]</code>" to your pattern.
"<code>-</code>" by itself is just a normal command, which you can use with any meaning.</p>
<h2>Option descriptions</h2>
<p>Option descriptions consist of a list of options that you put below your
usage patterns. It is optional to specify them if there is no ambiguity
in usage patterns (described in the <code>--option</code> section above).</p>
<p>An option's description allows to specify:</p>
<ul>
<li>that some short and long options are synonymous,</li>
<li>that an option has an argument,</li>
<li>and the default value for an option's argument.</li>
</ul>
<p>The rules are as follows:</p>
<p>Every line that starts with "<code>-</code>" or "<code>--</code>" (not counting spaces)
is treated as an option description, e.g.:</p>
<pre><code>Options:
--verbose # GOOD
-o FILE # GOOD
Other: --bad # BAD, line does not start with dash "-"
</code></pre>
<p>To specify that an option has an argument, put a word describing that
argument after a space (or equals "<code>=</code>" sign) as shown below. Follow
either <code><angular-brackets></code> or <code>UPPER-CASE</code> convention for options' arguments.
You can use a comma if you want to separate options. In the example below, both
lines are valid, however it is recommended to stick to a single style.</p>
<pre><code>-o FILE --output=FILE # without comma, with "=" sign
-i <file>, --input <file> # with comma, without "=" sign
</code></pre>
<p>Use two spaces to separate options with their informal description.</p>
<pre><code>--verbose MORE text. # BAD, will be treated as if verbose
# option had an argument MORE, so use
# 2 spaces instead
-q Quit. # GOOD
-o FILE Output file. # GOOD
--stdout Use stdout. # GOOD, 2 spaces
</code></pre>
<p>If you want to set a default value for an option with an argument, put it
into the option's description, in the form <code>[default: <the-default-value>]</code>.</p>
<pre><code>--coefficient=K The K coefficient [default: 2.95]
--output=FILE Output file [default: test.txt]
--directory=DIR Some directory [default: ./]
</code></pre>
<h2><a href="http://try.docopt.org">Try <code>docopt</code> in your browser</a></h2>
<h2>Implementations</h2>
<p><code>docopt</code> is available in numerous programming languages.
Official implementations are listed under the <a href="
https://github.com/docopt">docopt organization on GitHub</a>.</p>
<p><br></p>
<script>
var _gaq=[['_setAccount','UA-15242420-3'],['_trackPageview']];
(function(d,t){var g=d.createElement(t),s=d.getElementsByTagName(t)[0];
g.src=('https:'==location.protocol?'//ssl':'//www')+'.google-analytics.com/ga.js';
s.parentNode.insertBefore(g,s)}(document,'script'));
</script>
</body>
</html>