Tutorial
========

Basic Usage
-----------

Firstly, import module.
*headlessvim* module has some submodules for internal use.
Only the top module is designed to import by user.

.. code:: python

    >>> 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*.

.. code:: python

    >>> 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:

.. code:: python

    >>> 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 :py:class:`headlessvim.Vim`.

Generally, something which has been opened should be closed
when the manipulation has been finished.
``Vim`` is not the exception.

.. code:: python

    >>> vim.close()

Of course you can use ``with`` statement to ensure closing ``Vim``.
It is recommended.

.. code:: python

    >>> with headlessvim.open() as vim:
    ...     vim.echo('"spam"')
    ...
    'spam'

More complex example:

.. code:: python

    >>> 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): # doctest: +SKIP
    ...    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*:

.. code:: python

    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 <http://pytest.org>`_:

.. code:: python

    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'