Merge pull request #263 from python-cmd2/argparser_docs

Improved argument processing docs

Author: tleonhardt

README.md

@@ -108,12 +108,15 @@ Instructions for implementing each feature follow.
 
 - Parsing commands with `argparse`
 
-    ```python
+    ```Python
+    import argparse
+    from cmd2 import with_argparser
+
     argparser = argparse.ArgumentParser()
     argparser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
     argparser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
     argparser.add_argument('words', nargs='+', help='words to say')
-    @with_argument_parser(argparser)
+    @with_argparser(argparser)
     def do_speak(self, args):
         """Repeats what you tell me to."""
         words = []
@@ -154,7 +157,7 @@ A sample application for cmd2.
 import random
 import argparse
 
-from cmd2 import Cmd, with_argument_parser
+from cmd2 import Cmd, with_argparser
 
 
 class CmdLineApp(Cmd):
@@ -178,12 +181,12 @@ class CmdLineApp(Cmd):
         # Set use_ipython to True to enable the "ipy" command which embeds and interactive IPython shell
         Cmd.__init__(self, use_ipython=False)
 
-    argparser = argparse.ArgumentParser()
-    argparser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
-    argparser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
-    argparser.add_argument('-r', '--repeat', type=int, help='output [n] times')
-    argparser.add_argument('words', nargs='+', help='words to say')
-    @with_argument_parser(argparser)
+    speak_parser = argparse.ArgumentParser()
+    speak_parser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
+    speak_parser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
+    speak_parser.add_argument('-r', '--repeat', type=int, help='output [n] times')
+    speak_parser.add_argument('words', nargs='+', help='words to say')
+    @with_argparser(speak_parser)
     def do_speak(self, args):
         """Repeats what you tell me to."""
         words = []
@@ -201,10 +204,10 @@ class CmdLineApp(Cmd):
     do_say = do_speak  # now "say" is a synonym for "speak"
     do_orate = do_speak  # another synonym, but this one takes multi-line input
 
-    argparser = argparse.ArgumentParser()
-    argparser.add_argument('-r', '--repeat', type=int, help='how many times to repeat')
-    argparser.add_argument('words', nargs='+', help='words to say')
-    @with_argument_parser(argparser)
+    mumble_parser = argparse.ArgumentParser()
+    mumble_parser.add_argument('-r', '--repeat', type=int, help='how many times to repeat')
+    mumble_parser.add_argument('words', nargs='+', help='words to say')
+    @with_argparser(mumble_parser)
     def do_mumble(self, args):
         """Mumbles what you tell me to."""
         repetitions = args.repeat or 1

cmd2.py

@@ -122,7 +122,7 @@
 
 
 # The next 3 variables and associated setter functions effect how arguments are parsed for decorated commands
-#   which use one of the decorators such as @with_argument_list or @with_argument_parser
+#   which use one of the decorators such as @with_argument_list or @with_argparser
 # The defaults are sane and maximize ease of use for new applications based on cmd2.
 # To maximize backwards compatibility, we recommend setting USE_ARG_LIST to "False"
 

docs/argument_processing.rst

@@ -13,7 +13,13 @@ Argument Processing
 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
 
-These features are all provided by the ``@with_argparser`` decorator.
+These features are all provided by the ``@with_argparser`` decorator which is importable from ``cmd2``.
+
+See the either the argprint_ or argparse_ example to learn more about how to use the various ``cmd2`` argument
+processing decorators in your ``cmd2`` applications.
+
+.. _argprint: https://github.com/python-cmd2/cmd2/blob/master/examples/arg_print.py
+.. _argparse: https://github.com/python-cmd2/cmd2/blob/master/examples/argparse_example.py
 
 Using the argument parser decorator
 ===================================
@@ -27,6 +33,9 @@ of ``ArgumentParser.parse_args()``.
 
 Here's what it looks like::
 
+      import argparse
+      from cmd2 import with_argparser
+
       argparser = argparse.ArgumentParser()
       argparser.add_argument('-p', '--piglatin', action='store_true', help='atinLay')
       argparser.add_argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
@@ -61,6 +70,9 @@ for help on the command. When you use the ``@with_argparser``
 decorator, the docstring for the ``do_*`` method is used to set the description for the ``argparse.ArgumentParser`` is
 With this code::
 
+   import argparse
+   from cmd2 import with_argparser
+
    argparser = argparse.ArgumentParser()
    argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
@@ -89,6 +101,9 @@ The ``help tag`` command displays:
 If you would prefer you can set the ``description`` while instantiating the ``argparse.ArgumentParser`` and leave the
 docstring on your method empty::
 
+   import argparse
+   from cmd2 import with_argparser
+
    argparser = argparse.ArgumentParser(description='create an html tag')
    argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
@@ -115,10 +130,11 @@ Now when the user enters ``help tag`` they see:
 
 To add additional text to the end of the generated help message, use the ``epilog`` variable::
 
-   argparser = argparse.ArgumentParser(
-      description='create an html tag',
-      epilog='This command can not generate tags with no content, like <br/>.'
-   )
+   import argparse
+   from cmd2 import with_argparser
+
+   argparser = argparse.ArgumentParser(description='create an html tag',
+                                       epilog='This command can not generate tags with no content, like <br/>.')
    argparser.add_argument('tag', help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argparser(argparser)
@@ -150,17 +166,19 @@ Receiving an argument list
 The default behavior of ``cmd2`` is to pass the user input directly to your
 ``do_*`` methods as a string. If you don't want to use the full argument parser support outlined above, you can still have ``cmd2`` apply shell parsing rules to the user input and pass you a list of arguments instead of a string. Apply the ``@with_argument_list`` decorator to those methods that should receive an argument list instead of a string::
 
-   class CmdLineApp(cmd2.Cmd):
-      """ Example cmd2 application. """
+    from cmd2 import with_argument_list
+
+    class CmdLineApp(cmd2.Cmd):
+        """ Example cmd2 application. """
 
-      def do_say(self, cmdline):
-         # cmdline contains a string
-         pass
+        def do_say(self, cmdline):
+            # cmdline contains a string
+            pass
 
-      @with_argument_list
-      def do_speak(self, arglist):
-         # arglist contains a list of arguments
-         pass
+        @with_argument_list
+        def do_speak(self, arglist):
+            # arglist contains a list of arguments
+            pass
 
 
 Using the argument parser decorator and also receiving a a list of unknown positional arguments
@@ -170,6 +188,9 @@ decorate the command method with the ``@with_argparser_and_unknown_args`` decora
 
 Here's what it looks like::
 
+    import argparse
+    from cmd2 import with_argparser_and_unknown_args
+
     dir_parser = argparse.ArgumentParser()
     dir_parser.add_argument('-l', '--long', action='store_true', help="display in long format with one item per line")
 
@@ -209,6 +230,9 @@ recommends using ``argparse`` instead.
 
 Here's an example::
 
+   from optparse import make_option
+   from cmd2 import options
+
    opts = [make_option('-p', '--piglatin', action="store_true", help="atinLay"),
            make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"),
            make_option('-r', '--repeat', type="int", help="output [n] times")]