README.dev

   1 Extending BE
   2 ============
   3
   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
   7 libbe interface.
   8
   9 To fit into the current framework, your extension module should
  10 provide the following elements:
  11   __desc__
  12     A short string describing the purpose of your plugin
  13   execute(args)
  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']).
  17
  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.
  21   help()
  22      Return the string to be output by `be help <yourplugin>',
  23      `be <yourplugin> --help', etc.
  24
  25 While that's all that's strictly necessary, many plugins (all the
  26 current ones) use libbe.cmdutil.CmdOptionParser to provide a
  27 consistent interface
  28   get_parser()
  29     Return an instance of CmdOptionParser("<usage string>").  You can
  30     alter the parser (e.g. add some more options) before returning it.
  31
  32 Again, you can just browse around in becommands to get a feel for things.
  33
  34 Testing
  35 -------
  36
  37 Run any doctests in your plugin with
  38   be$ python test.py <yourplugin>
  39 for example
  40   be$ python test.py merge
  41
  42
  43 Command completion
  44 ------------------
  45
  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
  50   $ be --commands
  51       lists options accepted by be and the names of all available becommands.
  52   $ be list --commands
  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.
  63
  64 However, command completion is not critical.  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
  69 with and empty list.