diff options
Diffstat (limited to 'docs')
-rw-r--r-- | docs/source/classes.rst | 12 | ||||
-rw-r--r-- | docs/source/demoapp.rst | 29 | ||||
-rw-r--r-- | docs/source/index.rst | 1 | ||||
-rw-r--r-- | docs/source/show_commands.rst | 58 |
4 files changed, 100 insertions, 0 deletions
diff --git a/docs/source/classes.rst b/docs/source/classes.rst index 1777590..a1cadbb 100644 --- a/docs/source/classes.rst +++ b/docs/source/classes.rst @@ -20,6 +20,12 @@ Command .. autoclass:: cliff.command.Command :members: +ShowOne +======= + +.. autoclass:: cliff.show.ShowOne + :members: + Lister ====== @@ -37,3 +43,9 @@ ListFormatter .. autoclass:: cliff.formatters.base.ListFormatter :members: + +SingleFormatter +=============== + +.. autoclass:: cliff.formatters.base.SingleFormatter + :members: diff --git a/docs/source/demoapp.rst b/docs/source/demoapp.rst index 9c1ece8..1832077 100644 --- a/docs/source/demoapp.rst +++ b/docs/source/demoapp.rst @@ -199,6 +199,35 @@ output formatter and printing the data to the console. "Makefile",5569 "source",408 +.. _demoapp-show: + +show.py +------- + +``show.py`` includes a single command derived from +:class:`cliff.show.ShowOne` which prints the properties of the named +file. + +.. literalinclude:: ../../demoapp/cliffdemo/show.py + :linenos: + +:class:`File` prepares the data, and :class:`ShowOne` manages the +output formatter and printing the data to the console. + +:: + + (.venv)$ cliffdemo file setup.py + +---------------+--------------+ + | Field | Value | + +---------------+--------------+ + | Name | setup.py | + | Size | 5825 | + | UID | 502 | + | GID | 20 | + | Modified Time | 1335569964.0 | + +---------------+--------------+ + + setup.py -------- diff --git a/docs/source/index.rst b/docs/source/index.rst index d98a6cb..8994669 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -14,6 +14,7 @@ Contents: introduction demoapp list_commands + show_commands classes install developers diff --git a/docs/source/show_commands.rst b/docs/source/show_commands.rst new file mode 100644 index 0000000..c3b8914 --- /dev/null +++ b/docs/source/show_commands.rst @@ -0,0 +1,58 @@ +=============== + Show Commands +=============== + +One of the most common patterns with command line programs is the need +to print properties of objects. cliff provides a base class for +commands of this type so that they only need to prepare the data, and +the user can choose from one of several output formatter plugins to +see the data in their preferred format. + +ShowOne +======= + +The :class:`cliff.show.ShowOne` base class API extends +:class:`Command` to add a :func:`get_data` method. Subclasses should +provide a :func:`get_data` implementation that returns a two member +tuple containing a tuple with the names of the columns in the dataset +and an iterable that contains the data values associated with those +names. See the description of :ref:`the file command in the demoapp +<demoapp-show>` for details. + +Show Output Formatters +====================== + +cliff is delivered with output formatters for show +commands. :class:`ShowOne` adds a command line switch to let the user +specify the formatter they want, so you don't have to do any extra +work in your application. + +PrettyTable +----------- + +The ``PrettyTable`` formatter uses PrettyTable_ to produce output +formatted for human consumption. + +.. _PrettyTable: http://code.google.com/p/prettytable/ + +:: + + (.venv)$ cliffdemo file setup.py + +---------------+--------------+ + | Field | Value | + +---------------+--------------+ + | Name | setup.py | + | Size | 5825 | + | UID | 502 | + | GID | 20 | + | Modified Time | 1335569964.0 | + +---------------+--------------+ + +Creating Your Own Formatter +--------------------------- + +If the standard formatters do not meet your needs, you can bundle +another formatter with your program by subclassing from +:class:`cliff.formatters.base.ShowFormatter` and registering the +plugin in the ``cliff.formatter.show`` namespace. + |