.. include:: ../global.rst

.. idio:currentmodule:: argparse

argparse Functions
------------------

.. _`argparse/add-option`:

.. idio:generic:: argparse/add-option (ap ArgumentParser) names arg-data docstr


   
   add an option to `ap`
   
   :param ap: ArgumentParser instance
   :type ap: :ref:`ArgumentParser <argparse/ArgumentParser>`
   :param names: option name(s)
   :type names: list of symbols
   :param arg-data: argument data
   :type arg-data: see below
   :param docstr: documentation string
   :type docstr: string
   :return: ``#<unspec>``
   
   `arg-data` can be:
   
   * either one of:
   
     * ``:none`` meaning the option takes no argument
     * ``:optional`` meaning the option may take an argument, defaulting to ``#t``
     * ``:required`` meaning the option must take an argument
   
     where the nominal argument name is ``'ARG"`` for use in the usage string
   
   * or a list of ``:optional`` or ``:required`` and the nominal argument
     name as a string
   
   :Example:
   
   .. code-block:: idio
   
      ap := make-instance ArgumentParser :synopsis (sprintf "%s [options] [FRUIT ...]" ARGV0)
   
      add-option ap '(a apple) :none "add an apple"
      add-option ap '(o output) (:required "FILE") "direct output to FILE"
   
   


.. _`argparse/parse-args`:

.. idio:generic:: argparse/parse-args (ap ArgumentParser) argv


   
   parse the argument in `argv` using the options associated with `ap`
   
   :param ap: ArgumentParser instance
   :type ap: :ref:`ArgumentParser <argparse/ArgumentParser>`
   :param argv: argument strings
   :type argv: array of strings (
   :return: ``#<unspec>``
   
   Subsequently, `ap.options` will be a hash table with a key for each
   name defined in the options associated with `ap` and `ap.operands`
   will be a list of the remaining arguments.
   


.. _`argparse/usage`:

.. idio:generic:: argparse/usage (ap ArgumentParser)


   
   print the usage for the options associated with `ap`
   
   :param ap: ArgumentParser instance
   :type ap: :ref:`ArgumentParser <argparse/ArgumentParser>`
   :return: ``#<unspec>``
   
   :Example:
   
   For the options added above in a script called ``x.idio``:
   
   .. code-block:: idio
   
      usage ap
   
   #. when passed the argument ``-h``
   
      .. code-block:: text
   
         usage: x [options] [FRUIT ...]
   
         Options:
              --help, -h, -?       display this message and exit
          -a, --apple              option a
          -o, --output=FILE        direct output to FILE
   
   #. when passed the arguments ``-a -o foo``
   
      .. code-block:: text
   
         usage: x [options] [FRUIT ...]
   
         Options:
              --help, -h, -?       display this message and exit
          -a, --apple              option a [#t]
          -o, --output=FILE        direct output to FILE [foo]
   




.. include:: ../commit.rst