Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 485 lines (341 sloc) 14.333 kb
6cf2a8c Added README.
Juan Jose Comellas authored
1 Getopt for Erlang
2 =================
3
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
4 Command-line parsing module that uses a syntax similar to that of GNU *getopt*.
6cf2a8c Added README.
Juan Jose Comellas authored
5
6
7 Requirements
8 ------------
9
ca6313c Juan Jose Comellas Clean up documentation and fix typos
authored
10 You should only need a somewhat recent version of Erlang/OTP. The module has
11 been tested with Erlang R13B, R14B and R15B.
6cf2a8c Added README.
Juan Jose Comellas authored
12
a5279f5 Juan Jose Comellas Use rebar from the system path instead of a binary included in the proje...
authored
13 You also need a recent version of [rebar](http://github.com/basho/rebar) in
14 the system path. If you're going to run the unit tests you need the latest
15 version of rebar to make sure that the latest version of *getopt* is being
16 used. rebar already includes a compiled copy of the ``getopt`` module in its
17 own binary file and will give precedence to its own modules over the ones in
18 the project.
19
6cf2a8c Added README.
Juan Jose Comellas authored
20
21 Installation
22 ------------
23
3e83a0e Small formatting change to README.
Juan Jose Comellas authored
24 To compile the module you simply run ``make``.
e9cf4af Renamed some make targets.
Juan Jose Comellas authored
25
3e83a0e Small formatting change to README.
Juan Jose Comellas authored
26 To run the unit tests run ``make test``.
e9cf4af Renamed some make targets.
Juan Jose Comellas authored
27
3e83a0e Small formatting change to README.
Juan Jose Comellas authored
28 To run the example module run ``make example``.
e9cf4af Renamed some make targets.
Juan Jose Comellas authored
29
f539fbb Add support for rebar.
Juan Jose Comellas authored
30 To build the (very) limited documentation run ``make doc``.
6cf2a8c Added README.
Juan Jose Comellas authored
31
32
5a1d192 Updated documentation.
Juan Jose Comellas authored
33 Usage
34 -----
35
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
36 The *getopt* module provides four functions:
5a1d192 Updated documentation.
Juan Jose Comellas authored
37
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
38 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
39 parse([{Name, Short, Long, ArgSpec, Help}], Args :: string() | [string()]) ->
40 {ok, {Options, NonOptionArgs}} | {error, {Reason, Data}}
4695981 Cleaned up README.
Juan Jose Comellas authored
41
f55ef18 Juan Jose Comellas Expose getopt:tokenize/1 and command-line literals
authored
42 tokenize(CmdLine :: string()) -> [string()]
43
08931e2 Juan Jose Comellas Fix README format
authored
44 usage([{Name, Short, Long, ArgSpec, Help}], ProgramName :: string()) -> ok
5a1d192 Updated documentation.
Juan Jose Comellas authored
45
08931e2 Juan Jose Comellas Fix README format
authored
46 usage([{Name, Short, Long, ArgSpec, Help}], ProgramName :: string(),
47 CmdLineTail :: string()) -> ok
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
48
08931e2 Juan Jose Comellas Fix README format
authored
49 usage([{Name, Short, Long, ArgSpec, Help}], ProgramName :: string(),
50 CmdLineTail :: string(), OptionsTail :: [{string(), string}]) -> ok
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
51 ```
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
52
4b03285 Dropped record syntax for the option specifications to simplify use from...
Juan Jose Comellas authored
53 The ``parse/2`` function receives a list of tuples with the command line option
54 specifications. The type specification for the tuple is:
5a1d192 Updated documentation.
Juan Jose Comellas authored
55
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
56 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
57 -type arg_type() :: 'atom' | 'binary' | 'boolean' | 'float' | 'integer' | 'string'.
4b03285 Dropped record syntax for the option specifications to simplify use from...
Juan Jose Comellas authored
58
08931e2 Juan Jose Comellas Fix README format
authored
59 -type arg_value() :: atom() | binary() | boolean() | float() | integer() | string().
4b03285 Dropped record syntax for the option specifications to simplify use from...
Juan Jose Comellas authored
60
08931e2 Juan Jose Comellas Fix README format
authored
61 -type arg_spec() :: arg_type() | {arg_type(), arg_value()} | undefined.
4b03285 Dropped record syntax for the option specifications to simplify use from...
Juan Jose Comellas authored
62
08931e2 Juan Jose Comellas Fix README format
authored
63 -type option_spec() :: {
64 Name :: atom(),
65 Short :: char() | undefined,
66 Long :: string() | undefined,
67 ArgSpec :: arg_spec(),
68 Help :: string() | undefined
69 }.
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
70 ```
5a1d192 Updated documentation.
Juan Jose Comellas authored
71
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
72 The elements of the tuple are:
5a1d192 Updated documentation.
Juan Jose Comellas authored
73
4b03285 Dropped record syntax for the option specifications to simplify use from...
Juan Jose Comellas authored
74 - ``Name``: name of the option.
75 - ``Short``: character for the short option (e.g. $i for -i).
76 - ``Long``: string for the long option (e.g. "info" for --info).
77 - ``ArgSpec``: data type and optional default value the argument will be converted to.
d26cb9d Add support for arguments assigned to options with an equal ('=')
Juan Jose Comellas authored
78 - ``Help``: help message that is shown for the option when ``usage/2`` is called.
5a1d192 Updated documentation.
Juan Jose Comellas authored
79
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
80 e.g.
5a1d192 Updated documentation.
Juan Jose Comellas authored
81
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
82 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
83 {port, $p, "port", {integer, 5432}, "Database server port"}
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
84 ```
5a1d192 Updated documentation.
Juan Jose Comellas authored
85
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
86 The second parameter receives the list of arguments as passed to the ``main/1``
9283bc0 Juan Jose Comellas Add support for repetitions of options with integer arguments
authored
87 function in escripts or the unparsed command line as a string.
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
88
5a1d192 Updated documentation.
Juan Jose Comellas authored
89 If the function is successful parsing the command line arguments it will return
90 a tuple containing the parsed options and the non-option arguments. The options
4b03285 Dropped record syntax for the option specifications to simplify use from...
Juan Jose Comellas authored
91 will be represented by a list of key-value pairs with the ``Name`` of the
5a1d192 Updated documentation.
Juan Jose Comellas authored
92 option as *key* and the argument from the command line as *value*. If the option
4b03285 Dropped record syntax for the option specifications to simplify use from...
Juan Jose Comellas authored
93 doesn't have an argument, only the atom corresponding to its ``Name`` will be
5a1d192 Updated documentation.
Juan Jose Comellas authored
94 added to the list of options. For the example given above we could get something
95 like ``{port, 5432}``. The non-option arguments are just a list of strings with
96 all the arguments that did not have corresponding options.
97
e1f2397 Juan Jose Comellas Make multiple repetitions with implicit arguments more 'intuitive'
authored
98 e.g. Given the following option specifications:
5a1d192 Updated documentation.
Juan Jose Comellas authored
99
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
100 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
101 OptSpecList =
102 [
103 {host, $h, "host", {string, "localhost"}, "Database server host"},
104 {port, $p, "port", integer, "Database server port"},
105 {dbname, undefined, "dbname", {string, "users"}, "Database name"},
106 {xml, $x, undefined, undefined, "Output data in XML"},
107 {verbose, $v, "verbose", integer, "Verbosity level"},
108 {file, undefined, undefined, string, "Output file"}
109 ].
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
110 ```
5a1d192 Updated documentation.
Juan Jose Comellas authored
111
08392f6 The command line arguments can now be passed as string.
Juan Jose Comellas authored
112 And this command line:
5a1d192 Updated documentation.
Juan Jose Comellas authored
113
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
114 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
115 Args = "-h myhost --port=1000 -x myfile.txt -vvv dummy1 dummy2"
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
116 ```
5a1d192 Updated documentation.
Juan Jose Comellas authored
117
08392f6 The command line arguments can now be passed as string.
Juan Jose Comellas authored
118 Which could also be passed in the format the ``main/1`` function receives the arguments in escripts:
5a1d192 Updated documentation.
Juan Jose Comellas authored
119
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
120 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
121 Args = ["-h", "myhost", "--port=1000", "-x", "file.txt", "-vvv", "dummy1", "dummy2"].
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
122 ```
5a1d192 Updated documentation.
Juan Jose Comellas authored
123
08392f6 The command line arguments can now be passed as string.
Juan Jose Comellas authored
124 The call to ``getopt:parse/2``:
5a1d192 Updated documentation.
Juan Jose Comellas authored
125
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
126 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
127 getopt:parse(OptSpecList, Args).
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
128 ```
5a1d192 Updated documentation.
Juan Jose Comellas authored
129
08392f6 The command line arguments can now be passed as string.
Juan Jose Comellas authored
130 Will return:
5a1d192 Updated documentation.
Juan Jose Comellas authored
131
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
132 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
133 {ok,{[{host,"myhost"},
134 {port,1000},
135 xml,
136 {file,"file.txt"},
137 {dbname,"users"},
138 {verbose,3}],
139 ["dummy1","dummy2"]}}
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
140 ```
5a1d192 Updated documentation.
Juan Jose Comellas authored
141
f55ef18 Juan Jose Comellas Expose getopt:tokenize/1 and command-line literals
authored
142 The ``tokenize/1`` function will separate a command line string into
143 tokens, taking into account whether an argument is single or double
ecd03a8 Juan Jose Comellas Fix typo
authored
144 quoted, a character is escaped or if there are environment variables to
f55ef18 Juan Jose Comellas Expose getopt:tokenize/1 and command-line literals
authored
145 be expanded. e.g.:
146
147 ``` erlang
148 getopt:tokenize(" --name John\\ Smith --path \"John's Files\" -u ${USER}").
149 ```
150
151 Will return something like:
152
153 ``` erlang
154 ["--name","John Smith","--path","John's Files","-u","jsmith"]
155 ```
156
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
157 The other functions exported by the ``getopt`` module (``usage/2``, ``usage/3``
158 and ``usage/4``) are used to show the command line syntax for the program.
159 For example, given the above-mentioned option specifications, the call to
160 ``getopt:usage/2``:
161
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
162 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
163 getopt:usage(OptSpecList, "ex1").
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
164 ```
5a1d192 Updated documentation.
Juan Jose Comellas authored
165
c8fc803 Juan Jose Comellas Use the names given in Erlang to the stdio file descriptors (stdout; std...
authored
166 Will show (on *standard_error*):
5a1d192 Updated documentation.
Juan Jose Comellas authored
167
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
168 Usage: ex1 [-h <host>] [-p <port>] [--dbname <dbname>] [-x] [-v] <file>
5a1d192 Updated documentation.
Juan Jose Comellas authored
169
170 -h, --host Database server host
171 -p, --port Database server port
172 --dbname Database name
173 -x Output data in XML
9283bc0 Juan Jose Comellas Add support for repetitions of options with integer arguments
authored
174 -v Verbosity level
5a1d192 Updated documentation.
Juan Jose Comellas authored
175 <file> Output file
176
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
177 This call to ``getopt:usage/3`` will add a string after the usage command line:
178
08931e2 Juan Jose Comellas Fix README format
authored
179 ``` erlang
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
180 getopt:usage(OptSpecList, "ex1", "[var=value ...] [command ...]").
08931e2 Juan Jose Comellas Fix README format
authored
181 ```
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
182
c8fc803 Juan Jose Comellas Use the names given in Erlang to the stdio file descriptors (stdout; std...
authored
183 Will show (on *standard_error*):
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
184
185 Usage: ex1 [-h <host>] [-p <port>] [--dbname <dbname>] [-x] [-v <verbose>] <file> [var=value ...] [command ...]
9283bc0 Juan Jose Comellas Add support for repetitions of options with integer arguments
authored
186
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
187 -h, --host Database server host
188 -p, --port Database server port
189 --dbname Database name
190 -x Output data in XML
9283bc0 Juan Jose Comellas Add support for repetitions of options with integer arguments
authored
191 -v, --verbose Verbosity level
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
192 <file> Output file
193
194 Whereas this call to ``getopt:usage/3`` will also add some lines to the options
195 help text:
196
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
197 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
198 getopt:usage(OptSpecList, "ex1", "[var=value ...] [command ...]",
199 [{"var=value", "Variables that will affect the execution (e.g. debug=1)"},
200 {"command", "Commands that will be executed (e.g. count)"}]).
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
201 ```
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
202
c8fc803 Juan Jose Comellas Use the names given in Erlang to the stdio file descriptors (stdout; std...
authored
203 Will show (on *standard_error*):
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
204
205 Usage: ex1 [-h <host>] [-p <port>] [--dbname <dbname>] [-x] [-v <verbose>] <file> [var=value ...] [command ...]
9283bc0 Juan Jose Comellas Add support for repetitions of options with integer arguments
authored
206
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
207 -h, --host Database server host
208 -p, --port Database server port
209 --dbname Database name
210 -x Output data in XML
9283bc0 Juan Jose Comellas Add support for repetitions of options with integer arguments
authored
211 -v, --verbose Verbosity level
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
212 <file> Output file
213 var=value Variables that will affect the execution (e.g. debug=1)
214 command Commands that will be executed (e.g. count)
215
216
217 Command-line Syntax
218 -------------------
219
220 The syntax supported by the ``getopt`` module is very similar to that followed
221 by GNU programs, which is described [here](http://www.gnu.org/s/libc/manual/html_node/Argument-Syntax.html).
5a1d192 Updated documentation.
Juan Jose Comellas authored
222
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
223 Options can have both short (single character) and long (string) option names.
224
225 A short option can have the following syntax:
226
227 -a Single option 'a', no argument or implicit boolean argument
228 -a foo Single option 'a', argument "foo"
229 -afoo Single option 'a', argument "foo"
230 -abc Multiple options: 'a'; 'b'; 'c'
231 -bcafoo Multiple options: 'b'; 'c'; 'a' with argument "foo"
e1f2397 Juan Jose Comellas Make multiple repetitions with implicit arguments more 'intuitive'
authored
232 -aaa Multiple repetitions of option 'a'
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
233
234 A long option can have the following syntax:
235
236 --foo Single option 'foo', no argument
237 --foo=bar Single option 'foo', argument "bar"
238 --foo bar Single option 'foo', argument "bar"
239
e1f2397 Juan Jose Comellas Make multiple repetitions with implicit arguments more 'intuitive'
authored
240
241 Argument Types
242 --------------
243
244 The arguments allowed for options are: *atom*; *binary*; *boolean*; *float*; *integer*; *string*.
245 The ``getopt`` module checks every argument to see if it can be converted to its
246 correct type.
247
248 In the case of boolean arguments, the following values (in lower or
249 upper case) are considered ``true``: *true*; *t*; *yes*; *y*; *on*; *enabled*; *1*.
250 These ones are considered ``false``: *false*; *f*; *no*; *n*; *off*; *disabled*; *0*.
251
252 Numeric arguments can only be negative when passed as part of an assignment expression.
253
254 e.g. ``--increment=-100`` is a valid expression; whereas ``--increment -100`` is invalid
255
256
257 Implicit Arguments
258 ------------------
259
260 The arguments for options with the *boolean* and *integer* data types can sometimes
ca6313c Juan Jose Comellas Clean up documentation and fix typos
authored
261 be omitted. In those cases the value assigned to the option is *true* for *boolean*
e1f2397 Juan Jose Comellas Make multiple repetitions with implicit arguments more 'intuitive'
authored
262 arguments and *1* for integer arguments.
263
264
265 Multiple Repetitions
266 --------------------
267
268 An option can be repeated several times, in which case there will be multiple
269 appearances of the option in the resulting list. The only exceptions are short
270 options with integer arguments. In that particular case, each appearance of
271 the short option within a single command line argument will increment the
272 number that will be returned for that specific option.
273
274 e.g. Given an option specification list with the following format:
275
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
276 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
277 OptSpecList =
278 [
279 {define, $D, "define", string, "Define a variable"},
280 {verbose, $v, "verbose", integer, "Verbosity level"}
281 ].
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
282 ```
e1f2397 Juan Jose Comellas Make multiple repetitions with implicit arguments more 'intuitive'
authored
283
284 The following invocation:
285
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
286 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
287 getopt:parse(OptSpecList, "-DFOO -DVAR1=VAL1 -DBAR --verbose --verbose=3 -v -vvvv dummy").
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
288 ```
e1f2397 Juan Jose Comellas Make multiple repetitions with implicit arguments more 'intuitive'
authored
289
290 would return:
291
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
292 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
293 {ok,{[{define,"FOO"}, {define,"VAR1=VAL1"}, {define,"BAR"},
294 {verbose,1}, {verbose,3}, {verbose,1}, {verbose,4}],
295 ["dummy"]}}
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
296 ```
e1f2397 Juan Jose Comellas Make multiple repetitions with implicit arguments more 'intuitive'
authored
297
298
299 Positional Options
300 ------------------
301
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
302 We can also have options with neither short nor long option names. In this case,
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
303 the options will be taken according to their position in the option specification
304 list passed to ``getopt:/parse2``.
305
306 For example, with the following option specifications:
307
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
308 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
309 OptSpecList =
310 [
311 {xml, $x, "xml", undefined, "Output data as XML"},
312 {dbname, undefined, undefined, string, "Database name"},
313 {output_file, undefined, undefined, string, "File where the data will be saved to"}
314 ].
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
315 ```
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
316
ca6313c Juan Jose Comellas Clean up documentation and fix typos
authored
317 This call to ``getopt:parse/2``:
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
318
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
319 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
320 getopt:parse(OptSpecList, "-x mydb file.out dummy dummy").
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
321 ```
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
322
323 Will return:
6cf2a8c Added README.
Juan Jose Comellas authored
324
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
325 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
326 {ok,{[xml,{dbname,"mydb"},{output_file,"file.out"}],
327 ["dummy","dummy"]}}
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
328 ```
61e4792 Juan Jose Comellas Clean up documentation
authored
329
330
331 Option Terminators
332 ------------------
333
334 The string ``--`` is considered an option terminator. This means that all the
335 command-line arguments after it are considered non-option arguments and will be
336 returned without being evaluated even if they follow the *getopt* syntax.
337
338 e.g. This invocation using the first option specification list in the document:
339
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
340 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
341 getopt:parse(OptSpecList, "-h myhost -p 1000 -- --dbname mydb dummy").
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
342 ```
61e4792 Juan Jose Comellas Clean up documentation
authored
343
344 will return:
345
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
346 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
347 {ok,{[{host,"myhost"}, {port,1000},{dbname,"users"}],
348 ["--dbname","mydb","dummy"]}}
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
349 ```
61e4792 Juan Jose Comellas Clean up documentation
authored
350
351 Notice that the *dbname* option was assigned the value ``users`` instead of ``mydb``.
a5279f5 Juan Jose Comellas Use rebar from the system path instead of a binary included in the proje...
authored
352 This happens because the option terminator prevented *getopt* from evaluating it
61e4792 Juan Jose Comellas Clean up documentation
authored
353 and the default value was assigned to it.
354
355
356 Non-option Arguments
357 --------------------
358
359 The single ``-`` character is always considered as a non-option argument.
360
361 e.g. This invocation using the specification list from the previous example:
362
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
363 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
364 getopt:parse(OptSpecList, "-h myhost -p 1000 - --dbname mydb dummy").
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
365 ```
61e4792 Juan Jose Comellas Clean up documentation
authored
366
367 will return:
b2e8bcd Modify module to make it GNU getopt compliant.
Juan Jose Comellas authored
368
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
369 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
370 {ok,{[{host,"myhost"}, {port,1000}, {dbname,"mydb"}],
371 ["-","dummy"]}}
5807849 Juan Jose Comellas Add syntax highlighting for Erlang
authored
372 ```
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
373
374
375 Arguments with embedded whitespace
376 ----------------------------------
377
378 Arguments that have embedded whitespace have to be quoted with either
379 single or double quotes to be considered as a single
380 argument.
381
382
383 e.g. Given an option specification list with the following format:
384
385 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
386 OptSpecList =
387 [
388 {define, $D, "define", string, "Define a variable"},
389 {user, $u, "user", string, "User name"}
390 ].
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
391 ```
392
393 The following invocation:
394
395 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
396 getopt:parse(OptSpecList,
397 "-D'FOO=VAR 123' --define \"VAR WITH SPACES\" -u\"my user name\"").
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
398 ```
399
400 would return:
401
402 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
403 {ok,{[{define,"FOO=VAR 123"},
404 {define,"VAR WITH SPACES"},
405 {user,"my user name"}],
406 []}}
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
407 ```
408
409 When parsing a command line with unclosed quotes the last argument
410 will be a single string starting at the position where the last quote
411 was entered.
412
413 e.g. The following invocation:
414
415 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
416 getopt:parse(OptSpecList, "--user ' my user ' \"argument with unclosed quotes").
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
417 ```
418
419 would return:
420
421 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
422 {ok,{[{user," my user "}],
423 ["argument with unclosed quotes"]}}
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
424 ```
425
426
427 Environment variable expansion
428 ------------------------------
429
430 `getopt:parse/2` will expand environment variables when used with a command
431 line that is passed as a single string. The formats that are supported
432 for environment variable expansion are:
433
08931e2 Juan Jose Comellas Fix README format
authored
434 - $VAR (simple Unix/bash format)
435 - ${VAR} (full Unix/bash format)
436 - %VAR% (Windows format)
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
437
438 If a variable is not present in the environment it will not be
439 expanded. Variables can be expanded within double-quoted and free
440 arguments. *getopt* will not expand environment variables within
441 single-quoted arguments.
442
443 e.g. Given the following option specification list:
444
445 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
446 OptSpecList =
447 [
448 {path, $p, "path", string, "File path"}
449 ].
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
450 ```
451
452 The following invocation:
453
454 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
455 getopt:parse(OptSpecList, "--path ${PATH} $NONEXISTENT_DUMMY_VAR").
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
456 ```
457
458 would return (depending on the value of your PATH variable) something like:
459
460 ``` erlang
08931e2 Juan Jose Comellas Fix README format
authored
461 {ok,{[{path, "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"}],
462 ["$NONEXISTENT_DUMMY_VAR"]}}
1a01b82 Juan Jose Comellas Fix #15: add command-line tokenizer with support for quoted arguments
authored
463 ```
464
465 Currently, *getopt* does not perform wildcard expansion of file paths.
f55ef18 Juan Jose Comellas Expose getopt:tokenize/1 and command-line literals
authored
466
467
468 Escaping arguments
469 ==================
470
471 Any character can be escaped by prepending the \ (backslash) character
472 to it.
473
474 e.g.
475
476 ``` erlang
477 getopt:parse(OptSpecList, "--path /john\\'s\\ files dummy").
478 ```
479
480 Will return:
481
482 ``` erlang
483 {ok,{[{path,"/john's files"}],["dummy"]}}
484 ```
Something went wrong with that request. Please try again.