Integrate the unfreefeatures legacy documentation

5 files changed, 281 insertions, 0 deletions

diff --git a/docs/features/commands.rst b/docs/features/commands.rst
index 3eec2373..6a8fedee 100644
--- a/docs/features/commands.rst
+++ b/docs/features/commands.rst
@@ -1,4 +1,47 @@
 Commands
 ========
 
+.. _cmd: https://docs.python.org/3/library/cmd.html
+
 How to create a command with a ``do_command`` method,
+
+Parsed statements
+-----------------
+
+``cmd2`` passes ``arg`` to a ``do_`` method (or ``default``) as a Statement, a
+subclass of string that includes many attributes of the parsed input:
+
+command
+    Name of the command called
+
+args
+    The arguments to the command with output redirection
+    or piping to shell commands removed
+
+command_and_args
+    A string of just the command and the arguments, with
+    output redirection or piping to shell commands removed
+
+argv
+    A list of arguments a-la ``sys.argv``, including
+    the command as ``argv[0]`` and the subsequent
+    arguments as additional items in the list.
+    Quotes around arguments will be stripped as will
+    any output redirection or piping portions of the command
+
+raw
+    Full input exactly as typed.
+
+terminator
+    Character used to end a multiline command
+
+
+
+If ``Statement`` does not contain an attribute, querying for it will return
+``None``.
+
+(Getting ``arg`` as a ``Statement`` is technically "free", in that it requires
+no application changes from the cmd_ standard, but there will be no result
+unless you change your application to *use* any of the additional attributes.)
+
+
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
+
diff --git a/docs/features/misc.rst b/docs/features/misc.rst
index b556d44e..0ddc03e1 100644
--- a/docs/features/misc.rst
+++ b/docs/features/misc.rst
@@ -77,3 +77,73 @@ like so::
 This text file should contain a :ref:`Command Script
 <features/scripting:Command Scripts>`. See the AliasStartup_ example for a
 demonstration.
+
+
+select
+------
+
+Presents numbered options to user, as bash ``select``.
+
+``app.select`` is called from within a method (not by the user directly; it is
+``app.select``, not ``app.do_select``).
+
+.. automethod:: cmd2.cmd2.Cmd.select
+    :noindex:
+
+::
+
+    def do_eat(self, arg):
+        sauce = self.select('sweet salty', 'Sauce? ')
+        result = '{food} with {sauce} sauce, yum!'
+        result = result.format(food=arg, sauce=sauce)
+        self.stdout.write(result + '\n')
+
+::
+
+    (Cmd) eat wheaties
+        1. sweet
+        2. salty
+    Sauce? 2
+    wheaties with salty sauce, yum!
+
+
+Disabling Commands
+------------------
+
+``cmd2`` supports disabling commands during runtime. This is useful if certain
+commands should only be available when the application is in a specific state.
+When a command is disabled, it will not show up in the help menu or tab
+complete. If a user tries to run the command, a command-specific message
+supplied by the developer will be printed. The following functions support this
+feature.
+
+enable_command()
+    Enable an individual command
+
+enable_category()
+    Enable an entire category of commands
+
+disable_command()
+    Disable an individual command and set the message that will print when this
+    command is run or help is called on it while disabled
+
+disable_category()
+    Disable an entire category of commands and set the message that will print
+    when anything in this category is run or help is called on it while
+    disabled
+
+See the definitions of these functions for descriptions of their arguments.
+
+See the ``do_enable_commands()`` and ``do_disable_commands()`` functions in the
+HelpCategories_ example for a demonstration.
+
+.. _HelpCategories: https://github.com/python-cmd2/cmd2/blob/master/examples/help_categories.py
+
+
+Exit code
+---------
+
+The ``self.exit_code`` attribute of your ``cmd2`` application controls what
+exit code is returned from ``cmdloop()`` when it completes.  It is your job to
+make sure that this exit code gets sent to the shell when your application
+exits by calling ``sys.exit(app.cmdloop())``.
diff --git a/docs/features/os.rst b/docs/features/os.rst
index 780e99f2..40a7cbf4 100644
--- a/docs/features/os.rst
+++ b/docs/features/os.rst
@@ -9,3 +9,78 @@ Integrating with the OS
 - Automation and calling cmd2 from other CLI/CLU tools via commands at
   invocation and quit
 
