From 99cdddbc9de3f73325671aef5c7f6a6ae70b8f9c Mon Sep 17 00:00:00 2001 From: Peter Melnichenko Date: Thu, 12 Apr 2018 14:02:37 +0300 Subject: [PATCH] Update documentation [ci skip] --- docsrc/arguments.rst | 8 +- docsrc/callbacks.rst | 62 ++++++---- docsrc/commands.rst | 22 ++-- docsrc/defaults.rst | 25 ++-- docsrc/index.rst | 1 + docsrc/messages.rst | 266 +++++++++++++++++++++++++++++++++++++++++++ docsrc/misc.rst | 120 +++++++------------ docsrc/mutexes.rst | 24 +++- docsrc/options.rst | 14 +-- docsrc/parsers.rst | 19 ++-- 10 files changed, 417 insertions(+), 144 deletions(-) create mode 100644 docsrc/messages.rst diff --git a/docsrc/arguments.rst b/docsrc/arguments.rst index 7d8462c..02d65ef 100644 --- a/docsrc/arguments.rst +++ b/docsrc/arguments.rst @@ -3,12 +3,14 @@ Adding and configuring arguments Positional arguments can be added using ``:argument(name, description, default, convert, args)`` method. It returns an Argument instance, which can be configured in the same way as Parsers. The ``name`` property is required. +This and the following examples show contents of the result table returned by `parser:parse()` when the script is executed with given command-line arguments. + .. code-block:: lua :linenos: parser:argument "input" -:: +.. code-block:: none $ lua script.lua foo @@ -46,7 +48,7 @@ If more than one argument can be consumed, a table is used to store the data. parser:argument("optional", "An optional argument.") :args "?" -:: +.. code-block:: none $ lua script.lua foo bar @@ -56,7 +58,7 @@ If more than one argument can be consumed, a table is used to store the data. pair = {"foo", "bar"} } -:: +.. code-block:: none $ lua script.lua foo bar baz diff --git a/docsrc/callbacks.rst b/docsrc/callbacks.rst index 9b37984..d618483 100644 --- a/docsrc/callbacks.rst +++ b/docsrc/callbacks.rst @@ -14,7 +14,7 @@ argparse can perform automatic validation and conversion on arguments. If ``conv parser:option "-t --times" :convert(tonumber) -:: +.. code-block:: none $ lua script.lua foo.txt -t5 @@ -25,30 +25,52 @@ argparse can perform automatic validation and conversion on arguments. If ``conv times = 5 } -:: +.. code-block:: none $ lua script.lua nonexistent.txt -:: +.. code-block:: none Usage: script.lua [-t ] [-h] Error: nonexistent.txt: No such file or directory -:: +.. code-block:: none $ lua script.lua foo.txt --times=many -:: +.. code-block:: none Usage: script.lua [-t ] [-h] Error: malformed argument 'many' +If ``convert`` property of an element is an array of functions, they will be used as converters for corresponding arguments +in case the element accepts multiple arguments. + +.. code-block:: lua + :linenos: + + parser:option "--line-style" + :args(2) + :convert {string.lower, tonumber} + +.. code-block:: none + + $ lua script.lua --line-style DASHED 1.5 + +.. code-block:: lua + + { + line_style = {"dashed", 1.5} + } + + Table converters ^^^^^^^^^^^^^^^^ -If convert property of an element is a table, arguments passed to it will be used as keys. If a key is missing, an error is raised. +If convert property of an element is a table and doesn't have functions in array part, +arguments passed to it will be used as keys. If a key is missing, an error is raised. .. code-block:: lua :linenos: @@ -59,7 +81,7 @@ If convert property of an element is a table, arguments passed to it will be use bar = "Something bar-related" } -:: +.. code-block:: none $ lua script.lua bar @@ -69,11 +91,11 @@ If convert property of an element is a table, arguments passed to it will be use choice = "Something bar-related" } -:: +.. code-block:: none $ lua script.lua baz -:: +.. code-block:: none Usage: script.lua [-h] @@ -104,11 +126,11 @@ Initial value to be stored at target index in the result table can be set using end end):init({"foo", "bar"}) - parser:flag("--no-exceptions"):action(function() + parser:flag("--no-exceptions"):action(function(args) args.exceptions = {} end) -:: +.. code-block:: none $ lua script.lua --exceptions x y --exceptions z t @@ -125,7 +147,7 @@ Initial value to be stored at target index in the result table can be set using } } -:: +.. code-block:: none $ lua script.lua --exceptions x y --no-exceptions @@ -145,11 +167,11 @@ Actions can also be used when a flag needs to print some message and exit withou os.exit(0) end) -:: +.. code-block:: none $ lua script.lua -v -:: +.. code-block:: none script v1.0.0 @@ -179,7 +201,7 @@ Examples using ``store_false`` and ``concat`` actions: parser:flag("--rain", "Enable rain", false) parser:option("--exceptions"):args("*"):action("concat"):init({"foo", "bar"}) -:: +.. code-block:: none $ lua script.lua @@ -189,7 +211,7 @@ Examples using ``store_false`` and ``concat`` actions: rain = false } -:: +.. code-block:: none $ lua script.lua --candy @@ -200,7 +222,7 @@ Examples using ``store_false`` and ``concat`` actions: rain = false } -:: +.. code-block:: none $ lua script.lua --no-candy --rain @@ -211,7 +233,7 @@ Examples using ``store_false`` and ``concat`` actions: rain = true } -:: +.. code-block:: none $ lua script.lua --exceptions x y --exceptions z t @@ -246,11 +268,11 @@ Actions for parsers and commands are simply callbacks invoked after parsing, wit print("Callbacks are fun!") end) -:: +.. code-block:: none $ lua script.lua install -:: +.. code-block:: none Running install Callbacks are fun! diff --git a/docsrc/commands.rst b/docsrc/commands.rst index 91f1a38..acbf479 100644 --- a/docsrc/commands.rst +++ b/docsrc/commands.rst @@ -12,7 +12,7 @@ Commands can be added using ``:command(name, description, epilog)`` method. Just If a command it used, ``true`` is stored in the corresponding field of the result table. -:: +.. code-block:: none $ lua script.lua install @@ -24,11 +24,11 @@ If a command it used, ``true`` is stored in the corresponding field of the resul A typo will result in an appropriate error message. -:: +.. code-block:: none $ lua script.lua instal -:: +.. code-block:: none Usage: script.lua [-h] ... @@ -47,7 +47,7 @@ Use ``command_target`` property of the parser to store the name of used command parser:command("install") parser:command("remove") -:: +.. code-block:: none $ lua script.lua install @@ -70,7 +70,7 @@ The Command class is a subclass of the Parser class, so all the Parser's methods install:argument "rock" install:option "-f --from" -:: +.. code-block:: none $ lua script.lua install foo --from=bar @@ -85,21 +85,21 @@ The Command class is a subclass of the Parser class, so all the Parser's methods Commands have their own usage and help messages. -:: +.. code-block:: none $ lua script.lua install -:: +.. code-block:: none Usage: script.lua install [-f ] [-h] Error: too few arguments -:: +.. code-block:: none $ lua script.lua install --help -:: +.. code-block:: none Usage: script.lua install [-f ] [-h] @@ -122,11 +122,11 @@ By default, if a parser has commands, using one of them is obligatory. local parser = argparse() parser:command "install" -:: +.. code-block:: none $ lua script.lua -:: +.. code-block:: none Usage: script.lua [-h] ... diff --git a/docsrc/defaults.rst b/docsrc/defaults.rst index c01ac78..64bfb13 100644 --- a/docsrc/defaults.rst +++ b/docsrc/defaults.rst @@ -12,7 +12,7 @@ For elements such as arguments and options, if ``default`` property is set to a :description "Output file." :default "a.out" -:: +.. code-block:: none $ lua script.lua @@ -24,11 +24,11 @@ For elements such as arguments and options, if ``default`` property is set to a The existence of a default value is reflected in help message, unless ``show_default`` property is set to ``false``. -:: +.. code-block:: none $ lua script.lua --help -:: +.. code-block:: none Usage: script.lua [-o ] [-h] @@ -39,11 +39,11 @@ The existence of a default value is reflected in help message, unless ``show_def Note that invocation without required arguments is still an error. -:: +.. code-block:: none $ lua script.lua -o -:: +.. code-block:: none Usage: script.lua [-o ] [-h] @@ -54,7 +54,8 @@ Default mode ``defmode`` property regulates how argparse should use the default value of an element. -If ``defmode`` contains ``u`` (for unused), the default value will be automatically passed to the element if it was not invoked at all. This is the default behavior. +By default, or if ``defmode`` contains ``u`` (for unused), the default value will be automatically passed to the element if it was not invoked at all. +It will be passed minimal required of times, so that if the element is allowed to consume no arguments (e.g. using ``:args "?"``), the default value is ignored. If ``defmode`` contains ``a`` (for argument), the default value will be automatically passed to the element if not enough arguments were passed, or not enough invocations were made. @@ -69,11 +70,11 @@ Consider the difference: :default "password" :defmode "arg" -:: +.. code-block:: none $ lua script.lua -h -:: +.. code-block:: none Usage: script.lua [-o ] [-p [

]] [-h] @@ -82,7 +83,7 @@ Consider the difference: -p [

] default: password -h, --help Show this help message and exit. -:: +.. code-block:: none $ lua script.lua @@ -92,7 +93,7 @@ Consider the difference: o = "a.out" } -:: +.. code-block:: none $ lua script.lua -p @@ -104,11 +105,11 @@ Consider the difference: p = "password" } -:: +.. code-block:: none $ lua script.lua -o -:: +.. code-block:: none Usage: script.lua [-o ] [-p [

]] [-h] diff --git a/docsrc/index.rst b/docsrc/index.rst index 458cc48..0e8c6c0 100644 --- a/docsrc/index.rst +++ b/docsrc/index.rst @@ -12,6 +12,7 @@ Contents: commands defaults callbacks + messages misc This is a tutorial for `argparse `_, a feature-rich command line parser for Lua. diff --git a/docsrc/messages.rst b/docsrc/messages.rst new file mode 100644 index 0000000..6804e18 --- /dev/null +++ b/docsrc/messages.rst @@ -0,0 +1,266 @@ +Configuring help and usage messages +=================================== + +The usage and help messages of parsers and commands can be generated on demand using ``:get_usage()`` and ``:get_help()`` methods, and overridden using ``help`` and ``usage`` properties. +When using the autogenerated usage and help messages, there are several ways to adjust them. + +Hiding arguments, options, and commands from messages +----------------------------------------------------- + +If ``hidden`` property for an argument, an option or a command is set to ``true``, +it is not included into help and usage messages, but otherwise works normally. + +.. code-block:: lua + :linenos: + + parser:option "--normal-option" + parser:option "--deprecated-option" + :hidden(true) + +.. code-block:: none + + $ lua script.lua --help + +.. code-block:: none + + Usage: script.lua [--normal-option ] [-h] + + Options: + --normal-option + -h, --help Show this help message and exit. + +.. code-block:: none + + $ lua script.lua --deprecated-option value + +.. code-block:: lua + + { + deprecated_option = "value" + } + + +Setting argument placeholder +---------------------------- + +For options and arguments, ``argname`` property controls the placeholder for the argument in the usage message. + +.. code-block:: lua + :linenos: + + parser:option "-f" "--from" + :argname "" + +.. code-block:: none + + $ lua script.lua --help + +.. code-block:: none + + Usage: script.lua [-f ] [-h] + + Options: + -f , --from + -h, --help Show this help message and exit. + +``argname`` can be an array of placeholders. + +.. code-block:: lua + :linenos: + + parser:option "--pair" + :args(2) + :argname {"", ""} + +.. code-block:: none + + $ lua script.lua --help + +.. code-block:: none + + Usage: script.lua [--pair ] [-h] + + Options: + --pair + -h, --help Show this help message and exit. + +Grouping elements +----------------- + +``:group(name, ...)`` method of parsers and commands puts passed arguments, options, and commands into +a named group with its own section in the help message. Elements outside any groups are put into a default section. + +.. code-block:: lua + :linenos: + + parser:group("Configuring output format", + parser:flag "-v --verbose", + parser:flag "--use-colors", + parser:option "--encoding" + ) + + parser:group("Configuring processing", + parser:option "--compression-level", + parser:flag "--skip-broken-chunks" + ) + + parser:flag "--version" + :action(function() print("script.lua 1.0.0") os.exit(0) end) + +.. code-block:: none + + $ lua script.lua --help + +.. code-block:: none + + Usage: script.lua [-v] [--use-colors] [--encoding ] + [--compression-level ] + [--skip-broken-chunks] [--version] [-h] + + Configuring output format: + -v, --verbose + --use-colors + --encoding + + Configuring processing: + --compression-level + --skip-broken-chunks + + Other options: + --version + -h, --help Show this help message and exit. + +Help message line wrapping +-------------------------- + +If ``help_max_width`` property of a parser or a command is set, when generating its help message, argparse will automatically +wrap lines, attempting to fit into given number of columns. This includes wrapping lines in parser description and epilog +and descriptions of arguments, options, and commands. + +Line wrapping preserves existing line endings and only splits overly long input lines. +When breaking a long line, it replicates indentation of the line in the continuation lines. +Additionally, if the first non-space token in a line is ``*``, ``+``, or ``-``, the line is considered a list item, +and the continuation lines are aligned with the first word after the list item marker. + +.. code-block:: lua + :linenos: + + parser:help_max_width(80) + + parser:option "-f --foo" + :description("Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor " .. + "incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation " .. + "ullamco laboris nisi ut aliquip ex ea commodo consequat.\n" .. + "The next paragraph is indented:\n" .. + " Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. " .. + "Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.") + + parser:option "-b --bar" + :description("Here is a list:\n".. + "* Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor...\n" .. + "* Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip...\n" .. + "* Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.") + +.. code-block:: none + + $ lua script.lua --help + +.. code-block:: none + + Usage: script.lua [-f ] [-b ] [-h] + + Options: + -f , Lorem ipsum dolor sit amet, consectetur adipiscing + --foo elit, sed do eiusmod tempor incididunt ut labore et + dolore magna aliqua. Ut enim ad minim veniam, quis + nostrud exercitation ullamco laboris nisi ut aliquip ex + ea commodo consequat. + The next paragraph is indented: + Duis aute irure dolor in reprehenderit in voluptate + velit esse cillum dolore eu fugiat nulla pariatur. + Excepteur sint occaecat cupidatat non proident, sunt + in culpa qui officia deserunt mollit anim id est + laborum. + -b , Here is a list: + --bar * Lorem ipsum dolor sit amet, consectetur adipiscing + elit, sed do eiusmod tempor... + * Ut enim ad minim veniam, quis nostrud exercitation + ullamco laboris nisi ut aliquip... + * Duis aute irure dolor in reprehenderit in voluptate + velit esse cillum dolore eu fugiat nulla pariatur. + -h, --help Show this help message and exit. + +``help_max_width`` property is inherited by commands. + +Configuring help and usage message layout +----------------------------------------- + +Several other parser and command properties can be used to tweak help and usage message format. +Like ``help_max_width``, all of them are inherited by commands when set on the parser or a parent command. + +``usage_max_width`` property sets maximum width of the usage string. Default is ``70``. + +``usage_margin`` property sets margin width used when line wrapping long usage strings. Default is ``7``. + +.. code-block:: lua + :linenos: + + parser:usage_max_width(50) + :usage_margin(#"Usage: script.lua ") + + parser:option "--foo" + parser:option "--bar" + parser:option "--baz" + parser:option "--qux" + + print(parser:get_usage()) + +.. code-block:: none + + $ lua script.lua + +.. code-block:: none + + Usage: script.lua [--foo ] [--bar ] + [--baz ] [--qux ] [-h] + +Help message for a group of arguments, options, or commands is organized into two columns, with usage +template on the left side and descriptions on the right side. +``help_usage_margin`` property sets horizontal offset for the first column (``3`` by default). +``help_description_margin`` property sets horizontal offset for the second column (``25`` by default). + +``help_vertical_space`` property sets number of extra empty lines to put between descriptions for different elements +within a group (``0`` by default). + +.. code-block:: lua + :linenos: + + parser:help_usage_margin(2) + :help_description_margin(17) + :help_vertical_space(1) + + parser:option("--foo", "Set foo.") + parser:option("--bar", "Set bar.") + parser:option("--baz", "Set baz.") + parser:option("--qux", "Set qux.") + +.. code-block:: none + + $ lua script.lua --help + +.. code-block:: none + + Usage: script.lua [--foo ] [--bar ] [--baz ] + [--qux ] [-h] + + Options: + + --foo Set foo. + + --bar Set bar. + + --baz Set baz. + + --qux Set qux. + + -h, --help Show this help message and exit. diff --git a/docsrc/misc.rst b/docsrc/misc.rst index 86d77e7..f33fd3d 100644 --- a/docsrc/misc.rst +++ b/docsrc/misc.rst @@ -1,11 +1,6 @@ Miscellaneous ============= -Generating and overwriting help and usage messages --------------------------------------------------- - -The usage and help messages of parsers and commands can be generated on demand using ``:get_usage()`` and ``:get_help()`` methods, and overridden using ``help`` and ``usage`` properties. - Overwriting default help option ------------------------------- @@ -17,61 +12,17 @@ If the property ``add_help`` of a parser is set to ``false``, no help option wil local parser = argparse() :add_help "/?" -:: +.. code-block:: none $ lua script.lua /? -:: +.. code-block:: none Usage: script.lua [/?] Options: /? Show this help message and exit. -Setting argument placeholder ----------------------------- - -For options and arguments, ``argname`` property controls the placeholder for the argument in the usage message. - -.. code-block:: lua - :linenos: - - parser:option "-f" "--from" - :argname "" - -:: - - $ lua script.lua --help - -:: - - Usage: script.lua [-f ] [-h] - - Options: - -f , --from - -h, --help Show this help message and exit. - -``argname`` can be an array of placeholders. - -.. code-block:: lua - :linenos: - - parser:option "--pair" - :args(2) - :argname {"", ""} - -:: - - $ lua script.lua --help - -:: - - Usage: script.lua [--pair ] [-h] - - Options: - --pair - -h, --help Show this help message and exit. - Disabling option handling ------------------------- @@ -86,7 +37,7 @@ When ``handle_options`` property of a parser or a command is set to ``false``, a parser:option "-f" "--foo" :args "*" -:: +.. code-block:: none $ lua script.lua bar -f --foo bar @@ -106,7 +57,7 @@ By default, if an option is invoked too many times, latest invocations overwrite parser:option "-o --output" -:: +.. code-block:: none $ lua script.lua -oFOO -oBAR @@ -124,11 +75,11 @@ Set ``overwrite`` property to ``false`` to prohibit this behavior. parser:option "-o --output" :overwrite(false) -:: +.. code-block:: none $ lua script.lua -oFOO -oBAR -:: +.. code-block:: none Usage: script.lua [-o ] [-h] @@ -168,16 +119,22 @@ Property Type Other properties: -=================== ========================== -Property Type -=================== ========================== -``usage`` String -``help`` String -``require_command`` Boolean -``handle_options`` Boolean -``add_help`` Boolean or string or table -``command_target`` String -=================== ========================== +=========================== ========================== +Property Type +=========================== ========================== +``usage`` String +``help`` String +``require_command`` Boolean +``handle_options`` Boolean +``add_help`` Boolean or string or table +``command_target`` String +``usage_max_width`` Number +``usage_margin`` Number +``help_max_width`` Number +``help_usage_margin`` Number +``help_description_margin`` Number +``help_vertical_space`` Number +=========================== ========================== Command properties ^^^^^^^^^^^^^^^^^^ @@ -194,18 +151,25 @@ Property Type Other properties: -=================== ========================== -Property Type -=================== ========================== -``target`` String -``usage`` String -``help`` String -``require_command`` Boolean -``handle_options`` Boolean -``action`` Function -``add_help`` Boolean or string or table -``command_target`` String -=================== ========================== +=========================== ========================== +Property Type +=========================== ========================== +``target`` String +``usage`` String +``help`` String +``require_command`` Boolean +``handle_options`` Boolean +``action`` Function +``add_help`` Boolean or string or table +``command_target`` String +``hidden`` Boolean +``usage_max_width`` Number +``usage_margin`` Number +``help_max_width`` Number +``help_usage_margin`` Number +``help_description_margin`` Number +``help_vertical_space`` Number +=========================== ========================== Argument properties ^^^^^^^^^^^^^^^^^^^ @@ -233,6 +197,7 @@ Property Type ``argname`` String or table ``action`` Function or string ``init`` Any +``hidden`` Boolean =================== =============== Option and flag properties @@ -263,4 +228,5 @@ Property Type ``argname`` String or table ``action`` Function or string ``init`` Any +``hidden`` Boolean =================== ================== diff --git a/docsrc/mutexes.rst b/docsrc/mutexes.rst index a7b04ad..b4b9363 100644 --- a/docsrc/mutexes.rst +++ b/docsrc/mutexes.rst @@ -1,11 +1,17 @@ Mutually exclusive groups ========================= -A group of options can be marked as mutually exclusive using ``:mutex(option, ...)`` method of the Parser class. +A group of arguments and options can be marked as mutually exclusive using ``:mutex(argument_or_option, ...)`` method of the Parser class. .. code-block:: lua :linenos: + parser:mutex( + parser:argument "input" + :args "?", + parser:flag "--process-stdin" + ) + parser:mutex( parser:flag "-q --quiet", parser:flag "-v --verbose" @@ -13,12 +19,22 @@ A group of options can be marked as mutually exclusive using ``:mutex(option, .. If more than one element of a mutually exclusive group is used, an error is raised. -:: +.. code-block:: none $ lua script.lua -qv -:: +.. code-block:: none - Usage: script.lua ([-q] | [-v]) [-h] + Usage: script.lua ([-q] | [-v]) [-h] ([] | [--process-stdin]) Error: option '-v' can not be used together with option '-q' + +.. code-block:: none + + $ lua script.lua file --process-stdin + +.. code-block:: none + + Usage: script.lua ([-q] | [-v]) [-h] ([] | [--process-stdin]) + + Error: option '--process-stdin' can not be used together with argument 'input' diff --git a/docsrc/options.rst b/docsrc/options.rst index 793714d..bcc7556 100644 --- a/docsrc/options.rst +++ b/docsrc/options.rst @@ -10,7 +10,7 @@ Options can be added using ``:option(name, description, default, convert, args, parser:option "-f" "--from" parser:option "-f --from" -:: +.. code-block:: none $ lua script.lua --from there $ lua script.lua --from=there @@ -45,7 +45,7 @@ Flags are almost identical to options, except that they don't take an argument b parser:flag("-q --quiet") -:: +.. code-block:: none $ lua script.lua -q @@ -73,7 +73,7 @@ Just as arguments, options can be configured to take several command line argume parser:option "--optional" :args "?" -:: +.. code-block:: none $ lua script.lua --pair foo bar @@ -83,7 +83,7 @@ Just as arguments, options can be configured to take several command line argume pair = {"foo", "bar"} } -:: +.. code-block:: none $ lua script.lua --pair foo bar --optional @@ -94,7 +94,7 @@ Just as arguments, options can be configured to take several command line argume optional = {} } -:: +.. code-block:: none $ lua script.lua --optional=baz @@ -118,7 +118,7 @@ For options, it is possible to control how many times they can be used. argparse parser:option("-e --exclude") :count "*" -:: +.. code-block:: none $ lua script.lua -eFOO -eBAR @@ -139,7 +139,7 @@ As a special case, if an option can be used more than once and it consumes no ar :count "0-2" :target "verbosity" -:: +.. code-block:: none $ lua script.lua -vv diff --git a/docsrc/parsers.rst b/docsrc/parsers.rst index e56c3e2..65fc3f0 100644 --- a/docsrc/parsers.rst +++ b/docsrc/parsers.rst @@ -15,26 +15,25 @@ The ``argparse`` module is a function which, when called, creates an instance of Parsing command line arguments ------------------------------ -``:parse([args])`` method of the Parser class returns a table with processed data from the command line or ``args`` array. +``:parse([argv])`` method of the Parser class returns a table with processed data from the command line or ``argv`` array. .. code-block:: lua :linenos: local args = parser:parse() - print(args) -- Assuming print is patched to handle tables nicely. -When executed, this script prints ``{}`` because the parser is empty and no command line arguments were supplied. +After this is executed with ``lua script.lua``, ``args`` is an empty table because the parser is empty and no command line arguments were supplied. Error handling ^^^^^^^^^^^^^^ If the provided command line arguments are not recognized by the parser, it will print an error message and call ``os.exit(1)``. -:: +.. code-block:: none $ lua script.lua foo -:: +.. code-block:: none Usage: script.lua [-h] @@ -49,7 +48,7 @@ An error can raised manually using ``:error()`` method. parser:error("manual argument validation failed") -:: +.. code-block:: none Usage: script.lua [-h] @@ -62,11 +61,11 @@ As the automatically generated usage message states, there is a help option ``-h When a help option is used, parser will print a help message and call ``os.exit(0)``. -:: +.. code-block:: none $ lua script.lua -h -:: +.. code-block:: none Usage: script.lua [-h] @@ -78,11 +77,11 @@ Typo autocorrection When an option is not recognized by the parser, but there is an option with a similar name, a suggestion is automatically added to the error message. -:: +.. code-block:: none $ lua script.lua --hepl -:: +.. code-block:: none Usage: script.lua [-h]