.. -*- mode: rst -*-

==========
 Fancycmd
==========

Fancycmd is a command line parser, indented to make writing command line
applications easy and painless. It uses built-in Python types (lists,
dictionaries, etc) to define options (or subcommands in case you need them),
which makes configuration clear and concise.


Options
-------

Configuration of option parser is a list of tuples::

    opts = [('l', 'listen', 'localhost', 'ip to listen on'),
            ('p', 'port', 8000, 'port to listen on'),
            ('d', 'daemonize', False, 'daemonize process'),
            ('', 'pid-file', '', 'name of file to write process ID to')]

Each tuple is a definition of some option, consisting of 4 elements:

 1. short name
 2. long name
 3. default value
 4. help string

If a short name renders to False (for example, empty string), then it's not used
at all. Long name is pretended to be available in any case. Default value also
determines how supplied argument should be parsed:

 - function: return value of function called with a specified value is passed
 - integer: value is convert to integer
 - string: value is passed as is
 - list: value is appended to this list
 - boolean/None: ``not default`` is passed and option takes no argument

Usage is easy like that::

    from fancycmd import fancyopts
    def main(dirname, **opts):
        '''write some help here'''
        pass
    parser = fancyopts(main, opts, usage='%s [-l HOST] DIR' % sys.argv[0])
    parser(sys.argv[1:])

Subcommands
-----------

It's pretty usual for complex application to have some system of subcommands,
and fancycmd provides facility for handling them. Configuration is simple as
well::

    cmdtable = {
        '^simple':
            (simple,
             [('t', 'test', False, 'just test execution')],
             '[-t] ...'),
        'complex|hard':
            (complex_,
             [('p', 'pass', False, 'don\'t run the command'),
              ('', 'exit', 0, 'exit with supplied code (default: 0)')],
             '[-p] [--exit value] ...')}

Keys in this dictionary are subcommand names. You can add aliases for
subcommands, separating them with the ``|`` sign (of course, there can be few
aliases). Marking command with preceding ``^`` means that this commands should
be included in short help (more on that later).

Values here are tuples, consisting of 3 elements:

 1. function, which will handle this subcommand
 2. list of options
 3. usage string (used by help generator)

Your application will also always have ``help`` command, when it uses subcommand
system.

You can define your functions for subcommands like this::

    def simple(ui, *args, **opts):
        '''some descriptive text here

        more help, I'd said a lot of help here ;-)
        '''
        pass

Naturally ``args`` is a list, containing all arguments to command, and ``opts``
is a dictionary, containing every option. ``ui`` is an UI_ instance.

Usage::

   describe api here

UI
--

``UI`` is a special object intended to ease output handling in your
application. There are two global options added, which are used by this object:
``-v/--verbose`` and ``-q/--quiet``. And then you are encouraged to use ``UI``
instance to output instead of directly printing messages, which is possible by
using one of following methods:

  - ``UI.info`` prints by default, but hides output with quiet option
  - ``UI.note`` prints only if verbose option supplied
  - ``UI.write`` prints in any case
  - ``UI.warn`` prints to stderr (in any case)


Help generation
---------------

Help is generated automatically and is available by the ``--help`` command line
option or by ``help`` subcommand (if you're using subcommand system).

Help is wrapped to length of 70 characters.