diff options
Diffstat (limited to 'docs/features/generating_output.rst')
| -rw-r--r-- | docs/features/generating_output.rst | 60 |
1 files changed, 60 insertions, 0 deletions
diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst index 5813322b..c03f8778 100644 --- a/docs/features/generating_output.rst +++ b/docs/features/generating_output.rst @@ -9,6 +9,39 @@ how to generate output - exceptions - color support +Standard ``cmd`` applications produce their output with +``self.stdout.write('output')`` (or with ``print``, but ``print`` decreases +output flexibility). ``cmd2`` applications can use ``self.poutput('output')``, +``self.pfeedback('message')``, ``self.perror('errmsg')``, and +``self.ppaged('text')`` instead. These methods have these advantages: + +- Handle output redirection to file and/or pipe appropriately +- More concise + - ``.pfeedback()`` destination is controlled by ``quiet`` parameter. +- Option to display long output using a pager via ``ppaged()`` + +.. automethod:: cmd2.cmd2.Cmd.poutput + :noindex: +.. automethod:: cmd2.cmd2.Cmd.perror + :noindex: +.. automethod:: cmd2.cmd2.Cmd.pfeedback + :noindex: +.. automethod:: cmd2.cmd2.Cmd.ppaged + :noindex: + + +Suppressing non-essential output +-------------------------------- + +The ``quiet`` setting controls whether ``self.pfeedback()`` actually produces +any output. If ``quiet`` is ``False``, then the output will be produced. If +``quiet`` is ``True``, no output will be produced. + +This makes ``self.pfeedback()`` useful for non-essential output like status +messages. Users can control whether they would like to see these messages by +changing the value of the ``quiet`` setting. + + Output Redirection ------------------ @@ -43,3 +76,30 @@ If you need to include any of these redirection characters in your command, you can enclose them in quotation marks, ``mycommand 'with > in the argument'``. +Colored Output +-------------- + +The output methods in the previous section all honor the ``allow_ansi`` +setting, which has three possible values: + +Never + poutput(), pfeedback(), and ppaged() strip all ANSI escape sequences + which instruct the terminal to colorize output + +Terminal + (the default value) poutput(), pfeedback(), and ppaged() do not strip any + ANSI escape sequences when the output is a terminal, but if the output is a + pipe or a file the escape sequences are stripped. If you want colorized + output you must add ANSI escape sequences using either cmd2's internal ansi + module or another color library such as `plumbum.colors`, `colorama`, or + `colored`. + +Always + poutput(), pfeedback(), and ppaged() never strip ANSI escape sequences, + regardless of the output destination + +Colored and otherwise styled output can be generated using the `ansi.style()` +function: + +.. automethod:: cmd2.ansi.style + |