headlessvim package

Module contents

headlessvim module

Note

This module is the public interface of headlessvim package. Import this module to start using headlessvim.

Example:

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

class headlessvim.Vim(executable='vim', args=None, env=None, encoding='utf-8', size=(80, 24), timeout=0.25)

Bases: object

A class representing a headless Vim. Do not instantiate this directly, instead use open.

Vim object behaves as contextmanager.

Variables:Vim.default_args (string or list of string) – the default launch argument of Vim

args

Returns:arguments for the process. Return type:list of string

close()

Disconnect and close Vim.

command(command, capture=True)

Execute command on Vim. .. warning:: Do not use redir command if capture is True. It’s already enabled for internal use.

If capture argument is set False, the command execution becomes slightly faster.

Example:

>>> import headlessvim
>>> with headlessvim.open() as vim:
...     vim.command('echo 0')
...
'0'
>>> with headlessvim.open() as vim:
...     vim.command('let g:spam = "ham"', False)
...     vim.echo('g:spam')
...
'ham'

Parameters:

• command (string) – a command to execute
• capture (boolean) – True if command’s output needs to be captured, else False

Returns:

the output of the given command

Return type:

string

default_args = '-N -i NONE -n -u NONE'

display()

Shows the terminal screen connecting to Vim.

Example:

>>> import headlessvim
>>> with headlessvim.open(size=(64, 16)) as vim: 
...     print(vim.display())
...
~
~                          VIM - Vi IMproved
~
~                           version 7.4.52
~                      by Bram Moolenaar et al.
~
~             Vim is open source and freely distributable
~
~                      Sponsor Vim development!
~           type  :help sponsor<Enter>    for information
~
~           type  :q<Enter>               to exit
~           type  :help<Enter>  or  <F1>  for on-line help
~           type  :help version7<Enter>   for version info
~
~

Returns:screen as a text Return type:string

display_lines()

Shows the terminal screen splitted by newlines.

Almost equals to self.display().splitlines()

Returns:screen as a list of strings Return type:list of string

echo(expr)

Execute :echo command on Vim.

Note

The given string is passed to Vim as it is. Make sure to quote bare words.

Example:

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

Parameters:expr (string) – a expr to :echo Returns:the result of :echo command Return type:string

encoding

Returns:internal encoding of Vim. Return type:string

executable

Returns:the absolute path to the process. Return type:string

install_plugin(dir, entry_script=None)

Install Vim plugin.

Parameters:

• dir (string) – the root directory contains Vim script
• entry_script (string) – path to the initializing script

is_alive()

Check if the background Vim process is alive.

Returns:True if the process is alive, else False Return type:boolean

runtimepath

Returns:runtime path of Vim Return type:runtimepath.RuntimePath

screen_size

Returns:(lines, columns) tuple of a screen connected to Vim. Return type:(int, int)

send_keys(keys, wait=True)

Send a raw key sequence to Vim.

Note

Vim style key sequence notation (like <Esc>) is not recognized. Use escaped characters (like '') instead.

Example:

>>> import headlessvim
>>> with headlessvim.open() as vim:
...     vim.send_keys('ispam')
...     str(vim.display_lines()[0].strip())
...
'spam'

Parameters:

• keys (strgin) – key sequence to send
• wait (boolean) – whether if wait a response

set_mode(mode)

Set Vim mode to mode. Supported modes:

• normal
• insert
• command
• visual
• visual-block

This method behave as setter-only property.

Example:

>>> import headlessvim
>>> with headlessvim.open() as vim:
...     vim.set_mode('insert')
...     vim.mode = 'normal' # also accessible as property
...

Parameters:mode (string) – Vim mode to set Raises ValueError:  if mode is not supported

timeout

Returns:seconds to wait I/O. Return type:float

wait(timeout=None)

Wait for response until timeout. If timeout is specified to None, self.timeout is used.

Parameters:timeout (float) – seconds to wait I/O

headlessvim.open(**kwargs)

A factory function to open new Vim object. with statement can be used for this.

Submodules

headlessvim.arguments module

Note

This module is not designed to be used by user.

class headlessvim.arguments.Parser(default_args)

Bases: object

A class to parse launch arguments for Vim.

default_args

Returns:default arguments given on init. Return type:string or list of string

parse(args)

Parameters:args (None or string or list of string) – arguments Returns:formatted arguments if specified else self.default_args Return type:list of string

headlessvim.process module

Note

This module is not designed to be used by user.

class headlessvim.process.Process(executable, args, env)

Bases: object

A class representing a background Vim process.

args

Returns:launch arguments of the process. Return type:string or list of string

check_readable(timeout)

Poll self.stdout and return True if it is readable.

Parameters:timeout (float) – seconds to wait I/O Returns:True if readable, else False Return type:boolean

executable

Returns:the absolute path to the process. Return type:strIng

is_alive()

Check if the process is alive.

Returns:True if the process is alive, else False Return type:boolean

kill()

Kill this process. Use this only when the process seems to be hanging up.

stdin

Returns:file-like object representing the standard input of the process Return type:flie-like object

stdout

Returns:non blocking file-like object representing the standard output of the process Return type:file-like object

terminate()

Terminate this process. Use this method rather than self.kill.