diff options
| -rwxr-xr-x | README.md | 29 | ||||
| -rwxr-xr-x | cmd2.py | 2 | ||||
| -rw-r--r-- | docs/argument_processing.rst | 52 |
3 files changed, 55 insertions, 28 deletions
@@ -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 @@ -122,7 +122,7 @@ pyparsing.ParserElement.setDefaultWhitespaceChars(' \t') # 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" diff --git a/docs/argument_processing.rst b/docs/argument_processing.rst index 2a433bc7..957c842a 100644 --- a/docs/argument_processing.rst +++ b/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")] |