home *** CD-ROM | disk | FTP | other *** search
/ vim.ftp.fu-berlin.de / 2015-02-03.vim.ftp.fu-berlin.de.tar / vim.ftp.fu-berlin.de / mac / vim55rt.sit / runtime / doc / if_python.txt < prev    next >
Encoding:
Text File  |  1999-09-25  |  9.2 KB  |  244 lines  |  [TEXT/MPS ]
  1. *if_python.txt* For Vim version 5.5.  Last change: 1999 Sep 16
  2.  
  3.  
  4.           VIM REFERENCE MANUAL    by Paul Moore
  5.  
  6.  
  7. The Python Interface to Vim                *python* *Python*
  8.  
  9. 1. Commands            |python-commands|
  10. 2. The vim module        |python-vim|
  11. 3. Buffer objects        |python-buffer|
  12. 4. Range objects        |python-range|
  13. 5. Window objects        |python-window|
  14.  
  15. {Vi does not have any of these commands}
  16.  
  17. The Python interface only works when Vim was compiled with the |+python|
  18. feature.
  19.  
  20. ==============================================================================
  21. 1. Commands                        *python-commands*
  22.  
  23.                             *:python* *:py*
  24. :[range]py[thon] {stmt}    Execute Python statement {stmt}.  {not in Vi}
  25.  
  26.                             *:pyfile* *:pyf*
  27. :[range]pyf[ile] {file}    Execute the Python script in {file}.  {not in Vi}
  28.  
  29. Both of these commands do essentially the same thing - they execute a piece of
  30. Python code, with the "current range" |python-range| set to the given line
  31. range.
  32.  
  33. In the case of :python, the code to execute is specified on the command-line.
  34. In the case of :pyfile, the code to execute is the contents of the given file.
  35.  
  36. Here are some examples                    *python-examples*
  37.  
  38. >    :python from vim import *
  39. >    :python from string import upper
  40. >    :python current.line = upper(current.line)
  41. >    :python print "Hello"
  42. >    :python str = current.buffer[42]
  43.  
  44. (Note that changes - like the imports - persist from one command to the next,
  45. just like in the Python interpreter).
  46.  
  47. ==============================================================================
  48. 2. The vim module                    *python-vim*
  49.  
  50. Python code gets all of its access to vim (with one exception - see
  51. |python-output| below) via the "vim" module. The vim module implements two
  52. methods, three constants, and one error object.
  53.  
  54. Overview
  55. >    print "Hello"            # displays a message
  56. >    vim.command(cmd)        # execute an ex command
  57. >    w = vim.windows[n]        # gets window "n"
  58. >    cw = vim.current.window    # gets the current window
  59. >    b = vim.buffers[n]        # gets buffer "n"
  60. >    cb = vim.current.buffer    # gets the current buffer
  61. >    w.height = lines        # sets the window height
  62. >    w.cursor = (row, col)        # sets the window cursor position
  63. >    pos = w.cursor            # gets a tuple (row, col)
  64. >    name = b.name            # gets the buffer file name
  65. >    line = b[n]            # gets a line from the buffer
  66. >    lines = b[n:m]            # gets a list of lines
  67. >    num = len(b)            # gets the number of lines
  68. >    b[n] = str            # sets a line in the buffer
  69. >    b[n:m] = [str1, str2, str3]    # sets a number of lines at once
  70. >    del b[n]            # deletes a line
  71. >    del b[n:m]            # deletes a number of lines
  72.  
  73. Methods
  74.     vim.command(str)                *python-command*
  75.     Executes the vim (ex-mode) command str. Returns None.
  76.     Examples:
  77. >        vim.command("set tw=72")
  78. >        vim.command("%s/aaa/bbb/g")
  79.     To execute normal-mode commands, the following definition could be
  80.     used:
  81. >        def normal(str):
  82. >            vim.command("normal "+str)
  83. >        # Note the use of '...' to delimit a string containing double
  84. >        # quotes
  85. >        normal('"a2dd"aP')
  86.  
  87.     vim.expr(str)                    *python-expr*
  88.     Evaluates the expression str using the vim internal expression
  89.     evaluator (see |expression|). Returns the expression result as a
  90.     string.
  91.     Examples:
  92. >        text_width = vim.expr("'tw'")
  93. >        str = vim.expr("12+12")        # NB result is a string! Use
  94. >                        # string.atoi() to convert to
  95. >                        # a number.
  96.  
  97. Error object
  98.     vim.error                    *python-error*
  99.     All vim errors encountered by Python are raised as exceptions of type
  100.     vim.error.
  101.     Example:
  102. >        try:
  103. >            vim.command("put a")
  104. >        except vim.error:
  105. >            # nothing in register a
  106.  
  107. Constants
  108.     Note that these are not actually constants - in theory you could
  109.     reassign them. But this is silly, as you would then lose access to the
  110.     vim objects referred to by the variables.
  111.  
  112.     vim.buffers                    *python-buffers*
  113.     A sequence object providing access to the list of vim buffers. The
  114.     following operations are supported:
  115. >        b = vim.buffers[i]    # Indexing (read-only)
  116. >        b in vim.buffers    # Membership test
  117. >        n = len(vim.buffers)    # Number of elements
  118. >        for b in vim.buffers:    # Sequential access
  119.  
  120.     vim.windows                    *python-windows*
  121.     A sequence object providing access to the list of vim windows. The
  122.     following operations are supported:
  123. >        w = vim.windows[i]    # Indexing (read-only)
  124. >        w in vim.windows    # Membership test
  125. >        n = len(vim.windows)    # Number of elements
  126. >        for w in vim.windows:    # Sequential access
  127.  
  128.     vim.current                    *python-current*
  129.     An object providing access (via specific attributes) to various
  130.     "current" objects available in vim:
  131.         vim.current.line    The current line (RW)        String
  132.         vim.current.buffer    The current buffer (RO)        Buffer
  133.         vim.current.window    The current window (RO)        Window
  134.         vim.current.range    The current line range (RO)    Range
  135.  
  136.     The last case deserves a little explanation. When a range is specified
  137.     in the :python or :pyfile command, this range of lines is treated as
  138.     the "current range". A range is a bit like a buffer, but with all
  139.     access restricted to a subset of lines. See |python-range| for more
  140.     details.
  141.  
  142. Output from Python                    *python-output*
  143.     All output from Python code is displayed in the Vim message area.
  144.     Normal output is displayed as information messages, and error output
  145.     is displayed as error messages.
  146.  
  147.     In implementation terms, this means that all output directed to
  148.     sys.stdout (including the output from print statements) is displayed
  149.     by vim as an information message, and all output directed to
  150.     sys.stderr (including error tracebacks) is displayed by vim as an
  151.     error message.
  152.  
  153.                             *python-input*
  154.     Input (via sys.stdin, including input() and raw_input()) is not
  155.     supported, and may cause the program to crash. This should probably be
  156.     fixed.
  157.  
  158. ==============================================================================
  159. 3. Buffer objects                    *python-buffer*
  160.  
  161. Buffer objects represent vim buffers. They can be obtained in a number of
  162. ways:
  163.     - via vim.current.buffer (|python-current|)
  164.     - from indexing vim.buffers (|python-buffers|)
  165.     - from the "buffer" attribute of a window (|python-window|)
  166.  
  167. Buffer objects have one read-only attribute - name - the full file name for
  168. the buffer. They also have three methods (append, mark, and range) which are
  169. described below.
  170.  
  171. Buffer objects can also be treated as sequence objects. In this context, they
  172. act as if they were lists (yes, they are mutable) of strings, with each
  173. element being a line of the buffer. All of the usual sequence operations,
  174. including indexing, index assignment, slicing and slice assignment, work as
  175. you would expect. Note that the result of indexing (slicing) a buffer is a
  176. string (list of strings). This has one unusual consequence - b[:] is different
  177. from b. In particular, "b[:] = None" deletes the whole of the buffer, whereas
  178. "b = None" merely updates the variable b, with no effect on the buffer.
  179.  
  180. Buffer indexes start at zero, as is normal in Python. This differs from vim
  181. line numbers, which start from 1. This is particularly relevant when dealing
  182. with marks (see below) which use vim line numbers.
  183.  
  184. The buffer object methods are:
  185.     b.append(str)    Append a line to the buffer
  186.     b.append(list)    Append a list of lines to the buffer
  187.             Note that the option of supplying a list of strings to
  188.             the append method differs from the equivalent method
  189.             for Python's built-in list objects.
  190.     b.mark(name)    Return a tuple (row,col) representing the position
  191.             of the named mark (can also get the []"<> marks)
  192.     b.range(s,e)    Return a range object (see |python-range|) which
  193.             represents the part of the given buffer between line
  194.             numbers s and e (inclusive).
  195.  
  196. Examples (assume b is the current buffer)
  197. >    print b.name        # write the buffer file name
  198. >    b[0] = "hello!!!"    # replace the top line
  199. >    b[:] = None        # delete the whole buffer
  200. >    del b[:]        # delete the whole buffer (same as above)
  201. >    b[0:0] = "add a line"    # add a line at the top
  202. >    del b[2]        # delete a line (the third)
  203. >    b.append("bottom")    # add a line at the bottom
  204. >    n = len(b)        # number of lines
  205. >    (row,col) = b.mark('a') # named mark
  206. >    r = b.range(1,5)    # a sub-range of the buffer
  207.  
  208. ==============================================================================
  209. 4. Range objects                    *python-range*
  210.  
  211. Range objects represent a part of a vim buffer. They can be obtained in a
  212. number of ways:
  213.     - via vim.current.range (|python-current|)
  214.     - from a buffer's range() method (|python-buffer|)
  215.  
  216. A range object is almost identical in operation to a buffer object. However,
  217. all operations are restricted to the lines within the range (this line range
  218. can, of course, change as a result of slice assignments, line deletions, or
  219. the range.append() method).
  220.  
  221. Unlike buffers, ranges do not have a "name" attribute, nor do they have mark()
  222. or range() methods. They do have an append() method, however, which adds
  223. line(s) to the end of the range.
  224.  
  225. ==============================================================================
  226. 5. Window objects                    *python-window*
  227.  
  228. Window objects represent vim windows. They can be obtained in a number of
  229. ways:
  230.     - via vim.current.window (|python-current|)
  231.     - from indexing vim.windows (|python-windows|)
  232.  
  233. Window objects can only be manipulated through their attributes. They have no
  234. methods, and no sequence or other interface.
  235.  
  236. Window attributes are
  237.     buffer (read-only)    The buffer displayed in this window
  238.     cursor (read-write)    The current cursor position in the window
  239.                 This is a tuple, (row,col).
  240.     height (read-write)    The window height, in rows
  241.  
  242. ==============================================================================
  243.  vim:tw=78:ts=8:sw=8:
  244.