Tutorial¶
Basic Usage¶
Firstly, import module. headlessvim module has some submodules for internal use. Only the top module is designed to import by user.
>>> import headlessvim
Warning
DO NOT import by from headlessvim import *
.
headlessvim module has the function named open
.
So it hides built-in open
function.
Secondly, open the background Vim process.
open
is the only entry point to open Vim.
>>> vim = headlessvim.open()
open
returns Vim
object which is the interface to
the background Vim process.
open
takes some arguments which are passed to the constructor of Vim
.
Note
Make sure not instantiate Vim
by its constructor.
It’s like the relationship between built-in file
and open
.
Let it say something:
>>> vim.echo('"spam"') # make sure to quote bare words
'spam'
Yes, vim.echo
actually invokes :echo
command of the background Vim,
so you should quote bare words twice.
To know what is possible, see headlessvim.Vim
.
Generally, something which has been opened should be closed
when the manipulation has been finished.
Vim
is not the exception.
>>> vim.close()
Of course you can use with
statement to ensure closing Vim
.
It is recommended.
>>> with headlessvim.open() as vim:
... vim.echo('"spam"')
...
'spam'
More complex example:
>>> import headlessvim
>>> with headlessvim.open() as vim:
... vim.echo('"spam"') # make sure to quote bare words
...
'spam'
>>> import os
>>> env = dict(os.environ, LANG='C')
>>> with headlessvim.open(executable='/usr/bin/vim', args='-N -u /etc/vim/vimrc', env=env):
... vim.send_keys('iham\033')
... vim.display_lines()[0].strip()
...
'ham'
Unit Test Integration¶
headlessvim is useful for testing vim plugins.
An example for standard PyUnit:
import unittest
import headlessvim
class TestVimPlugin(unittest.TestCase):
def setUp(self):
self.vim = headlessvim.open()
self.vim.install_plugin('fixtures/spam', 'plugin/spam.vim')
def tearDown(self):
self.vim.close()
def testSomeFeature(self):
res = self.vim.echo('"ham egg"')
self.assertEqual(res, 'ham egg')
More example for pytest:
import os
import pytest
import headlessvim
@pytest.fixture
def env(request):
return dict(os.environ, LANG='C')
@pytest.yield_fixture
def vim(request, env):
with headlessvim.open(args='-N -u /etc/vim/vimrc', env=env) as vim:
vim.install_plugin('fixtures/spam', 'plugin/spam.vim')
yield vim
def test_spam(vim):
assert vim.echo('"spam"') == 'spam'