Usage
=====

There are 2 main ways to utilize click-shell: the decorator and the factory method.

Decorator
---------

The easiest way to get going with click-shell is with the click style decorator.
``@click_shell.shell`` is meant to replace click's ``@click.group`` decorator for the root level
of your app.  In fact, the object generated by ``@click_shell.shell`` is a
``click_shell.core.Shell`` object, which is a subclass of ``click.core.Group``.

.. code-block:: python

    from click_shell import shell

    # @click.group()  # no longer
    @shell(prompt='my-app > ', intro='Starting my app...')
    def my_app():
        pass

    @my_app.command()
    def testcommand():
        print('testcommand is running')

    # more commands

    if __name__ == '__main__':
        my_app()


When run with the above arguments, you should expect an output like so:

.. code-block:: bash

    $ python my_app.py
    Starting my app...
    my-app > testcommand
    testcommand is running
    my-app >


``@shell`` takes 4 arguments:

- ``prompt`` - this will get printed as the beginning of each line in the shell.
  This can take a callable that will be called each time a prompt is printed.
  On Python 3 ONLY, if the callable takes an argument named ``ctx``,
  the click context will be passed in as that argument.
  Defaults to ``'(Cmd) '``
- ``intro`` - this will get printed once when the shell first starts
  Defaults to ``None``, meaning nothing gets printed
- ``hist_file`` - this is the location of the history file used by the shell.
  Defaults to ``'~/.click-history'``
- ``on_finished`` - a callable that will be called when the shell exits.
  You can use it to clean up any resources that may need cleaning up.

``@shell`` also takes arbitrary keyword arguments, and they are passed on directly to the
constructor for the `click_shell.Shell`` class.


Factory Method
--------------

If you'd rather not use decorators (or can't for some reason), you can manually create a shell
object and start it up:


.. code-block:: python

    import click
    from click_shell import make_click_shell

    @click.group()
    @click.pass_context
    def my_app(ctx):
        pass



    # Somewhere else in your code (as long as you have access to the root level Context object)

    shell = make_click_shell(ctx, prompt='my-app > ', intro='Starting my app...')
    shell.cmdloop()


The first argument passed to ``make_click_shell`` must be the root level context object for
your click application.  The other 3 args (prompt, intro, hist_file) are the same as described
above under the Decorator section.
