*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