diff options
Diffstat (limited to 'vim73/doc/if_pyth.txt')
| -rw-r--r-- | vim73/doc/if_pyth.txt | 382 |
1 files changed, 382 insertions, 0 deletions
diff --git a/vim73/doc/if_pyth.txt b/vim73/doc/if_pyth.txt new file mode 100644 index 0000000..51f936e --- /dev/null +++ b/vim73/doc/if_pyth.txt @@ -0,0 +1,382 @@ +*if_pyth.txt* For Vim version 7.3. Last change: 2010 Oct 20 + + + 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. Dynamic loading |python-dynamic| +7. Python 3 |python3| + +{Vi does not have any of these commands} + +The Python 2.x interface is available only when Vim was compiled with the +|+python| feature. +The Python 3 interface is available only when Vim was compiled with the +|+python3| feature. + +============================================================================== +1. Commands *python-commands* + + *:python* *:py* *E205* *E263* *E264* +:[range]py[thon] {stmt} + Execute Python statement {stmt}. + +:[range]py[thon] << {endmarker} +{script} +{endmarker} + Execute Python script {script}. + Note: This command doesn't work when the Python + feature wasn't compiled in. 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. Also make sure the "class" +line and "EOF" do not have any indent. + + *:pyfile* *:pyf* +:[range]pyf[ile] {file} + Execute the Python script in {file}. The whole + argument is used as a single file name. {not in Vi} + +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.) + +============================================================================== +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'}] + + + +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 sequence 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: # Sequential access +< +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 +< +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 (RO) Buffer + vim.current.window The current window (RO) Window + 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. + + +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. + +============================================================================== +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 one read-only attribute - name - the full file name for +the buffer. 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 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()) + +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 + +============================================================================== +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" + +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|) + +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 +The height attribute is writable only if the screen is split horizontally. +The width attribute is writable only if the screen is split vertically. + +============================================================================== +6. Dynamic loading *python-dynamic* + +On MS-Windows the Python library can be loaded dynamically. The |:version| +output then includes |+python/dyn|. + +This means that Vim will search for the Python DLL file only when needed. +When you don't use the Python interface you don't need it, thus you can use +Vim without this DLL file. + +To use the Python interface the Python DLL must be in your search path. In a +console window type "path" to see what directories are used. + +The name of the DLL must match the Python version Vim was compiled with. +Currently the name is "python24.dll". That is for Python 2.4. To know for +sure edit "gvim.exe" and search for "python\d*.dll\c". + +============================================================================== +7. Python 3 *python3* + + *:py3* *:python3* +The |:py3| and |:python3| commands work similar to |:python|. + *:py3file* +The |:py3file| command works similar to |:pyfile|. + +Vim can be built in four ways (:version output): +1. No Python support (-python, -python3) +2. Python 2 support only (+python or +python/dyn, -python3) +3. Python 3 support only (-python, +python3 or +python3/dyn) +4. Python 2 and 3 support (+python/dyn, +python3/dyn) + +Some more details on the special case 4: + +When Python 2 and Python 3 are both supported they must be loaded dynamically. + +When doing this on Linux/Unix systems and importing global symbols, this leads +to a crash when the second Python version is used. So either global symbols +are loaded but only one Python version is activated, or no global symbols are +loaded. The latter makes Python's "import" fail on libraries that expect the +symbols to be provided by Vim. + *E836* *E837* +Vim's configuration script makes a guess for all libraries based on one +standard Python library (termios). If importing this library succeeds for +both Python versions, then both will be made available in Vim at the same +time. If not, only the version first used in a session will be enabled. +When trying to use the other one you will get the E836 or E837 error message. + +Here Vim's behavior depends on the system in which it was configured. In a +system where both versions of Python were configured with --enable-shared, +both versions of Python will be activated at the same time. There will still +be problems with other third party libraries that were not linked to +libPython. + +To work around such problems there are these options: +1. The problematic library is recompiled to link to the according + libpython.so. +2. Vim is recompiled for only one Python version. +3. You undefine PY_NO_RTLD_GLOBAL in auto/config.h after configuration. This + may crash Vim though. + + +============================================================================== + vim:tw=78:ts=8:ft=help:norl: |