Vim as a system interpreter for vimscript

One of the basic features that make Vim a powerful product is the scripting facility it offers, often called vimscript. It allows many authors to write plugins and scripts that can integrate Vim with and any software or system you can think of, and that allows Vim to be customized to work in almost any way you need it.

The language still uses the original ed / ex / vi commands. These are standard tools today, in the current POSIX (Portable Operating System Interfaces) specification, and scripts of ex commands can be used as a diff and patch format, or to perform other line-oriented manipulation of text.

You can see that ex scripts have a different purpose than the most Vim scripts today. They are used for test-manipulation tasks outside ex/vi/vim, unlike the kind of usage in current Vim scripts is to modify/improve/affect Vim itself. Lets consider the usual Vim scripts (plugin/syntax/compiler/indent and others) as "internal" scripts, and the ex scripts would be "command" or "external" scripts.

Now the nice thing is, Vim can of course run ex scripts too, and is also a command language that can run external command scripts, other than plugins and syntax files. And Vim can use more than plain ex commands, it uses the extended vimscript language, so Vim turns into a real interpreter, like the ones for other languages. Add to that that it can even invoke python and other languages, too.

Needless to say, for any text processing task vim can be a powerful command tool.

Vim running in ex mode

The -e and -E command options on the Vim command line put vim in "ex" mode (also reachable with gQ from a running vim instance), where all input to the program consists of ex and vimscript commands, like in a language interpreter. The difference between -e and -E is that -E introduces command-line editing and history (called improved ex mode) to the plain ex mode selected with -e. However command scripts do not use the command-line editing features and are often run with just vim -e.

Even with Ex mode you still get an edit window open, including when running vim in a terminal, which is not quite as expected from a system interpreter. For this Vim will also accepts the -s command line options when in ex mode, to run in silent (batch) mode. This has several effects:

• you will not see an edit window when running the editor
• all output is suppressed by default, except for some specific commands. This includes and error messages
• default initialization from ~/.vimrc and ~/.gvimrc is suppressed. Note the side-effect that without a .vimrc file Vim stays in compatible mode, which is not what you want.
• if any error occurs, the exit code from vim (at the end of the script) will be non-zero.

This is mostly a good approach to running vim as a system intepreter, except for a few things that need more attention:

• for any non-trivial program, suppressing error output is a show-stopper that will take down any kind of development effort. This can be changed by explicitly setting verbose level on the command line, most likey to the level of 1 with -V1
• Vim is not at all friendly in vi-compatible mode, so we want the -N option on the command line, to explicitly start vim in non-compatible mode and get all the non-vi features Vim has to offer
• while we are discussing command line, we may also include certain other options:
  • -i NONE will make Vim ignore the viminfo file
  • -n will more vim use no swap file.
  • -u NORC and -u NONE are on the same category as the others above, but they are implied by -s

One more needed thing to run Vim as an interpreter is to pass a script file to Vim and have Vim exit when the script finishes. This is traditionally achieved with input/output redirection, where the standard input stream is redirected from the script file to be run. But for an interpreter you would expected to also be able to pass in the script file directly, not only be redirection. For this we use the -S srcfile Vim option for Vim to source the given file, or even -S %, for vim to source the first file argument present on the command line. About quitting Vim, it is of course possible to use :qall! in the script itself. But using -c "qall!" option on the command line is a better way. This way the script only has to deal with the task it performs, and can be re-used and included in other scripts without implicitly ending the Vim session. To summarize, run vim as a language interpreter like this:

     vim -i NONE -u NORC -U NONE -V1 -nNesS script-cmd -c'echo""|qall!' -- args...

The echo "" is here for another reason: in vimscript, echo commands start each line with an end-of-line indicator, instead of eding the lines with an eol, as you would expect in a terminal. So an additional :echo "" is included before the end of the script. Sometimes a space is needed instead of the empty string.

References

• :help toc