Merge branch 'master' into black

# Conflicts:
#	cmd2/__init__.py
#	cmd2/argparse_completer.py
#	cmd2/argparse_custom.py
#	cmd2/cmd2.py
#	cmd2/decorators.py
#	cmd2/exceptions.py
#	cmd2/utils.py
#	examples/arg_decorators.py
#	examples/argparse_completion.py
#	examples/modular_commands_main.py
#	tests/test_argparse_completer.py
#	tests/test_argparse_custom.py
#	tests/test_cmd2.py
#	tests/test_completion.py
#	tests/test_history.py

5 files changed, 49 insertions, 20 deletions

diff --git a/docs/api/exceptions.rst b/docs/api/exceptions.rst
index db23eb0a..98afa97a 100644
--- a/docs/api/exceptions.rst
+++ b/docs/api/exceptions.rst
@@ -12,3 +12,6 @@ Custom cmd2 exceptions
 
 .. autoclass:: cmd2.exceptions.CommandSetRegistrationError
     :members:
+
+.. autoclass:: cmd2.exceptions.CompletionError
+    :members:
diff --git a/docs/api/utils.rst b/docs/api/utils.rst
index 0013bb7a..81c978c9 100644
--- a/docs/api/utils.rst
+++ b/docs/api/utils.rst
@@ -43,10 +43,28 @@ IO Handling
 Tab Completion
 --------------
 
-.. autoclass:: cmd2.utils.CompletionError
-    :members:
+.. autoclass:: cmd2.utils.CompletionMode
+
+    .. attribute:: NONE
+
+        Tab completion will be disabled during read_input() call. Use of custom
+        up-arrow history supported.
+
+    .. attribute:: COMMANDS
+
+        read_input() will tab complete cmd2 commands and their arguments.
+        cmd2's command line history will be used for up arrow if history is not
+        provided. Otherwise use of custom up-arrow history supported.
 
-.. autofunction:: cmd2.utils.basic_complete
+    .. attribute:: CUSTOM
+
+        read_input() will tab complete based on one of its following parameters
+        (choices, choices_provider, completer, parser). Use of custom up-arrow
+        history supported
+
+.. autoclass:: cmd2.utils.CustomCompletionSettings
+
+    .. automethod:: __init__
 
 
 Text Alignment
diff --git a/docs/features/argument_processing.rst b/docs/features/argument_processing.rst
index abe9a183..bcc68633 100644
--- a/docs/features/argument_processing.rst
+++ b/docs/features/argument_processing.rst
@@ -389,11 +389,7 @@ argparse arguments.
 
 - ``cmd2_statement`` - ``cmd2.Cmd2AttributeWrapper`` object containing
   ``cmd2.Statement`` object that was created when parsing the command line.
-- ``__statement__`` - ``cmd2.Statement`` object that was created when parsing
-  the command line. (This is deprecated and will be removed in 2.0.0.) Use
-  ``cmd2_statement`` instead.
-
-- ``__subcmd_handler__`` - used by cmd2 to identify the handler for a
-  subcommand created with ``@cmd2.as_subcommand_to`` decorator.
 - ``cmd2_handler`` - ``cmd2.Cmd2AttributeWrapper`` object containing
   a subcommand handler function or ``None`` if one was not set.
+- ``__subcmd_handler__`` - used by cmd2 to identify the handler for a
+  subcommand created with ``@cmd2.as_subcommand_to`` decorator.
diff --git a/docs/features/completion.rst b/docs/features/completion.rst
index 77a51136..3894a4eb 100644
--- a/docs/features/completion.rst
+++ b/docs/features/completion.rst
@@ -38,7 +38,7 @@ Included Tab Completion Functions
 ---------------------------------
 ``cmd2`` provides the following tab completion functions
 
