summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDaniel Kolesa <d.kolesa@samsung.com>2014-12-17 17:09:47 +0000
committerDaniel Kolesa <d.kolesa@samsung.com>2014-12-17 17:09:47 +0000
commit110e6c5abb11b33b2e6e3b95eb33d54b9327e67c (patch)
tree09aee626907e4e1130a144d397131419a6a9705c
parent208ad62d3cb184688f10198ce42c35cbd3489d90 (diff)
elua: document getopt.lua
-rw-r--r--src/scripts/elua/modules/getopt.lua205
1 files changed, 204 insertions, 1 deletions
diff --git a/src/scripts/elua/modules/getopt.lua b/src/scripts/elua/modules/getopt.lua
index 6ac5be83c3..ef16a8bd22 100644
--- a/src/scripts/elua/modules/getopt.lua
+++ b/src/scripts/elua/modules/getopt.lua
@@ -1,4 +1,34 @@
1-- Elua getopt module 1--[[ getopt.lua: An argument parsing library for Lua 5.1 and later.
2
3 This module is provided as a self-contained implementation with builtin
4 documentation.
5
6 TODO:
7 - arguments that can only be specified once (for now you can check
8 that manually by going over array values of opts)
9 - i18n support
10 - support for desc callback failures
11
12 Copyright (c) 2014 Daniel "q66" Kolesa <quaker66@gmail.com>
13
14 Permission is hereby granted, free of charge, to any person obtaining a
15 copy of this software and associated documentation files (the "Software"),
16 to deal in the Software without restriction, including without limitation
17 the rights to use, copy, modify, merge, publish, distribute, sublicense,
18 and/or sell copies of the Software, and to permit persons to whom the
19 Software is furnished to do so, subject to the following conditions:
20
21 The above copyright notice and this permission notice shall be included in
22 all copies or substantial portions of the Software.
23
24 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
25 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
26 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
27 THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
28 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
29 FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
30 DEALINGS IN THE SOFTWARE.
31]]
2 32
3local M = {} 33local M = {}
4 34
@@ -125,6 +155,118 @@ local getopt_u = function(parser)
125 return opts, args 155 return opts, args
126end 156end
127 157
158--[[
159 Given a parser definition, parse the arguments and return all optional
160 arguments, all positional arguments and the parser itself.
161
162 It takes exactly one argument, a parser.
163
164 The parser is a dictionary. It can contain these fields:
165 - usage - a usage string.
166 - prog - a program name.
167 - error_cb - a callback that is called when parsing fails.
168 - done_cb - a callback that is called when it's done parsing.
169 - args - the arguments.
170 - descs - argument descriptions.
171
172 In case of errors, this function returns nil and an error message.
173 You can also handle any error from the error callback of course.
174
175 Usage string is an arbitrary string that can contain a sequence "%prog".
176 This sequence is replaced with program name.
177
178 Program name can be explicitly specified here. If it's not, it's retrieved
179 from "args" as zeroth index. If that is nil, "program" is used.
180
181 Error callback is called on errors right before this function returns. It
182 returns no values. It takes the parser and an error message as arguments.
183
184 Done callack is called on success right before this function returns. It
185 takes the parser, optionala rguments and positional arguments.
186
187 Arguments ("args") is an array with zeroth index optionally specifying
188 program name. It contains strings, similarly to "argv" in other languages.
189
190 Descriptions (descs) is an array of tables, each table being an argument
191 description.
192
193 -- RETURN VALUES --
194
195 --- OPTIONAL ARGS ---
196
197 The returned optional arguments is a mixed table. It contains mappings
198 from argument names (without prefix) to values. The argument name here
199 is in this order: alias, short name, long name. The meaning of aliases
200 is described below. This also means that any given argument has one key
201 only. If a value is not given (optional or doesn't take it) it's the
202 boolean value "true" instead. If it is given, it's either the string
203 value or whatever a callback returns (see below).
204
205 It also contains array elements as the order of given arguments goes.
206 Those array elements have this layout:
207
208 { optn, short = shortn, long = longn, alias = aliasn, val = stringval, ... }
209
210 "optn" refers to the same name as above (in order alias, short, long).
211 "shortn" refers to the short name given in the description. "longn"
212 refers to the long name given in the description. "alias" refers to
213 the optional alias. "val" is the string value that was given, if given.
214 This is then followed by zero or more values which are return values
215 of either option callback (see below) or the string value or nothing.
216
217 --- POSITIONAL ARGS ---
218
219 The returned positional arguments is a simple array of strings.
220
221 -- DESCRIPTIONS --
222
223 The most important part of the parser is descriptions. It describes
224 what kind of arguments can be given and also describes categories
225 for the help listing.
226
227 A description is represented by a table. The table has this layout:
228
229 { shortn, longn, optional, help = helpmsg, metavar = metavar,
230 alias = alias, callback = retcb, list = list
231 }
232
233 "shortn" refers to the short name. For example if you want your argument
234 to be specifeable as "-x", you use "x". "longn" here refers to the long
235 name. For "--help", it's "help".
236
237 "optional" refers to whether it is required to specify value of the
238 argument. The boolean value "true" means that a value is always needed.
239 The value "false" means that the value can never be given.
240 The value "nil" means that the value is optional.
241
242 "help" refers to the description of the parameter in help listing.
243 The field "metavar" specifies the string under which the value field
244 will be displayed in help listing (see the documentation for "help").
245
246 The field "alias" can be used to specify an alias under which the
247 value/argument will be known in the returned optional arguments (i.e.
248 opts[alias]). It's fully optional, see above in "optional args".
249
250 The field "callback" can be used to specify a function that takes the
251 description, the parser and the string value and returns one or more
252 values. Those values will then be present in optional args. When multiple
253 values are returned from such callback, the mapping opts[n] will get you
254 an array of these values.
255
256 The field "list" can be used to specify a value into which values will
257 be appended. When you pass such parameter to your application multiple
258 times, the list will contain all the values provided. The mapping opts[n]
259 will refer to the list rather than the last value given like without list.
260
261 A description can also be used to specify a category, purely for help
262 listing purposes:
263
264 { category = "catname", alias = alias }
265
266 The alias here refers to a name by which the category can be referred
267 to when printing help. Useful when your category name is long and contains
268 spaces and you want a simple "--help=mycat".
269]]
128M.parse = function(parser) 270M.parse = function(parser)
129 local ret, opts, args = pcall(getopt_u, parser) 271 local ret, opts, args = pcall(getopt_u, parser)
130 if not ret then 272 if not ret then
@@ -263,6 +405,62 @@ local help = function(parser, f, category)
263 f:write(table.concat(buf)) 405 f:write(table.concat(buf))
264end 406end
265 407
408--[[
409 Given a parser, print help. The parser is the very same parser as given
410 to a normal parsing function.
411
412 Arguments:
413 - parser - the parser.
414 - category - optional, allows you to specify a category to print,
415 in which case only the given category will print (normally all
416 categories will print).
417 - f - optional file stream, defaults to io.stderr.
418
419 Keep in mind that if the second argument is given and it's not a string,
420 it's considered to be the file stream (without category being specified).
421
422 The help uses this format:
423
424 --------------
425
426 <USAGE STRING>
427
428 <HEADER>
429
430 The following options are supported:
431
432 <CATEGORYNAME>:
433 -x, --long Description for no argument.
434 -h[?<METAVAR>], --help=[?<METAVAR>] Description for optional argument.
435 -f<METAVAR>, --foo=<METAVAR> Description for mandatory argument.
436
437 <ANOTHERCATEGORYNAME>:
438 <MOREARGS>
439
440 <FOOTER>
441
442 --------------
443
444 The usage string can be either custom (specified within the parser) or
445 default, which is "Usage: <progname> [OPTIONS]" where "<progname>" is
446 replaced by the program name (either specified in the parser explicitly
447 or zeroth argument in the given args or "program" as a fallback).
448
449 The header is printed only when given as part of the parser.
450
451 The "The following optins are supported:" line is only printed when there
452 are options to print.
453
454 Same goes for the footer as for the header.
455
456 A metavar can be specified explicitly as part of the parameter description
457 in the parser. If not specified, it will check whether a "long" option is
458 given; if it is, it will use an uppercase version of it (for example a
459 default metavar for "--help" would be "HELP"). If it's not, it will
460 fallback to simply "VAL".
461
462 Please refer to parser documentation for more information.
463]]
266M.help = function(parser, category, f) 464M.help = function(parser, category, f)
267 if category and type(category) ~= "string" then 465 if category and type(category) ~= "string" then
268 f, category = category, f 466 f, category = category, f
@@ -277,14 +475,19 @@ M.help = function(parser, category, f)
277 return true 475 return true
278end 476end
279 477
478-- A utility callback for geometry parsing (--foo=x:y:w:h).
280M.geometry_parse_cb = function(desc, parser, v) 479M.geometry_parse_cb = function(desc, parser, v)
281 return v:match("^(%d+):(%d+):(%d+):(%d+)$") 480 return v:match("^(%d+):(%d+):(%d+):(%d+)$")
282end 481end
283 482
483-- A utility callback for size parsing (--foo=WxH).
284M.size_parse_cb = function(desc, parser, v) 484M.size_parse_cb = function(desc, parser, v)
285 return v:match("^(%d+)x(%d+)$") 485 return v:match("^(%d+)x(%d+)$")
286end 486end
287 487
488-- A utility callback generator for help. Returns a utility callback when
489-- called with file stream as an argument (optional, defaults to stderr).
490-- For help args that take a value, the value will be used as a category name.
288M.help_cb = function(fstream) 491M.help_cb = function(fstream)
289 return function(desc, parser, v) 492 return function(desc, parser, v)
290 M.help(parser, v, fstream) 493 M.help(parser, v, fstream)