*tmpl.vim*

tmpl.vim - vim file templates

=================================================================================
CONTENTS                                                      *tmpl.vim-contents*

  1. Introduction................................|tmpl.vim-introduction|
    1.1. Examples................................|tmpl.vim-examples|
  2. Global Options..............................|tmpl.vim-options|
  3. Commands....................................|tmpl.vim-commands|
  4. Template Tags...............................|tmpl.vim-tags|
    4.1. Variables...............................|tmpl.vim-tags-variables|
    4.2. Includes................................|tmpl.vim-tags-include|

=================================================================================
1. Introduction                                           *tmpl.vim-introduction*

tmpl.vim provides automated loading of templates for new files. You can load
templates for a specific environment, including on a per-buffer basis, for
various file types. Template files are kept in the |'runtimepath'|, allowing you
to easily add your own templates separately from this plugin (and other plugins
can contribute plugins).

Templates are loaded from a directory named `templates` on the |'runtimepath'|.
The name of the template to load is constructed:

1. The template environment is found (if none is given the default comes from
	 |g:tmplvim_default_environment|, or `default` if that is undefined). The
	 template environment may be overridden in each buffer by setting
	 |b:tmplvim_default_environment|.
2. The file extension is converted to lower-case and added to the template name.
3. If no file extension is found, the name of the file is converted to
	 lower-case and added to the template name as an extension.

---------------------------------------------------------------------------------
1.1 Examples                                                  *tmpl.vim-examples*

1. For a buffer with no name, no template file will be loaded automatically.
2. A buffer for `module.PY` will load the template `default.py`.
3. A buffer for `setup.sh` will load the template `default.sh`.
4. A buffer for `TARGETS` will load the template `default.targets`.
5. A buffer for `Makefile` with |g:tmplvim_default_environment| set to
	 `workplace` will load the template `workplace.makefile`.
6. A buffer for `setup.py` with |b:tmplvim_default_environment| set to
	 `myproject` will load the template `myproject.py`.

=================================================================================
2. Global Options                                              *tmpl.vim-options*

g:tmplvim_default_environment                     *g:tmplvim_default_environment*
                                                  *b:tmplvim_default_environment*
  Type: |String|
  Default: `'default'`

  Set the default template base name. This can be overridden on a per-buffer
  basis by setting `b:tmplvim_default_environment`.

g:tmplvim_template_vars                                 *g:tmplvim_template_vars*

  Type: |Dictionary|
  Default: `{}`

  Map template variables to the preferred value. Template variables are special
  tags in a template file which are expanded when the template is inserted into
  a buffer. The tag `<#TAG_NAME#>` requires `TAG_NAME` to be present in
  `g:tmplvim_template_vars` and will be replaced with the value of the
  |Dictionary| entry. Any tags without a corresponding entry will be ignored.

g:tmplvim_author                                               *g:tmplvim_author*

  Type: |String|
  Default: `$USER`

  The value to replace the template variable tag (see |tmplvim-tags-variables|)
  `AUTHOR` with. If not given, the value of the `$USER` environment variable
  will be the default value.

=================================================================================
3. Commands                                                   *tmpl.vim-commands*

LoadTemplateFile `name`                                        *LoadTemplateFile*

  Load a template file into the current buffer. If `name` is given use that,
  otherwise the value of |g:tmplvim_default_environment| will be used.

=================================================================================
4. Template Tags                                                  *tmpl.vim-tags*

Templates may contain tags which will be automatically expanded when the
template is loaded into the buffer. There are two types of tags:

1. Template variables (|tmpl.vim-tags-variables|)
2. Template includes (|tmpl.vim-tags-include|)

Template includes are processed first, then variables once includes have been
inserted into the buffer. Nested includes are not currently supported.

---------------------------------------------------------------------------------
4.1. Template variables                                 *tmpl.vim-tags-variables*

Template variable tags are upper-case letters surrounded by `<#` and `#>`. The
value of a template variable comes from |g:tmplvim_template_vars|, except for
some specific reserved tag names:

1. `DATE`: Always replaced with the value of `strftime('%Y-%m-%d')` (e.g.
   `2020-03-04`, see |strftime()|)
2. `YEAR`: Always replaced with the value of `strftime('%Y')` (e.g. `2020`, see
   |strftime()|)
3. `TIME`: Always replaced with the value of `strftime('%H:%M:%S')` (e.g.
   `13:03:34`, see |strftime()|)
4. `AUTHOR`: Always replaced with the value of |g:tmplvim_author|, or the value
   of `$USER` if that is not set.
5. `DIRNAME`: Always replaced with the name of the directory the file is in.
6. `BASENAME`: Always replaced with the name of the file without extensions.
7. `UPPERBASENAME`: Always replaced with the name of the file without extensions
	 in upper-case.

---------------------------------------------------------------------------------
4.2. Template includes                                    *tmpl.vim-tags-include*

Template include tags are letters, numbers, or periods surrounded by `<$` and
`$>`. The tag name is expected to be the name of another template, which may
include template variables but may not include other template includes. For
example, the include tag `<$ LICENSE.MIT $>` will be replaced with the contents
of the template file named `LICENSE.MIT`.

To accommodate including files in source code templates, an include with the
same extension as the current buffer will be searched for and preferred if
found. For example, the include tag `<$ LICENSE.MIT $>` in `setup.py` would use
the template named `LICENSE.MIT.py` if it exists, or `LICENSE.MIT` if not.