diff options
Diffstat (limited to 'runtime/doc/if_pyth.txt')
| -rw-r--r-- | runtime/doc/if_pyth.txt | 111 |
1 files changed, 85 insertions, 26 deletions
diff --git a/runtime/doc/if_pyth.txt b/runtime/doc/if_pyth.txt index 8946dd2e5a..df4b54ef76 100644 --- a/runtime/doc/if_pyth.txt +++ b/runtime/doc/if_pyth.txt @@ -1,22 +1,14 @@ -*if_pyth.txt* For Vim version 7.4. Last change: 2014 Jul 23 +*if_pyth.txt* Nvim VIM REFERENCE MANUAL by Paul Moore -The Python Interface to Vim *python* *Python* +The Python Interface to Vim *if_pyth* *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 |provider-python| for more information. -See |provider-python| for more information. {Nvim} + Type |gO| to see the table of contents. ============================================================================== 1. Commands *python-commands* @@ -48,7 +40,12 @@ Example: > print 'EAT ME' EOF endfunction -< + +To see what version of Python you have: > + :python print(sys.version) + +There is no need to import sys, it's done by default. + Note: Python is very sensitive to the indenting. Make sure the "class" line and "EOF" do not have any indent. @@ -67,6 +64,18 @@ Examples: :pydo return "%s\t%d" % (line[::-1], len(line)) :pydo if line: return "%4d: %s" % (linenr, line) < +One can use `:pydo` in possible conjunction with `:py` to filter a range using +python. For example: > + + :py3 << EOF + needle = vim.eval('@a') + replacement = vim.eval('@b') + + def py_vim_string_replace(str): + return str.replace(needle, replacement) + EOF + :'<,'>py3do return py_vim_string_replace(line) +< *:pyfile* *:pyf* :[range]pyf[ile] {file} Execute the Python script in {file}. The whole @@ -83,7 +92,6 @@ 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 @@ -122,7 +130,7 @@ Instead, put the Python command in a function and call that function: Note that "EOF" must be at the start of the line. ============================================================================== -2. The vim module *python-vim* +2. The vim module *python-vim* *python2* 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 @@ -181,11 +189,6 @@ vim.eval(str) *python-eval* # 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| @@ -688,7 +691,8 @@ vim.Function object *python-Function* 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. +functions to evaluate Python expressions and pass their values to Vim script. +|pyxeval()| is also available. ============================================================================== 9. Python 3 *python3* @@ -697,9 +701,13 @@ functions to evaluate Python expressions and pass their values to VimL. The `:py3` and `:python3` commands work similar to `:python`. A simple check if the `:py3` command is working: > :py3 print("Hello") + +To see what version of Python you have: > + :py3 import sys + :py3 print(sys.version) < *:py3file* The `:py3file` command works similar to `:pyfile`. - *:py3do* *E863* + *:py3do* The `:py3do` command works similar to `:pydo`. *E880* @@ -710,12 +718,63 @@ Raising SystemExit exception in python isn't endorsed way to quit vim, use: > You can test what Python version is available with: > if has('python') echo 'there is Python 2.x' - elseif has('python3') + endif + if 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. +============================================================================== +10. Python X *python_x* *pythonx* + +Because most python code can be written so that it works with Python 2.6+ and +Python 3, the pyx* functions and commands have been written. They work the +same as the Python 2 and 3 variants, but select the Python version using the +'pyxversion' setting. + +Set 'pyxversion' in your |vimrc| to prefer Python 2 or Python 3 for Python +commands. Changing this setting at runtime risks losing the state of plugins +(such as initialization). + +If you want to use a module, you can put it in the {rtp}/pythonx directory. +See |pythonx-directory|. + + *:pyx* *:pythonx* +`:pyx` and `:pythonx` work similar to `:python`. To check if `:pyx` works: > + :pyx print("Hello") + +To see what version of Python is being used: > + :pyx import sys + :pyx print(sys.version) +< + *:pyxfile* *python_x-special-comments* +`:pyxfile` works similar to `:pyfile`. But you can add a "shebang" comment to +force Vim to use `:pyfile` or `:py3file`: > + #!/any string/python2 " Shebang. Must be the first line of the file. + #!/any string/python3 " Shebang. Must be the first line of the file. + # requires python 2.x " Maximum lines depend on 'modelines'. + # requires python 3.x " Maximum lines depend on 'modelines'. +Unlike normal modelines, the bottom of the file is not checked. +If none of them are found, the 'pyxversion' option is used. + *W20* *W21* +If Vim does not support the selected Python version a silent message will be +printed. Use `:messages` to read them. + + *:pyxdo* +`:pyxdo` works similar to `:pydo`. + + *has-pythonx* +To check if pyx* functions and commands are available: > + if has('pythonx') + echo 'pyx* commands are available. (Python ' . &pyx . ')' + endif + +If you prefer Python 2 and want to fallback to Python 3, set 'pyxversion' +explicitly in your |.vimrc|. Example: > + if has('python') + set pyx=2 + elseif has('python3') + set pyx=3 + endif ============================================================================== - vim:tw=78:ts=8:ft=help:norl: + vim:tw=78:ts=8:noet:ft=help:norl: |