Updated docs and example

Author: kmvanbrunt

CHANGELOG.md

@@ -6,9 +6,9 @@
     also be colored.
         * `help_error` - the error that prints when no help information can be found
         * `default_error` - the error that prints when a non-existent command is run
-    * The `with_argparser` decorators now add a Statement object to the `argparse.Namespace` object they pass
-    to the `do_*` functions. It is stored in an attribute called `__statement__`. This can be useful if a command
-    function needs to know the command line for things like logging.
+    * The `with_argparser` decorators now add the Statement object created when parsing the command line to the
+    `argparse.Namespace` object they pass to the `do_*` methods. It is stored in an attribute called `__statement__`.
+    This can be useful if a command function needs to know the command line for things like logging.
 * Potentially breaking changes
     * The following commands now write to stderr instead of stdout when printing an error. This will make catching
     errors easier in pyscript.

cmd2/parsing.py

@@ -351,7 +351,7 @@ def tokenize(self, line: str, expand: bool = True) -> List[str]:
         :param expand: If True, then aliases and shortcuts will be expanded.
                        Set this to False if no expansion should occur because the command name is already known.
                        Otherwise the command could be expanded if it matched an alias name. This is for cases where
-                       a do_* function was called manually (e.g do_help('alias').
+                       a do_* method was called manually (e.g do_help('alias').
         :return: A list of tokens
         :raises ValueError if there are unclosed quotation marks.
         """
@@ -381,7 +381,7 @@ def parse(self, line: str, expand: bool = True) -> Statement:
         :param expand: If True, then aliases and shortcuts will be expanded.
                        Set this to False if no expansion should occur because the command name is already known.
                        Otherwise the command could be expanded if it matched an alias name. This is for cases where
-                       a do_* function was called manually (e.g do_help('alias').
+                       a do_* method was called manually (e.g do_help('alias').
         :return: A parsed Statement
         :raises ValueError if there are unclosed quotation marks
         """

docs/argument_processing.rst

@@ -10,8 +10,8 @@ Argument Processing
 1. Parsing input and quoted strings like the Unix shell
 2. Parse the resulting argument list using an instance of ``argparse.ArgumentParser`` that you provide
 3. Passes the resulting ``argparse.Namespace`` object to your command function. The ``Namespace`` includes the
-   ``Statement`` object that was parsed from the command line. It is stored in the ``__statement__`` attribute of
-   the ``Namespace``.
+   ``Statement`` object that was created when parsing the command line. It is stored in the ``__statement__``
+   attribute of the ``Namespace``.
 4. Adds the usage message from the argument parser to your command.
 5. Checks if the ``-h/--help`` option is present, and if so, display the help message for the command
 

examples/decorator_example.py

@@ -12,6 +12,7 @@
 """
 import argparse
 import sys
+from typing import List
 
 import cmd2
 
@@ -46,7 +47,7 @@ def __init__(self, ip_addr=None, port=None, transcript_files=None):
     speak_parser.add_argument('words', nargs='+', help='words to say')
 
     @cmd2.with_argparser(speak_parser)
-    def do_speak(self, args):
+    def do_speak(self, args: argparse.Namespace):
         """Repeats what you tell me to."""
         words = []
         for word in args.words:
@@ -67,13 +68,18 @@ def do_speak(self, args):
     tag_parser.add_argument('content', nargs='+', help='content to surround with tag')
 
     @cmd2.with_argparser(tag_parser)
-    def do_tag(self, args):
-        """create a html tag"""
+    def do_tag(self, args: argparse.Namespace):
+        """create an html tag"""
+        # The Namespace always includes the Statement object created when parsing the command line
+        statement = args.__statement__
+
+        self.poutput("The command line you ran was: {}".format(statement.command_and_args))
+        self.poutput("It generated this tag:")
         self.poutput('<{0}>{1}</{0}>'.format(args.tag, ' '.join(args.content)))
 
     @cmd2.with_argument_list
-    def do_tagg(self, arglist):
-        """verion of creating an html tag using arglist instead of argparser"""
+    def do_tagg(self, arglist: List[str]):
+        """version of creating an html tag using arglist instead of argparser"""
         if len(arglist) >= 2:
             tag = arglist[0]
             content = arglist[1:]