Mercurial > hg > CommandParser

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