diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/api/cmd.rst | 2 | ||||
| -rw-r--r-- | docs/api/history.rst | 3 | ||||
| -rw-r--r-- | docs/api/index.rst | 29 | ||||
| -rw-r--r-- | docs/api/parsing.rst | 15 | ||||
| -rw-r--r-- | docs/api/utils.rst | 12 | ||||
| -rw-r--r-- | docs/doc_conventions.rst | 15 | ||||
| -rw-r--r-- | docs/examples/alternate_event_loops.rst | 30 | ||||
| -rw-r--r-- | docs/features/history.rst | 45 |
8 files changed, 111 insertions, 40 deletions
diff --git a/docs/api/cmd.rst b/docs/api/cmd.rst index 3fcd3352..dd3d3abe 100644 --- a/docs/api/cmd.rst +++ b/docs/api/cmd.rst @@ -52,7 +52,7 @@ cmd2.Cmd A record of previously entered commands. This attribute is an instance of :class:`cmd2.history.History`, and - each command is an instance of :class:`cmd2.history.HistoryItem`. + each command is an instance of :class:`cmd2.Statement`. .. attribute:: statement_parser diff --git a/docs/api/history.rst b/docs/api/history.rst index 3a3ae2c4..5658238d 100644 --- a/docs/api/history.rst +++ b/docs/api/history.rst @@ -1,6 +1,9 @@ cmd2.history =============== +Classes for storing the history of previously entered commands. + + .. autoclass:: cmd2.history.History :members: diff --git a/docs/api/index.rst b/docs/api/index.rst index d5fc013b..aa3371b9 100644 --- a/docs/api/index.rst +++ b/docs/api/index.rst @@ -12,19 +12,42 @@ If a release of this library changes any of the items documented here, the version number will be incremented according to the `Semantic Version Specification <https://semver.org>`_. -This documentation is for version |version| of ``cmd2``. +This documentation is for ``cmd2`` version |version|. .. toctree:: :maxdepth: 1 + :hidden: cmd - parsing decorators - history + parsing argparse_completer argparse_custom ansi utils + history plugin py_bridge constants + +**Modules** + +- :ref:`api/cmd:cmd2.Cmd` - functions and attributes of the main + class in this library +- :ref:`api/decorators:cmd2.decorators` - decorators for ``cmd2`` + commands +- :ref:`api/parsing:cmd2.parsing` - classes for parsing and storing + user input +- :ref:`api/argparse_completer:cmd2.argparse_completer` - classes for + ``argparse``-based tab completion +- :ref:`api/argparse_custom:cmd2.argparse_custom` - classes and functions + for extending ``argparse`` +- :ref:`api/ansi:cmd2.ansi` - convenience classes and functions for generating + ANSI escape sequences to style text in the terminal +- :ref:`api/utils:cmd2.utils` - various utility classes and functions +- :ref:`api/history:cmd2.history` - classes for storing the history + of previously entered commands +- :ref:`api/plugin:cmd2.plugin` - data classes for hook methods +- :ref:`api/py_bridge:cmd2.py_bridge` - classes for bridging calls from the + embedded python environment to the host app +- :ref:`api/constants:cmd2.constants` - just like it says on the tin diff --git a/docs/api/parsing.rst b/docs/api/parsing.rst index c79c8f6b..fa726700 100644 --- a/docs/api/parsing.rst +++ b/docs/api/parsing.rst @@ -1,6 +1,15 @@ cmd2.parsing =============== +Classes for parsing and storing user input. + + +.. autoclass:: cmd2.parsing.StatementParser + :members: + + .. automethod:: __init__ + + .. autoclass:: cmd2.Statement :members: @@ -67,9 +76,3 @@ cmd2.parsing If output was redirected by the user, this contains the requested destination with quotes preserved. - - -.. autoclass:: cmd2.parsing.StatementParser - :members: - - .. automethod:: __init__ diff --git a/docs/api/utils.rst b/docs/api/utils.rst index 2ae5987b..8121fea8 100644 --- a/docs/api/utils.rst +++ b/docs/api/utils.rst @@ -42,12 +42,6 @@ Tab Completion .. autoclass:: cmd2.utils.CompletionError :members: -.. autofunction:: cmd2.utils.remove_duplicates - -.. autofunction:: cmd2.utils.alphabetical_sort - -.. autofunction:: cmd2.utils.natural_sort - .. autofunction:: cmd2.utils.basic_complete @@ -76,3 +70,9 @@ Miscellaneous .. autofunction:: cmd2.utils.namedtuple_with_defaults .. autofunction:: cmd2.utils.categorize + +.. autofunction:: cmd2.utils.remove_duplicates + +.. autofunction:: cmd2.utils.alphabetical_sort + +.. autofunction:: cmd2.utils.natural_sort diff --git a/docs/doc_conventions.rst b/docs/doc_conventions.rst index c37a4825..6adad4c9 100644 --- a/docs/doc_conventions.rst +++ b/docs/doc_conventions.rst @@ -159,6 +159,21 @@ comment instead of just #), or in a docstring after the definition. This project has standardized on the docstring after the definition approach. Do not use the specially formatted comment approach. +When using the Sphix ``autoclass`` directive, it must be preceded by two blank +lines like so: + +.. code-block:: rst + + Classes for storing the history of previously entered commands. + + + .. autoclass:: cmd2.history.History + :members: + + + .. autoclass:: cmd2.history.HistoryItem + :members: + Links to API Reference ---------------------- diff --git a/docs/examples/alternate_event_loops.rst b/docs/examples/alternate_event_loops.rst index 41e27369..b0ee7f8e 100644 --- a/docs/examples/alternate_event_loops.rst +++ b/docs/examples/alternate_event_loops.rst @@ -46,26 +46,27 @@ the main loop for the program by using code like the following:: app.postloop() -The **runcmds_plus_hooks()** method is a convenience method to run multiple -commands via **onecmd_plus_hooks()**. +The :meth:`~cmd2.Cmd.runcmds_plus_hooks()` method runs multiple commands via +:meth:`~cmd2.Cmd.onecmd_plus_hooks`. -The **onecmd_plus_hooks()** method will do the following to execute a single -``cmd2`` command in a normal fashion: +The :meth:`~cmd2.Cmd.onecmd_plus_hooks()` method will do the following to +execute a single command in a normal fashion: -#. Parse user input into `Statement` object -#. Call methods registered with `register_postparsing_hook()` +#. Parse user input into a :class:`~cmd2.Statement` object +#. Call methods registered with :meth:`~cmd2.Cmd.register_postparsing_hook()` #. Redirect output, if user asked for it and it's allowed #. Start timer -#. Call methods registered with `register_precmd_hook()` -#. Call `precmd()` - for backwards compatibility with ``cmd.Cmd`` -#. Add statement to history +#. Call methods registered with :meth:`~cmd2.Cmd.register_precmd_hook` +#. Call :meth:`~cmd2.Cmd.precmd` - for backwards compatibility with ``cmd.Cmd`` +#. Add statement to :ref:`features/history:History` #. Call `do_command` method -#. Call methods registered with `register_postcmd_hook()` -#. Call `postcmd(stop, statement)` - for backwards compatibility with +#. Call methods registered with :meth:`~cmd2.Cmd.register_postcmd_hook()` +#. Call :meth:`~cmd2.Cmd.postcmd` - for backwards compatibility with ``cmd.Cmd`` #. Stop timer and display the elapsed time #. Stop redirecting output if it was redirected -#. Call methods registered with `register_cmdfinalization_hook()` +#. Call methods registered with + :meth:`~cmd2.Cmd.register_cmdfinalization_hook()` Running in this fashion enables the ability to integrate with an external event loop. However, how to integrate with any specific event loop is beyond the @@ -75,8 +76,3 @@ with several disadvantages, including: * Requires the developer to write more code * Does not support transcript testing * Does not allow commands at invocation via command-line arguments - -Here is a little more info on ``runcmds_plus_hooks``: - -.. automethod:: cmd2.Cmd.runcmds_plus_hooks - :noindex: diff --git a/docs/features/history.rst b/docs/features/history.rst index 56c74ed7..c84b854c 100644 --- a/docs/features/history.rst +++ b/docs/features/history.rst @@ -4,14 +4,46 @@ History For Developers -------------- -- Describe how ``cmd2`` tracks history -- how persistent history works -- differences in history and bash shell history (we only store valid commands - in history) -- reference the public code structures we use to store history +The ``cmd`` module from the Python standard library includes ``readline`` +history. + +:class:`cmd2.Cmd` offers the same ``readline`` capabilities, but also maintains +it's own data structures for the history of all commands entered by the user. +When the class is initialized, it creates an instance of the +:class:`cmd2.history.History` class (which is a subclass of ``list``) as +:data:`cmd2.Cmd.history`. + +Each time a command is executed (this gets +complex, see :ref:`features/hooks:Command Processing Loop` for exactly when) +the parsed :class:`cmd2.Statement` is appended to :data:`cmd2.Cmd.history`. ``cmd2`` adds the option of making this history persistent via optional -arguments to :meth:`cmd2.Cmd.__init__`. +arguments to :meth:`cmd2.Cmd.__init__`. If you pass a filename in the +``persistent_history_file`` argument, the contents of :data:`cmd2.Cmd.history` +will be pickled into that history file. We chose to use pickle instead of plain +text so that we can save the results of parsing all the commands. + +.. note:: + + ``readline`` saves everything you type, whether it is a valid command or + not. ``cmd2`` only saves input to internal history if the command parses + successfully and is a valid command. This design choice was intentional, + because the contents of history can be saved to a file as a script, or can + be re-run. Not saving invalid input reduces unintentional errors when doing + so. + + However, this design choice causes an inconsistency between the + ``readline`` history and the ``cmd2`` history when you enter an invalid + command: it is saved to the ``readline`` history, but not to the ``cmd2`` + history. + +The :data:`cmd2.Cmd.history` attribute, the :class:`cmd2.history.History` +class, and the :class:`cmd2.history.HistoryItem` class are all part of the +public API for :class:`cmd2.Cmd`. You could use these classes to implement +write your own ``history`` command (see below for documentation on how the +included ``history`` command works). If you don't like pickled history, you +could implement your own mechanism for saving and loading history from a plain +text file. For Users @@ -236,4 +268,3 @@ If the entered command had no expansion, it is displayed as usual. However, if there is some change as the result of expanding macros and aliases, then the entered command is displayed with the number, and the expanded command is displayed with the number followed by an ``x``. - |