Document new actions

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!