From 9e5524e8ea0b6c9b747eba3cf6ecfc5ad974da17 Mon Sep 17 00:00:00 2001 From: mpeterv Date: Wed, 9 Dec 2015 13:59:41 +0300 Subject: [PATCH] Document new actions --- docsrc/callbacks.rst | 168 ++++++++++++++++++++++++++++++++++++++++--- docsrc/defaults.rst | 2 +- docsrc/misc.rst | 15 ++-- 3 files changed, 170 insertions(+), 15 deletions(-) diff --git a/docsrc/callbacks.rst b/docsrc/callbacks.rst index 10c3b93..0a5c8c5 100644 --- a/docsrc/callbacks.rst +++ b/docsrc/callbacks.rst @@ -82,18 +82,68 @@ If convert property of an element is a table, arguments passed to it will be use 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. +.. _actions: + +Argument and option actions +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +argparse uses action callbacks to process invocations of arguments and options. Default actions simply put passed arguments into the result table as a single value or insert into an array depending on number of arguments the option can take and how many times it can be used. + +A custom action can be set using ``action`` property. An action must be a function. and will be called after each invocation of the option or the argument it is assigned to. Four arguments are passed: result table, target index in that table, an argument or an array of arguments passed by user, and overwrite flag used when an option is invoked too many times. + +Converters are applied before actions. + +Initial value to be stored at target index in the result table can be set using ``init`` property, or also using ``default`` property if the value is not a string. .. code-block:: lua :linenos: - parser:argument "required_argument" + parser:option("--exceptions"):args("*"):action(function(args, _, exceptions) + for _, exception in ipairs(exceptions) do + table.insert(args.exceptions, exception) + end + end):init({"foo", "bar"}) - parser:flag("-v --version", "Show version info and exit.") - :action(function() - print("script.lua v1.0.0") - os.exit(0) - end) + parser:flag("--no-exceptions"):action(function() + args.exceptions = {} + end) + +:: + + $ lua script.lua --exceptions x y --exceptions z t + +.. code-block:: lua + + { + exceptions = { + "foo", + "bar", + "x", + "y", + "z", + "t" + } + } + +:: + + $ lua script.lua --exceptions x y --no-exceptions + +.. code-block:: lua + + { + exceptions = {} + } + +Actions can also be used when a flag needs to print some message and exit without parsing remaining arguments. + +.. code-block:: lua + :linenos: + + parser:flag("-v --version"):action(function() + print("script v1.0.0") + os.exit(0) + end) :: @@ -101,4 +151,106 @@ argparse can trigger a callback when an option or a command is encountered. The :: - script.lua v1.0.0 + script v1.0.0 + +Built-in actions +^^^^^^^^^^^^^^^^ + +These actions can be referred to by their string names when setting ``action`` property: + +=========== ======================================================= +Name Description +=========== ======================================================= +store Stores argument or arguments at target index. +store_true Stores ``true`` at target index. +store_false Stores ``false`` at target index. +count Increments number at target index. +append Appends argument or arguments to table at target index. +concat Appends arguments one by one to table at target index. +=========== ======================================================= + +Examples using ``store_false`` and ``concat`` actions: + +.. code-block:: lua + :linenos: + + parser:flag("--candy") + parser:flag("--no-candy"):target("candy"):action("store_false") + parser:flag("--rain", "Enable rain", false) + parser:option("--exceptions"):args("*"):action("concat"):init({"foo", "bar"}) + +:: + + $ lua script.lua + +.. code-block:: lua + + { + rain = false + } + +:: + + $ lua script.lua --candy + +.. code-block:: lua + + { + candy = true, + rain = false + } + +:: + + $ lua script.lua --no-candy --rain + +.. code-block:: lua + + { + candy = false, + rain = true + } + +:: + + $ lua script.lua --exceptions x y --exceptions z t + +.. code-block:: lua + + { + exceptions = { + "foo", + "bar", + "x", + "y", + "z", + "t" + }, + rain = false + } + +Command actions +^^^^^^^^^^^^^^^ + +Actions for parsers and commands are simply callbacks invoked after parsing, with the argument table as the only argument. Actions for nested commands are called first. + +.. code-block:: lua + :linenos: + + local install = parser:command("install"):action(function(args) + print("Running install...") + -- Use args here + ) + + parser:action(function(args) + print("Callbacks are fun!") + end) + +:: + + $ lua script.lua install + +:: + + Running install... + Callbacks are fun! diff --git a/docsrc/defaults.rst b/docsrc/defaults.rst index 3452570..c01ac78 100644 --- a/docsrc/defaults.rst +++ b/docsrc/defaults.rst @@ -1,7 +1,7 @@ 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. +For elements such as arguments and options, if ``default`` property is set to a string, its value is stored in case the element was not used (if it's not a string, it'll be used as ``init`` property instead, see :ref:`actions`). .. code-block:: lua :linenos: diff --git a/docsrc/misc.rst b/docsrc/misc.rst index 6a8bb10..86d77e7 100644 --- a/docsrc/misc.rst +++ b/docsrc/misc.rst @@ -217,7 +217,7 @@ Property Type =============== ================= ``name`` String ``description`` String -``default`` String +``default`` Any ``convert`` Function or table ``args`` Number or string =============== ================= @@ -231,6 +231,8 @@ Property Type ``defmode`` String ``show_default`` Boolean ``argname`` String or table +``action`` Function or string +``init`` Any =================== =============== Option and flag properties @@ -243,7 +245,7 @@ Property Type =============== ================= ``name`` String ``description`` String -``default`` String +``default`` Any ``convert`` Function or table ``args`` Number or string ``count`` Number or string @@ -251,13 +253,14 @@ Property Type Other properties: -=================== =============== +=================== ================== Property Type -=================== =============== +=================== ================== ``target`` String ``defmode`` String ``show_default`` Boolean ``overwrite`` Booleans ``argname`` String or table -``action`` Function -=================== =============== +``action`` Function or string +``init`` Any +=================== ==================