sponsor Vim development Vim logo Vim Book Ad

VPars : Parameter substitution functions to be used in text fragments

 script karma  Rating 17/8, Downloaded by 1364  Comments, bugs, improvements  Vim wiki

created by
Bernd Pol
script type

Parameter substitution functions to be used in text fragments.

Designed as kernel to yet another template processing script, but may as well be used stand-alone or from another Vim script.

May be used interactively or in batch processing mode, both called from another Vim script (e.g. a templates manager) or directly by the user on a visually selected text block or by calling functions from the command line.


These are basic capabilities only. But VPars is extensively documented in the accompanying Vim help text. Look there for more detail and for the programming interface.

VPars basically works on a specially selected text block. It finds variables in there, waits for the user to enter replacement text and substitutes this upon a simple keypress (<F3> by default, but may be redefined at any time). Then the next variable in sequence is found, etc.

There are built-in mechanisms which allow to skip or alter variables in the course of processing, so VPars will finally wrap around to the beginning of the text block and reprocess it until all variables have been handled.


Each variable is assumed to have one of the following formats.

is a cursor mark which will simply be removed and the cursor be positioned there.

where 'value' denotes both the variable label and the default value.

where 'value' denotes the (possible empty) default value, and 'label' the explicit label of this variable.

There are almost no restrictions on the default value and the label as well, except that they must fit in the same line, and cannot contain another VPars variable. The user can even enter multiple lines as substitution text.

Pressing <F3> with the cursor inside the 'value' field of a simple variable will cause this and all equally named variables be replaced by the following text.
    * The current variable will be replaced by the text extending from the left '<|' delimiter up to the current cursor position.
    * If the cursor is positioned immediately after the left delimiter, the variable will be replaced by the given 'default' value.
    * Any text to the right of the cursor does not count.
      (Exception: If the variable bears an explicit ':label:' and was initially empty (of the form <||:label:|>), any text between the bars will be taken as replacement, independent of where the cursor was positioned.)

Any equally labeled variable within the currently marked text block will automatically receive the same replacement text, except delayed ones (see below).

where 'alt_1'..'alt_n' denote given alternative substitution values of which the one bearing the cursor will replace this one variable.

same, but explicitely labeled. The selected substitution will replace any variable with this name.

There is a primitive means of defining another order to visit the variables and/or cursor marks within the selected text block. This is based on the VPars method of repeatedly processing the given text block until no variables are left over.

If the variable mark found is surrounded by another level of '< .. >' delimiters, this extra level will be removed and the variable skipped in this turn.

This allows delaying the variable substitution until others are available, or to position a cursor to a mark located near the beginning of the most recently inserted text after all variable substitutions were done.

If there is an explicit ':label:' given, all variables bearing this label will be replaced with the substitution of the first occurrence found. This occurs independent of the form the other variables. Especially will the replacement text of simple variables replace alternative variables bearing this name and vice versa.

Text replacement will occur upon pressing <F3>. As long as there are variables in this block, <F3> will wrap around from the its end to the marked beginning line. This mechanism allows the handling of delayed variables.
    * The text boundaries are marked linewise.
    * Usually, the text bundaries will be marked by some calling function.
    * The user can expressely select a visual block, which will then repeatedly be parsed for variables upon pressing <F3>.
    * When there is no text block marked or there are no more variables found, the script switches to 'global mode', where the next variable from cursor to the end of the buffer will be found, if any. This global mode is strictly linear, no wrapping around will happen.

There is a VPars function implemented which allows batch replacement of any variable in the selected text block before interactive mode is entered.

Calling scripts may provide so-called hook functions which provide ways to process a VPars variable before and after substitution. See the vpars.txt help for more.
install details
To install VPars, copy the vpars.zip file into the ~/.vim directory or equivalent and unzip it there. This will install vpars.vim into the plugins subdirectory and vpars.txt into the doc subdirectory.

To enable access to this vpars.txt documentation start Vim and issue:
    :helptags ~/.vim/doc
vpars.txt should then be listed in the LOCAL ADDITIONS section of the Vim main help (issue :help, and the scroll down to the end).

To access VPars help:
    :help vpars
will display the CONTENTS section of this help, and
    :help vpars-index
will get you to the INDEX section (which collects all VPars help targets).

Do not forget to re-initialize the help tags every time you upgrade to another VPars version.

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
vpars.zip 2.1 2007-01-12 7.0 Bernd Pol more bugfixes;
better behavior of pause/resume block processing
vpars.zip 2.0 2006-12-02 7.0 Bernd Pol A lot of bugs fixed (thanks to Igor Prischepoff for his thorough testing efforts).
Calling VPars simplified by adding a new VPars_Run() function (see documentation).
GUI menu user interface and shortcuts overworked; there is now the possibility to pause (,jp) and resume (,jr) processing the substition loop.
vpars.zip 1.2 2006-11-23 7.0 Bernd Pol It is possible to escape the delay meaning of <...> brackets by putting dots around the variable: "<.<|label|>.>" will result in "<value>" after replacement;
cursor end line positioning will behave better in virtualedit modes;
two new shortcuts provided:
,jo will visually select the currently valid dedicated text block;
,ji will invalid such a text block;
a calling script can now ask VPars to put a menu in the GUI.
vpars.zip 1.1 2006-11-10 7.0 Bernd Pol Jump to block beginning/end added. Alternate set of shortcuts added ( ,jj = next variable | ,jb = jump block begin | ,je = jump block end )
vpars.zip 1.0 2006-10-27 7.0 Bernd Pol Initial upload
ip used for rating:

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.