Written by Jannis Pohlmann, February 2008. Last updated on July 8th, 2008.
All you need to have is VIM (no idea as of which version the plugin works) with filetype detection enabled. To enable this, put the following into your .vimrc:
filetype plugin onTo install the plugin, just copy jptemplate.vim to the VIM plugin directory.
cp jptemplate.vim $HOME/.vim/plugin/All you need to do to configure VIM is to define the directory where all templates can be found. By default $HOME/.vim/jptemplate/ is used.
If you want to define a directory on your own, put the following into your .vimrc:
let g:jpTemplateDir = '/path/to/the/template/directory'| Parameter | Default value | Meaning |
|---|---|---|
| g:jpTemplateDir | '$HOME/.vim/jptemplate' | Path to the template directory. |
| g:jpTemplateKey | '<C-Tab>' | Keyboard shortcut for triggering templates |
| g:jpTemplateDateFormat | '%Y-%m-%d' | Default strftime format used for ${date} |
| g:jpTemplateDefaults | {} | Dictionary with global default values for (non-special) template variables. |
| g:jpTemplateVerbose | 0 | Can be used to increase the verbosity level (either 0 or 1). |
Writing templates is easy. They are plain text files with embedded variables. When triggering a template, you are asked to enter values for most of these variables. After that the template is inserted into your document and all variables are replaced by the values you defined before.
Variables are defined using the following syntax: ${put variable name here}.
You can optionally provide a default value with ${variable name:default value}. You can also define global defaults for any of these variables. See section Configuration parameters for more information. Please note that the value in ${variable name:default value} will always override the global default.
This is an example for a simple for loop:
for (${initializer expression:int i = 0}; ${loop test expression}; ${counting expression:++i})
{
${cursor}
}Please note that the ${cursor} variable is special. See the section Special variables for more information about ${cursor} and other special variables.
You can also define one variable to appear several times in the same template. In this case you'll be asked only once to enter a value for the variable. Imagine a signature template:
Yours faithfully,
${name}
Address:
${name}
${street}
${city}Variables are case sensitive. Multiple occurences like ${x:i} ${x}' will yield i i. ${x} ${x:i} with a global default j for x will result in i i. Templates like ${x:i} ${x:j} ... end up as i i.
This section deals with the structure of the template directory. See section Configuring VIM on how to define it.
Let's assume for now that you are using the default template directory, which is $HOME/.vim/jptemplate/. This is how the directory structure has to look like:
$HOME/.vim/jptemplate/
cpp/
class
for
fun
if
...
c -> cpp/
general/
ruby/
class
def
for
if
module
...
sh/
...
...Each subdirectory contains templates for one VIM file type. I guess the template filenames are pretty self-explanatory: Each filename represents the name you have to enter to trigger the template in VIM. Of course you can create symlinks everywhere if you like (as I did with c -> cpp/ in the example). Note that the general/ directory is special: it is used as a fallback lookup directory for all filetypes (even unknown ones). This way you can share templates across different file types.
Hint: If you need to find out the filetype of a file you want to write a plugin for, just enter :echo &ft and VIM will tell you.
The following table illustrates which variables are reserved for special situations or just for some magic. Some variables require a parameter.
| Variable | Parameters | Examples | Effect |
|---|---|---|---|
| ${cursor} | This is where the cursor will be located after the template has been inserted into your document. | ||
| ${date} | strftime format string (optional) | ${date} ${date:%Y-%m-%d} |
Insert the current date. |
| ${shell} | Shell command | ${shell:ls -la} ${shell:firefox &>/dev/null} |
Run a shell command and replace the variable with its output. |
| ${interactive_shell} | Shell command (optional) | See ${shell} | Same as ${shell} but will ask you to enter a shell command prior to executing it. |
Using the templates is pretty straight-forwarded. Let's assume you're editing a C++ file and you have a working for template. This is all you need to do to trigger the template:
for<C-Tab>Pressing <C-Tab> will lookup the template for. If the template contains any non-reserved variables, VIM will start asking you to enter values for these variables. Once all questions have been answered, the template will inserted where the for was in your code. If the template contains ${cursor}, the cursor will be moved to that position.
You can change the keyboard shortcut by setting the variable g:jpTemplateKey in your .vimrc. Example:
let g:jpTemplateKey = '<Esc>'These are some demo videos I prepared of version 1.0 of the script. See the Features section for a list of features supported by more recent versions.
Please send bugs and feature requests to jannis@xfce.org. Thanks!