diff options
Diffstat (limited to 'docs/argument_processing.rst')
| -rw-r--r-- | docs/argument_processing.rst | 52 |
1 files changed, 38 insertions, 14 deletions
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")] |