================
Writing Commands
================
Commands are the central focus of Clap. Even if you're just writing a plain
old application, you will need to use a command if you want to use a
:class:`~clap.base.Base`.


.. currentmodule:: clap.command

The :class:`Command` Base Class
===============================
The most straightforward way to create a command is to create a subclass of
the class :class:`Command`.

.. autoclass:: Command
   :members:


Shortcuts
=========
You can also use a decorator, :func:`command`, to create commands.

.. autofunction:: command

For example::

    @command(
        options=(
            Option('l', 'language', argument=True, desc="Language to write "
                   "Hello, World in")
        ),
        aliases=('hi',),
        short_desc=DOC,
        long_desc=DOC,
        usage='[OPTIONS] [PERSON]'
    )
    def hello(options, arguments):
        "Prints 'Hello, world!' or just 'Hello' to a given person"
        if arguments:
            person = arguments[0]
        else:
            person = None
        if options['language'] == 'es':
            print "Hola, %s!" % (person or 'mundo')
        else:
            print "Hello, %s!" % (person or 'world')

.. autodata:: DOC


Usage Errors from Commands
==========================
If you want to interrupt the command with a "normal" error message, then raise
a :class:`ScriptError` exception with your message. It will be displayed as a
normal usage error would.

.. autoexception:: clap.base.ScriptError