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)¶ ArgumentParser
that raisesCommandParseError
instead of printing to sys.stderr
-
alot.commands.
commandfactory
(cmdline, mode='global')¶ parses cmdline and constructs a
Command
.Parameters:
-
alot.commands.
lookup_command
(cmdname, mode)¶ returns commandclass, argparser and forced parameters used to construct a command for cmdname when called in mode.
Parameters: 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 usinglookup_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()
.