
Introduction
---------------

BlazeCommandHelper (BCH) is a framework that facilitates the quick creation of
shell and batch scripts.  It provides a core command (bch) which locates
sub-commands from system dirs, user dirs, and installed python packages
(through the "blazech.commands" setuptools endpoint).

It also provides a library for quickly creating console applications based on
the argparse parser.

Features
---------------

* locates plugin commands from various places
* provides logging facilities
* provides configuration file facilities (needs work)

The goal is to have an API that facilitates interaction between the environment,
command line options, and configuration files ala `pip <http://pip.openplans.org/configuration.html>`_.

Usage
---------------

Install BCH using easy_install or pip.  Once installed, create a file for your
first command::

    # file location:
    # *nix: ~/.blazech/command_hwp.py
    # windows: %APPDATA%\.blazech\command_hwp.py

    # file contents
    from blazech.commands import BaseCommand

    class Command(BaseCommand):
        name = 'hello-world'
        help = 'say hello'

        def create_arguments(self):
            #self.parser is the argparse parser for this sub-command
            self.parser.add_argument(
                '-n', '--name',
                help='who do you want to say hello to',
                default='world'
            )

        def execute(self, args):
            print 'hello %s' % args.name

to run::

    # bch -h
    usage: bch [-h] [-v] [-q] {hello-world} ...

    positional arguments:
      {hello-world}
        hello-world     say hello
    <...snip...>

    $ bch hello-world
    hello world

    $ bch hello-world -n foo
    hello foo

Alternate Usage
--------------------

BCH can also be used as a library to help quickly create commands line
scripts::

    # setup.py
    #<...snip...>
    entry_points=\"""
            [console_scripts]
            fooapp = foopackage.commands:script_entry
        \"""

Run `python setup.py develop` (or install, etc.).  Then, you will need::

    # foopackage.commands
    from blazech.application import Application
    from blazech.commands import BaseCommand

    def script_entry():
        app = Application('fooapp')
        app.load_commands(globals())
        # could also use
        # import foopackage.altcommands
        # app.load_commands(foopackage.altcommands)
        app.run_cmd()

    class BarCommand(BaseCommand):
        name = 'bar'
        help = 'process bar file'

        def create_arguments(self):
            #self.parser is the argparse parser for this sub-command, see
            # argparser docs for usage
            self.parser.add_argument(
                'fpath',
                help = 'path of the file to process',
            )

        def execute(self, args):
            if args.fpath:
                print 'bar file is: %s' % args.fpath

You should then be able to::

    $ fooapp -h
    $ fooapp bar -h
    $ fooapp bar ../my/bar/file.txt


Questions & Comments
---------------------

Please visit: http://groups.google.com/group/blazelibs

Current Status
---------------

Primary use cases work for me, but b/c of time constraints will probably move
forward slowly.

The `development version <http://bitbucket.org/rsyring/blazech/get/tip.zip#egg=BlazeCommandHelper-dev>`_
is installable with ``easy_install BlazeCommandHelper==dev``.
