===============
Parsing Options
===============
Clap comes with its own powerful and flexible option parser.

.. currentmodule:: clap.parser


Defining Options
================
Options are defined using the :class:`Option` class.

.. autoclass:: Option
   :members:

Here are a few example options::

    Option('v', 'verbose', desc='Prints extra output')
    Option('o', 'output', argument=True, desc='Write output to a file '
           'instead of stdout')
    Option('t', 'timeout', type=int, desc='Timeout for HTTP requests')
    Option(long='ignore-checksum', desc='Don\'t compute checksums of files '
           'to ensure integrity')


Parsing Options
===============
The preferred way to parse options is with the :func:`parse` function.

.. autofunction:: parse

However, if you need more control over the parsing process, you may want to
create an :class:`OptionParser` yourself.

.. autoclass:: OptionParser
   :members:
   :inherited-members: parse

   .. attribute:: arguments
      
      Once :meth:`parse` is called, this will be a list of the positional
      arguments that were parsed.
   
   .. attribute:: option_values
   
      Once :meth:`parse` is called, this will be a dictionary of values from
      all the options that were parsed.

Remember that since :meth:`OptionParser.parse` only invokes the parser loop
and doesn't return anything, you will need to access the :obj:`arguments` and
:obj:`option_values` attributes yourself.


Option Parsing Exceptions
=========================
All exceptions inherit from the :class:`OptionError` class.

.. autoexception:: OptionError
   :show-inheritance:

If you define an option that doesn't work (for example, you give neither a
long form nor a short form), a :class:`OptionDefError` will be raised.

.. autoexception:: OptionDefError
   :show-inheritance:

While actually parsing options, these exceptions may be raised:

.. autoexception:: OptionParsingError
   :show-inheritance:

.. autoexception:: DoesNotTakeArgument
   :show-inheritance:

.. autoexception:: ArgumentRequired
   :show-inheritance:

.. autoexception:: IllegalOption
   :show-inheritance: