templatesupport.txt MM Template Support Mar 26 2016
MM Template Support template-support
Plug-in version 1.0
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
--- Part I - User Documentation --- 1. Introduction |template-support-intro| 2. Basic Usage |template-support-basics| 3. Template Library |template-support-library| 3.1 Personalization |template-support-lib-person| 3.2 Interface Version |template-support-lib-interf| 4. Templates |template-support-templates| 4.1 Macros |template-support-templ-macro| 4.1.1 Predefined Macros |template-support-templ-predef| 4.1.2 Flags |template-support-templ-flag| 4.1.3 Format Specifiers |template-support-templ-format| 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| 5.3 Menu Customization |template-support-lists-menu| 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. Configuration |template-support-config| --- Part II - API Documentation --- 1. API |template-support-api| 1.1 Basic Usage |template-support-api-basic| 1.2 Creating Maps and Menus |template-support-api-maps| 1.3 Access |template-support-api-access| 1.4 Miscellany |template-support-api-misc| 2. Backwards Compatibility |template-support-backwards| --- Part III - Appendices --- 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| D.1 Interface Versions |template-support-change-interf| D.2 API Versions |template-support-change-api| E. Credits |template-support-credits|
------------------------------------------------------------------------------------------------------------------------------------------------------------- PART I --- USER DOCUMENTATION -------------------------------------------------------------------------------------------------------------------------------------------------------------
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)==starts a new template,<name>==<options>==== 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 ( "loads templates from another file (|<path>/<file>" )template-support-IncludeFile|). The path is given relative to the including file. The call:IncludeFile ( "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".<path>/<file>", "abs" )== 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 definitionThis 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) |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:YEAR|, |AUTHOR|' )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.
3.2 INTERFACE VERSION template-support-lib-interf
Further extension of the template engine might introduce minor
incompatibilities with previous versions. While this will generally be
avoided, not all features can be added (and bugs fixes) in a way that is
backwards compatible.
To avoid breaking existing template libraries, by default, all libraries will
use the interface introduced prior to version "1.0". Newer versions can be
unlocked by calling InterfaceVersion() (|template-support-InterfaceVersion()|)
from within the template library:
InterfaceVersion ( "1.0" )
This will enable advanced feature for this library. Other libraries loaded
with the same core can use other versions.
When this call is inserted into a library, it has to be checked for constructs
which can not be used anymore. However, existing libraries must not be changed
immediately once a new version comes along.
See |template-support-change-interf| for a change log limited to changes in
the interface.
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:==For consistency with other constructs, the following format is also supported:<name>== [<options>== ]== TEMPLATE: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 _ + - . ,<name>== [<options>== ]<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 are 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 ==
4.1.1 Predefined Macros template-support-templ-predef
The replacements for various macros are handled 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
Further macros can be used to print "pretty" dates in READMEs and other
documentation.
|DATE_PRETTY| |DATE_PRETTY1|
|DATE_PRETTY2| |DATE_PRETTY3|
|TIME_PRETTY| |YEAR_PRETTY|
The format of the inserted dates and times can be set via SetFormat (see
|template-support-SetFormat|).
4.1.2 Flags template-support-templ-flag Certain uses come with special requirements on the replacement text. 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 replacement text to lowercase :u - change replacement text to uppercase :c - capitalize text (change first letter to uppercase) :L - legalize name (replace all non-word characters with underscores) :T - remove tags (remove all cursor, split, and jump tags)
4.1.3 Format Specifiers template-support-templ-format A format specifier can be added to change the way the macro is replaced. E.g., in some comment boxes the formatting should not be broken. Consider this example:== Comments.file description == start ==# ################################################## ## File: |FILENAME| ## Description:<CURSOR>## ## Author: |AUTHOR| ## Version: 1.0 ## Created: |DATE| ## ################################################## #== ENDTEMPLATE ==Inserting this template into a file would result in a broken formatting:# ################################################## ## File: test.sh ## Description: | ## ## Author: Wolfgang Mehner ## Version: 1.0 ## Created: 11.11.2015 ## ################################################## #Therefore macros can be specified to be inserted with fixed width, for example:== Comments.file description == start ==# ################################################## ## File: |FILENAME%++++++++++++++++++++++l| ## Description:<RCURSOR>## ## Author: |AUTHOR%++++++++++++++++++++++++l| ## Version: 1.0 ## Created: |DATE%++++++++++++++++++++++++++l| ## ################################################## #== ENDTEMPLATE ==The format specifier causes the replacement text to be padded with spaces, such that a text of the desired width is inserted. The special cursor tag<RCURSOR>is replaced with the right amount of spaces as well, and after the template insertion replacement mode is started:# ################################################## ## File: test.sh ## Description: | ## ## Author: Wolfgang Mehner ## Version: 1.0 ## Created: 11.11.2015 ## ################################################## #The format specifier is a '%' followed by several plus characters '+', which are used to extend the macro to the desired width. The format specifier ends with an (optional) character 'l', 'c', or 'r' to indicate the alignment (left, center, or right, respectively). If the replacement text is longer than the macro in the template, the formatting will be broken. Instead of the plus character, several dashes can be used. In this case the replacement text will be cut off if it is longer than the macro:== Comments.file description == start ==# ################################################## ## File: |FILENAME%----------------------l| #...The width can also be specified by a number. To insert a text which is always at least 4 characters long:|To insert it such that the text is never longer than 4 characters:AUTHORREF%+4||AUTHORREF%-4|The following format specifiers are possible, the alignment is always optional: %++++++l - pad the replacement text %------l - pad the replacement text, cut off if it is to long %+10l - the width is given by the number %-10l - the width is given by the number, cut off if the text is to long %10l - the width is given by the number, do not cut off %+l %-l - align left %+c %-c - align center %+r %-r - align right
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>, but it may vary with each plug-in using the template support. Jump tags have one of the following formats:<+NAME+><-NAME->{+NAME+}{-NAME-}And with interface version 1.0+ (see |template-support-lib-interf|) "optional" jump tags have been introduced: [+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 ==** Interface Version 1.0+ ** The "optional" jumps tags [+NAME+] and [-NAME-] can be used in templates for argument lists:== Idiom.open file == insert ==fid = openfile (<+FILENAME+>, [+MODE+] )== ENDTEMPLATE ==The user can either jump to both tags and write down the arguments or only jump to FILENAME and then use the map<ctrl+d>to delete the optional jump tag MODE, together with the separator "," and whitespaces.
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 viaIncludeFile ( "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:<path>/<file>" )== 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:"|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:PickList( '<prompt>', '<list>' )|"== 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 ==Further options for customizing the look of the submenu are explained in |template-support-lists-menu|.
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 ==mathstdlibstdiostring== 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.
5.3 MENU CUSTOMIZATION template-support-lists-menu
** Interface Version 1.0+ **
With interface version 1.0+, the look of the submenu created for a template
can be modified.
A list can be given explicitly with "expandmenu", which is then used to create
the menu entries:
== Idioms.string function == insert, expandmenu:String_Functions ==
It is up to the user to ensure that the entries in this list are suitable to
select entries from the list used inside the template. The only purpose of the
list given with "expandmenu" is to change the look of the menu.
The created menu entries can use both the left- and the right-aligned text of
the entry. By default, the list element or the dictionary key are shown in the
menu. The right-aligned text can be set using "expandright:...":
== LIST: regex_char_class == hash ==
'digit' : '\d',
'whitespace' : '\s',
'word char.' : '\w',
== ENDLIST ==
== Regex.Character Class == insert, expandmenu, expandright:value, map:xc ==
|PickList( 'Char Class', 'regex_char_class' )|
|PICK|<CURSOR>
== ENDTEMPLATE ==
The created menu will use the values from the dictionary to create the menu
entries' right-aligned text:
Character Class \xc
------------------------------
digit \d
whitespace \s
word char. \w
This way the template becomes self documenting. Additionally, the user can go
to the menu for an overview of the character classes and their associated
expressions.
In the same way "expandleft:..." can be used to define the left-aligned text
of the menu entry. Among the allowed values for "expandleft:..." and
"expandright:..." are "key" and "value". With lists, both refer to the list
element, with dictionaries, they refer to the key and value, respectively. The
following would thus be possible:
== ... == expandmenu, expandleft:value, expandright:key ==
The submenu would show each dictionary key on the right, and each associated
value on the left.
Values for "expandleft:..." and "expandright:...":
Value usage with lists
----------------------------------------------------------------------------
key the list element
key-notags same as "key", but all tags (cursor, split, jump) removed
key-whitetags same as "key", but all tags replace with a space
value same as "key"
value-notags same as "key-notags"
value-whitetags same as "key-whitetags"
----------------------------------------------------------------------------
Value usage with dictionaries
----------------------------------------------------------------------------
key the key
key-notags the key, but all tags (cursor, split, jump) removed
key-whitetags the key, all tags replace with a space
value the value
value-notags the value, all tags removed
value-whitetags the value, all tags replace with a space
----------------------------------------------------------------------------
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#includeThe 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:<gl.h>== 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 viaIncludeFile ( "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:<path>/<file>" )== 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 (\(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:<template-library>, "set", "Templates::Mapleader", "<mapleader>" )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( 'HelpPathEnglish', 'http://en.wiktionary.org/wiki/' )== HELP: Help.english == map:he, sc:e ==|Word( '' )||Substitute( '\W', '', 'g' )||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 callsfirefox 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. The browser can be configured by setting |g:Templates_InternetBrowserExec|. 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:|Otherwise the |Word('W')|word| under the cursor is picked:|Lastly, the word can be picked using a regular expression (see |Word('')|regex|):|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( '[\\@]\w\+' )|<pattern>,<sub>,<flag>). For example, to remove every non-word character:|Substitute replaces the contents of "acc" using Vim's |Substitute( '\W', '', 'g' )|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. To replace all points with the text "-point-", use:|This would have to be written differently with regular expressions. 3. Calling Help After picking up and changing the text, a call is made using Browser(LiteralSub( '.', '-point-', 'g' )|<call>), 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. All three commands can have an optional second argument. If either nothing could be picked up in step 1, or the string is empty after step 2, the call is made using the command given as the second argument. If no such argument 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( '[\\@]', '', '' )||Browser( '|HelpPathDoxygen|#cmd|PICK|', '|HelpPathDoxygen|' )|== ENDTEMPLATE ==First, a Doxygen command is picked up under the cursor, then the leading "\" or "@" is removed. Then the browser is called, similar to:firefox http://www.stack.nl/~dimitri/doxygen/commands.html#cmdparamIf 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.htmlNote:The URL still worked as of November, 2013.
9. CONFIGURATION template-support-config
Some behavior can be defined globally for all template libraries in a Vim
session. The variables can be set in the .vimrc file.
Variable Default Description and further information
----------------------------------------------------------------------------
|g:Templates_OverwriteWarning|'no' whether to print a warning when
a template is overwritten
|g:Templates_MapInUseWarn| 'yes' whether to print a warning when
maps would overwrite existing maps
|g:Templates_TemplateBrowser| 'explore' how to browse template files
|g:Templates_PersonalizationFile|
'templates/personal.template*'
name of the personalization file
|g:Templates_UsePersonalizationFile|
'yes' whether to use the personal. file
|g:Templates_InternetBrowserExec|
'firefox' the browser for help templates (^1)
|g:Templates_InternetBrowserFlags|
'' additional flags for the browser
----------------------------------------------------------------------------
(^1) the Unix defaults are as follows:
|g:Templates_InternetBrowserExec| - firefox
the Windows defaults are as follows:
|g:Templates_InternetBrowserExec| - C:\Program Files\Mozilla Firefox\
firefox.exe
g:Templates_OverwriteWarning
Whenever a template is overwritten, a warning can be printed. This warning is
disable by default. It can be enabled by adding this setting to the ".vimrc":
let g:Templates_OverwriteWarning = 'yes'
g:Templates_MapInUseWarn
Whenever a map configured in a template library would overwrite a map which is
already set for a buffer, a warning is printed. This warning is printed once
per session and filetype.
If this is not desired, the warnings can be switched of entirely by adding
this setting to the ".vimrc":
let g:Templates_MapInUseWarn = 'no'
g:Templates_TemplateBrowser
When using a map or menu entry for editing templates, the template file can be
chosen by different means, which are configured in the ".vimrc" file:
let g:Templates_TemplateBrowser = 'browse'
The possible settings are listed below. If one method is not available, the
next lower one is used:
Value Meaning
----------------------------------------------------------------------------
'browse' select using a GUI file browser (gvim only)
'explore' (default) select using Vim's :Explore command
'edit' open the top-level template file via :edit
----------------------------------------------------------------------------
g:Templates_PersonalizationFile
g:Templates_UsePersonalizationFile
The name and directory (relative to |runtimepath|) of the personalization
file:
let g:Templates_PersonalizationFile = 'templates/personal.template*'
The first file which matches g:Templates_PersonalizationFile on runtimepath
will be used (uses |globpath|, with 'runtimepath' as the list of paths and
g:Templates_PersonalizationFile as the expressions).
The file "templates/personal.template" or "templates/personal.templates" will
be loaded by every template library that uses this feature. Since it is loaded
by every library, it should not contain anything that is specific to a
language. It can however be used to set the users name, and the date and time
format.
The usage of this feature can be disabled entirely by adding this setting to
the ".vimrc":
let g:Templates_UsePersonalizationFile = 'no'
It can also be disabled for individual libraries by setting the property
"Templates::UsePersonalizationFile" inside the library:
SetProperty ( "Templates::UsePersonalizationFile", "no" )
g:Templates_InternetBrowserExec
g:Templates_InternetBrowserFlags
Some help templates (see |template-support-help-templ|) require the executable
of an internet browser, to open websites with documentation. It is set in the
.vimrc file:
let g:Templates_InternetBrowserExec = 'firefox'
Additional flags can be set via:
let g:Templates_InternetBrowserFlags = '--new-window'
------------------------------------------------------------------------------------------------------------------------------------------------------------- PART II --- API DOCUMENTATION -------------------------------------------------------------------------------------------------------------------------------------------------------------
1. 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.
1.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: "api_version", vers - the API version to use (string, default "0.9") "debug", level - View debug information with the given level of detail. (integer, default: show no debug information) Returns: library - The template library. (dict) The API version parameter can be used to enable new behavior which is not backwards compatible, see |template-support-change-api|. 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) "personalization" - Load the template personalization file. "reload", what - Reload templates according to 'what', see below. (string or integer) "name", name - Associated symbolic name of the file. (string) "shortcut", sc - Associated shortcut for editing the file. (string) "map", map - Associated map for editing the file. (string) "optional" - If non-zero, this is an optional template file. (integer) "hidden" - If non-zero, this is an optional and hidden template file. (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 template file can be associated with a symbolic name. Furthermore a map and a shortcut can be set. This information will be used to create the special maps and menu entries for editing the templates (see |mmtemplates#core#CreateMaps| and |mmtemplates#core#CreateMenus|). The menu entry will read "edit<name>templates" and have the associated shortcut. The map will be created by prefixing the given characters with the mapleader. The callmmtemplates#core#ReadTemplates ( library, "load", "additional.templates",\ "name", "additional", "map", "nta" )will cause the creation of a menu entry "edit additional templates" and a map "\nta", depending on the mapleader. The default shortcut is the first letter of the name. If no map is associated, none is created. Optional template files will not cause warnings if they are not readable. Hidden template files do not show up in menus, debug output, ... if they are not available. To load the template personalization file into the library, call:mmtemplates#core#ReadTemplates ( library, "personalization",\ "name", "personal", "map", "ntp" )The personalization file will only be added if it is available and should be used, i.e. if calling |mmtemplates#core#FindPersonalizationFile()| returns a non-empty string. The personalization file can also be associated with a symbolic name, shortcut, and map. 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. (would be ".../local.templates" in the above example) Example 2.3: Reload templates by name:call mmtemplates#core#ReadTemplates ( g:My_C_Templates,\ "reload", "$HOME/.vim/.../local.templates" )
mmtemplates#core#EnableTemplateFile()
Previously unreadable template files can be enabled by using:
mmtemplates#core#EnableTemplateFile ( library, sym_name )
Parameters:
library - The template library. (string or dict)
sym_name - The symbolic name of the file. (string)
No returns.
Checks whether the template file named 'sym_name' is now available. If so, it
will be loaded the next time the library is reloaded.
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, "|returns "29.2.2000 12:00", depending on the format set in the library. This can be used for special menu entries such as:DATE| |TIME|" )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 librarycall 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>inoremapThis maps can be created automatically using |mmtemplates#core#CreateMaps()|.<buffer><C-j><C-R>=mmtemplates#core#JumpToTag ( regex )<CR>
mmtemplates#core#DeleteOptTag() Deleting an "optional" jump tag is performed by:e = mmtemplates#core#DeleteOptTag ( jmp_regex, sep_regex, mode )Parameters: jmp_regex - The regex of the optional jump tag. (string) sep_regex - The regex of the separator. (string) mode - "i" for insert mode, "n" for normal. (string) Deletes the next occurrence of an optional jump tag [+NAME+] or [-NAME-] and its accompanying separator. If the function is called in normal mode ('mode' is "n") and nothing can be deleted on the current line, the normal behavior of<ctrl-d>is invoked. This maps can be created automatically using |mmtemplates#core#CreateMaps()|.
1.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_del_opt_map" - Create a map for |mmtemplates#core#DeleteOptTag()|. (interface 1.0+) "do_special_maps" - Create maps for the special operations. "filetype", ftype - Create maps for the filetype ftype. (interface 1.0+, string, default: "default") No returns. If 'localleader' is an empty string, the standard mapleader is used. Otherwiselet maplocalleader = localleaderis executed before the maps are created. (see |mapleader|) The maps for the jump and the special operations (edit/reread the library, choose a style) are not created unless the corresponding options are given. The maps for editing templates can be customized for each file by passing additional information while loading a file using |mmtemplates#core#ReadTemplates()|. 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: edit/reread the library, choose a style. The corresponding menu entries are put in the sub-menus given by the option "specials_menu". The name of this sub-menu must already be correctly escaped. The menu entries for editing templates can be customized for each file by passing additional information while loading a file using |mmtemplates#core#ReadTemplates()|. 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 menu names given must already be correctly escaped. The library keeps track of all created sub-menus, to be able to add the headers correctly. "existing_menu" adds menus to this list. The names of the menus must be correctly escaped. "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-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:<Nop>'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)
1.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. - "template_list" : Return a list of the template files and their symbolic names, for debugging purposes. More special resources, mostly for internal usage: - "settings_table" : Return a dict of all the settings. Has one key "Templates_SomeSetting" for every configuration variable "g:Templates_SomeSetting" listed in the section |template-support-config|. 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". - "template_file", "s" : Information about the template file with the symbolic name "s". 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. Template Files: Returns a dict with information about the template file with the specified symbolic name. It contains the fields: "filename" : the path and filename "sym_name" : the symbolic name "available" : whether the file is readable "optional" : whether this is an optional template file "hidden" : whether this is a hidden template file For "optional" and "hidden", see also |mmtemplates#core#ReadTemplates()|. These properties cannot be set. 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 ...endifExample 4: Get the current style:let [ current_style, msg ] = mmtemplates#core#Resource (\ g:My_C_Templates, "style" )
1.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"
mmtemplates#core#FindPersonalizationFile()Search for the template personalization file:file = mmtemplates#core#FindPersonalizationFile ( library )Parameters: library - The template library. (string or dict) Returns: file - The template personalization file. (string) Searches |runtimepath| for the template personalization file and returns it. Respects the setting |g:Templates_PersonalizationFile|. An empty string is returned if: - the file can not be found - |g:Templates_UsePersonalizationFile| is set to "no" - the property "Templates::UsePersonalizationFile" is set to "no" for the library
mmtemplates#core#AddCustomTemplateFiles() Add additional template files:mmtemplates#core#AddCustomTemplateFiles ( library, list, list_name )Parameters: library - The template library. (string or dict) list - The list of files. (list of lists of strings) list_name - Name of the list variable, used for error reporting. (string) No returns. Loads additional template files given in 'list'. The files are given as a list of lists, each of which describes a custom template file:[ filename, symbolic_name, edit_map ]The file 'filename' will be loaded. It is associated with the name 'symbolic_name'. The map 'edit_map' can be used to open the file for editing. The second and third list entry are optional and will be replaced by default values if missing. A plug-in might offer a configuration variable, which can be used for adding custom templates. This list can then be passed on to the template engine. User's .vimrc:let g:C_AdditionalTemplates = []call add ( g:C_AdditionalTemplates,\ [ $HOME.'/.vim/.../doxygen.templates', 'Doxygen', 'ntd' ] )call add ( g:C_AdditionalTemplates,\ [ $HOME.'/.vim/.../lua_capi.templates', 'Lua', 'ntlc' ] )Plug-in script:call mmtemplates#core#AddCustomTemplateFiles (\ g:My_C_Templates, g:C_AdditionalTemplates, 'g:C_AdditionalTemplates' )The third argument 'list_name' is used to print debug messages which refer to the name of the variable the user assigned in the .vimrc.
2. 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.
------------------------------------------------------------------------------------------------------------------------------------------------------------- PART III --- APPENDICES -------------------------------------------------------------------------------------------------------------------------------------------------------------
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 == ** Interface Version 1.0+ ** FiletypeBlock (sequence):<start>== USE FILETYPES : 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 ==tabstopshiftwidthwrapnowrapfiletype== 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-InterfaceVersion() Use the interface version 'version':InterfaceVersion ( version )Template libraries use the interface version "0.9" by default. To enable newer features, this function must be called from inside a template library. The called must be made before defining any templates, lists, or any other features are used. This call might cause minor problems with an existing library, the library must be changed accordingly, see |template-support-lib-interf|. Example:InterfaceVersion ( "1.0" )Use interface version "1.0".
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".
template-support-SetExpansion() Set the menu expansion of the template 'name':SetExpansion ( name, expandleft [ , expandright ] )This changes the way menus for lists are expanded, offering more options than the expansion set via the template options (see |template-support-lists-menu|). Within 'expandleft' and 'expandright' the following macros are replaced for every list entry: Value usage with lists ---------------------------------------------------------------------------- |KEY| the list element |VALUE| same as |KEY| ---------------------------------------------------------------------------- Value usage with dictionaries ---------------------------------------------------------------------------- |KEY| the key |VALUE| the value ---------------------------------------------------------------------------- The name of the template appears in the template definition between the first pair of == , the menu is part of the name, also whitespaces contained within the name. Example:Consider this template definition:== LIST: list_headers == list =="stdlib","stdio","string",== ENDLIST ==== Include.standard include == expandmenu, below, sc:g ==|PickList( "header file: ", "list_headers" )|#include <|PICK|.h>== ENDTEMPLATE ==For the template a submenu is created with entries: stdlib stdio string A different list expansion is set using:SetExpansion ( "Include.global include", "|Now the following list is created, |VALUE| is replaced for every list entry: stdlib.h stdstdio.h stdstring.h The name is found in the head of the template:VALUE|.h" )== Include.standard include == below, sc:g ==^ ^|------ the name ------|
template-support-SetFormat() Set the format of 'item' to 'format':SetFormat ( item, format )This changes the way the time and date macros are formatted: DATE DATE_PRETTY DATE_PRETTY1 TIME TIME_PRETTY DATE_PRETTY2 YEAR YEAR_PRETTY DATE_PRETTY3 They use the same format as the function |strftime()|, also see the manpage of strftime(3). The locale can be set by calling the function with "TIME_LOCALE":SetFormat ( "TIME_LOCALE", "fr_FR" )Under Linux, run 'locale -a' to see all locales your system supports, compare the manpage of locale(1) and |:language|. Example:Change the format of |TIME| to only hours and minutes:SetFormat ( "TIME", "%H:%M" )The macro |TIME| will now be replaced by something like 10:24. Change the locale to Spanish:SetFormat ( "TIME_LOCALE", "es_ES" )The names of the days, month, ... will now be in Spanish.
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-SetMap()Set the map of the template 'name' to 'map':SetMap ( name, map )This changes the map of the template named 'name'. The map has to follow the rules as the "map:<map>" option (see |template-support-map|). The name of the template appears in the template definition between the first pair of == , the menu is part of the name, also whitespaces contained within the name. Example:Consider this template definition:== Include.global include == below, map:igi ==^ ^|Then you can set a different map using:----- the name -----|SetMap ( "Include.global include", "igl" )
template-support-SetMenuEntry() Set the menu entry of the template 'name' to 'entry':SetMenuEntry ( name, entry )This changes the menu entry of the template to 'entry'. By default the name itself is used as the menu entry. The name of the template appears in the template definition between the first pair of == , the menu is part of the name, also whitespaces contained within the name. Example:Consider this template definition:== Include.global include == below, sc:g ==^ ^|Then you can set a different menu entry using:----- the name -----|SetMenuEntry ( "Include.global include", "#include<>" )
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-SetShortcut() Set the shortcut of the template 'name' to 'sc':SetShortcut ( name, sc )This changes the shortcut of the template named 'name'. The shortcut has to follow the rules as the "shortcut:<sc>" option (see |template-support-sc|). The name of the template appears in the template definition between the first pair of == , the menu is part of the name, also whitespaces contained within the name. Example:Consider this template definition:== Include.global include == below, sc:g ==^ ^|Then you can set a different shortcut using:----- the name -----|SetShortcut ( "Include.global include", "l" )
template-support-SetStyle()
Set the active style to 'name':
SetStyle ( name )
This style will be used after the library has been loaded.
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/QPushButtonthe 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| : for dictionaries: the selected key, for lists: same as |VALUE| - |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 | (The position of the cursor is marked by "|". The jump key can be used to jump ahead and replace the tags.{+DEST+},{+SRC+})
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-nomenu template-support-expandmenu
template-support-sc template-support-expandleft
template-support-shortcut template-support-expandright
template-support-map
Menus and Maps:
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.
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.
Submenus for templates using lists (|template-support-PickList()|):
expandmenu - A submenu is created with entries matching those of the
list used in the templates.
expandmenu:<list> - A submenu is created with entries matching those of the
list <list>. (interface 1.0+)
expandleft:<what> - When creating the submenu, use the element <what> for
the left-aligned side of the menu entry. (^1)
(interface 1.0+)
expandright:<what> - When creating the submenu, use the element <what> for
the right-aligned side of the menu entry. (^1)
(interface 1.0+)
(^1) valid values for <what> are (see |template-support-lists-menu|):
key, key-notags, key-whitetags, value, value-notags, value-whitetags
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 1.0
** Added a system for introducing changes to the template library. ** ** By default, all template libraries will be limited to the features ** ** introduced prior to 1.0 . ** ** Calling InterfaceVersion() will enable newer features. ** - Add: 'InterfaceVersion' to enable newer features in the template library. (This feature is considered to be part of the old interface.) - Add: Templates can be associated with a filetype, and its maps only created for that filetype. - Add: Format specifiers for macros. - Add: New "replacement cursor" tags<RCURSOR>and{RCURSOR}. - Add: New date and time macros |DATE_PRETTY| , |TIME_PRETTY| , ... - Add: Left-right separators |<<>>| . - Add: New jump tags [+NAME+] and [-NAME-] for optional parameters. - Add: New map<ctrl-d>to delete optional jump tags [+NAME+] and [-NAME-]. - Change: Insert a breakpoint into the undo sequence before inserting templates or jumping via<ctrl+j>. - Add: Template options "expandleft" and "expandright". Extended the option "expandmenu". - Add: Functions 'SetMap', 'SetShortcut', 'SetMenuEntry', and 'SetExpansion'. - Change: If a template is redefined, the options are read again. - Change: During the creation of the submenu for a list-picking template, all special characters are escaped correctly. (The characters "\" and "|" were not escaped before.) - Change: Inserting templates in visual mode does not overwrite the unnamed register anymore. - Fix: Map creation could fail after reloading the template library. - Add: User setting |g:Templates_OverwriteWarning| to configure warnings in case a template is overwritten. - Add: User setting |g:Templates_TemplateBrowser| to configure the browser used for editing templates. - Add: User settings |g:Templates_PersonalizationFile| and |g:Templates_UsePersonalizationFile| to configure the personalization file. - Add: Help templates can call a browser using |Browser( <url> )|. - Add: User settings |g:Templates_InternetBrowserExec| and |g:Templates_InternetBrowserFlags| to configure the browser used by help templates. - Add: Proper filetype detection for template files, filetype plug-in. - Add: Setup wizard. - Extend the documentation. API: - Change: Template files can be associated with a symbolic name and a map, which are used for the creation of the "edit templates" menu entries and maps. - Change: Template files can be optional. Information such as their symbolic name is kept. They still show up in debug information, ... They can be enabled later on, e.g. by the template setup wizard. - Add: Extended the API with functionality for adding a personalization file which can be used by all libraries. - Add: Function |mmtemplates#core#EnableTemplateFile()|. - Add: Function |mmtemplates#core#FindPersonalizationFile()|. - Add: Function |mmtemplates#core#AddCustomTemplateFiles()|. - Change: New options for the function |mmtemplates#core#ReadTemplates()| and |mmtemplates#core#Resource()|. Internal Changes: - Major internal changes and code cleanup.
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.
D.1 INTERFACE VERSIONS template-support-change-interf
This section lists the changes to the template interface. By default, the interface "0.9" is used. Newer features can be enabled using the function InterfaceVersion (|template-support-InterfaceVersion()|). See also |template-support-lib-interf|.
INTERFACE VERSION 1.0
- Add: Templates can be associated with a filetype, and its maps only created for that filetype, using:== USE FILETYPES : ... ==- Add: New jump tags [+NAME+] and [-NAME-] for optional parameters. Can be used as targets for jumps. - Add: New map<ctrl-d>to delete optional jump tags [+NAME+] and [-NAME-] together with their separator ",". - Add: Template options "expandleft" and "expandright". Extended the option "expandmenu". - Change: During the creation of the submenu for a list-picking template, all special characters are escaped correctly. (The characters "\" and "|" were not escaped before.) - Add: Help templates can call a browser using |Browser( <url> )|.
INTERFACE VERSION 0.9
- Initial version of the interface with all changes introduced prior to version "1.0".
D.2 API VERSIONS template-support-change-api
The API version governs the behavior of the API, and is used to enable features which are not backwards compatible. The API version is set when calling |mmtemplates#core#NewLibrary()|. This only concerns plug-in developers.
API VERSION 1.0
- When calling |mmtemplates#core#CreateMenus()|, the menu names supplied with the options "existing_menus", "sub_menu", and "specials_menu" must now be correctly escaped for menu creation.
API VERSION 0.9
- Initial version of the API with all changes introduced prior to version "1.0".
E. CREDITS template-support-credits
Fritz Mehner (vim.org user name: mehner): - his plug-ins (bash-support, c-support, perl-support, ...) provided the inspiration for the template engine Jeremy Cantrell (jmcantrell): - the solution for getting the visual area is take from his plug-in "opener.vim", which is distributed under the same licence as Vim itself ( http://www.vim.org/scripts/script.php?script_id=3543 ) Andrew L: - suggested to insert a breakpoint into the undo sequence before inserting templates and provided the outline for the solution
vim:tw=78:noet:ts=2:ft=help:norl:expandtab:
Generated by vim2html (modified) on So 7. Aug 16:09:57 CEST 2016