mirror of
https://github.com/neovim/neovim.git
synced 2024-12-20 19:25:11 -07:00
722 lines
28 KiB
Plaintext
722 lines
28 KiB
Plaintext
*if_pyth.txt* For Vim version 7.4. Last change: 2014 Jul 23
|
|
|
|
|
|
VIM REFERENCE MANUAL by Paul Moore
|
|
|
|
|
|
The Python Interface to Vim *python* *Python*
|
|
|
|
1. Commands |python-commands|
|
|
2. The vim module |python-vim|
|
|
3. Buffer objects |python-buffer|
|
|
4. Range objects |python-range|
|
|
5. Window objects |python-window|
|
|
6. Tab page objects |python-tabpage|
|
|
7. vim.bindeval objects |python-bindeval-objects|
|
|
8. pyeval(), py3eval() Vim functions |python-pyeval|
|
|
9. Python 3 |python3|
|
|
|
|
See |nvim-python| for more information. {Nvim}
|
|
|
|
==============================================================================
|
|
1. Commands *python-commands*
|
|
|
|
*:python* *:py* *E263* *E264* *E887*
|
|
:[range]py[thon] {stmt}
|
|
Execute Python statement {stmt}. A simple check if
|
|
the `:python` command is working: >
|
|
:python print "Hello"
|
|
|
|
:[range]py[thon] << {endmarker}
|
|
{script}
|
|
{endmarker}
|
|
Execute Python script {script}.
|
|
Note: This command doesn't work when Python isn't
|
|
available. To avoid errors, see |script-here|.
|
|
|
|
{endmarker} must NOT be preceded by any white space. If {endmarker} is
|
|
omitted from after the "<<", a dot '.' must be used after {script}, like
|
|
for the |:append| and |:insert| commands.
|
|
This form of the |:python| command is mainly useful for including python code
|
|
in Vim scripts.
|
|
|
|
Example: >
|
|
function! IcecreamInitialize()
|
|
python << EOF
|
|
class StrawberryIcecream:
|
|
def __call__(self):
|
|
print 'EAT ME'
|
|
EOF
|
|
endfunction
|
|
<
|
|
Note: Python is very sensitive to the indenting. Make sure the "class" line
|
|
and "EOF" do not have any indent.
|
|
|
|
*:pydo*
|
|
:[range]pydo {body} Execute Python function "def _vim_pydo(line, linenr):
|
|
{body}" for each line in the [range], with the
|
|
function arguments being set to the text of each line
|
|
in turn, without a trailing <EOL>, and the current
|
|
line number. The function should return a string or
|
|
None. If a string is returned, it becomes the text of
|
|
the line in the current turn. The default for [range]
|
|
is the whole file: "1,$".
|
|
|
|
Examples:
|
|
>
|
|
:pydo return "%s\t%d" % (line[::-1], len(line))
|
|
:pydo if line: return "%4d: %s" % (linenr, line)
|
|
<
|
|
*:pyfile* *:pyf*
|
|
:[range]pyf[ile] {file}
|
|
Execute the Python script in {file}. The whole
|
|
argument is used as a single file name.
|
|
|
|
Both of these commands do essentially the same thing - they execute a piece of
|
|
Python code, with the "current range" |python-range| set to the given line
|
|
range.
|
|
|
|
In the case of :python, the code to execute is in the command-line.
|
|
In the case of :pyfile, the code to execute is the contents of the given file.
|
|
|
|
Python commands cannot be used in the |sandbox|.
|
|
|
|
To pass arguments you need to set sys.argv[] explicitly. Example: >
|
|
|
|
:python import sys
|
|
:python sys.argv = ["foo", "bar"]
|
|
:pyfile myscript.py
|
|
|
|
Here are some examples *python-examples* >
|
|
|
|
:python from vim import *
|
|
:python from string import upper
|
|
:python current.line = upper(current.line)
|
|
:python print "Hello"
|
|
:python str = current.buffer[42]
|
|
|
|
(Note that changes - like the imports - persist from one command to the next,
|
|
just like in the Python interpreter.)
|
|
|
|
*script-here*
|
|
When using a script language in-line, you might want to skip this when the
|
|
language isn't supported. Note that this mechanism doesn't work:
|
|
>
|
|
if has('python')
|
|
python << EOF
|
|
this will NOT work!
|
|
EOF
|
|
endif
|
|
|
|
Instead, put the Python command in a function and call that function:
|
|
>
|
|
if has('python')
|
|
function DefPython()
|
|
python << EOF
|
|
this works
|
|
EOF
|
|
endfunction
|
|
call DefPython()
|
|
endif
|
|
|
|
Note that "EOF" must be at the start of the line.
|
|
|
|
==============================================================================
|
|
2. The vim module *python-vim*
|
|
|
|
Python code gets all of its access to vim (with one exception - see
|
|
|python-output| below) via the "vim" module. The vim module implements two
|
|
methods, three constants, and one error object. You need to import the vim
|
|
module before using it: >
|
|
:python import vim
|
|
|
|
Overview >
|
|
:py print "Hello" # displays a message
|
|
:py vim.command(cmd) # execute an Ex command
|
|
:py w = vim.windows[n] # gets window "n"
|
|
:py cw = vim.current.window # gets the current window
|
|
:py b = vim.buffers[n] # gets buffer "n"
|
|
:py cb = vim.current.buffer # gets the current buffer
|
|
:py w.height = lines # sets the window height
|
|
:py w.cursor = (row, col) # sets the window cursor position
|
|
:py pos = w.cursor # gets a tuple (row, col)
|
|
:py name = b.name # gets the buffer file name
|
|
:py line = b[n] # gets a line from the buffer
|
|
:py lines = b[n:m] # gets a list of lines
|
|
:py num = len(b) # gets the number of lines
|
|
:py b[n] = str # sets a line in the buffer
|
|
:py b[n:m] = [str1, str2, str3] # sets a number of lines at once
|
|
:py del b[n] # deletes a line
|
|
:py del b[n:m] # deletes a number of lines
|
|
|
|
|
|
Methods of the "vim" module
|
|
|
|
vim.command(str) *python-command*
|
|
Executes the vim (ex-mode) command str. Returns None.
|
|
Examples: >
|
|
:py vim.command("set tw=72")
|
|
:py vim.command("%s/aaa/bbb/g")
|
|
< The following definition executes Normal mode commands: >
|
|
def normal(str):
|
|
vim.command("normal "+str)
|
|
# Note the use of single quotes to delimit a string containing
|
|
# double quotes
|
|
normal('"a2dd"aP')
|
|
< *E659*
|
|
The ":python" command cannot be used recursively with Python 2.2 and
|
|
older. This only works with Python 2.3 and later: >
|
|
:py vim.command("python print 'Hello again Python'")
|
|
|
|
vim.eval(str) *python-eval*
|
|
Evaluates the expression str using the vim internal expression
|
|
evaluator (see |expression|). Returns the expression result as:
|
|
- a string if the Vim expression evaluates to a string or number
|
|
- a list if the Vim expression evaluates to a Vim list
|
|
- a dictionary if the Vim expression evaluates to a Vim dictionary
|
|
Dictionaries and lists are recursively expanded.
|
|
Examples: >
|
|
:py text_width = vim.eval("&tw")
|
|
:py str = vim.eval("12+12") # NB result is a string! Use
|
|
# string.atoi() to convert to
|
|
# a number.
|
|
|
|
:py tagList = vim.eval('taglist("eval_expr")')
|
|
< The latter will return a python list of python dicts, for instance:
|
|
[{'cmd': '/^eval_expr(arg, nextcmd)$/', 'static': 0, 'name':
|
|
'eval_expr', 'kind': 'f', 'filename': './src/eval.c'}]
|
|
|
|
vim.bindeval(str) *python-bindeval*
|
|
Like |python-eval|, but returns special objects described in
|
|
|python-bindeval-objects|. These python objects let you modify (|List|
|
|
or |Dictionary|) or call (|Funcref|) vim objects.
|
|
|
|
vim.strwidth(str) *python-strwidth*
|
|
Like |strwidth()|: returns number of display cells str occupies, tab
|
|
is counted as one cell.
|
|
|
|
vim.foreach_rtp(callable) *python-foreach_rtp*
|
|
Call the given callable for each path in 'runtimepath' until either
|
|
callable returns something but None, the exception is raised or there
|
|
are no longer paths. If stopped in case callable returned non-None,
|
|
vim.foreach_rtp function returns the value returned by callable.
|
|
|
|
vim.chdir(*args, **kwargs) *python-chdir*
|
|
vim.fchdir(*args, **kwargs) *python-fchdir*
|
|
Run os.chdir or os.fchdir, then all appropriate vim stuff.
|
|
Note: you should not use these functions directly, use os.chdir and
|
|
os.fchdir instead. Behavior of vim.fchdir is undefined in case
|
|
os.fchdir does not exist.
|
|
|
|
Error object of the "vim" module
|
|
|
|
vim.error *python-error*
|
|
Upon encountering a Vim error, Python raises an exception of type
|
|
vim.error.
|
|
Example: >
|
|
try:
|
|
vim.command("put a")
|
|
except vim.error:
|
|
# nothing in register a
|
|
|
|
Constants of the "vim" module
|
|
|
|
Note that these are not actually constants - you could reassign them.
|
|
But this is silly, as you would then lose access to the vim objects
|
|
to which the variables referred.
|
|
|
|
vim.buffers *python-buffers*
|
|
A mapping object providing access to the list of vim buffers. The
|
|
object supports the following operations: >
|
|
:py b = vim.buffers[i] # Indexing (read-only)
|
|
:py b in vim.buffers # Membership test
|
|
:py n = len(vim.buffers) # Number of elements
|
|
:py for b in vim.buffers: # Iterating over buffer list
|
|
<
|
|
vim.windows *python-windows*
|
|
A sequence object providing access to the list of vim windows. The
|
|
object supports the following operations: >
|
|
:py w = vim.windows[i] # Indexing (read-only)
|
|
:py w in vim.windows # Membership test
|
|
:py n = len(vim.windows) # Number of elements
|
|
:py for w in vim.windows: # Sequential access
|
|
< Note: vim.windows object always accesses current tab page.
|
|
|python-tabpage|.windows objects are bound to parent |python-tabpage|
|
|
object and always use windows from that tab page (or throw vim.error
|
|
in case tab page was deleted). You can keep a reference to both
|
|
without keeping a reference to vim module object or |python-tabpage|,
|
|
they will not lose their properties in this case.
|
|
|
|
vim.tabpages *python-tabpages*
|
|
A sequence object providing access to the list of vim tab pages. The
|
|
object supports the following operations: >
|
|
:py t = vim.tabpages[i] # Indexing (read-only)
|
|
:py t in vim.tabpages # Membership test
|
|
:py n = len(vim.tabpages) # Number of elements
|
|
:py for t in vim.tabpages: # Sequential access
|
|
<
|
|
vim.current *python-current*
|
|
An object providing access (via specific attributes) to various
|
|
"current" objects available in vim:
|
|
vim.current.line The current line (RW) String
|
|
vim.current.buffer The current buffer (RW) Buffer
|
|
vim.current.window The current window (RW) Window
|
|
vim.current.tabpage The current tab page (RW) TabPage
|
|
vim.current.range The current line range (RO) Range
|
|
|
|
The last case deserves a little explanation. When the :python or
|
|
:pyfile command specifies a range, this range of lines becomes the
|
|
"current range". A range is a bit like a buffer, but with all access
|
|
restricted to a subset of lines. See |python-range| for more details.
|
|
|
|
Note: When assigning to vim.current.{buffer,window,tabpage} it expects
|
|
valid |python-buffer|, |python-window| or |python-tabpage| objects
|
|
respectively. Assigning triggers normal (with |autocommand|s)
|
|
switching to given buffer, window or tab page. It is the only way to
|
|
switch UI objects in python: you can't assign to
|
|
|python-tabpage|.window attribute. To switch without triggering
|
|
autocommands use >
|
|
py << EOF
|
|
saved_eventignore = vim.options['eventignore']
|
|
vim.options['eventignore'] = 'all'
|
|
try:
|
|
vim.current.buffer = vim.buffers[2] # Switch to buffer 2
|
|
finally:
|
|
vim.options['eventignore'] = saved_eventignore
|
|
EOF
|
|
<
|
|
vim.vars *python-vars*
|
|
vim.vvars *python-vvars*
|
|
Dictionary-like objects holding dictionaries with global (|g:|) and
|
|
vim (|v:|) variables respectively. Identical to `vim.bindeval("g:")`,
|
|
but faster.
|
|
|
|
vim.options *python-options*
|
|
Object partly supporting mapping protocol (supports setting and
|
|
getting items) providing a read-write access to global options.
|
|
Note: unlike |:set| this provides access only to global options. You
|
|
cannot use this object to obtain or set local options' values or
|
|
access local-only options in any fashion. Raises KeyError if no global
|
|
option with such name exists (i.e. does not raise KeyError for
|
|
|global-local| options and global only options, but does for window-
|
|
and buffer-local ones). Use |python-buffer| objects to access to
|
|
buffer-local options and |python-window| objects to access to
|
|
window-local options.
|
|
|
|
Type of this object is available via "Options" attribute of vim
|
|
module.
|
|
|
|
Output from Python *python-output*
|
|
Vim displays all Python code output in the Vim message area. Normal
|
|
output appears as information messages, and error output appears as
|
|
error messages.
|
|
|
|
In implementation terms, this means that all output to sys.stdout
|
|
(including the output from print statements) appears as information
|
|
messages, and all output to sys.stderr (including error tracebacks)
|
|
appears as error messages.
|
|
|
|
*python-input*
|
|
Input (via sys.stdin, including input() and raw_input()) is not
|
|
supported, and may cause the program to crash. This should probably be
|
|
fixed.
|
|
|
|
*python2-directory* *python3-directory* *pythonx-directory*
|
|
Python 'runtimepath' handling *python-special-path*
|
|
|
|
In python vim.VIM_SPECIAL_PATH special directory is used as a replacement for
|
|
the list of paths found in 'runtimepath': with this directory in sys.path and
|
|
vim.path_hooks in sys.path_hooks python will try to load module from
|
|
{rtp}/python2 (or python3) and {rtp}/pythonx (for both python versions) for
|
|
each {rtp} found in 'runtimepath'.
|
|
|
|
Implementation is similar to the following, but written in C: >
|
|
|
|
from imp import find_module, load_module
|
|
import vim
|
|
import sys
|
|
|
|
class VimModuleLoader(object):
|
|
def __init__(self, module):
|
|
self.module = module
|
|
|
|
def load_module(self, fullname, path=None):
|
|
return self.module
|
|
|
|
def _find_module(fullname, oldtail, path):
|
|
idx = oldtail.find('.')
|
|
if idx > 0:
|
|
name = oldtail[:idx]
|
|
tail = oldtail[idx+1:]
|
|
fmr = find_module(name, path)
|
|
module = load_module(fullname[:-len(oldtail)] + name, *fmr)
|
|
return _find_module(fullname, tail, module.__path__)
|
|
else:
|
|
fmr = find_module(fullname, path)
|
|
return load_module(fullname, *fmr)
|
|
|
|
# It uses vim module itself in place of VimPathFinder class: it does not
|
|
# matter for python which object has find_module function attached to as
|
|
# an attribute.
|
|
class VimPathFinder(object):
|
|
@classmethod
|
|
def find_module(cls, fullname, path=None):
|
|
try:
|
|
return VimModuleLoader(_find_module(fullname, fullname, path or vim._get_paths()))
|
|
except ImportError:
|
|
return None
|
|
|
|
@classmethod
|
|
def load_module(cls, fullname, path=None):
|
|
return _find_module(fullname, fullname, path or vim._get_paths())
|
|
|
|
def hook(path):
|
|
if path == vim.VIM_SPECIAL_PATH:
|
|
return VimPathFinder
|
|
else:
|
|
raise ImportError
|
|
|
|
sys.path_hooks.append(hook)
|
|
|
|
vim.VIM_SPECIAL_PATH *python-VIM_SPECIAL_PATH*
|
|
String constant used in conjunction with vim path hook. If path hook
|
|
installed by vim is requested to handle anything but path equal to
|
|
vim.VIM_SPECIAL_PATH constant it raises ImportError. In the only other
|
|
case it uses special loader.
|
|
|
|
Note: you must not use value of this constant directly, always use
|
|
vim.VIM_SPECIAL_PATH object.
|
|
|
|
vim.find_module(...) *python-find_module*
|
|
vim.path_hook(path) *python-path_hook*
|
|
Methods or objects used to implement path loading as described above.
|
|
You should not be using any of these directly except for vim.path_hook
|
|
in case you need to do something with sys.meta_path. It is not
|
|
guaranteed that any of the objects will exist in the future vim
|
|
versions.
|
|
|
|
vim._get_paths *python-_get_paths*
|
|
Methods returning a list of paths which will be searched for by path
|
|
hook. You should not rely on this method being present in future
|
|
versions, but can use it for debugging.
|
|
|
|
It returns a list of {rtp}/python2 (or {rtp}/python3) and
|
|
{rtp}/pythonx directories for each {rtp} in 'runtimepath'.
|
|
|
|
==============================================================================
|
|
3. Buffer objects *python-buffer*
|
|
|
|
Buffer objects represent vim buffers. You can obtain them in a number of ways:
|
|
- via vim.current.buffer (|python-current|)
|
|
- from indexing vim.buffers (|python-buffers|)
|
|
- from the "buffer" attribute of a window (|python-window|)
|
|
|
|
Buffer objects have two read-only attributes - name - the full file name for
|
|
the buffer, and number - the buffer number. They also have three methods
|
|
(append, mark, and range; see below).
|
|
|
|
You can also treat buffer objects as sequence objects. In this context, they
|
|
act as if they were lists (yes, they are mutable) of strings, with each
|
|
element being a line of the buffer. All of the usual sequence operations,
|
|
including indexing, index assignment, slicing and slice assignment, work as
|
|
you would expect. Note that the result of indexing (slicing) a buffer is a
|
|
string (list of strings). This has one unusual consequence - b[:] is different
|
|
from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas
|
|
"b = None" merely updates the variable b, with no effect on the buffer.
|
|
|
|
Buffer indexes start at zero, as is normal in Python. This differs from vim
|
|
line numbers, which start from 1. This is particularly relevant when dealing
|
|
with marks (see below) which use vim line numbers.
|
|
|
|
The buffer object attributes are:
|
|
b.vars Dictionary-like object used to access
|
|
|buffer-variable|s.
|
|
b.options Mapping object (supports item getting, setting and
|
|
deleting) that provides access to buffer-local options
|
|
and buffer-local values of |global-local| options. Use
|
|
|python-window|.options if option is window-local,
|
|
this object will raise KeyError. If option is
|
|
|global-local| and local value is missing getting it
|
|
will return None.
|
|
b.name String, RW. Contains buffer name (full path).
|
|
Note: when assigning to b.name |BufFilePre| and
|
|
|BufFilePost| autocommands are launched.
|
|
b.number Buffer number. Can be used as |python-buffers| key.
|
|
Read-only.
|
|
b.valid True or False. Buffer object becomes invalid when
|
|
corresponding buffer is wiped out.
|
|
|
|
The buffer object methods are:
|
|
b.append(str) Append a line to the buffer
|
|
b.append(str, nr) Idem, below line "nr"
|
|
b.append(list) Append a list of lines to the buffer
|
|
Note that the option of supplying a list of strings to
|
|
the append method differs from the equivalent method
|
|
for Python's built-in list objects.
|
|
b.append(list, nr) Idem, below line "nr"
|
|
b.mark(name) Return a tuple (row,col) representing the position
|
|
of the named mark (can also get the []"<> marks)
|
|
b.range(s,e) Return a range object (see |python-range|) which
|
|
represents the part of the given buffer between line
|
|
numbers s and e |inclusive|.
|
|
|
|
Note that when adding a line it must not contain a line break character '\n'.
|
|
A trailing '\n' is allowed and ignored, so that you can do: >
|
|
:py b.append(f.readlines())
|
|
|
|
Buffer object type is available using "Buffer" attribute of vim module.
|
|
|
|
Examples (assume b is the current buffer) >
|
|
:py print b.name # write the buffer file name
|
|
:py b[0] = "hello!!!" # replace the top line
|
|
:py b[:] = None # delete the whole buffer
|
|
:py del b[:] # delete the whole buffer
|
|
:py b[0:0] = [ "a line" ] # add a line at the top
|
|
:py del b[2] # delete a line (the third)
|
|
:py b.append("bottom") # add a line at the bottom
|
|
:py n = len(b) # number of lines
|
|
:py (row,col) = b.mark('a') # named mark
|
|
:py r = b.range(1,5) # a sub-range of the buffer
|
|
:py b.vars["foo"] = "bar" # assign b:foo variable
|
|
:py b.options["ff"] = "dos" # set fileformat
|
|
:py del b.options["ar"] # same as :set autoread<
|
|
|
|
==============================================================================
|
|
4. Range objects *python-range*
|
|
|
|
Range objects represent a part of a vim buffer. You can obtain them in a
|
|
number of ways:
|
|
- via vim.current.range (|python-current|)
|
|
- from a buffer's range() method (|python-buffer|)
|
|
|
|
A range object is almost identical in operation to a buffer object. However,
|
|
all operations are restricted to the lines within the range (this line range
|
|
can, of course, change as a result of slice assignments, line deletions, or
|
|
the range.append() method).
|
|
|
|
The range object attributes are:
|
|
r.start Index of first line into the buffer
|
|
r.end Index of last line into the buffer
|
|
|
|
The range object methods are:
|
|
r.append(str) Append a line to the range
|
|
r.append(str, nr) Idem, after line "nr"
|
|
r.append(list) Append a list of lines to the range
|
|
Note that the option of supplying a list of strings to
|
|
the append method differs from the equivalent method
|
|
for Python's built-in list objects.
|
|
r.append(list, nr) Idem, after line "nr"
|
|
|
|
Range object type is available using "Range" attribute of vim module.
|
|
|
|
Example (assume r is the current range):
|
|
# Send all lines in a range to the default printer
|
|
vim.command("%d,%dhardcopy!" % (r.start+1,r.end+1))
|
|
|
|
==============================================================================
|
|
5. Window objects *python-window*
|
|
|
|
Window objects represent vim windows. You can obtain them in a number of ways:
|
|
- via vim.current.window (|python-current|)
|
|
- from indexing vim.windows (|python-windows|)
|
|
- from indexing "windows" attribute of a tab page (|python-tabpage|)
|
|
- from the "window" attribute of a tab page (|python-tabpage|)
|
|
|
|
You can manipulate window objects only through their attributes. They have no
|
|
methods, and no sequence or other interface.
|
|
|
|
Window attributes are:
|
|
buffer (read-only) The buffer displayed in this window
|
|
cursor (read-write) The current cursor position in the window
|
|
This is a tuple, (row,col).
|
|
height (read-write) The window height, in rows
|
|
width (read-write) The window width, in columns
|
|
vars (read-only) The window |w:| variables. Attribute is
|
|
unassignable, but you can change window
|
|
variables this way
|
|
options (read-only) The window-local options. Attribute is
|
|
unassignable, but you can change window
|
|
options this way. Provides access only to
|
|
window-local options, for buffer-local use
|
|
|python-buffer| and for global ones use
|
|
|python-options|. If option is |global-local|
|
|
and local value is missing getting it will
|
|
return None.
|
|
number (read-only) Window number. The first window has number 1.
|
|
This is zero in case it cannot be determined
|
|
(e.g. when the window object belongs to other
|
|
tab page).
|
|
row, col (read-only) On-screen window position in display cells.
|
|
First position is zero.
|
|
tabpage (read-only) Window tab page.
|
|
valid (read-write) True or False. Window object becomes invalid
|
|
when corresponding window is closed.
|
|
|
|
The height attribute is writable only if the screen is split horizontally.
|
|
The width attribute is writable only if the screen is split vertically.
|
|
|
|
Window object type is available using "Window" attribute of vim module.
|
|
|
|
==============================================================================
|
|
6. Tab page objects *python-tabpage*
|
|
|
|
Tab page objects represent vim tab pages. You can obtain them in a number of
|
|
ways:
|
|
- via vim.current.tabpage (|python-current|)
|
|
- from indexing vim.tabpages (|python-tabpages|)
|
|
|
|
You can use this object to access tab page windows. They have no methods and
|
|
no sequence or other interfaces.
|
|
|
|
Tab page attributes are:
|
|
number The tab page number like the one returned by
|
|
|tabpagenr()|.
|
|
windows Like |python-windows|, but for current tab page.
|
|
vars The tab page |t:| variables.
|
|
window Current tabpage window.
|
|
valid True or False. Tab page object becomes invalid when
|
|
corresponding tab page is closed.
|
|
|
|
TabPage object type is available using "TabPage" attribute of vim module.
|
|
|
|
==============================================================================
|
|
7. vim.bindeval objects *python-bindeval-objects*
|
|
|
|
vim.Dictionary object *python-Dictionary*
|
|
Dictionary-like object providing access to vim |Dictionary| type.
|
|
Attributes:
|
|
Attribute Description ~
|
|
locked One of *python-.locked*
|
|
Value Description ~
|
|
zero Variable is not locked
|
|
vim.VAR_LOCKED Variable is locked, but can be unlocked
|
|
vim.VAR_FIXED Variable is locked and can't be unlocked
|
|
Read-write. You can unlock locked variable by assigning
|
|
`True` or `False` to this attribute. No recursive locking
|
|
is supported.
|
|
scope One of
|
|
Value Description ~
|
|
zero Dictionary is not a scope one
|
|
vim.VAR_DEF_SCOPE |g:| or |l:| dictionary
|
|
vim.VAR_SCOPE Other scope dictionary,
|
|
see |internal-variables|
|
|
Methods (note: methods do not support keyword arguments):
|
|
Method Description ~
|
|
keys() Returns a list with dictionary keys.
|
|
values() Returns a list with dictionary values.
|
|
items() Returns a list of 2-tuples with dictionary contents.
|
|
update(iterable), update(dictionary), update(**kwargs)
|
|
Adds keys to dictionary.
|
|
get(key[, default=None])
|
|
Obtain key from dictionary, returning the default if it is
|
|
not present.
|
|
pop(key[, default])
|
|
Remove specified key from dictionary and return
|
|
corresponding value. If key is not found and default is
|
|
given returns the default, otherwise raises KeyError.
|
|
popitem()
|
|
Remove random key from dictionary and return (key, value)
|
|
pair.
|
|
has_key(key)
|
|
Check whether dictionary contains specified key, similar
|
|
to `key in dict`.
|
|
|
|
__new__(), __new__(iterable), __new__(dictionary), __new__(update)
|
|
You can use `vim.Dictionary()` to create new vim
|
|
dictionaries. `d=vim.Dictionary(arg)` is the same as
|
|
`d=vim.bindeval('{}');d.update(arg)`. Without arguments
|
|
constructs empty dictionary.
|
|
|
|
Examples: >
|
|
d = vim.Dictionary(food="bar") # Constructor
|
|
d['a'] = 'b' # Item assignment
|
|
print d['a'] # getting item
|
|
d.update({'c': 'd'}) # .update(dictionary)
|
|
d.update(e='f') # .update(**kwargs)
|
|
d.update((('g', 'h'), ('i', 'j'))) # .update(iterable)
|
|
for key in d.keys(): # .keys()
|
|
for val in d.values(): # .values()
|
|
for key, val in d.items(): # .items()
|
|
print isinstance(d, vim.Dictionary) # True
|
|
for key in d: # Iteration over keys
|
|
class Dict(vim.Dictionary): # Subclassing
|
|
<
|
|
Note: when iterating over keys you should not modify dictionary.
|
|
|
|
vim.List object *python-List*
|
|
Sequence-like object providing access to vim |List| type.
|
|
Supports `.locked` attribute, see |python-.locked|. Also supports the
|
|
following methods:
|
|
Method Description ~
|
|
extend(item) Add items to the list.
|
|
|
|
__new__(), __new__(iterable)
|
|
You can use `vim.List()` to create new vim lists.
|
|
`l=vim.List(iterable)` is the same as
|
|
`l=vim.bindeval('[]');l.extend(iterable)`. Without
|
|
arguments constructs empty list.
|
|
Examples: >
|
|
l = vim.List("abc") # Constructor, result: ['a', 'b', 'c']
|
|
l.extend(['abc', 'def']) # .extend() method
|
|
print l[1:] # slicing
|
|
l[:0] = ['ghi', 'jkl'] # slice assignment
|
|
print l[0] # getting item
|
|
l[0] = 'mno' # assignment
|
|
for i in l: # iteration
|
|
print isinstance(l, vim.List) # True
|
|
class List(vim.List): # Subclassing
|
|
|
|
vim.Function object *python-Function*
|
|
Function-like object, acting like vim |Funcref| object. Supports `.name`
|
|
attribute and is callable. Accepts special keyword argument `self`, see
|
|
|Dictionary-function|. You can also use `vim.Function(name)` constructor,
|
|
it is the same as `vim.bindeval('function(%s)'%json.dumps(name))`.
|
|
|
|
Examples: >
|
|
f = vim.Function('tr') # Constructor
|
|
print f('abc', 'a', 'b') # Calls tr('abc', 'a', 'b')
|
|
vim.command('''
|
|
function DictFun() dict
|
|
return self
|
|
endfunction
|
|
''')
|
|
f = vim.bindeval('function("DictFun")')
|
|
print f(self={}) # Like call('DictFun', [], {})
|
|
print isinstance(f, vim.Function) # True
|
|
|
|
==============================================================================
|
|
8. pyeval() and py3eval() Vim functions *python-pyeval*
|
|
|
|
To facilitate bi-directional interface, you can use |pyeval()| and |py3eval()|
|
|
functions to evaluate Python expressions and pass their values to VimL.
|
|
|
|
==============================================================================
|
|
9. Python 3 *python3*
|
|
|
|
*:py3* *:python3*
|
|
The `:py3` and `:python3` commands work similar to `:python`. A simple check
|
|
if the `:py3` command is working: >
|
|
:py3 print("Hello")
|
|
< *:py3file*
|
|
The `:py3file` command works similar to `:pyfile`.
|
|
*:py3do* *E863*
|
|
The `:py3do` command works similar to `:pydo`.
|
|
|
|
*E880*
|
|
Raising SystemExit exception in python isn't endorsed way to quit vim, use: >
|
|
:py vim.command("qall!")
|
|
<
|
|
*has-python*
|
|
You can test what Python version is available with: >
|
|
if has('python')
|
|
echo 'there is Python 2.x'
|
|
elseif has('python3')
|
|
echo 'there is Python 3.x'
|
|
endif
|
|
|
|
Note however, that if Python 2 and 3 are both available, but not loaded,
|
|
these has() calls will try to load them.
|
|
|
|
==============================================================================
|
|
vim:tw=78:ts=8:ft=help:norl:
|