diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/features/generating_output.rst | 118 | ||||
| -rw-r--r-- | docs/features/startup_commands.rst | 2 |
2 files changed, 84 insertions, 36 deletions
diff --git a/docs/features/generating_output.rst b/docs/features/generating_output.rst index 2ee820f1..d63acea2 100644 --- a/docs/features/generating_output.rst +++ b/docs/features/generating_output.rst @@ -1,45 +1,93 @@ Generating Output ================= -how to generate output +A standard ``cmd`` application can produce output by using either of these +methods:: + + print("Greetings, Professor Falken.", file=self.stdout) + self.stdout.write("Shall we play a game?\n") + +While you could send output directly to ``sys.stdout``, ``cmd`` can be +initialized with a ``stdin`` and ``stdout`` variables, which it stores +as ``self.stdin`` and ``self.stdout``. By using these variables every +time you produce output, you can trivially change where all the output +goes by changing how you initialize your class. + +``cmd2`` extends this approach in a number of convenient ways. See +:ref:`features/redirection:Output Redirection And Pipes` for information +on how users can change where the output of a command is sent. In order +for those features to work, the output you generate must be sent to +``self.stdout``. You can use the methods described above, and everything +will work fine. ``cmd2`` also includes a number of convenience methods +which you may use to enhance the output your application produces. + + +TODO: - poutput - perror -- paging +- pwarning +- pexcept +- ppaging + +- column formatting? +- wcswidth? + +- allow_ansi setting +- cmd2.ansi.style() + - 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. + +Ordinary Output +--------------- + + +Error Messages +-------------- + + +Warning Messages +---------------- + + +Feedback +-------- + +You may have the need to display information to the user which is not intended +to be part of the generated output. This could be debugging information or +status information about the progress of long running commands. It's not output, +it's not error messages, it's feedback. If you use the +:ref:`features/settings:Timing` setting, the output of how long it took the +command to run will be output as feedback. ``cmd2`` has a ``self.pfeedback()`` +method to produce this type of output, and several +:ref:`features/settings:Settings` to control how this output is handled. + +If the ``quiet`` setting is ``True``, then calling ``self.pfeedback()`` produces +no output. If ``quiet`` is ``False``, then the ``feedback_to_output`` setting is +consulted to determine which file descriptor the feedback will be sent to. The +default value of ``False`` means all feedback is sent to ``sys.stderr``. If set +to ``True``, then the feedback output will be sent to ``self.stdout`` along with +the rest of the generated output. + + +Exceptions +---------- + + +Paging Output +------------- + + +Centering Text +-------------- + +utils.center_text() + + +Columnar Output +--------------- + +Using wcswidth() and ansi.ansi_safe_wcswidth() Colored Output diff --git a/docs/features/startup_commands.rst b/docs/features/startup_commands.rst index 93984db6..aaaf7722 100644 --- a/docs/features/startup_commands.rst +++ b/docs/features/startup_commands.rst @@ -5,7 +5,7 @@ Startup Commands after your application starts up: 1. Commands at Invocation -1. Startup Script +2. Startup Script Commands run as part of a startup script are always run immediately after the application finishes initializing so they are guaranteed to run before any |