"""
a command-line interface to the command line, a la pythonpaste
"""

import inspect
import sys
from optparse import OptionParser

if 'commands' not in globals():
    commands = {}
    
def command(function):
    # XXX should get bound/unbound state from function (how?)
    global commands
    name = function.func_name
    doc = inspect.cleandoc(function.__doc__)
    argspec = inspect.getargspec(function)
    defaults = argspec.defaults
    if defaults:
        args = argspec.args[1:-len(defaults)]
        optional = dict(zip(argspec.args[-len(defaults):], defaults))
    else:
        args = argspec.args[1:]
        optional = None
    commands[name] = { 'doc': doc,
                       'args': args, 
                       'optional': optional,
                       'varargs': argspec.varargs
                       }
    return function

def commandargs2str(command):
    if isinstance(command, basestring):
        command = commands[command]
    retval = []
    retval.extend(['<%s>' % arg for arg in command['args']])
    varargs = command['varargs']
    if varargs:
        retval.append('<%s> [%s] [...]' % (varargs, varargs))
    if command['optional']:
        retval.append('[options]')
    return ' '.join(retval)

def list_commands():
    for command in sorted(commands.keys()):
        print '%s %s' % (command, commandargs2str(command))
        print '\n%s\n' % commands[command]['doc']

def doc2arghelp(docstring, decoration='-', delimeter=':'):
    """
    Parse a docstring and get at the section describing arguments
    - decoration: decoration character
    - delimeter: delimter character

    Yields a tuple of the stripped docstring and the arguments help
    dictionary
    """
    lines = [ i.strip() for i in docstring.split('\n') ]
    argdict = {}
    doc = []
    option = None
    for line in lines:
        if not line and option: # blank lines terminate
            break
        if line.startswith(decoration) and delimeter in line:
            name, description = line.split(delimeter, 1)
            name = name.lstrip(decoration).strip()
            description = description.strip()
            argdict[name] = [ description ]
            option = name
        else:
            if option:
                argdict[name].append(line)
            else:
                doc.append(line)
    argdict = dict([(key, ' '.join(value))
                    for key, value in argdict.items()])
    return ('\n'.join(doc), argdict)

def command2parser(command):
    doc, argdict = doc2arghelp(commands[command]['doc'])
    parser = OptionParser('%%prog %s %s' % (command, commandargs2str(command)),
                          description=doc, add_help_option=False)
    if commands[command]['optional']:
        for key, value in commands[command]['optional'].items():
            help = argdict.get(key)
            if value is True:
                parser.add_option('--no-%s' % key, dest=key,
                                  action='store_false', default=True,
                                  help=help)
            elif value is False:
                parser.add_option('--%s' % key, action='store_true',
                                  default=False, help=help)
            else:
                parser.add_option('--%s' % key, help=help)
                                  
    return parser