Module vpe.mapping¶

Python support for key sequence mapping.

This module provides support for mapping key sequences to Python function calls.

KeyHandler¶

class vpe.mapping.KeyHandler¶

Mix-in to support mapping key sequences to methods.

Methods

auto_map_keys()¶

Set up mappings for methods.

Static methods

static mapped(...)¶
mapped(
        mode: str,
        keyseq: Union[str, Iterable[str]],
        **kwargs
Decorator to make a keyboard mapping invoke a method.

Parameters

mode: str
The mode in which the mapping applies, one of normal, op-pending, visual or insert.

keyseq: typing.Union[str, typing.Iterable[str]]
A key sequence string or sequence thereof, as used by map.

kwargs
See map for the supported values.

MapCallback¶

class vpe.mapping.MapCallback(*args, **kwargs)¶

Wrapper for a function to be invoked by a key mapping.

This extends the core Callback to provide a MappingInfo as the first positional argument.

Parameters

pass_info: If True, provide a MappingInfo object as the first argument to the callback function.

Methods

get_call_args(_vpe_args: Dict[str, Any])¶

Get the Python positional and keyword arguments.

This makes the first positional argument a MappingInfo instance, unless self.pass_info has been cleared.

MappingInfo¶

class vpe.mapping.MappingInfo(mode: str, keys: str)¶

Information passed to a key mapping callback handler.

The initialisation parameters are made available as attributes.

Attributes

end_cursor¶

When mode==”visual”, a tuple (line, column) of the selection end. Both values are 1-based. Will be (-1, -1) when not applicable.

keys¶

The sequence of keys that triggered the mapping.

mode¶

The mode in which the mapping was triggered (normal, visual, op-pending or insert).

start_cursor¶

When mode==”visual”, a tuple (line, column) of the selection start. Both values are 1-based. Will be (-1, -1) when not applicable.

vmode¶

The visual mode (character, line or block). Will be None when not applicable.

Properties

property line_range → Optional[Tuple[int, int]]¶

The line range, if visual mode was active.

This is a Python style range.

imap¶

vpe.mapping.imap(...)¶

imap(
        keys: Union[str, Iterable[str]],
        func: Union[Callable, str],
        buffer: bool = True,
        silent: bool = True,
        unique: bool = False,
        pass_info=True,
        nowait: bool = False,
        command: bool = False,
        args=(),
        kwargs: Optional[dict] = None,

Set up an insert mapping that invokes a Python function.

See map for argument details.

map¶

vpe.mapping.map(...)¶

map(
        mode: str,
        keys: Union[str, Iterable[str]],
        func: Union[Callable, str],
        buffer: bool = True,
        silent: bool = True,
        unique: bool = False,
        nowait: bool = False,
        command: bool = False,
        pass_info=True,
        args=(),
        kwargs: Optional[dict] = None,

Set up a key mapping that invokes a Python function.

By default, the effective map command has the form:

{m}noremap <buffer> <silent> keys …

Where {m} is one of n, x, o, i.

The noremap form is always used.

By default the first argument passed to the mapped function is a MappingInfo object. The pass_info argument can be used to prevent this. Additional arguments can be speficied using args and kwargs.

For convenience, mode specific versions are provided (nmap, xmap, omap and imap). See those for details of what he mapped function can do. It is recommended that these mode specific versions are use in preference to this function.

The func argument may also be a string, in which case it is interpreted as the literal RHS of the key mapping.

Parameters

mode: str: A string defining the mode in which the mapping occurs. This should be one of: normal, visual, op-pending, insert, command, select. The command and select mode are not supported when func is not a string.
keys: typing.Union[str, typing.Iterable[str]]: The key sequence to be mapped. This may be an interable set of key sequences that should all be mapped to the same action.
func: typing.Union[typing.Callable, str]: The Python function to invoke for the mapping or a string to use as the right hand side of the mapping.
buffer: bool: Use the <buffer> special argument. Defaults to True.
silent: bool: Use the <silent> special argument. Defaults to True.
unique: bool: Use the <unique> special argument. Defaults to False.
nowait: bool: Use the <nowait> special argument. Defaults to False.
command: bool: Only applicable to insert mode. If true then the function is invoked from the command prompt and the return value is not used. Otherwise (the default) the function should return the text to be inserted.
pass_info: If set then the first argument passed to func is a MappingInfo object. Defaults to True.
args: Additional arguments to pass to the mapped function.
kwargs: typing.Optional[dict]: Additional keyword arguments to pass to the mapped function.
vim_exprs: typing.Tuple[str, …]: Vim expressions to be evaluated and passed to the callback function, when the mapping is triggered.

nmap¶

vpe.mapping.nmap(...)¶

nmap(
        keys: Union[str, Iterable[str]],
        func: Union[Callable, str],
        buffer: bool = True,
        silent: bool = True,
        unique: bool = False,
        pass_info=True,
        nowait: bool = False,
        args=(),
        kwargs: Optional[dict] = None,

Set up a normal mode mapping that invokes a Python function.

See map for argument details.

omap¶

vpe.mapping.omap(...)¶

omap(
        keys: Union[str, Iterable[str]],
        func: Union[Callable, str],
        buffer: bool = True,
        silent: bool = True,
        unique: bool = False,
        pass_info=True,
        nowait: bool = False,
        args=(),
        kwargs: Optional[dict] = None,

Set up an operator-pending mode mapping that invokes a Python function.

See map for argument details.

xmap¶

vpe.mapping.xmap(...)¶

xmap(
        keys: Union[str, Iterable[str]],
        func: Union[Callable, str],
        buffer: bool = True,
        silent: bool = True,
        unique: bool = False,
        pass_info=True,
        nowait: bool = False,
        args=(),
        kwargs: Optional[dict] = None,

Set up a visual mode mapping that invokes a Python function.

See map for argument details.