**Candela** is a simple shell-building system that uses python and curses to
help developers create customized command line interfaces. It has a simple
interface, is well documented, and allows developers to take command-based
tools to the next level of complexity and usability.

Features
--------

* Commands are 100% python and can run aribtrary code
* Commands can run code in secondary threads for asynchronous operation
* Customizable tab completion hooks for command arguments
* Responsive layout for smaller terminals
* Numerous built-in command templates
* Simple command syntax and help system
* "stickers" allow persistent information display
* Automatically generated command validation
* Up/Down arrows cycle through history
* Copy/Paste, insert text mode
* Easy transitions between menus
* Supports both named and positional command arguments

Example Shell
-------------

There is an example shell project in `shell_example.py`. To run it, use

    python shell_example.py

in a maximized terminal window.

Download
--------

Download the source from PyPI with

    pip install candela

You can also clone this repo to take a closer look at the code and demo app.

    git clone https://github.com/emmett9001/candela.git

Then, install the library with

    python setup.py install

Basic Use
---------

Importing
---------

Import Candela commands, menus, and the shell

    from candela.shell import Shell
    from candela.menu import Menu
    from candela.command import Command
    from candela import constants

Alternatively, you can simply `import candela` and reference the components
with `candela.shell.Shell`, etc.

Subclass Shell
--------------

Every Candela app is built as a subclass of `candela.shell.Shell`. A `Shell`
initialization follows this general outline:

* Set `self.name`
* Set `self.header`
* Define and instantiate `Command`s
* Define and instantiate `Menu`s
* Add `Command`s to `Menu`s
* Set `self.menus` to contain instantiated `Menu`s
* Set `self.menu` to be the name of the default menu

Commands
--------

In general, a command instantiation looks like this

    com = Command('first_command', 'Intro to commands')
    def _run(*args, **kwargs):
        # do anything
        return constants.CHOICE_VALID
    com.run = _run
    return com

Functions that execute on command invocation are modeled as python first-class
functions (callbacks).

Advanced Use
------------

Please see the
[shell example](https://github.com/emmett9001/candela/blob/master/shell_example.py)
for a full walkthrough of how to use Candela. This example is both
well-commented and an instructional app demonstrating Candela's features.

Name
----

The name "Candela" was chosen after Spanish architect
[Felix Candela](http://en.wikipedia.org/wiki/F%C3%A9lix_Candela), who
pioneered the technique of building shell-shaped structures out of reinforced
concrete. He is sometimes known as the "shell builder".

Support
-------

If you need help using Candela, or have found a bug, please create an issue on
the [Github repo](https://github.com/emmett9001/candela/issues).

License
-------

    Copyright 2013 Emmett Butler

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

        http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.
