vim.mappings
/{buffer}.mappings
:Mapping-like object mapping mode constants to vim.modemappings objects below. Unlike vim.buffers iteration is being done for keys. Mode constants are described below in
vim.current.mode
object description, but for convenience additional constants are defined:vim.MODE_ANY_SELECTION
:vim.MODE_VISUAL|vim.MODE_SELECT
: stands for the mode list ofvnoremap
command.vim.MODE_MAPPING_DEFAULT
:vim.MODE_NORMAL|vim.MODE_ANY_SELECTION|vim.MODE_OPERATOR_PENDING
: stands for the mode list of plainnoremap
command.vim.MODE_GENERIC_INSERT
:vim.MODE_INSERT|vim.MODE_COMMAND
: stands for the mode list ofnoremap!
command.
Existing
vim.MODE_LANGUAGE
stands forlnoremap
mappings.vim.abbreviations
/{buffer}.abbreviations
:- Same as above, but for abbreviations. Supports only
vim.MODE_INSERT
,vim.MODE_COMMAND
andvim.MODE_GENERIC_INSERT
as modes. modemappings
:- Dictionary-like object mapping expanded (see vim.special_expand() below)
strings to vim.Mapping objects. Assigning Mapping objects to some key works
like
:*map
..sid
attribute is ignored when assigning. Unlikevim.buffers
iteration is being done for keys. mapping
:Namedtuple-like object with the following attributes:
Attribute Description rhs Rhs of the mapping. sid Script ID. silent True or False, tells whether mapping is silent. expr True or False, tells whether it is <expr> mapping. noremap - Depends on the numeric constant:
vim.MAPPING_REMAP False (zero) constant, mapping is remappable vim.MAPPING_NOREMAP True (non-zero), mapping is noremappable vim.MAPPING_SCRIPT True (non-zero), mapping is <script> one
No
.mode
or.buffer
attributes: they are expressed in using appropriatevim.mappings[mode]
(buffer.mappings[mode]
) objects.vim.menus
/{buffer}.menus
:Similar to the above
vim.mappings
, but with a slightly different end-point objects: in addition to attributes described inmapping
,menu
object should also containhint
attribute holding the part of the menu after<Tab>
.Supports the following mode constants:
vim.MODE_NORMAL
,vim.MODE_VISUAL
,vim.MODE_SELECT
,vim.MODE_INSERT
,vim.MODE_COMMAND
andvim.MODE_OPERATOR_PENDING
. And the following shortcuts:vim.MODE_ANY_SELECTION
(seevim.mappings
description above),vim.MODE_ANY
(vim.MODE_GENERIC_INSERT|vim.MODE_MAPPING_DEFAULT
),vim.MODE_MAPPING_DEFAULT
.vim.commands
/{buffer}.commands
:- Mapping-like object mapping command names to
vim.Command
objects. Assigningvim.Command
object to the key acts like:command
,.sid
attribute is ignored. Unlikevim.buffers
iteration is being done for keys. command
:Namedtuple-like object with the following attributes:
Attribute Description command Command string. sid Script ID. nargs One of constants:
vim.COMMAND_ARGS_NO vim.COMMAND_ARGS_ONE vim.COMMAND_ARGS_ANY vim.COMMAND_ARGS_ONE_OR_NO vim.COMMAND_ARGS_SOME
complete String or None
.range Number or None
. Number is eithervim.COMMAND_RANGE_CURRENT
,vim.COMMAND_RANGE_WHOLE
or non-negative integer. All constants are negative integers.None
is used when neither range nor count is allowed.count True
orFalse
. Determines whether.range
attribute really describes -count argument.bang, bar, register True
orFalse
.vim.autocommands
:- Mapping-like object mapping autocommand groups to
vim.Augroup
objects. Iteration is done for keys. Autocommands without groups are autocommands with group None. Defines method.run(event, fname={fname}, modeline=False)
. augroup
:Mapping-like object mapping event names to list of
vim.Autocommand
objects. Iteration is done for keys. Methods:.append_autocmd(event, autocommand) .del_autocmds(event, pattern=None) .clear(event=None) .run(event, fname={fname}, modeline=False)
As usual,
.sid
attribute is ignored when using above methods. Item assignment works by calling first.clear(event=key)
and then a sequence of.append_autocmd(event=key, autocmd=item)
.autocommand
:Namedtuple-like object with the following attributes:
Attribute Description command Command string. sid Script ID. nested True or False. pattern Glob. vim.signs
:- Mapping-like object mapping sign names to vim.Sign attributes. Iterates over keys, supports item assignment.
sign
:Namedtuple-like object with the following attributes:
Attribute Description icon None or file name. linehl None or string. text String. texthl None or string. {buffer}.signs
:Mapping-like object mapping place ids to signplace objects (note: they is no constructor for this). Iterates over signplace objects in order they are shown in the buffer. Methods:
.place(line, name, id=None)
:- Place given sign on the given line. Returns id which is equal to id argument if it was given or a new unique id.
.unplace(line=None, id=None)
:- Unplace sign from the given line or id or all signs if no arguments were given. If both line and id are present then it verifies whether sign with given id is placed on the given line and either unplaces it or raises ValueError.
.find(line)
:- Returns
signplace
object describing sign placed on the given line orNone
if no sign was placed there.
signplace
:Object with the following attributes:
Attribute Description id Identifier. line Line number. name Names of signs: keys in vim.signs. Also has method .jump().
vim.hlgroups
:- Mapping-like object mapping highlight group names to
vim.HighlightGroup
objects or strings (keys ofvim.hlgroups
). Iterates over keys, supports item assignment (bothvim.HighlightGroup
and names). highlightgroup
:Namedtuple-like object with the following attributes:
Attribute Description cterm, gui, term Tuples listing attributes or None
ctermfg, ctermbg Integers, color index used or None
guifg, guibg, guisp 3-tuple with floating-point values: color coordinates in RGB space or None
if no gui colors were specified or vim was compiled without+gui
_ctermfg, _ctermbg, _guifg, _guibg, _guisp Strings: colors as specified when defining highlight group or None
vim.functions
:Mapping-like object mapping user function names to
vim.Function
objects. Acceptss:
and<SID>
in keys, but always expands it when creating objects.Also uses
vim.functions.builtin
syntax: e.g.vim.functions.fnameescape(string)
will escape the string.function
:Callable object with the following attributes:
Attribute Description name Function name callable (extended funcref only) Return unwrapped python callable used by given function reference. code Function code sid Script ID is_dictionary True or False. dict For convenience vim.Dictionary can be assigned to this attribute in order to forget about specifying self= arg. Supports assigning any mapping-like object that can be converted. vim._tag_files
,{buffer}._tag_files
:- Iterators yielding tag file names.
list(vim._tag_files)
is an expanded version of&tags
option. vim.tags
,{buffer}.tags
:Mapping-like object mapping tag names to
vim.Tag
objects. Does not support assignment. Iterates overvim.Tag
objects, not over tag names. Iterator loads tags from files lazily, holding file handle while until its destruction or until exhausting tags in that file.Note: it would be good if parsed contents of tag files was cached and if there added a possibility to define tags not present in files (like with zsh
hash
command: by adding tags to cache through existing API). Without caching it would not be possible to solve performance problems withtaglist()
.tag
:Objects with the following attributes:
Attribute Description name Name of the tag filename Name of the file where tag is defined lineno None
or line number in that filepattern None
or pattern used to locate tag in that filecmd None
or Ex command used to locate tag; is present in case it is neither lineno nor pattern (should not really ever happen)kind String, tag kind static True
orFalse
, specifies whether tag is specific to this fileAlso has method
.jump()
.vim.jumps
:- Sequence-like object that removes the need of parsing
:jumps
. Contains jump objects. {buffer}.changes
:- Like vim.jumps, but for
:changes
in the given buffer. jump
:Objects with the following attributes:
Attribute Description line Line number. col Column number. file None or file name. buffer None (file not loaded) or vim.buffer object. Also has method
.jump()
.vim.current.jump
:- Index of the current jump in vim.jumps.
{buffer}.change
:- Index of the current change in {buffer}.changes.
{buffer}.changed_tick
:- Value of
b:changedtick
. Added as it is not available from{buffer}.vars
. vim.qflists
:- Sequence-like object that provides access to a list of quickfix lists. Iterates over lists, supports item assignment.
{window}.loclists
:- Same as
vim.qflists
, but for window location lists. {window}.loclist
:- Current
vim.QFList
object representing current location list. qflist
:Sequence-like object with the following attributes:
Attribute Description title Quickfix list title. itervalid Iterator, iterates only over QFItem’s with .valid=True. Read-only, supports __getitem__, slicing, __len__ and iteration.
qfitem
:Namedtuple-like object with the following attributes:
Attribute Description valid True or False, determines whether item represents error or is just a text. text Item text. lnum Line number if specified, not present otherwise. pattern Pattern used to search for the item, may be absent. buffer vim.buffer
object pointing to a buffer containing the item.col Byte offset from the start of the line pointing to the start of the item. May be absent. vcol Virtual column where the item starts. May be absent. type Character with the error type. May be absent. nr Error number. Additionally contains method
.jump()
.vim.environ
:- Mapping-like object, used like
os.environ
. If we are mockingos.chdir
it also makes sense to mockos.environ
with this object asos.environ
is not updated. vim.scripts
:- Sequence-like object that removes the need of parsing
:scriptnames
. Maps script numbers (subtracted by one) to file names. vim.select(start_line=vim.functions.line('.'), end_line=start_line, start_col=None, end_col=start_col, start_virtcol=None, end_virtcol=None, mode=vim.MODE_VISUAL, type=(vim.SELECT_LINEWISE if not start_col and not start_virtcol else vim.SELECT_CHARACTERWISE))
:Start selection after script execution finishes (like
:startinsert
).start_virtcol
overridesstart_col
,end_virtcol
overridesend_col
,mode
may only be eithervim.MODE_VISUAL
orvim.MODE_SELECT
. If neitherstart_col
norstart_virtcol
is specifiedend_col
andend_virtcol
are ignored.type
is one of the following:Type Description vim.SELECT_CHARACTERWISE Characterwise selection, default if starting column was specified vim.SELECT_LINEWISE Linewise selection, default if no starting column was specified vim.SELECT_BLOCK Blockwise selection vim.current.selection
:- Returns dictionary or mapping-like object with current selection that is
suitable for passing into
vim.select
and containstype
,start_line
,end_line
,start_virtcol
andend_virtcol
keys. vim.registers
:- Mapping-like object providing access to vim registers. Iterates over keys,
supports assignment.
vim.registers["a"]
returns 2-tuple(vim.SELECT_*, text)
(or namedtuple-like object with.text
and.type
attributes? And, probably, more namedtuple-like: subclass of tuple) and expects similar 2-tuple when assigning (though can accept text in place of a tuple deducing type of the register from the last character: if it is newline then register is linewise, else characterwise). vim.marks
:- Mapping-like object providing access to global marks. Returns
jump
objects. {buffer}.marks
:- Same as
vim.marks
, but for buffer. Unlike{buffer}.mark
function supports iteration, returnsjump
objects (allowing{buffer}.marks["a"].jump()
) and supports item assignment. Also does not provide access to global marks, even if these marks are defined for the current buffer. vim.history
:Mapping-like object, providing access to command history. Supports the following keys:
Key hist*()
argumentvim.HISTORY_COMMAND "cmd"
/":"
vim.HISTORY_SEARCH "search"
/"/"
vim.HISTORY_EXPRESSION "expr"
/"="
vim.HISTORY_INPUT "input"
/"@"
vim.HISTORY_DEBUG "debug"
/">"
Is assignable.
history
:- Sequence-like object providing access to specific history. Supports assignment, slice assignment, deleting, slice deleting, iteration (over history entries).
vim.digraphs
:- Dictionary-like object mapping digraph characters (there must be two of them) to inserted text. Supports item assignment and deletion.
vim.argv
:- Sequence-like object providing access to vim argument list like
argv()
. Supports item and slice assignment and iteration.
Notes:
- “Namedtuple-like” means that all attributes are RO and that there are no methods.
- “Ignored when assigning” means “set to sid which is current when assigning”.
- “Dictionary-like” means that object supports iteration over keys,
.keys()
,.items()
and.values()
methods. If it is assignable it should also support.update()
. If keys can be deleted it should also support.clear()
.- “Mapping-like” means that object supports
__getitem__
method without supporting slices. All other restrictions are mentioned in the object description.
maplist([{mode}[, {bufnr}]])
:- Returns a list of strings suitable for
maparg()
. cmdarg({cmdname}[, {bufnr}])
:Returns a dictionary with the following keys, works with partial commands:
Key Value name Full {cmdname}. command Command string. sid Script ID. nargs String constant or empty string. complete String, possibly empty. range String constant or empty string, stands only for -nargs. count String constant or empty string, stands only for -count. bang, bar, register, buffer One or zero. cmdlist([{bufnr}])
:- Returns a list of command names suitable for
cmdarg()
. aulist({event}[, {augroup}[, {pattern}]])
:Returns a list of dictionaries with the following keys:
Key Value event {event} augroup Autocmd group. patterns List of globs. command Command string. nested One or zero. sid Script ID. auglist()
:- Returns a list of autocmd groups.
signarg({name})
:Returns a dictionary with the following keys:
Key Value name {name} icon Icon file or empty string. linehl String or empty string. texthl String or empty string. text String. signlist()
:- Returns a list of sign names suitable for
signarg()
. signplacelist({bufnr})
:Returns a list of signs placed in the given buffer: dictionaries with keys
Key Value name Name suitable for signarg(). id Sign ID. line Line number. getjumps()
:Returns a list of dictionaries with the following keys:
Key Value line Line number. col Column number. file File name. getchanges({bufnr})
:- Returns a list of lists, latter lists are suitable for
cursor()
: look like([{line}, {col}])
. getdigraphs()
:- Returns a dictionary
{digraph : text}
wheredigraph
is a two-character sequence andtext
is text inserted when this sequence is used as an digraph. setdigraphs({dict})
:- Replace digraph table with given dictionary. Format is the same as returned
by
getdigraphs()
. cmdcomplete(command, cursor=len(command))
:- Returns a 3-tuple
[before, after, variants]
with completion variants for the given command.before
andafter
are unchanged parts of originalcommand
. exprcomplete(complete, text, cursor=len(text))
:- Like above, but complete using given
complete
argument (likeinput()
completion).
Note: {bufnr}
is {expr}
argument from bufnr()
function.
vim.Mapping(rhs, noremap=vim.MAPPING_NOREMAP, silent=False, expr=False)
:Returns mapping object described above. New mappings that are created using vim.Mapping are then to be assigned to appropriate
{vim,buffer}.mappings[mode][lhs]
thus there are no attributes likemode
,buffer
orlhs
: they are determined by appropriate keys and objects when assigning.sid
attribute is created automatically (though in any case it is ignored when assigning).If
rhs
is callable it automatically setsexpr
toTrue
and uses the result of the call asrhs
(like other<expr>
mappings do).Defines method
.run()
that runs given mapping object in the current mode. It is up to developer to make sure current mode is a proper one.Note: the same object is used for mappings and abbreviations.
vim.Menu(rhs, noremap=vim.MAPPING_NOREMAP, silent=False, expr=False, hint=None)
:- Like above
vim.Mapping
, but for menus. Additionalhint
argument describes a right-aligned hint in the menu. Is a subclass ofvim.Mapping
. vim.Command(command, nargs=vim.COMMAND_ARGS_NO, complete=None, range=None, count=False, bang=False, bar=True, register=False)
:Returns command object described above. New commands that are created using vim.Command are then to be assigned to
{vim,buffer}.commands[cmd]
thus there are no attributes likename
orbuffer
.sid
attribute is created automatically (though in any case it is ignored when assigning).If
command
is a callable, it will receive the following keyword arguments:Argument Description args List of command arguments count (Only for commands with count=True
) count receivedrange (Only for commands with range=True
)vim.range
objectbang (Only for commands with bang=True
)True
orFalse
reg (Only for commands with register=True
) Register namevim.Autocommand(command, pattern, nested=True)
:Returns new autocmd group as described above.
If
command
is a callable, it will receive the following keyword arguments:Argument Description buf Buffer number match Matched string vim.HighlightGroup(gui=None, guifg=None, guibg=None, guisp=None, cterm=None, ctermfg=None, ctermbg=None, term=None)
:- Returns new highlight group as described above.
vim.Sign(text, icon=None, linehl=None, texthl=None)
:- Returns new sign as described above.
vim.Function(args, code, name=None, is_dictionary=False, dict=None)
:- Returns function object like above (
name=None
means anonymous function,name
is automatically generated). Code is a iterable of strings. vim.Function(callable)
:- (extended funcref only) Returns function object like above which contains python callable wrapped into vim Funcref.
vim.QFList(iterable, title=None)
/vim.QFList(*iterable, title=None)
:- Sequence-like object with a list of
vim.QFItem
objects. Read-only. vim.QFItem(text, lnum=None, pattern=None, type=None, nr=0, col=1, vcol=None, buffer=vim.current.buffer, filename=None)
:Returns quickfix/location list item. There are additional inter-argument dependencies:
filename=string
overridesbuffer
argument.lnum=None
andpattern=None
implies.valid=False
.buffer=None
andfilename=None
implies.valid=False
andValueError
when trying to use.jump()
method. Note thatbuffer=None
is not the default.vcol=number
impliescol=None
. Unlike vim, vcol argument does not mean thatcol
argument represents byte offset, instead it accepts virtual column number.
vim.Jump(line=vim.functions.line('.'), col=vim.functions.col('.'), buffer=vim.current.buffer, file=None)
:- Returns
jump
object as described earlier. For use when assigning tovim.marks
or{buffer}.marks
. vim.History(items=())
:- Returns
history
object for use invim.input()
.
Note: here are different (more convenient) defaults:
Place New default Mapping(noremap=vim.MAPPING_NOREMAP) in place of vim.MAPPING_REMAP Command(bar=True) in place of False Autocommand(nested=True) in place of False
vim.special_expand(string)
+special_expand(string)
:- Expands special characters like
<C-a>
in the string. Currently it is done in VimL by usingeval('"'.escape(str, '\<"').'"')
which is rather hacky. vim.match_glob(glob, string)
,match_glob(string, glob)
:- Match string against glob expression. Order is different in python and VimL:
in python it is taken from
re.match(pattern, string)
, in VimL frommatchstr({expr}, {pat})
. vim.buffers.find(string)
:Similar to
vim.buffers[vim.bindeval("bufnr(string)")]
, but does not raise exception.returns: vim.buffer
object orNone
.vim.get_highlighting(hlgroup)
:- Like
vim.hlgroups[hlgroup]
, but always returnsvim.HighlightGroup
objects or raisesKeyError
. vim._gen_function(callable, args=())
:Generates vim.Function object from python callable object. At this point can only do something like the following (but not exactly this; and also written in C):
id = vim._callables.save(callable) return vim.Function(args, ('python import vim', 'return pyeval("vim._callables[{0}]({1})")'.format(id, ','.join((arg+'=vim.bindeval("a:'+arg+'")' for arg in args)))), dict={}) # Rather hacky, but standard solution is preferred over 100500 ways # plugin writers can reimplement it just to call python function # from various places where it is needed.
. Is not supposed to be used directly: it is for
vim.Command(command=callable)
,vim.Autocommand(command=callable)
andvim.Mapping(rhs=callable, expr=True)
, also for assigning options.When using pyeval, calling functions or binded types this one will be used to transform python callable into vim function. It is supposed that implementation will eventually change to func_T structure in place of char* in funcrefs.
vim.disabled_autocommands
:Object with defined
__enter__
method setting&eventignore
toall
and__exit__
method restoring previous value. Should be written in pure python. Used to allow expressions like:… with vim.disabled_autocommands: buffer = vim.buffers.new('aurum://file:…') vim.current.buffer = buffer …
vim.jump(buffer, lnum=None, pattern=None, col=None, vcol=None, window=None)
:Function used to implement all
.jump
methods of all objects.col
andvcol
arguments are mutually exclusive.vcol
argument overridescol
one.lnum
andpattern
are also exclusive,pattern
overrideslnum
. If neitherlnum
norpattern
are present it only jumps to the buffer. If neithercol
norvcol
are present it jumps to the first column. Withoutwindow
argument it tries to find window which already shows requested buffer and jump to that window.When used from the object, first five arguments are determined by the object holding the called method. Next arguments (currently only
window
) are passed from the method arguments. Default of these arguments depends on the object.vim.input(prompt, text="", complete=None, history=vim.history[vim.HISTORY_INPUT], dialog=False, secret=False)
:Like
input()
, but with two differencies:complete
may be a python callable (as invim.Command()
) andhistory
argument that temporary replacesvim.HISTORY_INPUT
history with itself.Unless implementation is altered
dialog=True
implies ignoringcomplete
.secret=True
implies ignoringdialog
,complete
andhistory
.Note: should care about nesting:
input()
andvim.input()
calls should use originalvim.history[vim.HISTORY_INPUT]
.Note 2: built-in vim
input()
should also supporthistory
argument.Note 3:
inputlist()
sucks and in the current state would not be supported.vim.confirm(message, choices=((True, '&OK'),), default=choices[0][0], type="Generic")
:- Prompt user for the confirmation. On interrupt (escape)
vim.ConfirmInterrupt
exception (subclass ofvim.Error
) is raised.choices
is an iterable with 2-tuples; second value in a tuple is used in a prompt; first will be returned if corresponding choice was made.default
will be returned if no choice was made. The first choice inchoices
for whichchoice[0] is default
is true (note: they must be same objects, it is not==
comparison) is displayed as the default one. If there are no such choices nothing is displayed as the default choice, but default value always exists. User should use escape orCTRL-C
to abort. vim.undobreak()
:- Break current undo sequence, like
i_CTRL-G_u
. vim.undojoin()
:- Join current change with the next one.
vim.redraw(all=False, status=False)
::redraw
(no arguments),:redraw!
(all=True
),redrawstatus
(status=True
) andredrawstatus!
(all=True, status=True
) replacement. Supports only keyword arguments.
Iterators for
*.windows
andvim.tabpages
that allow:for window in vim.windows: window.close()
like it is allowed for buffer list.
{function}.sid
and{function}.code
attributes.{windowlist}.valid
and{function}.valid
attributes.vim.eval(expr, number_strings=True)
: sometimes python objects are more desired then whatvim.bindeval
returns, but numbers represented as strings spoil it all.Some of the keys in
*.options
will be able to receive callable as an argument. Namely these are&statusline
(will use something like %! and receivevim.window
argument).&indentexpr
,&formatexpr
,&balloonexpr
,&foldexpr
,&diffexpr
,&includeexpr
,&patchexpr
,&printexpr
,&omnifunc
,&completefunc
,&operatorfunc
.Make checks for numbers less strict. I.e. it should use number protocol (
PyNumber_*
) in place of checking for integers and/or long values.{buffer}
,{window}
and{tabpage}
__enter__
and__exit__
methods: temporary switch to given buffer/window/tabpage and switch back afterwards.vim.current.qflist
: current quickfix list. Supports assignment.vim.current.word
,vim.current.nonblanks
(vim.current.WORD
looks like a constant),vim.current.script
(object with.file
,.sid
and.lnum
attributes representing variousexpand("<s*>")
things),vim.current.file
.vim.current.mode
: current mode, likemode()
, but uses less crypticvim.MODE_*
constants (of course, less cryptic only if developers are sane and use constants in place of embedding magic numbers). Supports assignment, assignment works like:startinsert
. Cannot assignvim.MODE_VISUAL|*
. Modes:vim.MODE_NORMAL
. Assigning this works likeCTRL-\_CTRL-N
.vim.MODE_OPERATOR_PENDING
. Not assignable.vim.MODE_VISUAL
. Supports flags:vim.MODE_VISUAL|vim.SELECT_LINEWISE
is linewise visual mode. Refer tovim.select()
description for a full list ofvim.SELECT_*
flags. Asssigning this start selects current line or character.vim.MODE_SELECT
. Supports flags like above. Assigning this selects current line or character.vim.MODE_INSERT
. Supports flags:vim.MODE_INSERT_INSERT
,vim.MODE_INSERT_REPLACE
,vim.MODE_INSERT_VIRTUAL_REPLACE
. Also supportsvim.MODE_MENU
. Assigning this works like:startinsert
.vim.MODE_COMMAND
. Supports flags:vim.HISTORY_*
,vim.COMMAND_COMMAND
,vim.MODE_COMMAND_EX
andvim.MODE_COMMAND_NORMAL_EX
. Also supportsvim.MODE_MENU
. Assigning this works likeCTRL-\_CTRL-N
followed by appropriate character (:
,Q
orgQ
).vim.MODE_PROMPT
. Supports flags:vim.MODE_PROMPT_HIT_ENTER
,vim.MODE_PROMPT_MORE
,vim.MODE_PROMPT_CONFIRM
. Not assignable.vim.MODE_SHELL
. Not assignable.
Flags:
vim.MODE_MENU
: insert and command modes flag; is active when popupmenu (insert) or wild menu (command) is active. Ignored when assigning. Seepumvisible()
andwildmenumode()
.vim.MODE_INSERT_INSERT
: insert mode flag; is active when mode is regular insert mode.vim.MODE_INSERT_REPLACE
: insert mode flag; is active in replace mode.vim.MODE_INSERT_VIRTUAL_REPLACE
: insert mode flag; is active in virtual replace mode.vim.MODE_COMMAND_COMMAND
: command mode flag; is activevim.MODE_COMMAND_EX
: command mode flag; is active in Ex mode.vim.MODE_COMMAND_NORMAL_EX
: command mode flag; is active in normal Ex mode.vim.MODE_PROMPT_HIT_ENTER
: prompt mode flag; is active when prompt is hit-enter one.vim.MODE_PROMPT_MORE
: prompt mode flag; is active when prompt is more prompt.vim.MODE_PROMPT_CONFIRM
: prompt mode flag; is active when prompt is:confirm
prompt.vim.SELECT_*
: visual and select mode flag; represent type of
selection. *
vim.HISTORY_*
: command mode flag: location of history, seevim.history
description. *vim.MODE_INSERT_CTRL_O
: any mode, represents that command enteringcurrent mode was launched using
i_CTRL-O
.vim.MODE_LANGUAGE
: any mode, represents that:lmap
commands are active.
Bits:
No
constants
01
MODE_NORMAL
02
MODE_OPERATOR_PENDING
03
MODE_VISUAL
04
MODE_SELECT
05
MODE_INSERT
06
MODE_COMMAND
07
MODE_PROMPT
08
MODE_SHELL
Flags:09
MODE_LANGUAGE
10
MODE_MENU
11
MODE_INSERT_CTRL_O
12
MODE_INSERT_INSERT
,MODE_COMMAND_COMMAND
,MODE_PROMPT_HIT_ENTER
13
MODE_INSERT_REPLACE
,MODE_COMMAND_EX
,MODE_PROMPT_MORE
14
MODE_INSERT_VIRTUAL_REPLACE
,MODE_COMMAND_NORMAL_EX
,MODE_PROMPT_CONFIRM
15
SELECT_LINEWISE
,HISTORY_COMMAND
16
SELECT_CHARACTERWISE
,HISTORY_SEARCH
After 16 bits. Should check out whether this situation is to be avoided17
SELECT_BLOCK
,HISTORY_EXPRESSION
18
HISTORY_INPUT
19
HISTORY_DEBUG
{buffer}.map(callable)
,{range}.map(callable)
: convenience wrapper for the following code:r = [] for line in buffer: # or “in range” line = callable(line) if isinstance(line, (unicode, str)): r.append(line) else: r.extend(line) buffer[:] = r # same
with a difference that lines are replace right away without delaying the replacement until all lines are processed.
vim.current.command
: namedtuple-like object with.text
and.cursor
arguments providing access to current command-line if in command-line mode. Attributes are assignable.vim.Dictionary.copy
,vim.Dictionary.clear
,vim.Dictionary.setdefault
,vim.Dictionary.fromkeys
,vim.Dictionary.iter*
(also use onlyiter*
for python-3), comparison support, betterrepr()
.vim.List.pop
,vim.List.remove
,vim.List.count
,vim.List.index
,vim.List.append
,vim.List.insert
,vim.List.reverse
,vim.List.__add__
,vim.List.__mul__
,vim.List.__imul__
, comparison support, betterrepr()
.
vim.buffers.open(name=None, encoding={&enc}, binary=False, fileformat={…}, readonly=None)
:Create a new buffer.
None
in place of name means “create buffer with empty name”. Returnsvim.Buffer
object.Note:
readonly=False
should be different fromreadonly=None
: former should raise an exception in case opening file for read-write access failed.vim.windows.create(direction, buffer=vim.current.buffer, size=0.5, preview=False)
, also forvim.current.tabpage.windows
:Split the window.
size
may be either an integer (absolute size) or a floating-point value in the open interval(0.0, 1.0)
(size relative to the current window size or total vim size, depending on direction).buffer
specifies what buffer will be opened in new window, must be a validvim.Buffer
object.direction
may be one of the following:Direction Description horizontal
Like :split
vertical
Like :vsplit
diff
Like :diffsplit
, but without settingdiff*
optionsabove
Like :above vsplit
below
Like :below vsplit
left
Like :lefta split
right
Like :rightb split
top
Like :top split
, uses &lines for relative sizesbottom
Like :bot split
, uses &lines for relative sizesleftmost
Like :topleft vsplit
, uses &columns for relative sizesrightmost
Like :botright vsplit
, uses &columns for relative sizesMay use numeric constants in place of strings as a direction.
Returns
vim.Window
object.vim.tabpages.create(after=vim.current.tabpage, before=None, direction=None, buffer=vim.current.buffer, window=None)
:Create new tabpage.
buffer
is handled in the same fashion as above;direction
,before
andafter
arguments are mutually exclusive.window
argument is here to simulate<C-w>T
(“Move the current window to a new tab page”), exppectsvim.Window
object.after
andbefore
accept onlyvim.TabPage
objects,direction
is one of the following:Direction Shortcut for before
.create(before=vim.current.tabpage)
after
.create(after=vim.current.tabpage)
or just.create()
first
.create(before=vim.tabpages[0])
last
.create(after=vim.tabpages[-1])
Returns
vim.TabPage
object.vim.TabPage.move(after=None, before=None, direction=None)
:- Move tabpage before or after the given one or to the given direction (see above). All arguments are mutually exclusive.
vim.Window.move(direction)
:Move the window in the given direction which is one of the following:
Direction Description left
To the left, raises exception if already at the far left right
To the right, raises exception if already at the far right above
Move upwards, raises exception if already at the very top below
Move downwards, raises exception if already at the very bottom leftmost
Like <C-w>H
, do not raise an exceptionrightmost
Like <C-w>L
, do not raise an exceptiontop
Like <C-w>K
, do not raise an exceptionbottom
Like <C-w>J
, do not raise an exceptionXXX Implementation (and existence) of first four variants is subjectable.
vim.Window.exchange(window)
:- Exchange the window with the given one. Expects
vim.Window
object. Works like<C-w>x
. vim.Window.resize(horizontal=None, vertical=None, relative=True)
:- Resize window to the given value (i.e.
vim.current.window.resize(horizontal=0.8)
should make window 20% less wide;vim.current.window.resize(vertical=20)
should make window be 20 lines taller).relative
option (TODO: provide better name) determines whether floating-point values should be relative to the resized window (default) or to the overall available space. Use assigning tovim.Window.height
andvim.Window.width
if you want to resize to some exact value. vim.Window.close(force=False)
,vim.Buffer.close(force=False)
,vim.TabPage.close(force=False)
:Guess it is obvious what they do.
Also
del vim.windows[number]
,del vim.buffers[number]
anddel vim.tabpages[number]
as an alternatives.vim.Window.diffthis()
:- Like
:diffthis
.
Vim errors and exceptions will be transformed into python exceptions
(implementation: pretend that there is :try
block active).
In addition to transforming exceptions there will be some subclasses of
vim.error
and vim.VimError
(that is the same object as vim.error
;
latter will be marked as deprecated):
vim.VimDeletedError
:- Exception thrown by
Check{Buffer,Window,TabPage}
. vim.VimEvalError
:- To this exception vim exceptions will be transformed.
vim.VimLockedError
:- Used when trying to modify locked structure. Also when trying to change lock state of fixed object.
vim.VimValueError
:- Expected exceptions that do not fall into one of the previous categories (e.g. “cursor position outside buffer”).
vim.VimRuntimeError
:- Other errors which should not normally happen. E.g. errors starting with
"internal error: …"
. Usually indicates a bug or problems with allocating memory.
The following is additional stuff to ease creating python-only plugins by adding basic plugin management support:
'pythoninstallprg'
/'pip'
and'python3installprg'
/'pip3'
options:- Specify what program is used by
:pyload
/:py3load
commands below in case importing failed. :pyload[!] module.submodule[ args]
(and:py3load
) commands:Try to import
module.submodule
python module and run function__viminit__
from it. In case importing module fails runs&pythoninstallprg . " " . args
. If there are no arguments usesmodule
(without.submodule
) as an argument. Does not run&pythoninstallprg
if bang was specified. If module was successfully imported, but it does not contain__viminit__
function it errors out. Pseudo-code:def pyload(module, args=None, bang=False): try: # Don’t use this in real code, there is __import__! exec('import ' + module + ' as m') except ImportError: if not bang: vim.command('!' + vim.options['pip' + ('' if sys.version_info < (3,) else '3')] + + ' ' + (args or module.partition('.')[0])) pyload(module, bang=True) else: # Runs code if there was no exception, but outside of try: block # May raise AttributeError. Or any other error occurred in __viminit__ m.__viminit__()
:confirm pyload
should run confirmation before installing anything, otherwise program is installed using regular!
(well, underlying C functions) without asking.silent pyload
should supress any messages and installation process output likesilent !pip install …
would do. I guess this part will be gained “for free”.