2369 lines
88 KiB
Plaintext
2369 lines
88 KiB
Plaintext
*templatesupport.txt* MM Template Support Mar 28 2014
|
|
|
|
MM Template Support *template-support*
|
|
|
|
Plug-in version 0.9.3
|
|
for Vim version 7.0 and above
|
|
Wolfgang Mehner <wolfgang-mehner at web.de>
|
|
|
|
|
|
--- The Maps & Menus Template Support ... ---
|
|
|
|
-- ... for Vim Users --
|
|
|
|
This plug-in aims at providing extendible template libraries. A template
|
|
library can assist in speeding up the writing of code, while at the same time
|
|
ensuring a consistent style. The templates are written in an easy to use
|
|
markup language, which enables the user to customize templates without much
|
|
hassle.
|
|
|
|
Menus and maps to access the templates are created automatically. While maps
|
|
might or might not be the preferred way of inserting templates (as well as
|
|
using Vim in general), the menus always provide an overview of the templates
|
|
and the associated maps. This makes it quite easy to use the templates and
|
|
learn their maps at the same time.
|
|
|
|
-- ... for Plug-Ins --
|
|
|
|
The template support is controlled by an API and thus can be integrated into
|
|
another plug-in. A template library is essentially an object, several of which
|
|
can exist in parallel. This makes it relatively easy to write a plug-in for
|
|
the programming language of your choice.
|
|
|
|
Here is a list of high profile plug-ins which use the template support:
|
|
- Bash-Support (www.vim.org/scripts/script.php?script_id=365)
|
|
- C-Support (www.vim.org/scripts/script.php?script_id=213)
|
|
- Perl-Support (www.vim.org/scripts/script.php?script_id=556)
|
|
|
|
==============================================================================
|
|
0. TABLE OF CONTENTS *template-support-contents*
|
|
==============================================================================
|
|
|
|
1. Introduction |template-support-intro|
|
|
2. Basic Usage |template-support-basics|
|
|
3. Template Library |template-support-library|
|
|
3.1 Personalization |template-support-lib-person|
|
|
4. Templates |template-support-templates|
|
|
4.1 Macros |template-support-templ-macro|
|
|
4.1.1 Predefined Macros |template-support-templ-predef|
|
|
4.2 Tags |template-support-templ-tags|
|
|
4.3 Placement |template-support-templ-place|
|
|
4.3.1 Visual Mode |template-support-templ-visual|
|
|
4.4 Maps & Menus |template-support-templ-maps|
|
|
5. Lists |template-support-lists|
|
|
5.1 Formats |template-support-lists-format|
|
|
5.2 Hashes |template-support-lists-hash|
|
|
6. Advanced Features |template-support-advanced|
|
|
6.1 Coding Styles |template-support-adv-styles|
|
|
6.2 File Pickers |template-support-adv-files|
|
|
7. Menus |template-support-menus|
|
|
8. Help Templates |template-support-help-templ|
|
|
|
|
9. API |template-support-api|
|
|
9.1 Basic Usage |template-support-api-basic|
|
|
9.2 Creating Maps and Menus |template-support-api-maps|
|
|
9.3 Access |template-support-api-access|
|
|
9.4 Miscellany |template-support-api-misc|
|
|
10. Backwards Compatibility |template-support-backwards|
|
|
|
|
A. Syntax |template-support-syntax|
|
|
A.1 Command Section |template-support-syntax-cmd|
|
|
A.2 Templates |template-support-syntax-templ|
|
|
A.3 Lists |template-support-syntax-list|
|
|
B. Commands |template-support-commands|
|
|
B.1 Command Section |template-support-cmd-cmd-sct|
|
|
B.2 Templates |template-support-cmd-templates|
|
|
C. Options |template-support-options|
|
|
C.1 Templates |template-support-opt-templ|
|
|
C.2 List |template-support-opt-list|
|
|
D. Change Log |template-support-change-log|
|
|
|
|
==============================================================================
|
|
1. INTRODUCTION *template-support-intro*
|
|
==============================================================================
|
|
|
|
The manual at hand documents the Maps & Menus Template Support. The next
|
|
chapter |template-support-basics|, gives a short preview of the capabilities of
|
|
the template support. Templates are listed, together with further
|
|
configuration, in a so-called template library. Template libraries are
|
|
explained in |template-support-library|, followed by the description of
|
|
templates in |template-support-templates|. These chapters will enable the
|
|
average user to configure his or her templates.
|
|
|
|
Advanced topics are addressed in the following chapters. Lists are explained
|
|
in |template-support-lists|, followed in |template-support-advanced| by more
|
|
advanced features. The customization of the automatic menu creation is
|
|
explained in |template-support-menus|. Help templates offer a mechanism to
|
|
quickly access different documentations, they are documented in
|
|
|template-support-help-templ|.
|
|
|
|
Plug-In developers will find information on the API in |template-support-api|.
|
|
|
|
==============================================================================
|
|
2. BASIC USAGE *template-support-basics*
|
|
==============================================================================
|
|
|
|
Templates are short pieces of text which can be included into source code or
|
|
text of any other kind. But they are not just plain text, they can be extended
|
|
with macros and tags to provide further convenience. Macros can be
|
|
automatically replaced with the date or the filename, or they can be replaced
|
|
with input from the user, for example the name of a new function.
|
|
|
|
The following example shows two templates, as they appear in a so-called
|
|
template library. A template library is a text file which lists several
|
|
templates, along with their maps and menu shortcuts.
|
|
>
|
|
== file description == start ==
|
|
// ==================================================
|
|
// File: |FILENAME|
|
|
// Description: <CURSOR>
|
|
//
|
|
// Author: |AUTHOR|
|
|
// Version: 1.0
|
|
// Created: |DATE|
|
|
// ==================================================
|
|
|
|
== function == below ==
|
|
void |?FUNCTION_NAME| ( <CURSOR> )
|
|
{
|
|
<SPLIT>
|
|
} /* end of function |FUNCTION_NAME| */
|
|
== ENDTEMPLATE ==
|
|
<
|
|
Each line (the so-called header) >
|
|
== <name> == <options> ==
|
|
starts a new template, >
|
|
== ENDTEMPLATE ==
|
|
marks the end of the template "function".
|
|
|
|
When the template "file description" is inserted, it is placed at the start of
|
|
the file (option "start"). The filename and the date are inserted where the
|
|
macros *|FILENAME|* and *|DATE|* appear, the name of the user is also inserted.
|
|
After insertion, the cursor is placed where the <CURSOR> tag appears (the
|
|
cursor is represented by "|"):
|
|
>
|
|
// ==================================================
|
|
// File: helloworld.cc
|
|
// Description: |
|
|
//
|
|
// Author: Me!
|
|
// Version: 1.0
|
|
// Created: 29.2.2000
|
|
// ==================================================
|
|
<
|
|
The template "function" is inserted below the current line (option "below").
|
|
The user is asked to provide a replacement for the macro *|FUNCTION_NAME|* (it
|
|
is marked with "?"), which is then inserted into the text:
|
|
>
|
|
void say_hello ( | )
|
|
{
|
|
|
|
} /* end of function say_hello */
|
|
<
|
|
The macro can also be used in visual mode (it contains the tag <SPLIT>). The
|
|
template is then inserted surrounding the selected lines, which appear at the
|
|
position of the split tag.
|
|
|
|
Assume the line "printf(...)" is selected:
|
|
>
|
|
// ...
|
|
<
|
|
printf ( "Hello world!" ); ~
|
|
>
|
|
// ...
|
|
<
|
|
After inserting the template, the code looks like this:
|
|
>
|
|
// ...
|
|
|
|
void say_hello ( | )
|
|
{
|
|
printf ( "Hello world!" );
|
|
} /* end of function say_hello */
|
|
|
|
// ...
|
|
<
|
|
==============================================================================
|
|
3. TEMPLATE LIBRARY *template-support-library*
|
|
==============================================================================
|
|
|
|
A template library is a text file which lists several templates, along with
|
|
other objects, and commands to configure the behavior of the templates. This
|
|
file must be given to the template support in order to be loaded. If you are
|
|
working with a plug-in which uses the template support, the plug-in itself
|
|
will take care of that.
|
|
|
|
Along with templates, a library file can contain comments. Comments always
|
|
start at the beginning of a line. The standard is for comments to start with
|
|
the character '§'. This may vary, depending on which plug-in uses the template
|
|
support.
|
|
Comment lines end the current template, so comments should only be used
|
|
outside of templates.
|
|
|
|
Outside of templates, the library can contain commands. Among other things,
|
|
they configure the behavior of the templates and the menus the template
|
|
support creates.
|
|
Commands always start at the beginning of the line and, as all other names in
|
|
the library, are case sensitive.
|
|
|
|
A template library can be organized in several files. The command: >
|
|
IncludeFile ( "<path>/<file>" )
|
|
loads templates from another file (|template-support-IncludeFile|). The path
|
|
is given relative to the including file. The call: >
|
|
IncludeFile ( "<path>/<file>", "abs" )
|
|
interprets the path as a absolute path instead.
|
|
|
|
The names of the templates also define the menu structure which the template
|
|
support creates. Dots appearing in the names place the templates into
|
|
submenus. The following library will create two menus and a submenu "special".
|
|
>
|
|
== Comments.special.GNU license == below ==
|
|
// License: Copyright (c) |YEAR|, |AUTHOR|
|
|
//
|
|
// This program is free software; you can redistribute it and/or
|
|
// modify it under the terms of the GNU General Public License as
|
|
// published by the Free Software Foundation, version 2 of the
|
|
// License.
|
|
// This program is distributed in the hope that it will be
|
|
// useful, but WITHOUT ANY WARRANTY; without even the implied
|
|
// warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
|
|
// PURPOSE.
|
|
// See the GNU General Public License version 2 for more details.
|
|
== Comments.file description == start ==
|
|
// ==================================================
|
|
// File: |FILENAME|
|
|
// Description: <CURSOR>
|
|
//
|
|
// Author: |AUTHOR|
|
|
// Version: 1.0
|
|
// Created: |DATE|
|
|
// ==================================================
|
|
|
|
== Idioms.function definition == below ==
|
|
void |?FUNCTION_NAME| ( <CURSOR> )
|
|
{
|
|
<SPLIT>
|
|
} /* end of function |FUNCTION_NAME| */
|
|
== ENDTEMPLATE ==
|
|
<
|
|
Menus and entries are generated in the order in which the corresponding
|
|
templates are encountered in the library. The above example will generate this
|
|
menu structure:
|
|
>
|
|
Plug-In Menu
|
|
>-+ Comments
|
|
| >-+ Special
|
|
| | >--- GNU license
|
|
| >-- file description
|
|
>-+ Idioms
|
|
| >-- function definition
|
|
<
|
|
This also means that a new menu entry can be added by simply putting a new
|
|
template at that position in the library. Details on the menu creation can be
|
|
found in |template-support-menus|.
|
|
|
|
------------------------------------------------------------------------------
|
|
3.1 PERSONALIZATION *template-support-lib-person*
|
|
------------------------------------------------------------------------------
|
|
|
|
A personalization of the template library can be achieved by using macros. The
|
|
command 'SetMacro' (|template-support-SetMacro|) is used to set replacements
|
|
for various macros (my settings as an example):
|
|
>
|
|
SetMacro( 'AUTHOR', 'Wolfgang Mehner' )
|
|
SetMacro( 'AUTHORREF', 'wm' )
|
|
SetMacro( 'EMAIL', 'wolfgang-mehner@web.de' )
|
|
SetMacro( 'ORGANIZATION', '' )
|
|
SetMacro( 'COPYRIGHT', 'Copyright (c) |YEAR|, |AUTHOR|' )
|
|
<
|
|
The replacements may contain other macros. When a template is inserted all
|
|
macros will be substituted by the respective replacements.
|
|
|
|
Other macros and replacements can be added at will, e.g. the following could
|
|
be used in a template library for Bash: >
|
|
SetMacro( 'INTERPRETER', '/bin/sh' )
|
|
Then the template for the file description may look as follows:
|
|
>
|
|
== file description == start ==
|
|
#! |INTERPRETER|
|
|
# ==================================================
|
|
# File: |FILENAME|
|
|
# Description: <CURSOR>
|
|
#
|
|
# Author: |AUTHOR|
|
|
# Version: 1.0
|
|
# Created: |DATE|
|
|
# ==================================================
|
|
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The format of the included dates and times can be set in a similar fashion,
|
|
using 'SetFormat' (|template-support-SetFormat|):
|
|
>
|
|
SetFormat( 'DATE', '%D' )
|
|
SetFormat( 'TIME', '%H:%M' )
|
|
SetFormat( 'YEAR', 'year %Y' )
|
|
<
|
|
These special macros can never be set by 'SetMacro'. The following call will
|
|
have no effect and produce a warning: >
|
|
SetMacro( 'DATE', "April Fools' Day" )
|
|
<
|
|
During template insertion, the macros *|DATE|* , *|TIME|* and *|YEAR|* will be
|
|
replaced with the current date and time.
|
|
|
|
==============================================================================
|
|
4. TEMPLATES *template-support-templates*
|
|
==============================================================================
|
|
|
|
Templates are short pieces of text which are enhanced by so-called macros and
|
|
tags. They define a simple markup language which determines the preparation of
|
|
the text before it is inserted and control is handed back to the user.
|
|
Beyond that, every template has a name which also determines its place in the
|
|
menu structure the template support creates. Together with the template, its
|
|
menu shortcut and map are defined. The whole accessibility of the template is
|
|
specified in this one place.
|
|
|
|
Each template starts with a header: >
|
|
== <name> == [ <options> == ]
|
|
For consistency with other constructs, the following format is also supported: >
|
|
== TEMPLATE: <name> == [ <options> == ]
|
|
The list of options can be omitted.
|
|
|
|
The name of the template starts with a letter or underscore, and can not end
|
|
with a whitespace. Whitespaces in between the name and "==" will be ignored.
|
|
The name can contain these characters:
|
|
a-z, A-Z, 0-9
|
|
_ + - . , <Space>
|
|
Dots have a special meaning. They determine the menu structure the template
|
|
support will create (see |template-support-library| for a short introduction).
|
|
|
|
The list of option defines the map and menu shortcut of the template, and some
|
|
aspects of its behavior during insertion into a text, such as its placement
|
|
relative to the position of the cursor.
|
|
|
|
The following example shows a possible template for the C statement "if":
|
|
>
|
|
== Statements.if == below, map:si, sc:i ==
|
|
if ( <CURSOR> )
|
|
{
|
|
|
|
}
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The option "below" specifies that the template should always be inserted in
|
|
the lines below the current cursor position. The map is set by the option
|
|
"map", it will be |<LocalLeader>|si. The option "sc" sets the shortcut of the
|
|
entry within the menu "Statements".
|
|
|
|
------------------------------------------------------------------------------
|
|
4.1 MACROS *template-support-templ-macro*
|
|
------------------------------------------------------------------------------
|
|
|
|
Templates are useful because in source code, certain structures are repeated
|
|
regularly. Within this structures however, certain parts a variable. Templates
|
|
represent those via macros. Macros have a name, which has to follow the same
|
|
rules as C identifiers. They start with a letter or underscore, and can
|
|
contain numbers after that. Within a template, macros are written as their
|
|
names, surrounded by two bars:
|
|
*|AUTHOR|*
|
|
Replacement for macros can be given in the template library itself: >
|
|
SetMacro( 'AUTHOR', 'Wolfgang Mehner' )
|
|
These macros are replaced when inserting the template:
|
|
>
|
|
== Comments.file description == start ==
|
|
# ==================================================
|
|
# File: |FILENAME|
|
|
# Description: <CURSOR>
|
|
#
|
|
# Author: |AUTHOR|
|
|
# Version: 1.0
|
|
# Created: |DATE|
|
|
# ==================================================
|
|
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The template library will appropriately replace *|FILENAME|* and *|DATE|* and
|
|
take the replacement for *|AUTHOR|* from the template library.
|
|
|
|
Another option is to ask the user for a replacement every time the template is
|
|
inserted:
|
|
>
|
|
== Idioms.function == below ==
|
|
void |?FUNCTION_NAME| ( <CURSOR> )
|
|
{
|
|
<SPLIT>
|
|
} /* end of function |FUNCTION_NAME| */
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The question mark in front of the name means the user will be prompted for a
|
|
replacement for "FUNCTION_NAME". This replacement is then inserted twice. This
|
|
becomes particularly useful if this name appears in another template. If a
|
|
replacement for a certain macro has been given before, this replacement will
|
|
be suggested the next time the user has to replace this macro:
|
|
>
|
|
== Comments.function description == below ==
|
|
# ==================================================
|
|
# Function: |?FUNCTION_NAME|
|
|
# Purpose: <CURSOR>
|
|
# Description: TODO
|
|
# ==================================================
|
|
|
|
== ENDTEMPLATE ==
|
|
<
|
|
Certain uses come with special requirements on the format of the replacement.
|
|
Consider an include guard, where usually an upper case version of the files
|
|
name is used to name the guard, such as "_THISFILE_INC":
|
|
>
|
|
== Preprocessor.include guard == below, noindent ==
|
|
#ifndef _|BASENAME:u|_INC
|
|
#define _|BASENAME:u|_INC
|
|
<CURSOR>
|
|
#endif // ----- #ifndef _|BASENAME:u|_INC -----
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The macro *|BASENAME|* is automatically replaced with the name of the current
|
|
file, not including the extension. The flag ":u" means the replacement will be
|
|
inserted with all letters in uppercase. So a file named "string.h" will have
|
|
an include guard named "_STRING_INC".
|
|
|
|
The possible flags are listed below:
|
|
:l - change text to lowercase
|
|
:u - change text to uppercase
|
|
:c - capitalize text (change first letter to uppercase)
|
|
:L - legalize name (replace all non-word characters with underscores)
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
4.1.1 Predefined Macros *template-support-templ-predef*
|
|
|
|
The replacements for various macros are handles automatically by the template
|
|
support. Mostly, they will help with the basic documentation of the file: What
|
|
was edited and when?
|
|
|
|
*|PATH|* : the path of the current file
|
|
*|FILENAME|* : the name of the file
|
|
*|BASENAME|* : the name of the file without the suffix
|
|
*|SUFFIX|* : the suffix of the file
|
|
|
|
Except for using flags, the user has no further influence on the replacements
|
|
of these macros, they can not be set via SetMacro().
|
|
|
|
*|TIME|* : the current time
|
|
*|DATE|* : the current date
|
|
*|YEAR|* : the current year
|
|
|
|
The format of the inserted dates and times can be set via SetFormat (see
|
|
|template-support-SetFormat|).
|
|
|
|
------------------------------------------------------------------------------
|
|
4.2 TAGS *template-support-templ-tags*
|
|
------------------------------------------------------------------------------
|
|
|
|
Templates can contain tags, which influence the behavior after the template
|
|
has been inserted into the current buffer. The simplest one is <CURSOR>,
|
|
which specifies the position of the cursor after the template has been
|
|
inserted. Consider the following example:
|
|
>
|
|
== Statements.if == below ==
|
|
if ( <CURSOR> )
|
|
{
|
|
|
|
}
|
|
== ENDTEMPLATE ==
|
|
<
|
|
After template insertion the cursor is placed between the round brackets and
|
|
the user can write down the condition.
|
|
|
|
The cursor tag may cause the indentation to be slightly off after template
|
|
insertion. Therefore a second version of the cursor tag exists: {CURSOR}. You
|
|
should always choose the one which is more naturally compatible with the
|
|
languages syntax, and in extension its automatic indentation:
|
|
>
|
|
== Statements.block == below ==
|
|
{
|
|
{CURSOR}
|
|
}
|
|
== ENDTEMPLATE ==
|
|
<
|
|
Further convenience is introduced by jump tags. Instead of moving into the
|
|
block using arrow keys, the user can be given the possibility to jump to the
|
|
next position where editing is required:
|
|
>
|
|
== Statements.if == below ==
|
|
if ( <CURSOR> )
|
|
{
|
|
<+IF_PART+>
|
|
}
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The standard map for jumping is <ctrl+j>, also it may vary with each plug-in
|
|
using the template support.
|
|
Jump tags have one of the following formats:
|
|
<+NAME+> <-NAME->
|
|
{+NAME+} {-NAME-}
|
|
The text will be indented automatically with the jump tags still appearing in
|
|
it, so for every language the appropriate version has to be chosen. The name
|
|
consists of arbitrary word characters (letters, digits and underscores) and
|
|
can even be empty. The name has no other function than "documenting" the
|
|
inserted code:
|
|
>
|
|
== Statements.if, else == below ==
|
|
if ( <CURSOR> )
|
|
{
|
|
<+IF_PART+>
|
|
}
|
|
else
|
|
{
|
|
<+ELSE_PART+>
|
|
}
|
|
== ENDTEMPLATE ==
|
|
|
|
------------------------------------------------------------------------------
|
|
4.3 PLACEMENT *template-support-templ-place*
|
|
------------------------------------------------------------------------------
|
|
|
|
Templates can be placed at different positions relative to the cursor. In most
|
|
examples above the option "below" has been used. It means the template is
|
|
inserted below the current line. The opposite can be achieved using "above",
|
|
while "start" places the template at the beginning of the file, which makes
|
|
sense for example for file descriptions:
|
|
>
|
|
== Comments.file description == start ==
|
|
...
|
|
== Idioms.function definition == below ==
|
|
...
|
|
== ENDTEMPLATE ==
|
|
<
|
|
These options cause whole lines to be inserted. Two other options exist:
|
|
>
|
|
== Comments.end-of-line comment == append ==
|
|
/* <CURSOR> */
|
|
== Comments.date and time == insert ==
|
|
|DATE|, |TIME|<CURSOR>
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The template "Comments.end-of-line comment" will be inserted at the end of the
|
|
current line, while "Comments.date and time" will insert a timestamp at the
|
|
cursor position.
|
|
|
|
These placement modes are available:
|
|
start - the text is placed above the first line
|
|
above - the text is placed above the current line
|
|
below - the text is placed below the current line (default)
|
|
append - the text is appended to the current line
|
|
insert - the text is inserted at the cursor position
|
|
|
|
By default, the lines containing a newly inserted template are automatically
|
|
indented. To suppress this behavior use the option "noindent". This can be
|
|
used for code fragments which contain constructs the indentation program does
|
|
not handle correctly.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
4.3.1 Visual Mode *template-support-templ-visual*
|
|
|
|
Oftentimes, existing code needs to be rearranged, for example some lines of
|
|
code must be surrounded with an if-statement. For this reason, the <SPLIT>
|
|
tag exists:
|
|
>
|
|
== Statements.if == below ==
|
|
if ( <CURSOR> )
|
|
{
|
|
<SPLIT>
|
|
}
|
|
== ENDTEMPLATE ==
|
|
<
|
|
If the template is inserted in normal or insert mode, nothing changes. The tag
|
|
will be removed automatically. In visual mode however, the selected line will
|
|
be surrounded with the template. Consider these lines of code, where the lines
|
|
containing "printf" are selected:
|
|
>
|
|
// ...
|
|
<
|
|
printf ( "Loading the file ..." ); ~
|
|
printf ( "... reading %d bytes.", n ) ~
|
|
>
|
|
// ...
|
|
<
|
|
After inserting the template "Statements.if", the code looks like this:
|
|
>
|
|
// ...
|
|
|
|
if ( | )
|
|
{
|
|
printf ( "Loading the file ..." ); ~
|
|
printf ( "... reading %d bytes.", n ) ~
|
|
}
|
|
|
|
// ...
|
|
<
|
|
Now the user can type in the condition.
|
|
|
|
Jump and split tags might be in conflict. Consider the following example:
|
|
>
|
|
== Statements.if, else == below ==
|
|
if ( <CURSOR> )
|
|
{
|
|
<SPLIT><+IF_PART+>
|
|
}
|
|
else
|
|
{
|
|
<+ELSE_PART+>
|
|
}
|
|
== ENDTEMPLATE ==
|
|
<
|
|
When using the template in visual mode, the jump tag <+IF_PART+> should not
|
|
appear, since the if block already contains the selected line. This is why
|
|
jump tag exist in different versions. The two version <-NAME-> and {-NAME-}
|
|
are removed in visual mode. They behave opposite to the <SPLIT> tag, which is
|
|
removed in every other mode. A better version of the above example looks like
|
|
this:
|
|
>
|
|
== Statements.if, else == below ==
|
|
if ( <CURSOR> )
|
|
{
|
|
<SPLIT><-IF_PART->
|
|
}
|
|
else
|
|
{
|
|
<+ELSE_PART+>
|
|
}
|
|
== ENDTEMPLATE ==
|
|
<
|
|
For templates containing a split tag, the option "noindent" is particularly
|
|
useful, since it can prevent large sections of code from being indented
|
|
unnecessarily. The following example shows a template for an include guard,
|
|
using a C-macro "_THISFILE_INC":
|
|
>
|
|
== Preprocessor.include guard == below, noindent ==
|
|
#ifndef _|BASENAME:u|_INC
|
|
#define _|BASENAME:u|_INC
|
|
<CURSOR><SPLIT>
|
|
#endif // ----- #ifndef _|BASENAME:u|_INC -----
|
|
== ENDTEMPLATE ==
|
|
<
|
|
Here, running the indentation program after insertion is an unnecessary effort
|
|
and may potentially destroy hand-crafted indentation in a large piece of code.
|
|
|
|
------------------------------------------------------------------------------
|
|
4.4 MAPS & MENUS *template-support-templ-maps*
|
|
------------------------------------------------------------------------------
|
|
|
|
The template support automatically creates maps and menu entries for the
|
|
templates in the library. The menu entries appear in the order the templates
|
|
have been read. Including a file via >
|
|
IncludeFile ( "<path>/<file>" )
|
|
will cause this file to be processed first, then the rest of the including
|
|
file is read.
|
|
|
|
The map and menu shortcut of a template are defined together with the
|
|
template:
|
|
>
|
|
== Statements.if == below, map:si, sc:i ==
|
|
if ( <CURSOR> )
|
|
{
|
|
<+IF_PART+>
|
|
}
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The templates will have the map |<LocalLeader>|si and the shortcut "i".
|
|
|
|
Menu entries are created by default. The option "nomenu" suppresses this
|
|
behavior:
|
|
>
|
|
== Comments.fix this == nomenu, append, map:cfx ==
|
|
// TODO: fix this
|
|
== ENDTEMPLATE ==
|
|
<
|
|
This template will not clutter the menu and can only be inserted via its map.
|
|
|
|
An overview of all the options:
|
|
nomenu - no menu entry is created
|
|
sc:<sc> - a shortcut is created for the menu entry of this template
|
|
shortcut:<sc> - long version of sc:<sc>
|
|
map:<map> - a map is created for this template
|
|
|
|
==============================================================================
|
|
5. LISTS *template-support-lists*
|
|
==============================================================================
|
|
|
|
Template libraries would regularly contain a huge number of templates with a
|
|
repetitive structure. Consider these templates for a C template library:
|
|
>
|
|
== Preprocessor.include math, map: pim ==
|
|
#include <math.h>
|
|
== Preprocessor.include stdlib, map:pisl ==
|
|
#include <stdlib.h>
|
|
== Preprocessor.include stdio, map:pisio ==
|
|
#include <stdio.h>
|
|
== Preprocessor.include string, map:pistr ==
|
|
#include <string.h>
|
|
== ENDTEMPLATE ==
|
|
<
|
|
This has several disadvantages. Besides being difficult to write and maintain,
|
|
these templates would not be well accessible. The user would have to memorize
|
|
a map for each and every one of them.
|
|
|
|
This is why lists exist. They appear as objects in the template library. The
|
|
header of a list starts with "LIST:" and then contains a name, which has to
|
|
follow the same rules as C identifiers. They start with a letter or
|
|
underscore, and can contain numbers after that.
|
|
>
|
|
== LIST: C_StandardLibs ==
|
|
'math',
|
|
'stdlib',
|
|
'stdio',
|
|
'string',
|
|
== ENDLIST ==
|
|
|
|
== Preprocessor.c libs == below, map:pcl ==
|
|
|PickList( '#include <~.h>', 'C_StandardLibs' )|
|
|
#include <|PICK|.h><CURSOR>
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The template "Preprocessor.c libs" uses this list. The command: >
|
|
"|PickList( '<prompt>', '<list>' )|"
|
|
determines which list is used. During template insertion the user is prompted
|
|
to choose an entry from the list, but can also type another name. The prompt
|
|
supports tab-completion and navigation with arrow keys. The first argument is
|
|
a string which is displayed on the command line, to clarify the meaning of the
|
|
choice. After the users makes the choice, the macro *|PICK|* is created, which
|
|
contains the chosen item.
|
|
Lists can be used again in another context, for example to support C++
|
|
programming:
|
|
>
|
|
== Preprocessor.c++, c libs == below, map:ppc ==
|
|
|PickList( '#include <c~>', 'C_StandardLibs' )|
|
|
#include <c|PICK|><CURSOR>
|
|
== ENDTEMPLATE ==
|
|
<
|
|
When the template is inserted via a map, the user is prompted to choose an
|
|
entry from the list, thus only one map is required to choose from a huge
|
|
number of options. When the template is accessed via the menu, two
|
|
possibilities exists. Without further changes, the same prompt opens as when
|
|
the template is used via a map. But whenever the template includes the
|
|
"expandmenu" option, a submenu is created which lists all the entries, which
|
|
allows the user to choose in the menu, rather than on the command line: >
|
|
== Preprocessor.c libs == below, expandmenu, map:pcl ==
|
|
<
|
|
------------------------------------------------------------------------------
|
|
5.1 FORMATS *template-support-lists-format*
|
|
------------------------------------------------------------------------------
|
|
|
|
Lists also support options. The standard format for lists is named "list":
|
|
>
|
|
== LIST: C_StandardLibs == list ==
|
|
'math', 'stdlib',
|
|
'stdio', 'string',
|
|
== ENDLIST ==
|
|
<
|
|
The text contained between "== LIST: name ==" and "== ENDLIST ==" is a
|
|
comma-separated list of strings, which come as |expr-string| in double quotes
|
|
or |literal-string| in single quotes.
|
|
|
|
An easier way of writing lists are bare lists, defined with the option "bare":
|
|
>
|
|
== LIST: C_StandardLibs == list, bare ==
|
|
math
|
|
stdlib
|
|
stdio
|
|
string
|
|
== ENDLIST ==
|
|
<
|
|
They contain each entry on a new line, leading and trailing whitespaces are
|
|
ignored.
|
|
|
|
------------------------------------------------------------------------------
|
|
5.2 HASHES *template-support-lists-hash*
|
|
------------------------------------------------------------------------------
|
|
|
|
Hashes, or dictionaries, are another type of lists. They associate a key with
|
|
a value:
|
|
>
|
|
== LIST: String_Functions == hash ==
|
|
"strcpy" : "{+DEST+}, {+SRC+}",
|
|
"strncpy" : "{+DEST+}, {+SRC+}, {+N+}",
|
|
"strcmp" : "{+STR1+}, {+STR2+}",
|
|
"strncmp" : "{+STR1+}, {+STR2+}, {+N+}",
|
|
"strlen" : "{+STR+}",
|
|
== ENDLIST ==
|
|
<
|
|
A hash is a comma-separated list of entries. Each entry contains a key and a
|
|
value, separated by a colon.
|
|
|
|
During template insertion, the user has to choose one of the keys. Then two
|
|
macros *|KEY|* and *|VALUE|* are created, containing the chosen key and its
|
|
associated value. Both can be used in the template.
|
|
In this example, a function call is inserted, with jump tags named for the
|
|
parameters:
|
|
>
|
|
== Idioms.string function == insert, expandmenu ==
|
|
|PickList( "function: ", "String_Functions" )|
|
|
|KEY|<CURSOR> ( |VALUE| )
|
|
== ENDTEMPLATE ==
|
|
<
|
|
These templates also support the option "expandmenu". The menu will list all
|
|
the keys.
|
|
|
|
==============================================================================
|
|
6. ADVANCED FEATURES *template-support-advanced*
|
|
==============================================================================
|
|
|
|
Editing source code comes with challenges common to many different languages
|
|
and systems.
|
|
|
|
Different projects may require different coding styles. Template libraries can
|
|
be written to support multiple styles (|template-support-adv-styles|).
|
|
|
|
Many languages deal with files placed in one or more significant directory,
|
|
such as C's include directories or modules in other languages. File pickers
|
|
assist in working with these directories (|template-support-adv-files|).
|
|
|
|
------------------------------------------------------------------------------
|
|
6.1 CODING STYLES *template-support-adv-styles*
|
|
------------------------------------------------------------------------------
|
|
|
|
Different software projects may require different styles for comments and
|
|
code. In the case of C/C++, different kinds of comments can be chosen, with
|
|
Doxygen introducing even more possibilities. The template engine assists with
|
|
these problems by offering so called styles. Styles are named using the same
|
|
rules as macros (see |template-support-templ-macro|).
|
|
|
|
Every template is assigned to one or more styles. By default, all templates are
|
|
assigned to the style "default". Templates can be associated with different
|
|
styles by placing them inside a "USE STYLES" statement:
|
|
>
|
|
== USE STYLES : CPP ==
|
|
|
|
== Comments.function description == ==
|
|
# ==================================================
|
|
# Function: |?FUNCTION_NAME|
|
|
# Purpose: <CURSOR>
|
|
# Description: TODO
|
|
# ==================================================
|
|
|
|
== ENDTEMPLATE ==
|
|
|
|
== ENDSTYLES ==
|
|
|
|
== USE STYLES : Doxygen ==
|
|
|
|
== Comments.function description == ==
|
|
/*!
|
|
* \brief <CURSOR>
|
|
*
|
|
* TODO
|
|
*/
|
|
|
|
== ENDTEMPLATE ==
|
|
|
|
== ENDSTYLES ==
|
|
<
|
|
Now the "function description" template inserts different code, depending on
|
|
whether the style "CPP" or "Doxygen" is chosen (see the documentation of your
|
|
plug-in for how to change the style).
|
|
|
|
The "USE STYLES" statement can contain the names of several styles. Templates
|
|
inside are associated with all the styles appearing in the list. This makes
|
|
reuse of templates for different styles possible.
|
|
>
|
|
== USE STYLES : CPP, Doxygen ==
|
|
|
|
== Comments.end-of-line command == ==
|
|
// <CURSOR>
|
|
== ENDTEMPLATE ==
|
|
|
|
== USE STYLES : CPP ==
|
|
|
|
== Comments.function description == ==
|
|
...
|
|
== ENDTEMPLATE ==
|
|
|
|
== ENDSTYLES ==
|
|
|
|
== USE STYLES : Doxygen ==
|
|
|
|
== Comments.function description == ==
|
|
...
|
|
== ENDTEMPLATE ==
|
|
|
|
== ENDSTYLES ==
|
|
|
|
== ENDSTYLES ==
|
|
<
|
|
The template "end-of-line comment" inserts the same text for both styles,
|
|
while "function description" is different. If a template is not associated
|
|
with a given style it can be inserted anyway, using the version of the
|
|
template associated with the "default" style as a fallback. Only if a template
|
|
does not exist for the current style or the default style, an error message is
|
|
displayed and nothing inserted.
|
|
|
|
Using nested "USE STYLES" statement is also possible. The styles listed in a
|
|
nested statement have to be a subset of the styles listed in the one
|
|
surrounding it.
|
|
Templates inside nested statements are only associated with the styles
|
|
listed in the innermost "USE STYLES" statement.
|
|
|
|
When files are included inside a "USE STYLES" statement (see
|
|
|template-support-IncludeFile|), the templates inside the file are associated
|
|
with the style, as they would if they appeared in the including file itself.
|
|
The rules for nested "USE STYLES" statements also hold across included files.
|
|
|
|
------------------------------------------------------------------------------
|
|
6.2 FILE PICKERS *template-support-adv-files*
|
|
------------------------------------------------------------------------------
|
|
|
|
In many languages files are addressed in relation to some significant
|
|
directory, such the include mechanism of the C preprocessor or LaTeX's
|
|
\graphicspath{} command. To assist in dealing with those files, the template
|
|
support offers so-called file pickers.
|
|
|
|
File pickers are templates which use the command PickFile( <prompt>, <path> )
|
|
(|template-support-PickFile|), which asks the user to interactively select a
|
|
file:
|
|
>
|
|
SetPath( 'global_include', '/usr/include/' )
|
|
|
|
== Include.global include == below ==
|
|
|PickFile( 'global include directory', 'global_include' )|
|
|
#include "|PICK|"<CURSOR>
|
|
== Include.global, filename only == below ==
|
|
|PickFile( 'global include directory', 'global_include' )|
|
|
#include <|FILENAME|><CURSOR>
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The first argument to the function is a prompt which is being displayed while
|
|
the user selects the file. The second argument is the name of a path set
|
|
beforehand, such as "global_include". After the user selects a file, several
|
|
macros are created which can be used in the template. *|PICK|* is the path and
|
|
name of the file, relative to the path given as the second argument.
|
|
*|FILENAME|* is only the name of the file. For a list of all macros, see
|
|
|template-support-PickFile|.
|
|
|
|
Names for paths are created using the function SetPath( <name>, <path> )
|
|
(see |template-support-SetPath|), which is a lot like SetMacro.
|
|
|
|
For example, if the user picks "/usr/include/GL/gl.h", the first template
|
|
would result in the line >
|
|
#include "GL/gl.h"
|
|
being inserted, while the second template would insert >
|
|
#include <gl.h>
|
|
The paths "/usr/include" or "/usr/include/GL" would have to be in the include
|
|
path, of course.
|
|
|
|
The second argument can also be a path. In fact, if it does not match an
|
|
identifier, it is always assumed to be a path:
|
|
>
|
|
== Include.local include == below ==
|
|
|PickFile( 'local include directory', './' )|
|
|
#include "|PICK|"<CURSOR>
|
|
== ENDTEMPLATE ==
|
|
<
|
|
This template lets the user pick a file relative to the current working
|
|
directory.
|
|
|
|
==============================================================================
|
|
7. MENUS *template-support-menus*
|
|
==============================================================================
|
|
|
|
The template support automatically creates menus for every template. The user
|
|
has a measure of influence on the result. Some of these options where already
|
|
explained in |templates-support-templ-maps|, this chapter will introduce further
|
|
capabilities.
|
|
|
|
The menu entries appear in the order the templates have been read. Including a
|
|
file via >
|
|
IncludeFile ( "<path>/<file>" )
|
|
will cause this file to be processed first, then the rest of the including
|
|
file is read.
|
|
|
|
The menu structure is defined by the names of the menus. Dots appearing in the
|
|
names place the templates into submenus:
|
|
>
|
|
== Comments.file description == start, sc:f ==
|
|
...
|
|
== Statements.if == below, sc:i ==
|
|
...
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The shortcut for the menu entry is defined in the header. The automatic
|
|
creation of a menu entry for a template can be suppressed using the option
|
|
"nomenu".
|
|
|
|
The maps of submenus are set via the command 'MenuShortcut'
|
|
(see |template-support-MenuShortcut()|):
|
|
>
|
|
MenuShortcut ( "Comments.Special", "p" )
|
|
MenuShortcut ( "Comments", "c" )
|
|
MenuShortcut ( "Statements", "s" )
|
|
<
|
|
Each call sets the shortcut for the last submenu mentioned. So the above
|
|
example sets the shortcut "c" for the menu "Comments", "s" for "Statements"
|
|
and "p" for the submenu "Special" within "Comments". The placement of these
|
|
calls has no influence on the order of menu creation, only the appearance of
|
|
their names in template headers.
|
|
|
|
The template library can also contain menu separators, a solid line appearing
|
|
between two menu entries. They can help to provide a better overview in a menu
|
|
with lots of entries. Menu separators are defined outside of templates using
|
|
the syntax: >
|
|
== SEP: Statements.sep1 ==
|
|
The header start with "SEP:" and then contains the name of the separator. The
|
|
dots in the name again define which submenu the separator will appear in,
|
|
while the relative position in relation to the other templates defines the
|
|
placement. The last part of the name following the last dot has no influence,
|
|
but must be unique.
|
|
Unlike templates and lists, separators do not have to be ended with a line
|
|
like "== ENDTEMPLATE ==". Separators only span one line. Separators could
|
|
utilize the syntax of function calls, such as "SetMacro()". However, they have
|
|
been designed in this way to visually be on the same level as templates.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
Note: A short remark for plug-in developers.
|
|
|
|
Each menu entry also displays the map of the template, if it has one. By
|
|
default, it is prefixes with the standard mapleader, a backslash. Using the
|
|
API, this can be changed to the mapleader the user has set: >
|
|
call mmtemplates#core#Resource (
|
|
\ <template-library>, "set", "Templates::Mapleader", "<mapleader>" )
|
|
(see |mmtemplates#core#Resource()|). This mapleader may also appear in menu
|
|
entries the plug-in itself creates. As a convenience, the mapleader is
|
|
provided by the API, already correctly escaped for menu creation: >
|
|
let [ esc_mapleader, msg ] = mmtemplates#core#Resource (
|
|
\ g:My_C_Templates, "escaped_mapleader" )
|
|
<
|
|
==============================================================================
|
|
8. HELP TEMPLATES *template-support-help-templ*
|
|
==============================================================================
|
|
|
|
A quick access to the documentation is important for every language. Help
|
|
templates offer a mechanism to pick up a word under the cursor and make a
|
|
system call using this text. For example, a browser could be opened with help
|
|
for a certain command.
|
|
|
|
Help templates look a lot like templates in the library, but do not insert
|
|
text. They share a lot of other features with regular templates though, they
|
|
will create a menu entry and can have shortcuts and maps.
|
|
|
|
The syntax of help templates is very close to that of regular templates,
|
|
except that their name is prefixed by "HELP:"
|
|
>
|
|
SetMacro( 'HELP_BROWSER', 'firefox' )
|
|
SetMacro( 'HelpPathEnglish', 'http://en.wiktionary.org/wiki/' )
|
|
|
|
== HELP: Help.english == map:he, sc:e ==
|
|
|Word( '' )|
|
|
|Substitute( '\W', '', 'g' )|
|
|
|System( '|HELP_BROWSER| |HelpPathEnglish||PICK:l|' )|
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The help template "Help.english" picks up the word under the cursor, removes
|
|
every non-word character from that string and then calls >
|
|
firefox http://en.wiktionary.org/wiki/...
|
|
This will open a new tab containing the article about the word under the
|
|
cursor, which is very helpful while writing documentation.
|
|
|
|
A help template always performs three steps:
|
|
1. Pick up text under the cursor.
|
|
2. Change the text (optional).
|
|
3. Make a system call or a call on the Vim command line.
|
|
|
|
1. Picking Text
|
|
|
|
To pick up text under the cursor, the function Word(<flag>) is used. If the
|
|
flag is 'W', the |WORD| under the cursor is picked up: >
|
|
|Word('W')|
|
|
Otherwise the |word| under the cursor is picked: >
|
|
|Word('')|
|
|
Lastly, the word can be picked using a regular expression (see |regex|): >
|
|
|Pattern( '[\\@]\w\+' )|
|
|
This call picks a word prefix by "\" or "@", which in a C comment could be a
|
|
Doxygen command.
|
|
The text which has just been picked up is then stored in a sort of register,
|
|
which for the purpose of the further explanation shall be called "acc".
|
|
|
|
2. Editing the Text
|
|
|
|
After picking up text, the register "acc" can be changed by one or more calls
|
|
to the function Substitute( <pattern>, <sub>, <flag> ). For example, to remove
|
|
every non-word character: >
|
|
|Substitute( '\W', '', 'g' )|
|
|
Substitute replaces the contents of "acc" using Vim's |substitute()| function:
|
|
acc = substitute( acc, <pattern>, <sub>, <flag> )
|
|
If the flag is an empty string, the first occurrence of <pattern> is replaced
|
|
with <sub>. If flag equals "g", all occurrences are replaced. The function
|
|
LiteralSub(<string>,<sub>,<flag>) works similarly, except that the first
|
|
argument is not interpreted as a regular expression.
|
|
|
|
3. Calling Help
|
|
|
|
After picking up and changing the text, a call is made using System(<call>) or
|
|
Vim(<call>). The argument is a string and it can contain macros which are
|
|
replaced before the call. The macro *|PICK|* is replaced with "acc", the
|
|
picked and changed text. The call is however only made if "acc" is not the
|
|
empty string.
|
|
If either an empty string has been picked up in step 1, or the string is empty
|
|
after step 2, the call is made using the command given in Default(<call>). If
|
|
no default call is given, no action is performed for an empty string.
|
|
|
|
The following help template shows help for Doxygen commands:
|
|
>
|
|
SetMacro( 'HelpPathDoxygen', 'http://www.stack.nl/~dimitri/doxygen/commands.html' )
|
|
|
|
== HELP: Help.doxygen cmd == map:hd, sc:d ==
|
|
|Pattern( '[\\@]\w\+' )|
|
|
|Substitute( '[\\@]', '', '' )|
|
|
|System( '|HELP_BROWSER| |HelpPathDoxygen|#cmd|PICK|' )|
|
|
|Default( '|HELP_BROWSER| |HelpPathDoxygen|' )|
|
|
== ENDTEMPLATE ==
|
|
<
|
|
First, a Doxygen command is picked up under the cursor, then the leading "\"
|
|
or "@" is removed. Then a system call such as: >
|
|
firefox http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparam
|
|
is made. If there was no Doxygen command under the cursor, the following call
|
|
is made instead, which will show a table of all Doxygen commands: >
|
|
firefox http://www.stack.nl/~dimitri/doxygen/commands.html
|
|
<
|
|
Note: The examples still worked in November, 2013.
|
|
|
|
|
|
|
|
-------------------------------------------------------------------------- ~
|
|
|
|
-------------------------------------------------------------------------- ~
|
|
|
|
-------------------------------------------------------------------------- ~
|
|
|
|
|
|
|
|
==============================================================================
|
|
9. API *template-support-api*
|
|
==============================================================================
|
|
|
|
This chapter is only relevant if you want to use the template system with your
|
|
own plug-in!
|
|
|
|
The API enables other plug-ins to use the template system.
|
|
|
|
Each template library is stored in a dictionary (|Dictionary|).
|
|
- This dictionary must be a global variable, because it it used for purposes
|
|
such as callback functions for menu entries and maps.
|
|
- Do not change the entries of the dictionary directly, since the internal
|
|
structure may change. The API provides access to the stored information.
|
|
|
|
------------------------------------------------------------------------------
|
|
9.1 BASIC USAGE *template-support-api-basic*
|
|
------------------------------------------------------------------------------
|
|
|
|
These functions provide the basic functionality to load template libraries and
|
|
insert templates into a buffer. A further function expands macros in a text.
|
|
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#NewLibrary()*
|
|
To create a new template library call:
|
|
|
|
library = mmtemplates#core#NewLibrary ( ... ) ~
|
|
|
|
Optional parameters:
|
|
"debug", level - View debug information with the given level of detail.
|
|
(integer, default: show no debug information)
|
|
Returns:
|
|
library - The template library. (dict)
|
|
|
|
Example:
|
|
|
|
Create a new library and store it in the variable 'g:My_C_Templates': >
|
|
let g:My_C_Templates = mmtemplates#core#NewLibrary ()
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#ReadTemplates()*
|
|
Templates are loaded using the function:
|
|
|
|
mmtemplates#core#ReadTemplates ( library, ... ) ~
|
|
|
|
Parameters:
|
|
library - The template library. (string or dict)
|
|
Optional parameters:
|
|
"load", file - Load templates from 'file'. (string)
|
|
"reload", what - Reload templates according to 'what', see below.
|
|
(string or integer)
|
|
"overwrite_warning" - Print a warning each time a template is overwritten.
|
|
"debug", level - View debug information with the given level of detail.
|
|
(integer, default: show no debug information)
|
|
No returns.
|
|
|
|
The library can either be given directly, or as the name of the global
|
|
variable containing the library.
|
|
|
|
When loading a new file, it must be given with a path and filename. >
|
|
mmtemplates#core#ReadTemplates ( library, "load", "path/file.templates" )
|
|
<
|
|
The entire library can be reloaded by calling: >
|
|
mmtemplates#core#ReadTemplates ( library, "reload", "all" )
|
|
A file can be reloaded, but only if it has been loaded before: >
|
|
mmtemplates#core#ReadTemplates ( library, "reload", "path/file.templates" )
|
|
The i'th file which has been loaded can be reloaded via: >
|
|
mmtemplates#core#ReadTemplates ( library, "reload", i )
|
|
<
|
|
With the switch "overwrite_warning", a warning is displayed whenever a
|
|
template is encountered which already has been set for the current style.
|
|
|
|
|
|
Example 1:
|
|
|
|
Load a file: >
|
|
call mmtemplates#core#ReadTemplates ( g:My_C_Templates,
|
|
\ "load", "$HOME/.vim/c-support/templates/lib.templates",
|
|
\ "debug", 1, "overwrite_warning" )
|
|
Load the templates in the given file and print very little debug information.
|
|
Print a warning whenever a template is overwritten.
|
|
|
|
|
|
Example 2.1:
|
|
|
|
Load several files: >
|
|
call mmtemplates#core#ReadTemplates ( g:My_C_Templates,
|
|
\ "load", "/usr/share/vim/.../global.templates" )
|
|
|
|
call mmtemplates#core#ReadTemplates ( g:My_C_Templates,
|
|
\ "load", "$HOME/.vim/.../local.templates" )
|
|
Loads the templates in the two files.
|
|
|
|
|
|
Example 2.2:
|
|
|
|
Reload specific templates: >
|
|
call mmtemplates#core#ReadTemplates ( g:My_C_Templates, "reload", -1 )
|
|
Reload the last template which has been loaded.
|
|
(".../local.templates" from above)
|
|
|
|
|
|
Example 2.3:
|
|
|
|
Reload templates by name: >
|
|
call mmtemplates#core#ReadTemplates ( g:My_C_Templates,
|
|
\ "reload", "$HOME/.vim/.../local.templates" )
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#InsertTemplate()*
|
|
To insert templates into the current buffer use:
|
|
|
|
mmtemplates#core#InsertTemplate ( library, name, ... ) ~
|
|
|
|
Parameters:
|
|
library - The template library. (string or dict)
|
|
name - The name of the template. (string)
|
|
Optional parameters:
|
|
"i" - > "insert"
|
|
"insert" - Insert mode, special treatment of placement 'insert'.
|
|
"v" - > "visual"
|
|
"visual" - Visual mode, use the <SPLIT> tag.
|
|
"placement", place - Overwrite the template's placement. (string)
|
|
"range", a, b - Use the range from lines 'a' to 'b'. (integers)
|
|
"<macro>", replace - Set the replacement for the given macro. The string
|
|
<macro> must match a macro, e.g. *|FUNCTION_NAME|* .
|
|
(string)
|
|
"pick", choice - When inserting a list use 'choice', do not ask the user
|
|
to pick an entry. (string)
|
|
"debug", level - View debug information with the given level of detail.
|
|
(integer, default: show no debug information)
|
|
No returns.
|
|
|
|
The library can either be given directly, or as the name of the global
|
|
variable containing the library.
|
|
It the template 'name' does not exist, an error message is displayed.
|
|
|
|
Examples:
|
|
|
|
Include "Statement.If", surround the selected lines: >
|
|
call mmtemplates#core#InsertTemplate ( g:My_C_Templates,
|
|
\ "Statement.If", "v" )
|
|
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#ExpandText()*
|
|
To perform macro expansion in a text use:
|
|
|
|
rtext = mmtemplates#core#ExpandText ( library, text ) ~
|
|
|
|
Parameters:
|
|
library - The template library. (string or dict)
|
|
text - A text. (string)
|
|
Returns:
|
|
rtext - The text after the macro expansion (string).
|
|
|
|
The library can either be given directly, or as the name of the global
|
|
variable containing the library.
|
|
The expansion is done using all the settings in the library, as well as the
|
|
global macro replacements such as *|AUTHOR|* .
|
|
|
|
Examples:
|
|
|
|
Calling the function: >
|
|
let text = mmtemplates#core#ExpandText ( g:My_C_Templates, "|DATE| |TIME|" )
|
|
returns "29.2.2000 12:00", depending on the format set in the library.
|
|
|
|
This can be used for special menu entries such as: >
|
|
exe 'amenu Comments.Special.Date\ Time '
|
|
\ .':exe "normal! a".mmtemplates#core#ExpandText ( '
|
|
\ .'g:My_C_Templates, "\|DATE\| \|TIME\|" )<CR>'
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#EditTemplateFiles()*
|
|
Open the library for editing:
|
|
|
|
mmtemplates#core#EditTemplateFiles ( library, file ) ~
|
|
|
|
Parameters:
|
|
library - The template library. (string or dict)
|
|
file - A file. (string or integer)
|
|
No returns.
|
|
|
|
The library can either be given directly, or as the name of the global
|
|
variable containing the library.
|
|
|
|
The argument 'file' can be given as a filename, in which case it must have
|
|
been loaded before via |mmtemplates#core#ReadTemplates()|.
|
|
'file' can also be an integer i, which refers to the i'th file that has been
|
|
loaded.
|
|
|
|
A file browser is then opened for the directory containing the file.
|
|
|
|
Example:
|
|
|
|
Open a file browser in the directory "$HOME/.vim/.../templates/":
|
|
>
|
|
" load the last template file:
|
|
call mmtemplates#core#ReadTemplates ( g:My_C_Templates,
|
|
\ "load", "$HOME/.vim/.../templates/local.templates" )
|
|
|
|
" ...
|
|
|
|
" edit the library
|
|
call mmtemplates#core#EditTemplateFiles ( g:My_C_Templates, -1 )
|
|
<
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#JumpToTag()*
|
|
The jump to the next tag is performed by:
|
|
|
|
e = mmtemplates#core#JumpToTag ( regex ) ~
|
|
|
|
Parameters:
|
|
regex - The regex to jump to. (string)
|
|
Returns:
|
|
e - An empty string.
|
|
|
|
Jumps to the next occurrence of 'regex' and removes it from the buffer. Then
|
|
the function returns an empty string.
|
|
The regular expression can be obtained from the template library via the
|
|
function |mmtemplates#core#Resource()|.
|
|
|
|
Example:
|
|
|
|
This function is best used in maps such as this:
|
|
>
|
|
let regex = mmtemplates#core#Resource ( g:My_C_Templates, "jumptag" )[0]
|
|
|
|
" ...
|
|
|
|
nnoremap <buffer> <C-j> i<C-R>=mmtemplates#core#JumpToTag ( regex )<CR>
|
|
inoremap <buffer> <C-j> <C-R>=mmtemplates#core#JumpToTag ( regex )<CR>
|
|
<
|
|
This maps can be created automatically using |mmtemplates#core#CreateMaps()|.
|
|
|
|
------------------------------------------------------------------------------
|
|
9.2 CREATING MENUS AND MAPS *template-support-api-maps*
|
|
------------------------------------------------------------------------------
|
|
|
|
The automated generation of maps and menus is carried out by these functions.
|
|
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#CreateMaps()*
|
|
The automatic creation of maps is carried out by the function:
|
|
|
|
mmtemplates#core#CreateMaps ( library, localleader, ... ) ~
|
|
|
|
Parameters:
|
|
library - The name of the variable containing the library. (string)
|
|
localleader - The local mapleader. (string)
|
|
Optional parameters:
|
|
"do_jump_map" - Create a map for |mmtemplates#core#JumpToTag()|.
|
|
"do_special_maps" - Create maps for the special operations.
|
|
No returns.
|
|
|
|
If 'localleader' is an empty string, the standard mapleader is used.
|
|
Otherwise >
|
|
let maplocalleader = localleader
|
|
is executed before the maps are created. (see |mapleader|)
|
|
|
|
The maps for the jump and the special operations (choose a template/style,
|
|
reread/edit the library) are not created unless the corresponding options are
|
|
given.
|
|
|
|
This function creates maps which are local to the buffer, so it must be called
|
|
in the appropriate filetype-plugin, or by an autocommand.
|
|
An error message is displayed whenever a mapping already exists. The existing
|
|
mapping will not be overwritten.
|
|
|
|
Example:
|
|
|
|
Create maps using the standard mapleader: >
|
|
call mmtemplates#core#CreateMaps ( "g:My_C_Templates", "", "do_jump_map" )
|
|
A map to jump to the next tag is also created.
|
|
|
|
Technical Details:
|
|
- The library must be given as the name of the global variable, since this
|
|
name is required to create the maps.
|
|
- The function creates maps of the following types:
|
|
noremap, inoremap, vnoremap
|
|
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#CreateMenus()*
|
|
The automatic creation of menus is carried out by the function:
|
|
|
|
mmtemplates#core#CreateMenus ( library, rootmenu, ... ) ~
|
|
|
|
Parameters:
|
|
library - The name of the variable containing the library. (string)
|
|
rootmenu - The name of the root menu. (string)
|
|
Optional parameters:
|
|
"global_name", name - The name used in the menu headers.
|
|
(string, default: the value of 'rootmenu')
|
|
"existing_menu", names - The menus which already exist.
|
|
(string or list of strings)
|
|
"sub_menu", names - Additional sub-menus which should be created.
|
|
(string or list of strings)
|
|
"specials_menu", name - The name of the menu containing the special
|
|
operations. (string, default: "Run")
|
|
"priority", p - Create the sub-menu with priority p.
|
|
(integer, default: 500)
|
|
"do_all" - Action: Reset and create all menus.
|
|
"do_reset" - Action: Reset.
|
|
"do_templates" - Action: Create menus for all the templates.
|
|
"do_specials" - Action: Create a menu with the special entries.
|
|
"do_styles" - Action: Create a menu for selecting the style.
|
|
No returns.
|
|
|
|
"do_all", "do_templates", "do_specials" and "do_styles" starts the automatic
|
|
creation of menu entries. Sub-menus are created automatically as needed.
|
|
The special operations are: choose a template/style, reread/edit the library.
|
|
The corresponding menu entries are put in the sub-menus given by the option
|
|
"specials_menu".
|
|
|
|
Each sub-menu looks like this, starting with a header:
|
|
>
|
|
<menu name> <global name>
|
|
--- <separator> -------------
|
|
<entry1> <map>
|
|
<entry2>
|
|
... ...
|
|
<
|
|
The global name (option "global_name") helps to keep track of tear-off menus.
|
|
"sub_menu" can be used to create additional menus, which have the same header.
|
|
When a sub-menu is created through use of the API like this, an optional
|
|
priority can be specified.
|
|
|
|
The library keeps track of all created sub-menus, to be able to add the
|
|
headers correctly. "existing_menu" adds menus to this list.
|
|
"do_reset" resets this list and allows for the menus to be created once more.
|
|
"do_all" also reset the list before it carries out further operations.
|
|
|
|
The "&" and the trailing points in 'rootmenu' and "existing_menus" are
|
|
ignored. "sub_menus" and "specials_menu" also ignore trailing points, but use
|
|
the "&" to create shortcuts. However, if a shortcut for the menu has been set
|
|
in the library, that one is preferred.
|
|
|
|
|
|
Example 1: Basic usage.
|
|
|
|
Suppose a plug-in creates the following menus:
|
|
>
|
|
C-Support
|
|
>-+ Comments
|
|
| >-- code->comment
|
|
| >-- comment->code
|
|
| >-+ Special
|
|
| | >--- ...
|
|
>-+ Run
|
|
| >-- run
|
|
| >-- ...
|
|
<
|
|
Then the call has to look like this: >
|
|
call mmtemplates#core#CreateMenus ( "g:My_C_Templates", "&C-Support",
|
|
\ "do_all", "existing_menu", [ "&Comments","Comments.&Special.","&Run." ] )
|
|
<
|
|
To create headers for each sub-menu, similar to those the template support
|
|
creates, use code like this:
|
|
>
|
|
let root_menu = "&C-Support"
|
|
let global_name = "C/C++"
|
|
exe 'amenu '.root_menu.'.'.root_menu.' <Nop>'
|
|
exe 'amenu '.root_menu.'.-Sep0- <Nop>'
|
|
exe 'amenu '.root_menu.'.&Run.Run<TAB>'.global_name.' <Nop>'
|
|
exe 'amenu '.root_menu.'.Run.-Sep00- <Nop>'
|
|
<
|
|
|
|
Example 2: Advanced usage.
|
|
|
|
This facility can be used to create all the menu headers.
|
|
It also gives more control over the order of the menu entries.
|
|
|
|
First, reset the list of created menus: >
|
|
call mmtemplates#core#CreateMenus ( "g:My_C_Templates", "C-Support",
|
|
\ "do_reset" )
|
|
Then create a sub-menu (shortcut "c"): >
|
|
call mmtemplates#core#CreateMenus ( "g:My_C_Templates", "C-Support",
|
|
\ "sub_menu", "&Comments" )
|
|
" entries: comment/uncomment/... :
|
|
...
|
|
Create entries for the templates: >
|
|
call mmtemplates#core#CreateMenus ( "g:My_C_Templates", "C-Support",
|
|
\ "do_templates" )
|
|
Create a run menu (shortcut "r"): >
|
|
call mmtemplates#core#CreateMenus ( "g:My_C_Templates", "C-Support",
|
|
\ "sub_menu", "&Run" )
|
|
" entries: compile/run/test/... :
|
|
...
|
|
Create the special entries at the end of the run menu: >
|
|
call mmtemplates#core#CreateMenus ( "g:My_C_Templates", "C-Support",
|
|
\ "do_specials", "specials_menu", "Run." )
|
|
>
|
|
|
|
Technical Details:
|
|
- The library must be given as the name of the global variable, since this
|
|
name is required to create the menus.
|
|
- The function creates menus of the following types:
|
|
amenu, imenu and vmenu (where appropriate)
|
|
|
|
------------------------------------------------------------------------------
|
|
9.3 ACCESS *template-support-api-access*
|
|
------------------------------------------------------------------------------
|
|
|
|
The following functions are used to query and change the resources of a
|
|
template library. For example, they are used to change the style or to change
|
|
the format of the date and time.
|
|
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#ChooseStyle()*
|
|
The style is changed using the function:
|
|
|
|
mmtemplates#core#ChooseStyle ( library, style ) ~
|
|
|
|
Parameters:
|
|
library - The template library. (string or dict)
|
|
style - The name of the style or "!pick". (string)
|
|
No returns.
|
|
|
|
The library can either be given directly, or as the name of the global
|
|
variable containing the library.
|
|
If 'style' is "!pick", the user is presented with a list of all styles, and
|
|
can choose one.
|
|
It the style 'style' does not exist, an error message is displayed and the
|
|
style remains unchanged.
|
|
|
|
Example:
|
|
|
|
Prompt the user for a new style: >
|
|
call mmtemplates#core#ChooseStyle ( g:My_C_Templates, "!pick" )
|
|
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#Resource()*
|
|
Access to a number of resources is provided by:
|
|
|
|
[ rval, msg ] = mmtemplates#core#Resource ( library, mode, ... ) ~
|
|
|
|
[ rval, msg ] ~
|
|
= mmtemplates#core#Resource ( library, "get", resource, key ) ~
|
|
[ rval, msg ] ~
|
|
= mmtemplates#core#Resource ( library, "set", resource, key, val ) ~
|
|
|
|
Parameters:
|
|
library - The template library. (string or dict)
|
|
mode - The operation which should be executed. (string)
|
|
Optional parameters:
|
|
... - Depending on 'mode'.
|
|
Returns:
|
|
rval - Content and type depending on 'mode'.
|
|
msg - In case of success: An empty string. (string)
|
|
In case of failure: An error message. (string)
|
|
|
|
The library can either be given directly, or as the name of the global
|
|
variable containing the library.
|
|
|
|
Special resources:
|
|
|
|
- "escaped_mapleader" : Return the mapleader, escaped for use in a menu.
|
|
- "jumptag" : Return the regex used to find jump tags.
|
|
- "style" : Return the name of the current style.
|
|
|
|
Regular resources:
|
|
|
|
- "add" : Add the property with the given key and set it to 'val'.
|
|
- "get" : Return the resource with the given key or 0.
|
|
- "set" : Change the resource with the given key to 'val'.
|
|
|
|
The mode "get" supports the following resources:
|
|
- "list", "l": The list as generated by: == List: l == ... ==
|
|
- "macro", "m": A macro as set by: SetMacro( "m", ... )
|
|
- "path", "p": A path as set by: SetPath( "p", ... )
|
|
- "property", "p": An existing resource named "p".
|
|
It returns the integer 0, if the resource 'key' does not exist.
|
|
The mode "set" can be used to overwrite these resources.
|
|
The resource "list" is returned as a reference, use it responsibly.
|
|
|
|
For "add" and "set" 'rval' is undefined.
|
|
|
|
Macros:
|
|
|
|
Setting the special macros "DATE", "TIME", and "YEAR" changes the format of
|
|
the date and time. they use the same format as the function |strftime()|.
|
|
Setting "BASENAME", "FILENAME", "PATH" and "SUFFIX" has no effect.
|
|
|
|
Properties:
|
|
|
|
The mode "get" returns the property named 'key', but only if it already
|
|
exists. Only an existing property can be set in the mode "set". To create and
|
|
set a new property, the mode "add" must be used.
|
|
|
|
|
|
Example 1:
|
|
|
|
The format of the macro *|TIME|* can be changed by calling: >
|
|
call mmtemplates#core#Resource (
|
|
\ g:My_C_Templates, "set", "macro", "TIME", "%H:%M" )
|
|
<
|
|
|
|
Example 2:
|
|
|
|
Suppose there is a template like this:
|
|
>
|
|
== Include.project include == insert, pick-file ==
|
|
|Prompt( "project include directory" )|
|
|
|GetPath( "project_include" )|
|
|
#include "|PICK|"
|
|
== ENDTEMPLATE ==
|
|
<
|
|
When switching to a new project, execute: >
|
|
call mmtemplates#core#Resource (
|
|
\ g:My_C_Templates, "set", "path", "project_include", project_incl_dir )
|
|
<
|
|
The next time the template "Include.project include" is inserted, the file
|
|
browser will already be set to the project include directory.
|
|
|
|
|
|
Example 3:
|
|
|
|
Set the property "Templates::Mapleader": >
|
|
call mmtemplates#core#Resource (
|
|
\ g:My_C_Templates, "set", "Templates::Mapleader", "." )
|
|
<
|
|
Create a new property "C::RunCompiler::Map": >
|
|
call mmtemplates#core#Resource (
|
|
\ g:My_C_Templates, "add","C::RunCompiler::Map", "rc" )
|
|
<
|
|
Get the mapleader (already escaped): >
|
|
let [ esc_mapleader, msg ] = mmtemplates#core#Resource (
|
|
\ g:My_C_Templates, "escaped_mapleader" )
|
|
<
|
|
Get the map (not escaped!): >
|
|
let [ map_run, msg ] = mmtemplates#core#Resource (
|
|
\ g:My_C_Templates, "get", "C::RunCompiler::Map" )
|
|
|
|
Create the menu entry: >
|
|
if empty ( msg )
|
|
exe 'amenu '.root_menu
|
|
\ .'.Run.run\ &compiler<TAB>'.esc_mapleader.map_run.' :call Run()<CR>'
|
|
else
|
|
" handle error ...
|
|
endif
|
|
<
|
|
|
|
Example 4:
|
|
|
|
Get the current style: >
|
|
let [ current_style, msg ] = mmtemplates#core#Resource (
|
|
\ g:My_C_Templates, "style" )
|
|
<
|
|
------------------------------------------------------------------------------
|
|
9.4 MISCELLANY *template-support-api-misc*
|
|
------------------------------------------------------------------------------
|
|
|
|
This section describes various functions, provided for convenience.
|
|
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#SetMapleader()*
|
|
*mmtemplates#core#ResetMapleader()*
|
|
Set and reset |maplocalleader|:
|
|
|
|
mmtemplates#core#SetMapleader ( localleader ) ~
|
|
mmtemplates#core#ResetMapleader () ~
|
|
|
|
Parameters:
|
|
localleader - The new value for |maplocalleader|. (string)
|
|
No returns.
|
|
|
|
A call to mmtemplates#core#SetMapleader sets maplocalleader to the given
|
|
value. A subsequent call to mmtemplates#core#ResetMapleader restores the
|
|
previous setting, which can also mean that maplocalleader is undefined again.
|
|
Calls to SetMapleader and ResetMapleader can be nested.
|
|
If the argument 'localleader' is an empty string, maplocalleader remains
|
|
unchanged.
|
|
|
|
------------------------------------------------------------------------------
|
|
*mmtemplates#core#EscapeMenu()*
|
|
Escape a string to be used as a menu entry:
|
|
|
|
str = mmtemplates#core#EscapeMenu ( str ) ~
|
|
|
|
Parameters:
|
|
str - The menu item. (string)
|
|
Optional parameters:
|
|
mode - How to escape the string. (string, default "entry")
|
|
Returns:
|
|
str - The same string with appropriately escaped characters. (string)
|
|
|
|
The following modes are supported:
|
|
- "menu" : A menu name with possible submenus, escapes <space> \ | &
|
|
- "entry" : A menu entry, dots are escaped as well, escapes <space> . \ | &
|
|
- "right" : The right-aligned side of a menu entry, escapes <space> . \ |
|
|
|
|
In mode "entry" the function even escapes '.', so the menu and the entry must
|
|
be escaped separately, otherwise the entry 'frame comment' in the menu
|
|
'Comments': >
|
|
"Comments.frame comment"
|
|
would turn into the entry: >
|
|
"Comments\.frame\ comment"
|
|
|
|
==============================================================================
|
|
10. BACKWARDS COMPATIBILITY *template-support-backwards*
|
|
==============================================================================
|
|
|
|
The following behavior is not compatible with the old template systems of
|
|
various plug-ins. This list does not include new features which are now
|
|
supported.
|
|
|
|
c-support:
|
|
doxygen-support:
|
|
perl-support:
|
|
- No automatic uppercase for *|BASENAME|* .
|
|
- The format for *|DATE|* , *|TIME|* and *|YEAR|* is now configured via the
|
|
template library. Plug-ins may provide other ways to do the configuration.
|
|
|
|
perl-support:
|
|
- The template header can not have the format >
|
|
== templatename == [ position == ] [ indentation == ]
|
|
< anymore, since the last part would be ignored. Use the list of template
|
|
options instead: >
|
|
== templatename == [ position, indentation == ]
|
|
< Both 'position' and 'indentation' are optional, of course.
|
|
|
|
|
|
|
|
-------------------------------------------------------------------------- ~
|
|
|
|
-------------------------------------------------------------------------- ~
|
|
|
|
-------------------------------------------------------------------------- ~
|
|
|
|
|
|
|
|
==============================================================================
|
|
A. SYNTAX *template-support-syntax*
|
|
==============================================================================
|
|
|
|
The standards for the idioms are as follows, but may be changed via the API:
|
|
|
|
Idiom Changeable? Standard
|
|
|
|
CommentStart yes $
|
|
BlockDelimiter no ==
|
|
|
|
CommandName no same as MacroName
|
|
MacroName no a-z, A-Z, 0-9 and _
|
|
starting with a letter or underscore
|
|
OptionName no same as MacroName
|
|
ResourceName no same as MacroName
|
|
SeparatorName no same as MacroName
|
|
StyleName no same as MacroName
|
|
TemplateName no a-z, A-Z, 0-9 and _ + - . , <Space>
|
|
starting with a letter or underscore,
|
|
not ending with a whitespace
|
|
Mapping no a-z, A-Z, 0-9 and _ + -
|
|
|
|
The rules in the next sections use the following notation:
|
|
|
|
- Syntax category: StartsWithCapitalLetters
|
|
- Keyword: ALLCAPS
|
|
- Various items: -something-
|
|
- Square brackets [ ] mark an optional part of the rule.
|
|
- All other characters are as printed.
|
|
- Whitespaces are ignored, except where <start> marks the start of the line.
|
|
Whitespaces can not appear there.
|
|
|
|
------------------------------------------------------------------------------
|
|
A.1 COMMAND SECTION *template-support-syntax-cmd*
|
|
------------------------------------------------------------------------------
|
|
|
|
MacroAssignment (one of):
|
|
-text-
|
|
' -text- '
|
|
" -text- "
|
|
|
|
Note: Trailing whitespaces are ignored, even with the first rule.
|
|
|
|
|
|
Statement (one of):
|
|
-empty line-
|
|
<start> CommentStart -anything-
|
|
<start> CommandName ( ParameterList )
|
|
<start> *|MacroName|* = MacroAssignment
|
|
StyleBlock1
|
|
StyleBlock2
|
|
Template
|
|
HelpTemplate
|
|
MenuSeparator
|
|
List
|
|
|
|
|
|
StyleBlock1 (sequence):
|
|
<start> == IF *|STYLE|* IS MacroName ==
|
|
StatementList
|
|
<start> == ENDIF ==
|
|
|
|
|
|
StyleBlock2 (sequence):
|
|
<start> == USE STYLES : MacroNameList ==
|
|
StatementList
|
|
<start> == ENDSTYLES ==
|
|
|
|
|
|
Template (sequence):
|
|
<start> == [ TEMPLATE : ] TemplateName == [ OptionList == ]
|
|
-several lines-
|
|
<start> == ENDTEMPLATE ==
|
|
|
|
Note: The " TEMPLATE : " in the first line is optional, as opposed to the
|
|
structure of the next three rules.
|
|
|
|
|
|
HelpTemplate (sequence):
|
|
<start> == HELP : TemplateName == [ OptionList == ]
|
|
-several lines-
|
|
<start> == ENDTEMPLATE ==
|
|
|
|
|
|
MenuSeparator (one line):
|
|
<start> == SEP : SeparatorName ==
|
|
|
|
|
|
List (sequence):
|
|
<start> == LIST : MacroName == [ OptionList == ]
|
|
-several lines-
|
|
<start> == ENDLIST ==
|
|
|
|
|
|
MacroNameList (one of):
|
|
MacroName
|
|
MacroName , MacroNameList
|
|
|
|
|
|
OptionList (one of):
|
|
-empty-
|
|
Option
|
|
Option , OptionList
|
|
|
|
|
|
Option (one of):
|
|
OptionName
|
|
OptionName : MacroName
|
|
OptionName : Mapping
|
|
|
|
------------------------------------------------------------------------------
|
|
A.2 TEMPLATES *template-support-syntax-templ*
|
|
------------------------------------------------------------------------------
|
|
|
|
*Todo syntax templates
|
|
|
|
------------------------------------------------------------------------------
|
|
A.3 LISTS *template-support-syntax-list*
|
|
------------------------------------------------------------------------------
|
|
|
|
Lists can either be lists or dictionaries. (Corresponding to the types Vim
|
|
uses: |List| and |Dictionary|.)
|
|
|
|
Lists are a comma separated list of strings:
|
|
>
|
|
== LIST: Options == list ==
|
|
"tabstop", "shiftwidth",
|
|
"wrap", "nowrap",
|
|
"filetype"
|
|
== ENDLIST ==
|
|
<
|
|
Bare lists do not require quotes, each line is interpreted as an entry.
|
|
Leading and trailing whitespaces are ignored:
|
|
>
|
|
== LIST: Options == list, bare ==
|
|
tabstop
|
|
shiftwidth
|
|
wrap
|
|
nowrap
|
|
filetype
|
|
== ENDLIST ==
|
|
<
|
|
Dictionaries associate a key with a value. Key and value are separated by a
|
|
colon, different entries by a comma.
|
|
>
|
|
== LIST: FileEndings == dict ==
|
|
"C" : ".c" ,
|
|
"C++" : ".cc" ,
|
|
"Perl" : ".pl" ,
|
|
"Shell" : ".sh" ,
|
|
"Vimscript" : ".vim" ,
|
|
== ENDLIST ==
|
|
<
|
|
==============================================================================
|
|
B. COMMANDS *template-support-commands*
|
|
==============================================================================
|
|
|
|
This sections list the commands supported by the template system.
|
|
|
|
------------------------------------------------------------------------------
|
|
B.1 COMMAND SECTION *template-support-cmd-cmd-sct*
|
|
------------------------------------------------------------------------------
|
|
|
|
The following commands can be used outside of templates, in the so-called
|
|
command section.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-IncludeFile()*
|
|
Include the file 'filename':
|
|
|
|
IncludeFile ( filename [, "abs"] ) ~
|
|
|
|
'filename' can contain a path which can be absolute or relative. Relative
|
|
paths are interpreted in relation to the directory of the file containing the
|
|
command. The path is always understood to be relative, except when the
|
|
optional second argument "abs" is given.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-SetFormat()*
|
|
Set the format of 'item' to 'format':
|
|
|
|
SetFormat ( item, format ) ~
|
|
|
|
This changes the way the macros "TIME", "DATE" and "YEAR" are replaced. It
|
|
sets the format of the date and time. They use the same format as the function
|
|
|strftime()|.
|
|
|
|
Example: >
|
|
SetFormat ( "TIME", "%H:%M" )
|
|
The macro *|TIME|* will now be replaced by something like 10:24.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-SetMacro()*
|
|
Set the macro 'name' to 'text':
|
|
|
|
SetMacro ( name, text ) ~
|
|
|
|
This is used to set replacements for macros.
|
|
|
|
Setting the macros "TIME", "DATE", "YEAR", "BASENAME", "FILENAME" , "PATH" and
|
|
"SUFFIX" is not allowed. They are set to the appropriate values before
|
|
insertion of a template.
|
|
|
|
Example: >
|
|
SetMacro ( "AUTHOR", "My cat." )
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-SetPath()*
|
|
Set the resource 'name' to the given path.
|
|
|
|
SetPath ( name, path ) ~
|
|
|
|
Subsequently the path can be used in templates.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-SetProperty()*
|
|
Set the property 'name' to the given value.
|
|
|
|
SetProperty ( name, value ) ~
|
|
|
|
Only existing properties can be set. If 'name' does not refer to an existing
|
|
property, an error will be printed.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-SetStyle()*
|
|
Set the active style to 'name':
|
|
|
|
SetStyle ( name ) ~
|
|
|
|
This style will be used after the library has been loaded.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-MenuShortcut()*
|
|
Set the shortcut for the submenu 'menu' to 'shortcut':
|
|
|
|
MenuShortcut ( menu, shortcut ) ~
|
|
|
|
The shortcut is set for the menu named by the last component of 'menu', which
|
|
can consist of several parts, separated by points. Trailing points are
|
|
ignored.
|
|
|
|
Example: >
|
|
MenuShortcut ( "Comments.Frames.", "r" )
|
|
Sets the shortcut for the submenu "Frames", not "Comments".
|
|
|
|
------------------------------------------------------------------------------
|
|
B.2 TEMPLATES *template-support-cmd-templates*
|
|
------------------------------------------------------------------------------
|
|
|
|
Templates themselves support various commands, either in the command block at
|
|
the beginning of the template, or in the text itself.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-PickFile()*
|
|
Open a prompt and let the user select a file:
|
|
|
|
|PickFile ( prompt, path )| ~
|
|
|
|
Displays 'prompt' and lets the user select a file. The file browser starts out
|
|
in the directory named by 'path'. If 'path' matches an identifier, the path
|
|
resource by this name serves as the path. Otherwise the string path is used as
|
|
the path directly.
|
|
|
|
After the user selected a file, several replacements for macros are created,
|
|
which can be inserted into the template:
|
|
- *|PICK_COMPL|* : the complete path and name of the selected file
|
|
- *|PATH_COMPL|* : the complete path of the selected file
|
|
- *|PICK|* : the selected path and file relative to the directory given
|
|
in 'path'
|
|
- *|PATH|* : the path in *|PICK|*
|
|
- *|FILENAME|* : the name of the file
|
|
- *|BASENAME|* : the name of the file without the suffix
|
|
- *|SUFFIX|* : the suffix of the file
|
|
|
|
Example: >
|
|
|
|
SetPath ( "global", "/usr/include/" )
|
|
|
|
== global include == below ==
|
|
|PickFile( "select a file: ", "global" )|
|
|
#include <|PICK|>
|
|
== local include == below ==
|
|
|PickFile( "select a file: ", "global/" )|
|
|
#include "|PICK|"
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The path in the first template is the resource "global", which in turn is
|
|
"/usr/include/". The path in the second template will be "global/", since the
|
|
string does not match an identifier.
|
|
|
|
If the user inserts the template "global include", he will be asked to select
|
|
a file, starting in the directory "/usr/include/". If we selects the file: >
|
|
/usr/include/QtGui/QPushButton
|
|
the macro *|PICK|* will be set to "QtGui/QPushButton", and *|PATH|* to
|
|
"QtGui".
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-PickList()*
|
|
Open a prompt and let the user select an entry from a list:
|
|
|
|
|PickList ( prompt, list )| ~
|
|
|
|
Displays 'prompt' and lets the user select an entry from a list. If 'list' is
|
|
a string and matches an identifier, the list resource by this name is used.
|
|
If 'list' is a list or a dictionary, it is used directly.
|
|
|
|
In case of lists, the user has to choose an entry from the list. In case of
|
|
dictionaries, the user has to choose one of the keys.
|
|
|
|
After the user selected an entry, several replacements for macros are created,
|
|
which can be inserted in the template:
|
|
- *|VALUE|* : the selected entry from the list or dictionary
|
|
- *|KEY|* : the selected key (dictionaries only)
|
|
- *|PICK|* : same as *|VALUE|*
|
|
|
|
Example:
|
|
>
|
|
== LIST: headers == list ==
|
|
"stdlib",
|
|
"stdio",
|
|
"string",
|
|
== LIST: functions == hash ==
|
|
"strcpy" : "{+DEST+}, {+SRC+}",
|
|
"strncpy" : "{+DEST+}, {+SRC+}, {+N+}",
|
|
"strcmp" : "{+STR1+}, {+STR2+}",
|
|
"strncmp" : "{+STR1+}, {+STR2+}, {+N+}",
|
|
"strlen" : "{+STR+}",
|
|
== ENDLIST ==
|
|
|
|
== header include == below ==
|
|
|PickList( "header file: ", "headers" )|
|
|
#include <|PICK|.h>
|
|
== function call == insert ==
|
|
|PickList( "function: ", "functions" )|
|
|
|KEY|<CURSOR> ( |VALUE| )
|
|
== ENDTEMPLATE ==
|
|
<
|
|
The first template is quite simple. The user selects a header from the list,
|
|
then the preprocessor directive is inserted.
|
|
|
|
The second template uses a dictionary. The user has to pick an entry from the
|
|
list of function names. The template is inserted using both the selected key
|
|
and value. Each value is a list of jump tags, named for the arguments of the
|
|
corresponding function.
|
|
|
|
Inserting the template "function call" and selecting "strcpy" will results in
|
|
the following text to be inserted: >
|
|
strcpy | ( {+DEST+}, {+SRC+} )
|
|
The position of the cursor is marked by "|". The jump key can be used to jump
|
|
ahead and replace the tags.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-Prompt()*
|
|
Prompt the user for a replacement of the macro:
|
|
|
|
|Prompt ( macro, flag )| ~
|
|
|
|
The user is prompted for a replacement of 'macro'. After the user has entered
|
|
a text, the flag is applied. The replacement is saved to be reused later.
|
|
|
|
Flags:
|
|
- "" : no change to the text
|
|
- "l" : change text to lowercase
|
|
- "u" : change text to uppercase
|
|
- "c" : capitalize text (change first letter to uppercase)
|
|
- "L" : legalize name (replace all non-word characters with underscores)
|
|
|
|
Example:
|
|
>
|
|
== chapter, alt1 == below ==
|
|
============================================================================
|
|
|?NUMBER| |?NAME:u|
|
|
============================================================================
|
|
|
|
<CURSOR>
|
|
|
|
== chapter, alt2 == below ==
|
|
|Prompt( 'NAME', '' )|
|
|
|Prompt( 'NUMBER', '' )|
|
|
============================================================================
|
|
|NUMBER| |NAME:u|
|
|
============================================================================
|
|
|
|
<CURSOR>
|
|
|
|
== chapter, toc == below ==
|
|
|NUMBER| |NAME:c|
|
|
== ENDTEMPLATE ==
|
|
<
|
|
This inserts captions for chapters as used in this document. With the first
|
|
alternative, the user is first prompted for a replacement of *|NUMBER|* ,
|
|
because of the order both macros appear in the text. The name is saved in
|
|
uppercase.
|
|
Using the second alternative, the user is prompted for the name first. The
|
|
name is saved as entered and only inserted in uppercase. Now it can be
|
|
inserted into the table of contents as entered by the user.
|
|
|
|
==============================================================================
|
|
C. OPTIONS *template-support-options*
|
|
==============================================================================
|
|
|
|
The following sections list the options for templates and lists.
|
|
|
|
------------------------------------------------------------------------------
|
|
C.1 TEMPLATES *template-support-opt-templ*
|
|
------------------------------------------------------------------------------
|
|
|
|
The template options appear in the header of the template:
|
|
== <name> == <options> == ~
|
|
|
|
It is not required to specify any options. The defaults are given below.
|
|
Help templates use the same options as normal templates.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-start* *template-support-append*
|
|
*template-support-above* *template-support-insert*
|
|
*template-support-below*
|
|
Placement:
|
|
|
|
start - The text is placed above the first line.
|
|
above - The text is placed above the current line.
|
|
below - The text is placed below the current line (default).
|
|
append - The text is appended to the current line.
|
|
insert - The text is inserted at the cursor position.
|
|
|
|
Note: "below" and "insert" support split tag in visual mode.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-visual* *template-support-indent*
|
|
*template-support-novisual* *template-support-noindent*
|
|
Insertion:
|
|
|
|
visual - Use the split tag in visual mode (default?).
|
|
novisual - No special behavior in visual mode (default?).
|
|
|
|
indent - The inserted text is indented (default).
|
|
noindent - No automatic indentation.
|
|
|
|
Note: "visual" is the default for templates containing the split tag,
|
|
"novisual" for templates without the split tag.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-sc* *template-support-nomenu*
|
|
*template-support-shortcut* *template-support-expandmenu*
|
|
*template-support-map*
|
|
Menus and Maps:
|
|
|
|
nomenu - No menu entry is created.
|
|
expandmenu - A submenu is created for this template with entries matching
|
|
those of a given list.
|
|
sc:<sc> - A shortcut is created for the menu entry of this template.
|
|
shortcut:<sc> - Long version of sc:<sc>.
|
|
map:<map> - A map is created for this template.
|
|
|
|
Note: The default is for a menu entry to be created.
|
|
Note: A shortcut can only be one character long. A map can be several
|
|
characters long. It is always preceded by the local mapleader.
|
|
|
|
------------------------------------------------------------------------------
|
|
C.2 LISTS *template-support-opt-list*
|
|
------------------------------------------------------------------------------
|
|
|
|
The list options appear in the header of the list:
|
|
== List: OutputModifiers == <options> == ~
|
|
|
|
It is not required to specify any options. The defaults are given below.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-list* *template-support-dict*
|
|
*template-support-hash* *template-support-dictionary*
|
|
Type:
|
|
|
|
list - The object is given as a list. (default)
|
|
hash - The object is a hash, or dictionary.
|
|
dict - Same as hash.
|
|
dictionary - Same as hash.
|
|
|
|
For a description see |template-support-syntax-list|.
|
|
|
|
------------------------------------------------------------------------------
|
|
*template-support-bare*
|
|
Interpretation:
|
|
|
|
bare - The list is interpreted as a bare list. Each line is considered to be
|
|
a new entry.
|
|
|
|
Note: Bare lists are not the default.
|
|
|
|
==============================================================================
|
|
D. CHANGE LOG *template-support-change-log*
|
|
==============================================================================
|
|
|
|
------------------------------------------------------------------------------
|
|
RELEASE NOTES FOR VERSION 0.9.3
|
|
------------------------------------------------------------------------------
|
|
|
|
- Change: In case several version of autoload/mmtemplates/core.vim are
|
|
available on 'runtimepath', pick out the newest one to load.
|
|
|
|
Includes the patches 0.9.2-1 to 0.9.2-2:
|
|
- Change: More checks when rereading templates.
|
|
- Change: Better compatibility with custom mappings
|
|
(use "normal!", "noremap" and "noremenu" consistently).
|
|
- Change: During template insertion, find <CURSOR> tag independent of the
|
|
settings 'magic' and 'startofline'.
|
|
- Added: API functions "mmtemplates#core#SetMapleader" and
|
|
"mmtemplates#core#ResetMapleader".
|
|
- Extended the documentation.
|
|
|
|
------------------------------------------------------------------------------
|
|
RELEASE NOTES FOR VERSION 0.9.2
|
|
------------------------------------------------------------------------------
|
|
|
|
- Added: 'SetProperty' to set properties using a template library.
|
|
- Change: Improved list picker.
|
|
|
|
API:
|
|
- Change: Extended 'mmtemplates#core#EscapeMenu'.
|
|
|
|
Includes the patches 0.9.1-1 to 0.9.1-3:
|
|
- Bugfix: Problem with macro replacements containing macros with flags.
|
|
- Change: Syntax highlighting.
|
|
- Change: Warnings about overwritten maps are only printed once for every
|
|
filetype.
|
|
- Bugfix: Inserting templates in visual mode with placement "insert" could
|
|
cause rare problems interacting with the indent program.
|
|
- Extended the documentation.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
PATCH 0.9.2-1:
|
|
- Released with slight changes in the core functionality.
|
|
- Change: More checks when rereading templates.
|
|
- Extended the documentation.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
PATCH 0.9.2-2:
|
|
- Released with slight changes in the core functionality.
|
|
- Change: Better compatibility with custom mappings
|
|
(use "normal!", "noremap" and "noremenu" consistently).
|
|
- Change: During template insertion, find <CURSOR> tag independent of the
|
|
settings 'magic' and 'startofline'.
|
|
- Added: API functions "mmtemplates#core#SetMapleader" and
|
|
"mmtemplates#core#ResetMapleader".
|
|
|
|
------------------------------------------------------------------------------
|
|
RELEASE NOTES FOR VERSION 0.9.1
|
|
------------------------------------------------------------------------------
|
|
|
|
- Change: When checking for already existing maps: Check each mode individually.
|
|
- Added: Menu separators can be inserted via the template library.
|
|
- Bugfix: Changing the mapleader now works.
|
|
- Bugfix: Inserting templates with placement "insert" did not work in some
|
|
cases.
|
|
- Minor improvements and bugfixes.
|
|
|
|
API:
|
|
- Added: Sub-menus can be created with priorities.
|
|
- Added: Properties.
|
|
- Added: The mapleader shown in the menu is configurable.
|
|
- Added: The maps for "edit templates", "reread templates" and "choose style"
|
|
are configurable.
|
|
|
|
Internal Changes:
|
|
- Changes to the template data structure.
|
|
- Major code cleanup.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
PATCH 0.9.1-1:
|
|
- Released with no changes in the core functionality.
|
|
- Change: Some commands are now executed silently.
|
|
- Bugfix: Syntax highlighting.
|
|
- Extended the documentation.
|
|
|
|
PATCH 0.9.1-2:
|
|
- Released with slight changes in the core functionality.
|
|
- Bugfix: Problem with macro replacements containing macros with flags.
|
|
- Change: Syntax highlighting.
|
|
- Slightly extended the documentation.
|
|
|
|
PATCH 0.9.1-3:
|
|
- Released with slight changes in the core functionality.
|
|
- Change: Warnings about overwritten maps are only printed once for every
|
|
filetype.
|
|
- Bugfix: Inserting templates in visual mode with placement "insert" could
|
|
cause rare problems interacting with the indent program.
|
|
- Extended the documentation.
|
|
|
|
------------------------------------------------------------------------------
|
|
RELEASE NOTES FOR VERSION 0.9
|
|
------------------------------------------------------------------------------
|
|
|
|
- Initial upload.
|
|
|
|
==============================================================================
|
|
vim:tw=78:noet:ts=2:ft=help:norl:expandtab:
|