4.6. Commands

User actions are represented by Command objects that can then be triggered by alot.ui.UI.apply_command(). Command-line strings given by the user via the prompt or key bindings can be translated to Command objects using alot.commands.commandfactory(). Specific actions are defined as subclasses of Command and can be registered to a global command pool using the registerCommand decorator.

Note

that the return value of commandfactory() depends on the current mode the user interface is in. The mode identifier is a string that is uniquely defined by the currently focuses Buffer.

Note

The names of the commands available to the user in any given mode do not correspond one-to-one to these subclasses. You can register a Command multiple times under different names, with different forced constructor parameters and so on. See for instance the definition of BufferFocusCommand in ‘commands/globals.py’:

@registerCommand(MODE, 'bprevious', forced={'offset': -1},
                 help='focus previous buffer')
@registerCommand(MODE, 'bnext', forced={'offset': +1},
                 help='focus next buffer')
class BufferFocusCommand(Command):
    def __init__(self, buffer=None, offset=0, **kwargs):
    ...
class alot.commands.Command

base class for commands

apply(ui)

code that gets executed when this command is applied

class alot.commands.CommandParseError

could not parse commandline string

class alot.commands.CommandArgumentParser(prog=None, usage=None, description=None, epilog=None, parents=[], formatter_class=<class 'argparse.HelpFormatter'>, prefix_chars='-', fromfile_prefix_chars=None, argument_default=None, conflict_handler='error', add_help=True, allow_abbrev=True, exit_on_error=True)

ArgumentParser that raises CommandParseError instead of printing to sys.stderr

alot.commands.commandfactory(cmdline, mode='global')

parses cmdline and constructs a Command.

Parameters:

  • cmdline (str) – command line to interpret

  • mode (str) – mode identifier

alot.commands.lookup_command(cmdname, mode)

returns commandclass, argparser and forced parameters used to construct a command for cmdname when called in mode.

Parameters:

  • cmdname (str) – name of the command to look up

  • mode (str) – mode identifier

Return type:

(Command, ArgumentParser, dict(str->dict))

alot.commands.lookup_parser(cmdname, mode)

returns the CommandArgumentParser used to construct a command for cmdname when called in mode.

class alot.commands.registerCommand(mode, name, help=None, usage=None, forced=None, arguments=None)

Decorator used to register a Command as handler for command name in mode so that it can be looked up later using lookup_command().

Consider this example that shows how a Command class definition is decorated to register it as handler for ‘save’ in mode ‘thread’ and add boolean and string arguments:

.. code-block::
@registerCommand(‘thread’, ‘save’, arguments=[

([’–all’], {‘action’: ‘store_true’, ‘help’:’save all’}), ([‘path’], {‘nargs’:’?’, ‘help’:’path to save to’})], help=’save attachment(s)’)

class SaveAttachmentCommand(Command):

pass

Parameters:

  • mode (str) – mode identifier

  • name (str) – command name to register as

  • help (str) – help string summarizing what this command does

  • usage (str) – overides the auto generated usage string

  • forced (dict (str->str)) – keyword parameter used for commands constructor

  • arguments (list of (list of str, dict (str->str)) – list of arguments given as pairs (args, kwargs) accepted by argparse.ArgumentParser.add_argument().

4.6.1. Globals

4.6.2. Envelope

4.6.3. Bufferlist

4.6.5. Taglist

4.6.6. Namedqueries

4.6.7. Thread