Quick Start
###########

So you need to create a command-line interface? ``decree-tree``
can help with that!

Installation
************

Install ``decree-tree`` from PyPI via pip:

.. code:: bash

   pip install decree-tree

If you are using a different package manager, such as Poetry,
use its appropriate installation command for the ``decree-tree``
package on PyPI.

Basic Usage
***********

To create a basic command, subclass :class:`decree_tree.DecreeTree`
to define command-line arguments and its behavior.

.. literalinclude:: code/basic.py
    :language: python
    :caption: ``basic.py``
    :lines: 4-

Invoking the script in the expected way yields output like the
following:

.. shtest::
    :cwd: code

    $ python basic.py "foo bar"
    foo bar

Options can be specified:

.. shtest::
    :cwd: code

    $ python basic.py --upper "foo bar"
    FOO BAR

If there is missing input, the command fails:

.. shtest::
    :cwd: code
    :returncode: 2
    :stderr:

    $ python basic.py
    usage: basic.py [-h] [--upper] value
    basic.py: error: the following arguments are required: value

There is also a built-in help option:

.. shtest::
    :cwd: code

    $ python basic.py --help
    usage: basic.py [-h] [--upper] value

    Echo and optionally up-case input.

    positional arguments:
      value       the value to echo

    options:
      -h, --help  show this help message and exit
      --upper

Many aspects of the command can be configured. See
:doc:`configuration` and :doc:`nesting`.

Nested Commands
***************

To create a tree of subcommands, create additional classes.
Instantiate the root and add each to their parent.

.. literalinclude:: code/basic_tree.py
    :language: python
    :caption: ``basic_tree.py``
    :lines: 4-

Either subcommand can be invoked, and processing of the parent
command is inherited by default. For example:

.. _basic tree example:

.. shtest::
    :cwd: code

    $ python basic_tree.py basic_command -e --upper "foo bar"
    Extra output
    FOO BAR

The built-in help can be displayed at the root level...

.. shtest::
    :cwd: code

    $ python basic_tree.py -h
    usage: basic_tree.py [-h] [-e] {basic_command,double} ...

    An example command tree.

    options:
      -h, --help            show this help message and exit
      -e, --extra

    subcommands:
      {basic_command,double}
        basic_command       Echo and optionally up-case input.
        double              Doubly-echo the input.

... or at any subcommand level.

.. shtest::
    :cwd: code

    $ python basic_tree.py basic_command --help
    usage: basic_tree.py basic_command [-h] [-e] [--upper] value

    Echo and optionally up-case input.

    positional arguments:
      value       the value to echo

    options:
      -h, --help   show this help message and exit
      -e, --extra
      --upper

Commands can be nested to an arbitrary depth, and the nesting can
be configured in a variety of ways. See :doc:`nesting` for details.