
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 "cliff.show.ShowOne" base class API extends "Command" to allow
"take_action()" to return data to be formatted using a user-selectable
formatter. Subclasses should provide a "take_action()" 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 *the file
command in the demoapp* for details.


Show Output Formatters
======================

cliff is delivered with output formatters for show commands. "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.


shell
-----

The "shell" formatter produces output that can be parsed directly by a
typical UNIX shell as variable assignments. This avoids extra parsing
overhead in shell scripts.

   (.venv)$ cliffdemo file -f shell setup.py
   name="setup.py"
   size="5916"
   uid="527"
   gid="501"
   modified_time="1335655655.0"

   (.venv)$ eval "$(cliffdemo file -f shell --prefix example_ setup.py)"
   (.venv)$ echo $example_size
   5916


table
-----

The "table" formatter uses PrettyTable to produce output formatted for
human consumption.

   (.venv)$ cliffdemo file setup.py
   +---------------+--------------+
   |     Field     |    Value     |
   +---------------+--------------+
   | Name          | setup.py     |
   | Size          | 5825         |
   | UID           | 502          |
   | GID           | 20           |
   | Modified Time | 1335569964.0 |
   +---------------+--------------+


Other Formatters
----------------

Formatters using tablib to produce JSON, YAML, and HTML are available
as part of cliff-tablib.


Creating Your Own Formatter
---------------------------

If the standard formatters do not meet your needs, you can bundle
another formatter with your program by subclassing from
"cliff.formatters.base.ShowFormatter" and registering the plugin in
the "cliff.formatter.show" namespace.
