4 To write a plugin, you simply create a new file in the becommands
5 directory. Take a look at one of the simpler plugins (e.g. open.py)
6 for an example of how that looks, and to start getting a feel for the
9 To fit into the current framework, your extension module should
10 provide the following elements:
12 A short string describing the purpose of your plugin
14 The entry function for your plugin. args is everything from
15 sys.argv after the name of your plugin (e.g. for the command
16 `be open abc', args=['abc']).
18 Note: be supports command-completion. To avoid raising errors you
19 need to deal with possible '--complete' options and arguments.
20 See the 'Command completion' section below for more information.
22 Return the string to be output by `be help <yourplugin>',
23 `be <yourplugin> --help', etc.
25 While that's all that's strictly necessary, many plugins (all the
26 current ones) use libbe.cmdutil.CmdOptionParser to provide a
29 Return an instance of CmdOptionParser("<usage string>"). You can
30 alter the parser (e.g. add some more options) before returning it.
32 Again, you can just browse around in becommands to get a feel for things.
37 Run any doctests in your plugin with
38 be$ python test.py <yourplugin>
40 be$ python test.py merge
46 BE implements a general framework to make it easy to support command
47 completion for arbitrary plugins. In order to support this system,
48 all becommands should properly handle the '--complete' commandline
49 argument, returning a list of possible completions. For example
51 lists options accepted by be and the names of all available becommands.
53 lists options accepted by becommand/list
54 $ be list --status --commands
55 lists arguments accepted by the becommand/list --status option
56 $ be show -- --commands
57 lists possible vals for the first positional argument of becommand/show
58 This is a lot of information, but command-line completion is really
59 convenient for the user. See becommand/list.py and becommand/show.py
60 for example implementations. The basic idea is to raise
61 cmdutil.GetCompletions(['list','of','possible','completions'])
62 once you've determined what that list should be.
64 However, command completion is not critcal. The first priority is to
65 implement the target functionality, with fancy shell sugar coming
66 later. In recognition of this, cmdutil provides the default_complete
67 function which ensures that if '--complete' is any one of the
68 arguments, options, or option-arguments, GetCompletions will be raised