share/vim/vim58/doc/if_python.txt

   1 *if_python.txt* For Vim version 5.8.  Last change: 1999 Oct 28
   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.eval(str)                                   *python-eval*
  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.eval("'tw'")
  93 >               str = vim.eval("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: