# HG changeset patch # User Catherine Devlin # Date 1289610201 18000 # Node ID f16f444a4d10bbc4481ca9aa60685139d47ba592 # Parent 5bd1d2b11548172530bdb93f6e075229c650bd6b added arg_desc to @options, thanks Renzo Crispiatico diff -r 5bd1d2b11548 -r f16f444a4d10 cmd2.py --- a/cmd2.py Tue Nov 09 05:23:56 2010 -0500 +++ b/cmd2.py Fri Nov 12 20:03:21 2010 -0500 @@ -97,7 +97,7 @@ options_defined = [] # used to distinguish --options from SQL-style --comments -def options(option_list): +def options(option_list, arg_desc="arg"): '''Used as a decorator and passed a list of optparse-style options, alters a cmd2 method to populate its ``opts`` argument from its raw text argument. @@ -107,7 +107,8 @@ into @options([make_option('-q', '--quick', action="store_true", - help="Makes things fast")]) + help="Makes things fast")], + "source dest") def do_something(self, arg, opts): if opts.quick: self.fast_button = True @@ -120,7 +121,7 @@ optionParser = OptionParser() for opt in option_list: optionParser.add_option(opt) - optionParser.set_usage("%s [options] arg" % func.__name__[3:]) + optionParser.set_usage("%s [options] %s" % (func.__name__[3:], arg_desc)) optionParser._func = func def new_func(instance, arg): try: diff -r 5bd1d2b11548 -r f16f444a4d10 docs/unfreefeatures.rst --- a/docs/unfreefeatures.rst Tue Nov 09 05:23:56 2010 -0500 +++ b/docs/unfreefeatures.rst Fri Nov 12 20:03:21 2010 -0500 @@ -28,16 +28,16 @@ grammar applied to ``arg``. It may include: command - Name of the command called + Name of the command called raw - Full input exactly as typed. + Full input exactly as typed. terminator - Character used to end a multiline command + Character used to end a multiline command suffix - Remnant of input after terminator + Remnant of input after terminator :: @@ -46,17 +46,17 @@ :: - (Cmd) parsereport A B /* C */ D; E - ['parsereport', 'A B D', ';', 'E'] - - args: A B D - - command: parsereport - - raw: parsereport A B /* C */ D; E - - statement: ['parsereport', 'A B D', ';'] - - args: A B D - - command: parsereport - - terminator: ; - - suffix: E - - terminator: ; + (Cmd) parsereport A B /* C */ D; E + ['parsereport', 'A B D', ';', 'E'] + - args: A B D + - command: parsereport + - raw: parsereport A B /* C */ D; E + - statement: ['parsereport', 'A B D', ';'] + - args: A B D + - command: parsereport + - terminator: ; + - suffix: E + - terminator: ; If ``parsed`` does not contain an attribute, querying for it will return ``None``. (This @@ -67,7 +67,7 @@ process are painfully complex and should not be considered stable; future ``cmd2`` releases may change it somewhat (hopefully reducing complexity). - + (Getting ``arg`` as a ``ParsedString`` is technically "free", in that it requires no application changes from the cmd_ standard, but there will @@ -95,7 +95,7 @@ degrees_c = 22 sunny = False settable = Cmd.settable + '''degrees_c temperature in Celsius - sunny''' + sunny''' def do_sunbathe(self, arg): if self.degrees_c < 20: result = "It's {temp} C - are you a penguin?".format(temp=self.degrees_c) @@ -106,7 +106,7 @@ self.stdout.write(result + '\n') app = App() app.cmdloop() - + :: (Cmd) set --long @@ -145,9 +145,9 @@ :: @options([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") - ]) + make_option('-s', '--shout', action="store_true", help="N00B EMULATION MODE"), + make_option('-r', '--repeat', type="int", help="output [n] times") + ]) def do_speak(self, arg, opts=None): """Repeats what you tell me to.""" arg = ''.join(arg) @@ -162,14 +162,36 @@ :: - (Cmd) say goodnight, gracie - goodnight, gracie - (Cmd) say -sp goodnight, gracie - OODNIGHT, GRACIEGAY - (Cmd) say -r 2 --shout goodnight, gracie - GOODNIGHT, GRACIE - GOODNIGHT, GRACIE + (Cmd) say goodnight, gracie + goodnight, gracie + (Cmd) say -sp goodnight, gracie + OODNIGHT, GRACIEGAY + (Cmd) say -r 2 --shout goodnight, gracie + GOODNIGHT, GRACIE + GOODNIGHT, GRACIE + +``options`` takes an optional additional argument, ``arg_desc``. +If present, ``arg_desc`` will appear in place of ``arg`` in +the option's online help. + +:: + @options([make_option('-t', '--train', action='store_true', help='by train')], + arg_desc='(from city) (to city)') + def do_travel(self, arg, opts=None): + 'Gets you from (from city) to (to city).' + + +:: + + (Cmd) help travel + Gets you from (from city) to (to city). + Usage: travel [options] (from-city) (to-city) + + Options: + -h, --help show this help message and exit + -t, --train by train + .. _optparse: .. _outputters: @@ -182,9 +204,9 @@ ``self.poutput('output')``, ``self.pfeedback('message')``, and ``self.perror('errmsg')`` instead. These methods have these advantages: - - More concise - - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. - +- More concise + - ``.pfeedback()`` destination is controlled by :ref:`quiet` parameter. + color ===== @@ -212,17 +234,18 @@ .. automethod:: cmd2.Cmd.select :: - + def do_eat(self, arg): sauce = self.select('sweet salty', 'Sauce? ') result = '{food} with {sauce} sauce, yum!' result = result.format(food=arg, sauce=sauce) self.stdout.write(result + '\n') - + :: - (Cmd) eat wheaties - 1. sweet - 2. salty - Sauce? 2 - wheaties with salty sauce, yum! + (Cmd) eat wheaties + 1. sweet + 2. salty + Sauce? 2 + wheaties with salty sauce, yum! + \ No newline at end of file diff -r 5bd1d2b11548 -r f16f444a4d10 example/example.py --- a/example/example.py Tue Nov 09 05:23:56 2010 -0500 +++ b/example/example.py Fri Nov 12 20:03:21 2010 -0500 @@ -12,7 +12,7 @@ @options([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") - ]) + ], arg_desc = '(text to say)') def do_speak(self, arg, opts=None): """Repeats what you tell me to.""" arg = ''.join(arg) diff -r 5bd1d2b11548 -r f16f444a4d10 example/exampleSession.txt --- a/example/exampleSession.txt Tue Nov 09 05:23:56 2010 -0500 +++ b/example/exampleSession.txt Fri Nov 12 20:03:21 2010 -0500 @@ -12,7 +12,7 @@ (Cmd) help say Repeats what you tell me to. -Usage: speak [options] arg +Usage: speak [options] (text to say) Options: -h, --help show this help message and exit