Changed @with_argument_parser to only pass single argument to commands

Also added another @with_argparser_and_list decorator that uses argparse.parse_known_args to pass two arguments to a command:  both the argparse output and a list of unknown/unmatched args.

1 files changed, 33 insertions, 10 deletions

diff --git a/docs/argument_processing.rst b/docs/argument_processing.rst
index 4ab4e12f..b4df68c1 100644
--- a/docs/argument_processing.rst
+++ b/docs/argument_processing.rst
@@ -20,7 +20,8 @@ For each command in the ``cmd2`` subclass which requires argument parsing,
 create an instance of ``argparse.ArgumentParser()`` which can parse the
 input appropriately for the command. Then decorate the command method with
 the ``@with_argument_parser`` decorator, passing the argument parser as the
-first parameter to the decorator. Add a third variable to the command method, which will contain the results of ``ArgumentParser.parse_args()``.
+first parameter to the decorator. This changes the second argumen to the command method, which will contain the results
+of ``ArgumentParser.parse_args()``.
 
 Here's what it looks like::
 
@@ -31,9 +32,8 @@ Here's what it looks like::
       argparser.add_argument('word', nargs='?', help='word to say')
 
       @with_argument_parser(argparser)
-      def do_speak(self, arglist, opts)
+      def do_speak(self, opts)
          """Repeats what you tell me to."""
-         # arglist contains a list of arguments as parsed by shlex.split()
          arg = opts.word
          if opts.piglatin:
             arg = '%s%say' % (arg[1:], arg[0])
@@ -43,8 +43,6 @@ Here's what it looks like::
          for i in range(min(repetitions, self.maxrepeats)):
             self.poutput(arg)
 
-This decorator also changes the value passed to the first argument of the ``do_*`` method. Instead of a string, the method will be passed a list of arguments as parsed by ``shlex.split()``.
-
 .. note::
 
    The ``@with_argument_parser`` decorator sets the ``prog`` variable in
@@ -65,7 +63,7 @@ appended to the docstring for the method of that command. With this code::
    argparser.add_argument('tag', nargs=1, help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argument_parser(argparser)
-   def do_tag(self, arglist, args=None):
+   def do_tag(self, args):
       """create a html tag"""
       self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
       self.stdout.write('\n')
@@ -91,7 +89,7 @@ If you would prefer the short description of your command to come after the usag
    argparser.add_argument('tag', nargs=1, help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argument_parser(argparser)
-   def do_tag(self, arglist, args=None):
+   def do_tag(self, args):
       self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
       self.stdout.write('\n')
 
@@ -120,7 +118,7 @@ To add additional text to the end of the generated help message, use the ``epilo
    argparser.add_argument('tag', nargs=1, help='tag')
    argparser.add_argument('content', nargs='+', help='content to surround with tag')
    @with_argument_parser(argparser)
-   def do_tag(self, cmdline, args=None):
+   def do_tag(self, args):
       self.stdout.write('<{0}>{1}</{0}>'.format(args.tag[0], ' '.join(args.content)))
       self.stdout.write('\n')
 
@@ -150,17 +148,42 @@ The default behavior of ``cmd2`` is to pass the user input directly to your
 
    class CmdLineApp(cmd2.Cmd):
       """ Example cmd2 application. """
-   
+
       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
 
 
+Using the argument parser decorator and also receiving a a list of unknown positional arguments
+===============================================================================================
+If you want all unknown arguments to be passed to your command as a list of strings, then
+decorate the command method with the ``@with_argparser_and_list`` decorator.
+
+Here's what it looks like::
+
+    dir_parser = argparse.ArgumentParser()
+    dir_parser.add_argument('-l', '--long', action='store_true', help="display in long format with one item per line")
+
+    @with_argparser_and_list(dir_parser)
+    def do_dir(self, args, unknown):
+        """List contents of current directory."""
+        # No arguments for this command
+        if unknown:
+            self.perror("dir does not take any positional arguments:", traceback_war=False)
+            self.do_help('dir')
+            self._last_result = CmdResult('', 'Bad arguments')
+            return
+
+        # Get the contents as a list
+        contents = os.listdir(self.cwd)
+
+        ...
+
 Deprecated optparse support
 ===========================