-- :attr:`cmd2.utils.basic_complete` - helper method for tab completion against
+- :attr:`cmd2.Cmd.basic_complete` - helper method for tab completion against
   a list
 - :attr:`cmd2.Cmd.path_complete` - helper method provides flexible tab
   completion of file system paths
@@ -79,7 +79,7 @@ to be reported to the user. These include the following example cases:
   is invalid
 - Tab completion hints
 
-``cmd2`` provides the :class:`cmd2.utils.CompletionError` exception class for
+``cmd2`` provides the :class:`cmd2.exceptions.CompletionError` exception class for
 this capability. If an error occurs in which it is more desirable to display
 a message than a stack trace, then raise a ``CompletionError``. By default, the
 message displays in red like an error. However, ``CompletionError`` has a
@@ -89,24 +89,25 @@ completion hints.
 
 .. _argparse-based:
 
+
 Tab Completion Using argparse Decorators
 ----------------------------------------
 
 When using one the argparse-based :ref:`api/decorators:cmd2.decorators`,
 ``cmd2`` provides automatic tab completion of flag names.
 
-Tab completion of argument values can be configured by using one of five
+Tab completion of argument values can be configured by using one of three
 parameters to :meth:`argparse.ArgumentParser.add_argument`
 
 - ``choices``
-- ``choices_function`` or ``choices_method``
-- ``completer_function`` or ``completer_method``
+- ``choices_provider``
+- ``completer``
 
 See the arg_decorators_ or colors_ example for a demonstration of how to
 use the ``choices`` parameter. See the argparse_completion_ example for a
-demonstration of how to use the ``choices_function`` and ``choices_method``
-parameters. See the arg_decorators_ or argparse_completion_ example for a
-demonstration of how to use the ``completer_method`` parameter.
+demonstration of how to use the ``choices_provider`` parameter. See the
+arg_decorators_ or argparse_completion_ example for a demonstration
+of how to use the ``completer`` parameter.
 
 When tab completing flags or argument values for a ``cmd2`` command using
 one of these decorators, ``cmd2`` keeps track of state so that once a flag has
@@ -126,12 +127,23 @@ When tab completing things like a unique ID from a database, it can often be
 beneficial to provide the user with some extra context about the item being
 completed, such as a description.  To facilitate this, ``cmd2`` defines the
 :class:`cmd2.argparse_custom.CompletionItem` class which can be returned from
-any of the 4 completion functions: ``choices_function``, ``choices_method``,
-``completion_function``, or ``completion_method``.
+any of the 3 completion parameters: ``choices``, ``choices_provider``, and
+``completer``.
 
 See the argparse_completion_ example or the implementation of the built-in
 :meth:`~cmd2.Cmd.do_set` command for demonstration of how this is used.
 
+
+Custom Completion with ``read_input()``
+--------------------------------------------------
+
+``cmd2`` provides :attr:`cmd2.Cmd.read_input` as an alternative to Python's
+``input()`` function. ``read_input`` supports configurable tab completion and
+up-arrow history at the prompt. See read_input_ example for a demonstration.
+
+.. _read_input: https://github.com/python-cmd2/cmd2/blob/master/examples/read_input.py
+
+
 For More Information
 --------------------
 
diff --git a/docs/features/modular_commands.rst b/docs/features/modular_commands.rst
index 8bd9ba2f..fa643080 100644
--- a/docs/features/modular_commands.rst
+++ b/docs/features/modular_commands.rst
@@ -44,7 +44,7 @@ functions with ``help_``, and completer functions with ``complete_``.
 
 A new decorator ``with_default_category`` is provided to categorize all commands within a CommandSet in the
 same command category.  Individual commands in a CommandSet may be override the default category by specifying a
-specific category with ``cmd.with_category``.
+specific category with ``cmd2.with_category``.
 
 CommandSet command methods will always expect the same parameters as when defined in a ``cmd2.Cmd`` sub-class,
 except that ``self`` will now refer to the ``CommandSet`` instead of the cmd2 instance. The cmd2 instance can