mirror of https://codeberg.org/jgoguen/tmpl.vim
You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
132 lines
6.5 KiB
Plaintext
132 lines
6.5 KiB
Plaintext
4 years ago
|
*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.
|