mirrors/argparse
1
0
Fork 0
mirror of https://github.com/TangentFoxy/argparse.git synced 2025-07-28 02:52:20 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add tutorial in sphinx/.rst format

Browse Source
This commit is contained in:
mpeterv
2015-06-20 16:56:31 +03:00
parent b37cdfe552
commit 8dde1f7472
16 changed files with 1246 additions and 1389 deletions
Download Patch File Download Diff File Expand all files Collapse all files

68
docsrc/arguments.rst Normal file
View File

@@ -0,0 +1,68 @@
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.
.. code-block:: lua
:linenos:
parser:argument "input"
::
$ lua script.lua foo
.. code-block:: lua
{
input = "foo"
}
The data passed to the argument is stored in the result table at index ``input`` because it is the argument's name. The index can be changed using ``target`` property.
Setting number of consumed arguments
------------------------------------
``args`` property sets how many command line arguments the argument consumes. Its value is interpreted as follows:
================================================= =============================
Value Interpretation
================================================= =============================
Number ``N`` Exactly ``N`` arguments
String ``A-B``, where ``A`` and ``B`` are numbers From ``A`` to ``B`` arguments
String ``N+``, where ``N`` is a number ``N`` or more arguments
String ``?`` An optional argument
String ``*`` Any number of arguments
String ``+`` At least one argument
================================================= =============================
If more than one argument can be consumed, a table is used to store the data.
.. code-block:: lua
:linenos:
parser:argument("pair", "A pair of arguments.")
:args(2)
parser:argument("optional", "An optional argument.")
:args "?"
::
$ lua script.lua foo bar
.. code-block:: lua
{
pair = {"foo", "bar"}
}
::
$ lua script.lua foo bar baz
.. code-block:: lua
{
pair = {"foo", "bar"},
optional = "baz"
}

104
docsrc/callbacks.rst Normal file
View File

@@ -0,0 +1,104 @@
Callbacks
=========
Converters
----------
argparse can perform automatic validation and conversion on arguments. If ``convert`` property of an element is a function, it will be applied to all the arguments passed to it. The function should return ``nil`` and, optionally, an error message if conversion failed. Standard ``tonumber`` and ``io.open`` functions work exactly like that.
.. code-block:: lua
:linenos:
parser:argument "input"
:convert(io.open)
parser:option "-t --times"
:convert(tonumber)
::
$ lua script.lua foo.txt -t5
.. code-block:: lua
{
input = file_object,
times = 5
}
::
$ lua script.lua nonexistent.txt
::
Usage: script.lua [-t <times>] [-h] <input>
Error: nonexistent.txt: No such file or directory
::
$ lua script.lua foo.txt --times=many
::
Usage: script.lua [-t <times>] [-h] <input>
Error: malformed argument 'many'
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.
.. code-block:: lua
:linenos:
parser:argument "choice"
:convert {
foo = "Something foo-related",
bar = "Something bar-related"
}
::
$ lua script.lua bar
.. code-block:: lua
{
choice = "Something bar-related"
}
::
$ lua script.lua baz
::
Usage: script.lua [-h] <choice>
Error: malformed argument 'baz'
Actions
-------
argparse can trigger a callback when an option or a command is encountered. The callback can be set using ``action`` property. Actions are called regardless of whether the rest of command line arguments are correct.
.. code-block:: lua
:linenos:
parser:argument "required_argument"
parser:flag("-v --version", "Show version info and exit.")
:action(function()
print("script.lua v1.0.0")
os.exit(0)
end)
::
$ lua script.lua -v
::
script.lua v1.0.0

119
docsrc/commands.rst Normal file
View File

@@ -0,0 +1,119 @@
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.
::
$ lua script.lua install
.. code-block:: lua
{
install = true
}
A typo will result in an appropriate error message.
::
$ lua script.lua instal
::
Usage: script.lua [-h] <command> ...
Error: unknown command 'instal'
Did you mean '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"
::
$ lua script.lua install foo --from=bar
.. code-block:: lua
{
install = true,
rock = "foo",
from = "bar"
}
Commands have their own usage and help messages.
::
$ lua script.lua install
::
Usage: script.lua install [-f <from>] [-h] <rock>
Error: too few arguments
::
$ lua script.lua install --help
::
Usage: script.lua install [-f <from>] [-h] <rock>
Arguments:
rock
Options:
-f <from>, --from <from>
-h, --help Show this help message and exit.
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"
::
$ lua script.lua
::
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"

265
docsrc/conf.py Normal file
View File

