This is a description of proposed new python interfaces.
==================
New python objects
==================
vim.mappings/{buffer}.mappings:
Dictionary-like object mapping mode characters to vim.modemappings objects
below. Unlike vim.buffers iteration is being done for keys.
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. Unlike vim.buffers
iteration is being done for keys.
mapping:
Namedtuple-like object with the following attributes:
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 appropriate
vim.mappings[mode] (buffer.mappings[mode]) objects.
vim.commands/{buffer}.commands
Mapping-like object mapping command names to vim.command objects. Assigning
vim.Command object to the key acts like :command, `sid` attribute is
ignored. Unlike vim.buffers iteration is being done for keys.
command:
Namedtuple-like object with the following attributes:
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 either
vim.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 or False. Determines whether .range attribute really
describes -count argument.
bang, bar, register
True or False.
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.
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)
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:
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:
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 is 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.
signplace:
Object with the following attributes:
id Identifier.
line Line number.
name Names of signs: keys in vim.signs.
. Also has method .jump().
vim.scripts:
Sequence-like object that removes the need of parsing :scriptnames. Maps
script numbers (subtracted by one) to file names.
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:
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.
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”.
==================
New VimL functions
==================
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:
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:
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:
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
name Name suitable for signarg().
id Sign ID.
line Line number.
getjumps()
Returns a list of dictionaries with the following keys:
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}]).
Note: {bufnr} is {expr} argument from bufnr() function.
=======================================
Python classes that are made accessible
=======================================
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 like
`mode`,
`buffer` or `lhs`: they are determined by appropriate keys and objects when
assigning. `sid` attribute is created automatically (though in any case it
is ignored when assigning).
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 like `name` or `buffer`. `sid` attribute is created
automatically (though in any case it is ignored when assigning).
vim.Autocommand(command, pattern, nested=True)
Returns new autocmd group as described above.
vim.Sign(text, icon=None, linehl=None, texthl=None)
Returns new sign as described above.
vim.Dictionary(dict)
vim.Dictionary(iterable)
vim.Dictionary(**kwargs)
Returns a vim.dictionary object. Is subclassable.
vim.List(iterable)
Returns a vim.list object. Is subclassable. Main reason for creating this
and
previous classes is not subclassability (it is highly optional) or ability
to define new lists without using `vim.bindeval`, but ability to use
`isinstance(vim.bindeval("var"), vim.Dictionary)`.
Note: here are different (more convenient) defaults:
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
=========================
Auxilary/helper functions
=========================
vim.special_expand() + special_expand() :: string -> string
Expands special characters like `<C-a>` in the string. Currently it is done
in VimL by using `eval('"'.escape(str, '\<"').'"')` which is rather hacky.
vim.match_glob() :: glob, string -> boolean
match_glob() :: string, glob -> boolean
Match string against glob expression. Order is different in python and
VimL:
in python it is taken from `re.match(pattern, string)`, in VimL from
`matchstr({expr}, {pat})`.
vim.find_buffer() :: string -> vim.buffer
Like vim.buffers[vim.bindeval("bufnr(string)")].
=================================
Changes to existing functionality
=================================
- Iterators for *.windows and vim.tabpages that allow
for window in vim.windows:
window.close()
like it is allowed for buffer list.
- {buffer}.wipe(), {window}.close() and {tabpage}.close() methods.
Alternative: `del vim.buffers[number]`, `del {windowlist}[number]` and
`del vim.tabpages[number]`.
- {dictionary}.items(), {dictionary}.values(), {dictionary}.pop() and
{dictionary}.update() (last is most useful).
- Doing `item in {dictionary}` without doing `{dictionary}[item]`.
- `iter({dictionary})` iterating over keys.
- {function}.sid and {function}.code attributes.
- {buffer}.valid, {window}.valid, {tabpage}.valid, {windowlist}.valid and
{function}.valid attributes.
- {window}.tabpage attribute and {window}.number attribute working for
non-current tab pages.
- vim.eval(expr, number_strings=True): sometimes python objects are more
desired
then what vim.bindeval returns, but numbers represented as strings spoil it
all.
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups
"vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
For more options, visit https://groups.google.com/groups/opt_out.
