diff options
Diffstat (limited to 'doc/README.dev')
| -rw-r--r-- | doc/README.dev | 104 |
1 files changed, 36 insertions, 68 deletions
diff --git a/doc/README.dev b/doc/README.dev index 2a09463..a2b8d30 100644 --- a/doc/README.dev +++ b/doc/README.dev @@ -1,84 +1,52 @@ Extending BE ============ -To write a plugin, you simply create a new file in the becommands -directory. Take a look at one of the simpler plugins (e.g. open.py) +Adding commands +--------------- + +To write a plugin, you simply create a new file in the libbe/commands/ +directory. Take a look at one of the simpler plugins (e.g. remove.py) for an example of how that looks, and to start getting a feel for the libbe interface. -To fit into the current framework, your extension module should -provide the following elements: - __desc__ - A short string describing the purpose of your plugin - execute(args, manipulate_encodings=True, restrict_file_access=False, - dir=".") - The entry function for your plugin. args is everything from - sys.argv after the name of your plugin (e.g. for the command - `be open abc', args=['abc']). - - manipulate_encodings should be passed through to any calls to - bugdir.BugDir(). See the BugDir documentation for details. - - If restrict_file_access==True, you should call - cmdutil.restrict_file_access(bugdir, path) - before attempting to read or write a file. See the - restrict_file_access documentation for details. - - dir is a directory inside the repository of interest. - - Note: be supports command-completion. To avoid raising errors you - need to deal with possible '--complete' options and arguments. - See the 'Command completion' section below for more information. - help() - Return the string to be output by `be help <yourplugin>', - `be <yourplugin> --help', etc. - -While that's all that's strictly necessary, many plugins (all the -current ones) use libbe.cmdutil.CmdOptionParser to provide a -consistent interface - get_parser() - Return an instance of CmdOptionParser("<usage string>"). You can - alter the parser (e.g. add some more options) before returning it. - -Again, you can just browse around in becommands to get a feel for things. +See libbe/commands/base.py for the definition of the important classes +Option, Argument, Command, InputOutput, StorageCallbacks, and +UserInterface classes. You'll be subclassing Command for your +command, but all those classes will be important. + + +Command completion + +BE implements a general framework to make it easy to support command +completion for arbitrary plugins. In order to support this system, +any of your completable Argument() instances (in your commands +.options or .args) should be initialized with some valid +completion_callback function. Some common cases are defined in +libbe.command.util. If you need more flexibility, see +libbe.command.list's "--sort" option for an example of extensions via +libbe.command.util.Completer, or write a custom completion function +from scratch. + + +Adding user interfaces +---------------------- + +Take a look at libbe/ui/command_line.py for an example. Basically +you'll need to setup a UserInterface instance for running commands. +More details to come after I write an HTML ui... Testing -------- +======= -Run any doctests in your plugin with - be$ python test.py <yourplugin> +Run any tests in your module with + be$ python test.py <python.module.name> for example - be$ python test.py merge + be$ python test.py libbe.command.merge +For a definition of "any tests", see test.py's add_module_tests() +function. -Command completion ------------------- - -BE implements a general framework to make it easy to support command -completion for arbitrary plugins. In order to support this system, -all becommands should properly handle the '--complete' commandline -argument, returning a list of possible completions. For example - $ be --commands - lists options accepted by be and the names of all available becommands. - $ be list --commands - lists options accepted by becommand/list - $ be list --status --commands - lists arguments accepted by the becommand/list --status option - $ be show -- --commands - lists possible vals for the first positional argument of becommand/show -This is a lot of information, but command-line completion is really -convenient for the user. See becommand/list.py and becommand/show.py -for example implementations. The basic idea is to raise - cmdutil.GetCompletions(['list','of','possible','completions']) -once you've determined what that list should be. - -However, command completion is not critical. The first priority is to -implement the target functionality, with fancy shell sugar coming -later. In recognition of this, cmdutil provides the default_complete -function which ensures that if '--complete' is any one of the -arguments, options, or option-arguments, GetCompletions will be raised -with and empty list. Profiling ========= |