The basics in depth

Omnipytent is based around the tasks file - a file that contains your tasks, which are small Python functions that you can invoke. The basic Omnipytent Vim commands are:

• :OP [<task-name> [<args>...]] - run tasks. Without arguments it'll prompt you to choose a task to run. If you run it with an argument, that argument will be the name of the task that will run. You can add more arguments and they'll be passed to the task.
• :OPedit [<task-name>] - edit the tasks file. If you don't have a tasks file, it will be created. If you pass it a task name as an argument, it will automatically create a scaffold task with that name. If such a task already exists, it'll open the tasks file and jump to that task.
  • There are also :OPsedit, :OPvedit and :OPtedit flavors that open the tasks file in a new split, vertical split, or tab.

Let us look at the tasks file we created in the getting started guide:

import vim
from omnipytent import *


@task
def build(ctx):
    CMD.make('--quiet')


@task
def run(ctx):
    BANG('./a.out', 'hello', 'world')


@task
def debug(ctx):
    TERMINAL_PANEL('gdb', './a.out')

The two imports at the top are added automatically when you create the tasks file. One import Vim's python module (see :help python-vim), and the other import Omnipytent's goodies - like task, CMD, BANG and TERMINAL_PANEL. These are things commonly used in tasks files.

The first task, build, is using the CMD object - a shortcut for running Vim commands. With CMD.make we get the make function, and the same goes for all other commands - be they builtin or user-defined. You have to use the command's full name. This creates a Python function that invokes the commands with its arguments (as strings) when called.

If you want to use a command with an exclamation mark, use .bang. Like this:

CMD.make.bang('--quiet')

to run :make! --quiet.

You can also use CMD as a dictionary:

CMD['make']()
CMD['make!']()

BANG(<command>) is just good old :!<command>. Note that unlike CMD, BANG will shell-escape its arguments. So:

BANG('rm' ,'foo bar')

Will delete one file named foo bar, not two files named foo and bar. If you want to run an unescaped command use the << operator:

BANG << 'rm foo bar'

BANG is a ShellCommandExecuter - an Omnipytent class used as an interface for conveniently running shell commands in various ways. Another shell command executer is TERMINAL_PANEL - that opens a :terminal in a new panel to run the command, and is useful for interactive commands or REPLs.

Two more executers not shown in the getting started guide's tasks file:

• SH - same as BANG, but will raise an an exception if the command returns a non-zero exit code.
• TERMINAL_TAB - same as TERMINAL_PANEL but opens the terminal in a new tab.