@@ -0,0 +1,265 @@
# -*- coding: utf-8 -*-
#
# argparse documentation build configuration file, created by
# sphinx-quickstart on Sat Jun 20 14:03:24 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#sys.path.insert(0, os.path.abspath('.'))
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
#needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = []
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
#source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = u'argparse'
copyright = u'2013 - 2015, Peter Melnichenko'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '0.4.0'
# The full version, including alpha/beta/rc tags.
release = '0.4.0'
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
#language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
#today = ''
# Else, today_fmt is used as the format for a strftime call.
#today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = []
# The reST default role (used for this markup: `text`) to use for all
# documents.
#default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
#add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
#add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
#show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
#keep_warnings = False
# -- Options for HTML output ----------------------------------------------
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
if on_rtd:
html_theme = 'default'
else:
import sphinx_rtd_theme
html_theme = 'sphinx_rtd_theme'
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
#html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
#html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
html_title = "argparse 0.4.0 tutorial"
# A shorter title for the navigation bar. Default is the same as html_title.
#html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
#html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = []
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
#html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
#html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
#html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
#html_additional_pages = {}
# If false, no module index is generated.
#html_domain_indices = True
# If false, no index is generated.
#html_use_index = True
# If true, the index is split into individual pages for each letter.
#html_split_index = False
# If true, links to the reST sources are added to the pages.
#html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
#html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
#html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
#html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'argparsetutorial'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
#'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
#'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
#'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'argparse.tex', u'argparse tutorial',
u'Peter Melnichenko', 'manual')
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
#latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
#latex_use_parts = False
# If true, show page references after internal links.
#latex_show_pagerefs = False
# If true, show URL addresses after external links.
#latex_show_urls = False
# Documents to append as an appendix to all manuals.
#latex_appendices = []
# If false, no module index is generated.
#latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'argparse', u'argparse tutorial',
[u'Peter Melnichenko'], 1)
]
# If true, show URL addresses after external links.
#man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'argparse', u'argparse tutorial',
u'Peter Melnichenko', 'argparse', 'Command line parser for Lua.',
'Miscellaneous')
]
# Documents to append as an appendix to all manuals.
#texinfo_appendices = []
# If false, no module index is generated.
#texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
#texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
#texinfo_no_detailmenu = False

115
docsrc/defaults.rst Normal file
View File

@@ -0,0 +1,115 @@
Default values
==============
For elements such as arguments and options, if ``default`` property is set, its value is stored in case the element was not used.
.. code-block:: lua
:linenos:
parser:option("-o --output", "Output file.", "a.out")
-- Equivalent:
parser:option "-o" "--output"
:description "Output file."
:default "a.out"
::
$ lua script.lua
.. code-block:: lua
{
output = "a.out"
}
The existence of a default value is reflected in help message, unless ``show_default`` property is set to ``false``.
::
$ lua script.lua --help
::
Usage: script.lua [-o <output>] [-h]
Options:
-o <output>, --output <output>
Output file. (default: a.out)
-h, --help Show this help message and exit.
Note that invocation without required arguments is still an error.
::
$ lua script.lua -o
::
Usage: script.lua [-o <output>] [-h]
Error: too few arguments
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.
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.
Consider the difference:
.. code-block:: lua
:linenos:
parser:option "-o"
:default "a.out"
parser:option "-p"
:default "password"
:defmode "arg"
::
$ lua script.lua -h
::
Usage: script.lua [-o <o>] [-p [<p>]] [-h]
Options:
-o <o> default: a.out
-p [<p>] default: password
-h, --help Show this help message and exit.
::
$ lua script.lua
.. code-block:: lua
{
o = "a.out"
}
::
$ lua script.lua -p
.. code-block:: lua
{
o = "a.out",
p = "password"
}
::
$ lua script.lua -o
::
Usage: script.lua [-o <o>] [-p [<p>]] [-h]
Error: too few arguments

17
docsrc/index.rst Normal file
View File

@@ -0,0 +1,17 @@
Argparse tutorial
=================
Contents:
.. toctree::
parsers
arguments
options
mutexes
commands
defaults
callbacks
misc
This is a tutorial for `argparse <https://github.com/mpeterv/argparse>`_, a feature-rich command line parser for Lua.

261
docsrc/misc.rst Normal file
View File

