290 lines
10 KiB
Plaintext
290 lines
10 KiB
Plaintext
|
*template.txt* Simple templates plug-in
|
|||
|
|
|
|||
|
|
CONTENTS *template-contents*
|
|||
|
|
|
|||
|
|
Introduction |template-introduction|
|
|||
|
|
Usage |template-usage|
|
|||
|
|
Commands |template-commands|
|
|||
|
|
Configuration |template-configuration|
|
|||
|
|
Search order |template-search-order|
|
|||
|
|
Variables |template-variables|
|
|||
|
|
User Variables |template-user-variables|
|
|||
|
|
Troubleshooting |template-troubleshooting|
|
|||
|
|
|
|||
|
|
|
|||
|
|
===========================================================================
|
|||
|
|
INTRODUCTION *template-introduction*
|
|||
|
|
|
|||
|
|
This is a simple plug-in for Vim (and NeoVim) allowing to have template
|
|||
|
|
files per file type, which will be used as starting point when creating
|
|||
|
|
new buffers. Template files may contain variables (|template-variables|),
|
|||
|
|
which are expanded at the time of buffer creation (see |template-usage|).
|
|||
|
|
The main purpose of the templates is to add boilerplate code to new
|
|||
|
|
files, like C/C++ header guards, or license disclaimers.
|
|||
|
|
|
|||
|
|
|
|||
|
|
===========================================================================
|
|||
|
|
USAGE *template-usage*
|
|||
|
|
|
|||
|
|
Templates can be used by creating a new file name, the file suffix will
|
|||
|
|
determine which template is used:
|
|||
|
|
>
|
|||
|
|
$ vim foo.c
|
|||
|
|
<
|
|||
|
|
Templates can be manually expanded in the current buffer using the
|
|||
|
|
|:Template| command. For example, the following will load and expand the
|
|||
|
|
template for a file matching the pattern `*.c`:
|
|||
|
|
>
|
|||
|
|
:Template *.c
|
|||
|
|
<
|
|||
|
|
|
|||
|
|
Note that automatic insertion of templates can be disabling by setting
|
|||
|
|
the `g:templates_no_autocmd` variable.
|
|||
|
|
|
|||
|
|
|
|||
|
|
===========================================================================
|
|||
|
|
COMMANDS *template-commands*
|
|||
|
|
|
|||
|
|
The plug-in defines two commands, both of which expand a template in the
|
|||
|
|
current buffer. The first expands a matched template at the beginning of
|
|||
|
|
the current buffer. Its syntax is:
|
|||
|
|
|
|||
|
|
*:Template* <pattern>
|
|||
|
|
|
|||
|
|
The <pattern> must be the same as for the template file that is to be
|
|||
|
|
expanded into the current buffer. For example:
|
|||
|
|
>
|
|||
|
|
:Template *.c
|
|||
|
|
>
|
|||
|
|
will expand the local template `.vim-template:*.c`, or the global template
|
|||
|
|
`template:*.c`, whichever is found first (see |template-search-order|
|
|||
|
|
for more information).
|
|||
|
|
|
|||
|
|
The second command works exactly the same except that it will expand a matched
|
|||
|
|
template under the cursor instead of at the beginning of the buffer. Its syntax
|
|||
|
|
is:
|
|||
|
|
|
|||
|
|
*:TemplateHere* <pattern>
|
|||
|
|
|
|||
|
|
|
|||
|
|
===========================================================================
|
|||
|
|
CONFIGURATION *template-configuration*
|
|||
|
|
|
|||
|
|
The following variables can be used to configure the behaviour of the
|
|||
|
|
plug-in:
|
|||
|
|
|
|||
|
|
`g:templates_no_autocmd`
|
|||
|
|
Whether to disable automatic insertion of templates when new
|
|||
|
|
buffers are created. (Default: `0`).
|
|||
|
|
|
|||
|
|
`g:templates_directory`
|
|||
|
|
Path of a directory containing additional global templates.
|
|||
|
|
Alternatively, it can contain a list of paths, which will
|
|||
|
|
be searched in order. See |template-search-order| for more
|
|||
|
|
details. (Default: `[]`).
|
|||
|
|
|
|||
|
|
`g:templates_name_prefix`
|
|||
|
|
Prefix for path-relative templates. See |template-search-order|
|
|||
|
|
for more details. (Default: `.vim-template:`).
|
|||
|
|
|
|||
|
|
`g:templates_global_name_prefix`
|
|||
|
|
Prefix for global templates (builtin and those listed in
|
|||
|
|
`g:templates_directory`, NOT path-relative templates). See
|
|||
|
|
|template-search-order| for more details. (Default:
|
|||
|
|
`=template=`).
|
|||
|
|
|
|||
|
|
`g:templates_fuzzy_start`
|
|||
|
|
If non-zero, template patterns are not forced to match the
|
|||
|
|
entire file name, just the end (`<pattern>$`). If zero, template
|
|||
|
|
patterns need to consume the entire file name to procure a match
|
|||
|
|
(`^<pattern>$`). For example, if `g:templates_fuzzy_start = 1`,
|
|||
|
|
a file named `template:.c` would match files named `.c` and
|
|||
|
|
`test.c`. If set to zero, the template would only match `.c`
|
|||
|
|
(Default: `1`).
|
|||
|
|
|
|||
|
|
`g:templates_tr_in`, and `g:templates_tr_out`
|
|||
|
|
These variables control how template names are interpreted as
|
|||
|
|
regular expressions for matching file names. This can be
|
|||
|
|
useful on a Windows box where `*` is not allowed in file
|
|||
|
|
names. The default configuration converts underscores (`_`)
|
|||
|
|
into regular expression wildcards (`.*`).
|
|||
|
|
|
|||
|
|
(Default: `['.','*','?']`, and `['\.','.*','\?']`).
|
|||
|
|
|
|||
|
|
`g:templates_no_builtin_templates`
|
|||
|
|
If non-zero, disables usage of the built-in templates. See
|
|||
|
|
|template-search-order| for more details. (Default: `0`).
|
|||
|
|
|
|||
|
|
`g:templates_user_variables`
|
|||
|
|
Allows expansion of user-defined variables. See
|
|||
|
|
|template-user-variables| for more details.
|
|||
|
|
(Default: `[]`).
|
|||
|
|
|
|||
|
|
`g:templates_debug`
|
|||
|
|
If non-zero, output debugging information. (Default: `0`).
|
|||
|
|
|
|||
|
|
`g:templates_plugin_loaded`
|
|||
|
|
Setting this to a non-zero value will disable the plug-in.
|
|||
|
|
(Default: `0`).
|
|||
|
|
|
|||
|
|
`g:templates_search_height`
|
|||
|
|
Controls the search in the current directory and parents. If
|
|||
|
|
set to -1, the template is searched for in the given
|
|||
|
|
directory and all parents in its directory structure, stopping
|
|||
|
|
at the first matching template. If set to 0, no searching
|
|||
|
|
is done in the given directory or any parents. If set to [1]
|
|||
|
|
only the given directory is searched. If greater
|
|||
|
|
than one, n parents and the given directory will be searched
|
|||
|
|
where n is equal to height - 1. (Default: `-1`).
|
|||
|
|
|
|||
|
|
|
|||
|
|
===========================================================================
|
|||
|
|
SEARCH ORDER *template-search-order*
|
|||
|
|
|
|||
|
|
Searching for templates uses the following logic:
|
|||
|
|
|
|||
|
|
1. If a file named `.vim-template:<pattern>` exists in the current
|
|||
|
|
directory, it is used. If there are multiple template files that match
|
|||
|
|
pattern in the same directory, the one that is most specific is used.
|
|||
|
|
If no suitable template is found, goto step `(2)`.
|
|||
|
|
|
|||
|
|
2. If a parent directory exists, it is set as current directory, and goto
|
|||
|
|
step `(1)`; otherwise goto step `(3)`.
|
|||
|
|
|
|||
|
|
3. Try to use `=template=<pattern>` file from the directories specified using
|
|||
|
|
the `g:templates_directory` variable (only if the option is defined,
|
|||
|
|
and the directory exists).
|
|||
|
|
|
|||
|
|
4. Try to use the `=template=<pattern>` file supplied with the plug-in (only
|
|||
|
|
if `g:templates_no_builtin_templates` is undefined or has a zero value).
|
|||
|
|
|
|||
|
|
Note that the `.vim-template:` local file prefix can be set using the
|
|||
|
|
`g:templates_name_prefix` variable, and the `=template=` global file prefix
|
|||
|
|
can be set using the `g:templates_global_name_prefix` variable. The variable
|
|||
|
|
`g:templates_search_height` controls searching the current directory and
|
|||
|
|
parents.
|
|||
|
|
|
|||
|
|
|
|||
|
|
===========================================================================
|
|||
|
|
VARIABLES *template-variables*
|
|||
|
|
|
|||
|
|
Template variables are all-caps identifiers surrounded by percent signs,
|
|||
|
|
e.g. `%VAR%`. The following variables are available for expansion in
|
|||
|
|
templates:
|
|||
|
|
|
|||
|
|
`%DAY%`, `%YEAR%`, `%MONTH`
|
|||
|
|
Current day of the month, year, and month of the year,
|
|||
|
|
as numeric values.
|
|||
|
|
|
|||
|
|
`%DATE%`
|
|||
|
|
Current date in `YYYY-mm-dd` format. This is equivalent
|
|||
|
|
to expanding `%YEAR%-%MONTH%-%DAY%`.
|
|||
|
|
|
|||
|
|
`%TIME%`
|
|||
|
|
Current time in `HH:MM` format.
|
|||
|
|
|
|||
|
|
`%FDATE%`
|
|||
|
|
Current full date (date and time) in `YYYY-mm-dd HH:MM`
|
|||
|
|
format. This is equivalent to expanding `%DATE% %TIME%`.
|
|||
|
|
|
|||
|
|
`%FILE%`
|
|||
|
|
File name, without extension.
|
|||
|
|
|
|||
|
|
`%EXT%`
|
|||
|
|
File extension (component after the last period).
|
|||
|
|
|
|||
|
|
`%FFILE%`
|
|||
|
|
File name, with extension. This is equivalent to
|
|||
|
|
expanding `%FILE%.%EXT%`.
|
|||
|
|
|
|||
|
|
`%MAIL%`
|
|||
|
|
E-mail address of the current user. May be overriden by
|
|||
|
|
defining the `g:email` variable.
|
|||
|
|
|
|||
|
|
`%USER%`
|
|||
|
|
Current logged-in user name. May be overriden by defining
|
|||
|
|
the `g:username` variable.
|
|||
|
|
|
|||
|
|
`%LICENSE%`
|
|||
|
|
Expands to the string `MIT` by default. May be overriden
|
|||
|
|
by definining the `g:license` variable.
|
|||
|
|
|
|||
|
|
`%HOST%`
|
|||
|
|
Current host name.
|
|||
|
|
|
|||
|
|
`%GUARD%`
|
|||
|
|
A string containing only alphanumeric characters, and
|
|||
|
|
underscores, suitable to be used as preprocessor guards
|
|||
|
|
for C/C++/Objective-C header file.
|
|||
|
|
|
|||
|
|
`%CLASS%`
|
|||
|
|
File name, without extension, and the first character of
|
|||
|
|
each word capitalised. This is typically used for Java/C++
|
|||
|
|
class names.
|
|||
|
|
`%MACROCLASS%`
|
|||
|
|
File name, without extension, in all-capitals.
|
|||
|
|
|
|||
|
|
`%CAMELCLASS%`
|
|||
|
|
File name, without extension, with the first character of
|
|||
|
|
every work capitalised, and underscores removed.
|
|||
|
|
|
|||
|
|
`%HERE%`
|
|||
|
|
Expands to nothing, but ensures that the cursor will be placed in
|
|||
|
|
the position where this variable appears after expanding the template.
|
|||
|
|
|
|||
|
|
|
|||
|
|
===========================================================================
|
|||
|
|
USER VARIABLES *template-user-variables*
|
|||
|
|
|
|||
|
|
The `g:templates_user_variables` variable allows to expand user-defined
|
|||
|
|
variables in templates. It should be set to an array, where each item is
|
|||
|
|
a two-element array: the first element is the name of the user-defined
|
|||
|
|
variable, and the second element the name of a function. For example,
|
|||
|
|
the following can be added to the user |vimrc|:
|
|||
|
|
>
|
|||
|
|
let g:templates_user_variables = [
|
|||
|
|
\ ['FULLPATH', 'GetFullPath'],
|
|||
|
|
\ ]
|
|||
|
|
|
|||
|
|
function! GetFullPath()
|
|||
|
|
return expand('%:p')
|
|||
|
|
endfunction
|
|||
|
|
>
|
|||
|
|
This way, each occurrence of `%FULLPATH%` in a template will be replaced
|
|||
|
|
with the absolute path of the current file.
|
|||
|
|
|
|||
|
|
===========================================================================
|
|||
|
|
TROUBLESHOOTING *template-troubleshooting*
|
|||
|
|
|
|||
|
|
Q: Why are no templates found by the plugin?
|
|||
|
|
|
|||
|
|
A: Make sure you are using a Bourne-compatible shell. Vim will pick by
|
|||
|
|
default the value of the `$SHELL` environment variable. If you are using
|
|||
|
|
a non-Bourn shell (like Fish, for example), you can tell Vim to use a
|
|||
|
|
different one by using the 'shell' option. This should not be needed
|
|||
|
|
in non-Unix systems, so you may want to add the following snippet to
|
|||
|
|
your `vimrc`:
|
|||
|
|
>
|
|||
|
|
if has('unix')
|
|||
|
|
set shell=/bin/sh
|
|||
|
|
endif
|
|||
|
|
<
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
Q: How can I debug how the plugin looks up templates?
|
|||
|
|
|
|||
|
|
A: Add `set g:templates_debug = 1` in your `vimrc`.
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
Q: My question is not answered here. How can I contact the developers?
|
|||
|
|
|
|||
|
|
A: Please file an issue at https://github.com/aperezdc/vim-template/issues
|
|||
|
|
We have a `question` category for the issues which you can check to see
|
|||
|
|
whether others have had the same question before. Eventually, the most
|
|||
|
|
common questions may end up in the |template-troubleshooting| section of
|
|||
|
|
the documentation (this one you are reading).
|
|||
|
|
|
|||
|
|
|
|||
|
|
vim:tw=78:sw=8:ts=8:ft=help:norl:noet
|