Mercurial > hg > CommandParser

comparison README.txt @ 12:e0a3148e67a8

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
bug fix and a short overhaul of documentation
author Jeff Hammel <jhammel@mozilla.com>
date Mon, 28 Jan 2013 19:54:36 -0800
parents a41537c4284f
children cf6b34894b68
comparison
equal deleted inserted replaced
11:03db23600c1f 12:e0a3148e67a8
1 CommandParser 1 CommandParser
2 =========== 2 =============
3 3
4 change objects to OptionParser instances via reflection 4 change objects to OptionParser instances via reflection
5
6 Overview
7 --------
8
9 It is a common pattern for command line interfaces to use subcomands (e.g.):
10
11 hg commit -m 'foo bar'
12 git push origin master
13
14 CommandParser does this via introspection of a given class. When
15 invoked with a class, CommandParser uses the inspect module to pull
16 out the mandatory and optional arguments for each of the class's
17 methods, which are translated to subcommands, and make a OptionParser
18 instance from them. ``%prog help`` will then display all of the
19 subcommands and ``%prog help <subcommand>`` will give you help on the
20 ``<subcommand>`` chosen. Methods beginning with an underscore (`_`)
21 are passed over. This gives an easy way to translate an API class
22 into a command line program::
23
24 class Foo(object):
25 """silly class that does nothing"""
26 def __init__(self): pass
27 def foo(self, value):
28 print "The value is %s" % value
29 def bar(self, fleem, verbose=False):
30 """
31 The good ole `bar` command
32 - fleem: you know, that thing fleem
33 - verbose: whether to print out more things or not
34 """
35 if verbose:
36 print "You gave fleem=%s" % fleem
37 return fleem * 2
38
39 import commandparser
40 parser = commandparser.CommandParser(Foo)
41 parser.invoke()
42
43 (From http://k0s.org/hg/CommandParser/file/tip/tests/simpleexample.py )
44
45 Example invocation::
46
47 (paint)│./simpleexample.py help
48 Usage: simpleexample.py [options] command [command-options]
49
50 silly class that does nothing
51
52 Options:
53 -h, --help show this help message and exit
54
55 Commands:
56 bar The good ole `bar` command
57 foo
58 help print help for a given command
59 (paint)│./simpleexample.py foo
60 Usage: simpleexample.py foo <value>
61
62 simpleexample.py: error: Not enough arguments given
63 (paint)│./simpleexample.py foo 4
64 The value is 4
65 (paint)│./simpleexample.py bar blah
66 blahblah
67
68 For optional arguments, the type of the default value will be
69 inspected from the function signature. Currently, mandatory arguments
70 are all strings, though this is clearly a shortcoming.
71
72 The class docstring is used for ``%prog --help`` (and ``%prog help``,
73 same thing). The method docstrings (including those of ``__init__``
74 for global options) are used for subcommand help. If the arguments
75 are listed in the docstring in the form given above
76 (``- <argument> : <something about the argument``) then these are used
77 to provide help on the individual options. Otherwise, these are left
78 blank.
79
80 For straight-forward cases, it may be enough to pass your class
81 directly to the CommandParser constructor. For more complex cases, it
82 is an advisable pattern to create a new class (either via subclassing
83 or e.g. rolling from scratch, as applicable) that is more amenable to
84 CommandParser rather than modifying an (e.g.) API class to fit what
85 CommandParser expects. This allows the use of an object-oriented
86 interface for subcommands without sacrificing your API class, and if
87 you can subclass then there's really not much extra code to write.
88
89 See http://k0s.org/hg/CommandParser/file/tip/tests for tests and examples.
5 90
6 ---- 91 ----
7 92
8 Jeff Hammel 93 Jeff Hammel
9 94