Fixes Issue #595 document search in interactive mode

This pr documents an option of the prompt-toolkit to allow incrementally
searching the history file in interactive mode.

The search options is initiated by <CTRL-r> and does an incremental
search based on a string entered after the <CTRL-r> returning the last
command in the command history that contains the the string.  The
string may be modified or <UP_ARROW>, <DOWN-ARROW> may will find
other instances of the string.

It changes the repl help text and the doc files to provide documentation on
this search option and a simple example.

There are no code changes and no tests for the search command.

We added some doc index entries also.

docs/changes.rst

@@ -229,6 +229,9 @@ Released: 2020-04-10
 * Added table formatted output for connection show and removed original
   free-form output format. (See issue #572)
 
+* Added documentation on incremental search option to search the command
+  history file in interactive mode. (See issue #595)
+
 
 pywbemtools 0.5.0
 -----------------

docs/pywbemcli/cmdlineinterface.rst

@@ -79,7 +79,7 @@ and ``--namespace`` is a command option.
    single: auto-suggestion
 
 Pywbemcli supports several modes of tab-completion, auto-completion suggestions
-and depending on whether it is in command or interactive mode. This is detailed
+depending on whether it is in command or interactive mode. This is detailed
 in the following sections.
 
 
@@ -100,6 +100,8 @@ Pywbemcli supports two modes of operation:
 Command mode
 ------------
 
+.. index:: command mode
+
 In command mode, the pywbemcli command performs its task and terminates
 like any other standalone non-interactive command.
 
@@ -121,12 +123,15 @@ WBEM server on ``localhost``:
     <Returns MOF for the enumerated classes>
 
 .. index::
-   single: tab-completion
-   single: auto-completion
+   pair: tab-completion; command mode
+   pair: auto-completion; command mode
 
 In command mode, tab completion is also supported for some command shells, but
 must be enabled specifically for each shell.
 
+.. index::
+   pair: command mode; bash
+
 For example, with a bash shell, enter the following to enable tab completion of
 pywbemcli:
 
@@ -224,6 +229,9 @@ above has the same effect as the standalone command:
     $ pywbemcli -s http://localhost -d root/cimv2 -u username class get CIM_System
     . . . <Class CIM_System in the default namespace in MOF format>
 
+
+.. index:: pair: interactive mode; help
+
 The internal commands ``:?``, ``:h``, or ``:help`` display general help
 information for external and internal commands:
 
@@ -240,10 +248,14 @@ information for external and internal commands:
         :?, :h, :help     displays general help information
         :exit, :q, :quit  exits the REPL
 
+.. index:: pair: interactive mode; exit
+
 In addition to using one of the internal exit commands shown in the help text
 above, you can also exit the pywbemcli shell by typing `Ctrl-D` (on Linux,
 OS-X and UNIX-like environments on Windows), or `Ctrl-C` (on native Windows).
 
+.. index:: pair: interactive mode; --help
+
 Typing ``--help`` or ``-h`` in the pywbemcli shell displays general help
 information for the pywbemcli commands which includes general options and a
 list of the supported command groups and commands without command group.
@@ -267,6 +279,8 @@ list of the supported command groups and commands without command group.
 The usage line in this help text shows the usage in command mode. In
 interactive mode, the ``pywbemcli`` word is omitted.
 
+.. index:: pair: interactive mode; command help
+
 Typing ``COMMAND --help``,  or ``COMMAND -h`` in the pywbemcli shell
 displays help information for the specified pywbemcli command group, for
 example:
@@ -285,15 +299,15 @@ example:
       . . .
 
 .. index::
-   single: tab-completion
-   single: auto-completion
-   single: auto-suggestion
+   pair: tab-completion; interactive mode
+   pair: auto-completion; interactive mode
 
-The pywbemcli shell in the interactive mode supports popup help text
-while for commands, arguments, and options typing, where the valid choices are shown based upon what was typed so
-far, and where an item from the popup list can be picked with <TAB> or with the
-cursor keys. It can be used to select from the list of general options. In the
-following examples, an underscore ``_`` is shown as the cursor:
+The pywbemcli shell in the interactive mode supports popup help text while for
+commands, arguments, and options typing, where the valid choices are shown
+based upon what was typed so far, and where an item from the popup list can be
+picked with <TAB> or with the cursor keys. It can be used to select from the
+list of general options. In the following examples, an underscore ``_`` is
+shown as the cursor:
 
 .. code-block:: text
 
@@ -306,15 +320,42 @@ following examples, an underscore ``_`` is shown as the cursor:
     pywbemcli> cl_
                   class
 
-.. index::
-   single: command history
+.. index:: pair: command history; interactive mode
 
 The pywbemcli shell supports history across multiple invocations of the shell
-using <UP-ARROW>, <DOWN-ARROW>.
-The pywbemcli history is stored in ``~/.pywbemcli_history``.
+using <UP_ARROW>, <DOWN-ARROW> to step through the history line by line.
 
 .. index::
-   single: auto-suggestion
+   single: command history; search
+   pair: interactive mode; command history
+
+A incremental search of the history can be initiated by entering <CTRL-r>
+followed by one or more characters that define the search. The search displays
+the last command containing the search string. This search string can be
+modified in place to change the search, returning the last command in the
+command history that contains the the string. <UP_ARROW>, <DOWN-ARROW> will
+find other commands in the history containing the same string.
+
+.. code-block:: text
+
+    pywbemcli> <CTRL-r>
+    (reverse-i-search)`':
+                                                        ENTER Characters CIM
+    (reverse-i-search)`CIM': class get CIM_ManagedElement
+                                                        <UP-ARROW> and <DOWN-ARROW> find
+                                                        other commands containing of "CIM"
+
+    <DOWN_ARROW>
+    (i-search)`get': instance get CIM_ComputerSystem.?
+                                                        Hit <ENTER> selects current found command
+    pywbemcli> instance get CIM_ComputerSystem.?
+
+.. index:: pair: interactive mode; history file
+
+The pywbemcli history is stored in the user home directory, ``~/.pywbemcli_history``.
+
+.. index::
+   pair: interactive mode; auto-suggestion
 
 The pywbemcli interactive mode also supports automated parameter suggestions based on
 the pywbemcli history file which works with the auto completion described
@@ -329,6 +370,8 @@ suggestion.
 Error handling
 --------------
 
+.. index:: Exit codes
+
 Pywbemcli terminates with one of the following program exit codes:
 
 * **0 - Success**: The pywbemcli command has succeeded.

docs/pywbemcli/cmdshelp.rst

@@ -1605,6 +1605,11 @@ Help text for ``pywbemcli repl`` (see :ref:`repl command`):
 
       Pywbemcli may be terminated from this mode by entering <CTRL-D>, :q, :quit, :exit
 
+      In the repl mode, <CTRL-r> man be used to initiate an interactive search of the history file.
+
+      Interactive mode also includes an autosuggest feature that makes suggestions from the command history as the command
+      the user types in the command and options.
+
     Command Options:
       -h, --help  Show this help message.
 

docs/pywbemcli/commands.rst

@@ -137,8 +137,7 @@ If the ``--deep-inheritance``/``--di`` command option is set, all direct and
 indirect subclasses are included in the result. Otherwise, only one level of
 the class hierarchy is in the result.
 
-.. index::
-   single: qualifier filters
+.. index:: single: qualifier filters
 
 The ``--association``/``--no-association``, ``--indication``/``--no-indication``,
 and ``--experimental``/``--no-experimental`` options filter the returned
@@ -171,8 +170,7 @@ argument in all namespaces of the connection, or otherwise in the specified
 namespaces if the ``-namespace``/``-n`` command option is specified one or more
 times.
 
-.. index::
-   single: qualifier filters
+.. index:: qualifier filters
 
 The ``--association``/``--no-association``, ``--indication``/``--no-indication``,
 and ``--experimental``/``--no-experimental`` options filter the returned
@@ -1465,6 +1463,9 @@ See :ref:`pywbemcli connection select --help` for the exact help output of the c
 Connection show command
 ^^^^^^^^^^^^^^^^^^^^^^^
 
+.. index:: single: connection show command
+.. index:: pair: command; connection show
+
 The ``connection show`` command shows information about a connection definition:
 
 * If ``NAME`` is ``?``, pywbemcli prompts the user to select one and shows
@@ -1496,6 +1497,10 @@ See :ref:`pywbemcli connection show --help` for the exact help output of the com
 Connection test command
 ^^^^^^^^^^^^^^^^^^^^^^^
 
+.. index::
+    single: connection test command
+    pair: command; connection test
+
 The ``connection test`` command executes a single predefined operation on
 the current connection to verify that accessing the WBEM server works.
 
@@ -1520,6 +1525,10 @@ See :ref:`pywbemcli connection test --help` for the exact help output of the com
 Repl command
 ------------
 
+.. index::
+    single: repl command
+    pair: command; repl
+
 The ``repl`` command sets pywbemcli into the :ref:`interactive mode`. Pywbemcli
 can be started in the :ref:`interactive mode` either by entering:
 
@@ -1539,12 +1548,29 @@ or by executing the script without any command or command group:
 
 The repl mode is recognized by the prompt ``pywbemcli>``.
 
+Command history is available in the :ref:`interactive mode` either by using
+<UP-ARROW> and <DOWN-ARROW> keys to step through the history file or by using
+incremental search of the command history.
+
+The incremental search is initiated by <CTRL-r> and does a search based on a
+string entered after the <CTRL-r> for the last command containing the search
+string. The search string may be modified and <UP_ARROW>, <DOWN-ARROW> will
+find other commands containing the search string. Hitting <ENTER> selects
+the currently shown command.
+
+see :ref:`interactive mode` for more details on using this mode and the
+search.
+
 
 .. _`Help command`:
 
 Help command
 ------------
 
+.. index::
+    single: help command
+    pair: help; command
+
 The ``help`` command provides information on special commands and controls
 that can be executed in the :ref:`interactive mode` including:
 

pywbemtools/pywbemcli/pywbemcli.py

@@ -610,6 +610,10 @@ def repl_help(ctx):  # pylint: disable=unused-argument
   COMMAND                     Execute pywbemcli command COMMAND.
   !SHELL-CMD                  Execute shell command SHELL-CMD.
   <CTRL-D>, :q, :quit, :exit  Exit interactive mode.
+  <CTRL-r>  <search string>   To search the  command history file.
+                              Can be used with <UP>, <DOWN>
+                              to display commands that match the search string.
+                              Editing the search string updates the search.
   <TAB>                       Tab completion (can be used anywhere).
   -h, --help                  Show pywbemcli general help message, including a
                               list of pywbemcli commands.
@@ -639,13 +643,21 @@ def repl(ctx):
 
     Pywbemcli may be terminated from this mode by entering
     <CTRL-D>, :q, :quit, :exit
+
+    In the repl mode, <CTRL-r> man be used to initiate an interactive
+    search of the history file.
+
+    Interactive mode also includes an autosuggest feature that makes
+    suggestions from the command history as the command the user types in the
+    command and options.
     """
 
     history_file = PYWBEMCLI_HISTORY_FILE
     if history_file.startswith('~'):
         history_file = os.path.expanduser(history_file)
 
-    click.echo("Enter 'help' for help, <CTRL-D> or ':q' to exit pywbemcli.")
+    click.echo("Enter 'help' for help, <CTRL-D> or ':q' "
+               "to exit pywbemcli or <CTRL-r> to search history, ")
 
     prompt_kwargs = {
         'message': PYWBEMCLI_PROMPT,

tests/unit/test_general_options.py

@@ -161,15 +161,20 @@ class       Command group for CIM classes.
 
   Enter interactive mode (default).
 
-  Enter the interactive mode where pywbemcli commands can be entered interactively. The prompt is changed to
-  'pywbemcli>'.
+  Enter the interactive mode where pywbemcli commands can be entered interactively. The prompt is changed to 'pywbemcli>'.
 
   Command history is supported. The command history is stored in a file ~/.pywbemcli_history.
 
   Pywbemcli may be terminated from this mode by entering <CTRL-D>, :q, :quit, :exit
 
+  In the repl mode, <CTRL-r> man be used to initiate an interactive search of the history file.
+
+  Interactive mode also includes an autosuggest feature that makes suggestions from the command history as the command the user types in the
+  command and options.
+
 Command Options:
   -h, --help  Show this help message.
+
 """  # noqa: E501
 
 INTERACTIVE_HELP = """
@@ -178,6 +183,10 @@ class       Command group for CIM classes.
   COMMAND                     Execute pywbemcli command COMMAND.
   !SHELL-CMD                  Execute shell command SHELL-CMD.
   <CTRL-D>, :q, :quit, :exit  Exit interactive mode.
+  <CTRL-r>  <search string>   To search the  command history file.
+                              Can be used with <UP>, <DOWN>
+                              to display commands that match the search string.
+                              Editing the search string updates the search.
   <TAB>                       Tab completion (can be used anywhere).
   -h, --help                  Show pywbemcli general help message, including a
                               list of pywbemcli commands.
@@ -186,6 +195,9 @@ class       Command group for CIM classes.
   :?, :h, :help               Show help message about interactive mode.
   <UP>, <DOWN>                Scroll through pwbemcli command history.
 
+  COMMAND: May be two words (class enumerate) for commands that are within
+  a group or a single word for special commands like `repl` that are not in
+  a group.
 """
 
 OK = True     # mark tests OK when they execute correctly
@@ -213,7 +225,7 @@ class       Command group for CIM classes.
      {'stdout': GENERAL_HELP,
       'rc': 0,
       'test': 'innows'},
-     None, RUN],
+     None, OK],
 
     ['Verify -h response.',
      {'general': ['--help'],
@@ -224,7 +236,7 @@ class       Command group for CIM classes.
       'test': 'innows'},
      None, OK],
 
-    ['Verify repl -help response.',
+    ['Verify repl -h option shows REPL help',
      {'general': [],
       'cmdgrp': 'repl',
       'args': ['-h']},