+
+Invoking With Arguments
+-----------------------
+
+Typically you would invoke a ``cmd2`` program by typing::
+
+    $ python mycmd2program.py
+
+or::
+
+    $ mycmd2program.py
+
+Either of these methods will launch your program and enter the ``cmd2`` command
+loop, which allows the user to enter commands, which are then executed by your
+program.
+
+You may want to execute commands in your program without prompting the user for
+any input. There are several ways you might accomplish this task. The easiest
+one is to pipe commands and their arguments into your program via standard
+input. You don't need to do anything to your program in order to use this
+technique. Here's a demonstration using the ``examples/example.py`` included in
+the source code of ``cmd2``::
+
+    $ echo "speak -p some words" | python examples/example.py
+    omesay ordsway
+
+Using this same approach you could create a text file containing the commands
+you would like to run, one command per line in the file. Say your file was
+called ``somecmds.txt``. To run the commands in the text file using your
+``cmd2`` program (from a Windows command prompt)::
+
+    c:\cmd2> type somecmds.txt | python.exe examples/example.py
+    omesay ordsway
+
+By default, ``cmd2`` programs also look for commands pass as arguments from the
+operating system shell, and execute those commands before entering the command
+loop::
+
+    $ python examples/example.py help
+
+    Documented commands (type help <topic>):
+    ========================================
+    alias  help     macro   orate  quit          run_script  set    shortcuts
+    edit   history  mumble  py     run_pyscript  say         shell  speak
+
+    (Cmd)
+
+You may need more control over command line arguments passed from the operating
+system shell. For example, you might have a command inside your ``cmd2``
+program which itself accepts arguments, and maybe even option strings. Say you
+wanted to run the ``speak`` command from the operating system shell, but have
+it say it in pig latin::
+
+    $ python example/example.py speak -p hello there
+    python example.py speak -p hello there
+    usage: speak [-h] [-p] [-s] [-r REPEAT] words [words ...]
+    speak: error: the following arguments are required: words
+    *** Unknown syntax: -p
+    *** Unknown syntax: hello
+    *** Unknown syntax: there
+    (Cmd)
+
+Uh-oh, that's not what we wanted. ``cmd2`` treated ``-p``, ``hello``, and
+``there`` as commands, which don't exist in that program, thus the syntax
+errors.
+
+There is an easy way around this, which is demonstrated in
+``examples/cmd_as_argument.py``. By setting ``allow_cli_args=False`` you can so
+your own argument parsing of the command line::
+
+    $ python examples/cmd_as_argument.py speak -p hello there
+    ellohay heretay
+
+Check the source code of this example, especially the ``main()`` function, to
+see the technique.
diff --git a/docs/features/settings.rst b/docs/features/settings.rst
index 696b085f..27730572 100644
--- a/docs/features/settings.rst
+++ b/docs/features/settings.rst
@@ -4,3 +4,36 @@ Settings
 - current settings and what they do
 - how a developer can add their own
 - how to hide built in settings from a user
+
+Your application can define user-settable parameters which your code can
+reference. First create a class attribute with the default value. Then update
+the ``settable`` dictionary with your setting name and a short description
+before you initialize the superclass. Here's an example, from
+``examples/environment.py``:
+
+.. literalinclude:: ../../examples/environment.py
+
+If you want to be notified when a setting changes (as we do above), then define
+a method ``_onchange_{setting}()``. This method will be called after the user
+changes a setting, and will receive both the old value and the new value.
+
+.. code-block:: text
+
+   (Cmd) set --long | grep sunny
+   sunny: False                # Is it sunny outside?
+   (Cmd) set --long | grep degrees
+   degrees_c: 22               # Temperature in Celsius
+   (Cmd) sunbathe
+   Too dim.
+   (Cmd) set degrees_c 41
+   degrees_c - was: 22
+   now: 41
+   (Cmd) set sunny
+   sunny: True
+   (Cmd) sunbathe
+   UV is bad for your skin.
+   (Cmd) set degrees_c 13
+   degrees_c - was: 41
+   now: 13
+   (Cmd) sunbathe
+   It's 13 C - are you a penguin?