add ShowOne base class for commands that need to show properties of an individual object

make the table formatter work as a single object formatter
update the docs for the new features

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.
+