@@ -0,0 +1,261 @@
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
-------------------------------
If the property ``add_help`` of a parser is set to ``false``, no help option will be added to it. Otherwise, the value of the field will be used to configure it.
.. code-block:: lua
:linenos:
local parser = argparse()
:add_help "/?"
::
$ lua script.lua /?
::
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 "<server>"
::
$ lua script.lua --help
::
Usage: script.lua [-f <server>] [-h]
Options:
-f <server>, --from <server>
-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 {"<key>", "<value>"}
::
$ lua script.lua --help
::
Usage: script.lua [--pair <key> <value>] [-h]
Options:
--pair <key> <value>
-h, --help Show this help message and exit.
Disabling option handling
-------------------------
When ``handle_options`` property of a parser or a command is set to ``false``, all options will be passed verbatim to the argument list, as if the input included double-hyphens.
.. code-block:: lua
:linenos:
parser:handle_options(false)
parser:argument "input"
:args "*"
parser:option "-f" "--foo"
:args "*"
::
$ lua script.lua bar -f --foo bar
.. code-block:: lua
{
input = {"bar", "-f", "--foo", "bar"}
}
Prohibiting overuse of options
------------------------------
By default, if an option is invoked too many times, latest invocations overwrite the data passed earlier.
.. code-block:: lua
:linenos:
parser:option "-o --output"
::
$ lua script.lua -oFOO -oBAR
.. code-block:: lua
{
output = "BAR"
}
Set ``overwrite`` property to ``false`` to prohibit this behavior.
.. code-block:: lua
:linenos:
parser:option "-o --output"
:overwrite(false)
::
$ lua script.lua -oFOO -oBAR
::
Usage: script.lua [-o <output>] [-h]
Error: option '-o' must be used at most 1 time
Parsing algorithm
-----------------
argparse interprets command line arguments in the following way:
============= ================================================================================================================
Argument Interpretation
============= ================================================================================================================
``foo`` An argument of an option or a positional argument.
``--foo`` An option.
``--foo=bar`` An option and its argument. The option must be able to take arguments.
``-f`` An option.
``-abcdef`` Letters are interpreted as options. If one of them can take an argument, the rest of the string is passed to it.
``--`` The rest of the command line arguments will be interpreted as positional arguments.
============= ================================================================================================================
Property lists
--------------
Parser properties
^^^^^^^^^^^^^^^^^
Properties that can be set as arguments when calling or constructing a parser, in this order:
=============== ======
Property Type
=============== ======
``name`` String
``description`` String
``epilog`` String
=============== ======
Other properties:
=================== ==========================
Property Type
=================== ==========================
``usage`` String
``help`` String
``require_command`` Boolean
``handle_options`` Boolean
``add_help`` Boolean or string or table
=================== ==========================
Command properties
^^^^^^^^^^^^^^^^^^
Properties that can be set as arguments when calling or constructing a command, in this order:
=============== ======
Property Type
=============== ======
``name`` String
``description`` String
``epilog`` String
=============== ======
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
=================== ==========================
Argument properties
^^^^^^^^^^^^^^^^^^^
Properties that can be set as arguments when calling or constructing an argument, in this order:
=============== =================
Property Type
=============== =================
``name`` String
``description`` String
``default`` String
``convert`` Function or table
``args`` Number or string
=============== =================
Other properties:
=================== ===============
Property Type
=================== ===============
``target`` String
``defmode`` String
``show_default`` Boolean
``argname`` String or table
=================== ===============
Option and flag properties
^^^^^^^^^^^^^^^^^^^^^^^^^^
Properties that can be set as arguments when calling or constructing an option or a flag, in this order:
=============== =================
Property Type
=============== =================
``name`` String
``description`` String
``default`` String
``convert`` Function or table
``args`` Number or string
``count`` Number or string
=============== =================
Other properties:
=================== ===============
Property Type
=================== ===============
``target`` String
``defmode`` String
``show_default`` Boolean
``overwrite`` Booleans
``argname`` String or table
``action`` Function
=================== ===============

24
docsrc/mutexes.rst Normal file
View File

@@ -0,0 +1,24 @@
Mutually exclusive groups
=========================
A group of options can be marked as mutually exclusive using ``:mutex(option, ...)`` method of the Parser class.
.. code-block:: lua
:linenos:
parser:mutex(
parser:flag "-q --quiet",
parser:flag "-v --verbose"
)
If more than one element of a mutually exclusive group is used, an error is raised.
::
$ lua script.lua -qv
::
Usage: script.lua ([-q] | [-v]) [-h]
Error: option '-v' can not be used together with option '-q'

150
docsrc/options.rst Normal file
View File

