===================
Argument Processing
===================

cmd2 currently includes code which makes it easier to add arguments to the
commands in your cmd2 subclass. This support utilizes the optparse library,
which has been deprecated since Python 2.7 (released on July 3rd 2010) and
Python 3.2 (released on February 20th, 2011). Optparse is still included in the
python standard library, but the documentation recommends using argparse
instead. It's time to modernize cmd2 to utilize argparse.

I don't believe there is a way to change cmd2 to use argparse instead of
optparse without requiring subclasses of cmd2 to make some change. The long
recomended way to use optparse in cmd2 includes the use of the
optparse.make_option, which must be changed in order to use argparse.

There are two potential ways to use argument parsing with cmd2: to parse
options given at the shell prompt when invoked, and to parse options given at
the cmd2 prompt prior to executing a command.

optparse example
================

Here's an example of the current optparse support:

      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")]

      @options(opts, arg_desc='(text to say)')
      def do_speak(self, arg, opts=None):
        """Repeats what you tell me to."""
        arg = ''.join(arg)
        if opts.piglatin:
            arg = '%s%say' % (arg[1:], arg[0])
        if opts.shout:
            arg = arg.upper()
        repetitions = opts.repeat or 1
        for i in range(min(repetitions, self.maxrepeats)):
            self.poutput(arg)

The current optparse decorator performs the following key functions for you:

1.  Use `shlex` to split the arguments entered by the user.
2.  Parse the arguments using the given optparse options.
3.  Replace the `__doc__` string of the decorated function (i.e. do_speak) with
the help string generated by optparse.
4.  Call the decorated function (i.e. do_speak) passing an additional parameter
which contains the parsed options.

Here are several options for replacing this functionality with argparse.


No cmd2 support
===============

The easiest option would be to just remove the cmd2 specific support for
argument parsing. The above example would then look something like this:

      argparser = argparse.ArgumentParser(
          prog='speak',
          description='Repeats what you tell me to'
      )
      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('word', nargs='?', help='word to say')

      def do_speak(self, argv)
        """Repeats what you tell me to."""
        opts = argparser.parse_args(shlex.split(argv, posix=POSIX_SHLEX))
        arg = opts.word
        if opts.piglatin:
            arg = '%s%say' % (arg[1:], arg[0])
        if opts.shout:
            arg = arg.upper()
        repetitions = opts.repeat or 1
        for i in range(min(repetitions, self.maxrepeats)):
            self.poutput(arg)

Using shlex in this example is technically not necessary because the `do_speak`
command only expects a single word argument. It is included here to show what
would be required to replicate the current optparse based functionality.


A single argparse specific decorator
====================================

In this approach, we would create one new decorator, perhaps called
`with_argument_parser`. This single decorator would take as it's argument a fully
defined `argparse.ArgumentParser`. This decorator would shelx the user input,
apply the ArgumentParser, and pass the resulting object to the decorated method, like so:

      argparser = argparse.ArgumentParser(
          prog='speak',
          description='Repeats what you tell me to'
      )
      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('word', nargs='?', help='word to say')

      @with_argument_parser(argparser)
      def do_speak(self, argv, opts)
        """Repeats what you tell me to."""
        arg = opts.word
        if opts.piglatin:
            arg = '%s%say' % (arg[1:], arg[0])
        if opts.shout:
            arg = arg.upper()
        repetitions = opts.repeat or 1
        for i in range(min(repetitions, self.maxrepeats)):
            self.poutput(arg)

Compared to the no argparse support in cmd2 approach, this replaces a line of
code with a nested function with a decorator without a nested function.


A whole bunch of argparse specific decorators
=============================================

This approach would turn out something like the climax library
(https://github.com/miguelgrinberg/climax), which includes a decorator for each method available
on the `ArgumentParser()` object. Our `do_speak` command would look like this:

      @command()
      @argument('-p', '--piglatin', action='store_true', help='atinLay')
      @argument('-s', '--shout', action='store_true', help='N00B EMULATION MODE')
      @argument('r', '--repeat', type='int', help='output [n] times')
      @add_argument('word', nargs='?', help='word to say')
      def do_speak(self, argv, piglatin, shout, repeat, word)
        """Repeats what you tell me to."""
        arg = word
        if piglatin:
            arg = '%s%say' % (arg[1:], arg[0])
        if shout:
            arg = arg.upper()
        repetitions = repeat or 1
        for i in range(min(repetitions, self.maxrepeats)):
            self.poutput(arg)