@@ -0,0 +1,150 @@
Adding and configuring options
==============================
Options can be added using ``:option(name, description, default, convert, args, count)`` method. It returns an Option instance, which can be configured in the same way as Parsers. The ``name`` property is required. An option can have several aliases, which can be set as space separated substrings in its name or by continuously setting ``name`` property.
.. code-block:: lua
:linenos:
-- These lines are equivalent:
parser:option "-f" "--from"
parser:option "-f --from"
::
$ lua script.lua --from there
$ lua script.lua --from=there
$ lua script.lua -f there
$ lua script.lua -fthere
.. code-block:: lua
{
from = "there"
}
For an option, default index used to store arguments passed to it is the first "long" alias (an alias starting with two control characters, typically hyphens) or just the first alias, without control characters. Hyphens in the default index are replaced with underscores. In the following table it is assumed that ``local args = parser:parse()`` has been executed.
======================== ==============================
Option's aliases Location of option's arguments
======================== ==============================
``-o`` ``args.o``
``-o`` ``--output`` ``args.output``
``-s`` ``--from-server`` ``args.from_server``
======================== ==============================
As with arguments, the index can be explicitly set using ``target`` property.
Flags
-----
Flags are almost identical to options, except that they don't take an argument by default.
.. code-block:: lua
:linenos:
parser:flag("-q --quiet")
::
$ lua script.lua -q
.. code-block:: lua
{
quiet = true
}
Control characters
------------------
The first characters of all aliases of all options of a parser form the set of control characters, used to distinguish options from arguments. Typically the set only consists of a hyphen.
Setting number of consumed arguments
------------------------------------
Just as arguments, options can be configured to take several command line arguments.
.. code-block:: lua
:linenos:
parser:option "--pair"
:args(2)
parser:option "--optional"
:args "?"
::
$ lua script.lua --pair foo bar
.. code-block:: lua
{
pair = {"foo", "bar"}
}
::
$ lua script.lua --pair foo bar --optional
.. code-block:: lua
{
pair = {"foo", "bar"},
optional = {}
}
::
$ lua script.lua --optional=baz
.. code-block:: lua
{
optional = {"baz"}
}
Note that the data passed to ``optional`` option is stored in an array. That is necessary to distinguish whether the option was invoked without an argument or it was not invoked at all.
Setting number of invocations
-----------------------------
For options, it is possible to control how many times they can be used. argparse uses ``count`` property to set how many times an option can be invoked. The value of the property is interpreted in the same way ``args`` is.
.. code-block:: lua
:linenos:
parser:option("-e --exclude")
:count "*"
::
$ lua script.lua -eFOO -eBAR
.. code-block:: lua
{
exclude = {"FOO", "BAR"}
}
If an option can be used more than once and it can consume more than one argument, the data is stored as an array of invocations, each being an array of arguments.
As a special case, if an option can be used more than once and it consumes no arguments (e.g. it's a flag), than the number of invocations is stored in the associated field of the result table.
.. code-block:: lua
:linenos:
parser:flag("-v --verbose", "Sets verbosity level.")
:count "0-2"
:target "verbosity"
::
$ lua script.lua -vv
.. code-block:: lua
{
verbosity = 2
}

123
docsrc/parsers.rst Normal file
View File

@@ -0,0 +1,123 @@
Creating and using parsers
==========================
The ``argparse`` module is a function which, when called, creates an instance of the Parser class.
.. code-block:: lua
:linenos:
-- script.lua
local argparse = require "argparse"
local parser = argparse()
``parser`` is now an empty parser which does not recognize any command line arguments or options.
Parsing command line arguments
------------------------------
``:parse([args])`` method of the Parser class returns a table with processed data from the command line or ``args`` 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.
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)``.
::
$ lua script.lua foo
::
Usage: script.lua [-h]
Error: too many arguments
If halting the program is undesirable, ``:pparse([args])`` method should be used. It returns boolean flag indicating success of parsing and result or error message.
An error can raised manually using ``:error()`` method.
.. code-block:: lua
:linenos:
parser:error("manual argument validation failed")
::
Usage: script.lua [-h]
Error: manual argument validation failed
Help option
^^^^^^^^^^^
As the automatically generated usage message states, there is a help option ``-h`` added to any parser by default.
When a help option is used, parser will print a help message and call ``os.exit(0)``.
::
$ lua script.lua -h
::
Usage: script.lua [-h]
Options:
-h, --help Show this help message and exit.
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.
::
$ lua script.lua --hepl
::
Usage: script.lua [-h]
Error: unknown option '--hepl'
Did you mean '--help'?
Configuring parsers
-------------------
Parsers have several properties affecting their behavior. For example, ``description`` and ``epilog`` properties set the text to be displayed in the help message after the usage message and after the listings of options and arguments, respectively. Another is ``name``, which overwrites the name of the program which is used in the usage message (default value is inferred from command line arguments).
There are several ways to set properties. The first is to chain setter methods of Parser object.
.. code-block:: lua
:linenos:
local parser = argparse()
:name "script"
:description "A testing script."
:epilog "For more info, see http://example.com"
The second is to call a parser with a table containing some properties.
.. code-block:: lua
:linenos:
local parser = argparse() {
name = "script",
description = "A testing script.",
epilog "For more info, see http://example.com."
}
Finally, ``name``. ``description`` and ``epilog`` properties can be passed as arguments when calling a parser.
.. code-block:: lua
:linenos:
local parser = argparse("script", "A testing script.", "For more info, see http://example.com.")