629 lines
18 KiB
Text
629 lines
18 KiB
Text
*XPTemplate* For Vim version 7.2. Last change: 2009 Nov 08
|
|
*xptemplate*
|
|
*xpt*
|
|
|
|
|
|
XP's Snippet Template engine
|
|
by drdr.xp
|
|
drdr.xp@gmail.com
|
|
|
|
XPTemplate is a snippet rendering engine.
|
|
|
|
|xpt-install|
|
|
|xpt-usage|
|
|
|xpt-personal-var|
|
|
|
|
|xpt-feature|
|
|
|xpt-option|
|
|
|xpt-key-bind|
|
|
|xpt-tips|
|
|
|xpt-with-supertab|
|
|
|
|
|xpt-customize|
|
|
|xpt-write-snippet|
|
|
|
|
|xpt-snippet-syntax|
|
|
|xpt-snippet-tutorial|
|
|
|xpt-api|
|
|
|
|
*xpt-install*
|
|
Copy files and directories into one of your 'runtimepath's.
|
|
|
|
*xpt-usage*
|
|
To see what snippets have been defined for the current filetype, press
|
|
<C-r><C-r><C-\> in insert mode. See |xpt-key-pum|.
|
|
|
|
In insert mode type the snippet name and press <C-\> to insert a
|
|
snippet. Use <Tab> to navigate through the snippet template.
|
|
For example when editing a C file: >
|
|
for<C-\>
|
|
< generates: >
|
|
for ( i = 0; i < len; ++i ) {
|
|
/* cursor */
|
|
}
|
|
< The first "i" being selected is the current item you are editing. "0"
|
|
is the next item and you can navigate to it by pressing <Tab>.
|
|
|
|
To change the snippet trigger (<C-\>) see |xpt-key-trigger|, to change
|
|
the navigate key (<Tab>) see |xpt-key-navigate|.
|
|
|
|
NOTE with some European keyboards <C-\> does NOT work. In this case
|
|
you need to specify another key to trigger snippets.
|
|
|
|
Now type "abc", this results in: >
|
|
////````````````````````````| edit area
|
|
////
|
|
//// ////`````````````````| lively updated
|
|
//// //// ////`````'
|
|
for ( abc = 0; abc < len; ++abc ) {
|
|
/* cursor */
|
|
}
|
|
< Now press <Tab>, the cursor jumps to "0", the next item: >
|
|
//```````````````````````| focus here
|
|
for ( abc = 0; abc < len; ++abc ) {
|
|
/* cursor */
|
|
}
|
|
< After pressing <Tab> twice the snippet ends up with cursor staying at
|
|
line 2, column 8 (or the value of 'softtabstop'): >
|
|
for ( abc = 0; abc < len; ++abc ) {
|
|
|
|
} \\___________________________| cursor stays here
|
|
|
|
< The usage is described in more detail below.
|
|
|
|
For more information regarding the syntax of snippets see
|
|
|xpt-snippet-syntax|. To customize settings see |xpt-option|.
|
|
|
|
|
|
*xpt-feature*
|
|
Live typing update
|
|
Navigate forward and backward |xpt-key-navigate|
|
|
Popup hint |xpt-popup|
|
|
|xpt-snippet-hint|
|
|
Ordered place holders |xpt-snippet-ComeFirst|
|
|
Embedded functions and variables |xpt-snippet-function|
|
|
Repeatable snippet generation |xpt-repetition|
|
|
Nested snippets |xpt-nested|
|
|
Wrapper snippets |xpt-wrapper-snippet|
|
|
Inclusion on snippet level or file level|xpt-snippet-include|
|
|
|xpt-snippet-XPTinclude|
|
|
|
|
Template priority |xpt-snippet-priority|
|
|
|
|
Named item or anonymous item |xpt-snippet-item|
|
|
Default value |xpt-snippet-default-value|
|
|
Preset value |xpt-snippet-preset-value|
|
|
Snippet Bundle/Library Support |xpt-bundle|
|
|
and more...
|
|
|
|
*xpt-name-matching*
|
|
See |xpt-snippet-name-matching-rule|.
|
|
|
|
*xpt-popup*
|
|
If you type nothing or an incomplete snippet key and press <C-\>, a
|
|
popup menu shows up listing all possible snippet keys. For example: >
|
|
fo<C-\>
|
|
< Shows: >
|
|
for
|
|
forever
|
|
fornn
|
|
forr
|
|
<
|
|
After selecting the item from the popup menu, press <C-\> again to
|
|
trigger the snippet.
|
|
|
|
*xpt-nested*
|
|
Templates can be expanded inside another template. There is no
|
|
difference between using a nested template or a top-level template.
|
|
For example, when you edit a C file type switch<C-\> to generate a
|
|
switch block template: >
|
|
switch (fn) {
|
|
case 0 :
|
|
<-------------- cursor stops here after two <Tab>s
|
|
break;
|
|
...
|
|
default:
|
|
|
|
}
|
|
< Now the cursor stops between "case 0 :" and "break;", type: >
|
|
if<C-\>
|
|
< It becomes: >
|
|
switch (fn) { | upper level snippet
|
|
case 0 : |
|
|
if () { . nested snippet
|
|
.
|
|
} .
|
|
break; | upper level snippet
|
|
... |
|
|
default: |
|
|
|
|
|
} |
|
|
< Type <Tab>, <Tab>.. to navigate out of the nested snippet: >
|
|
switch (fn) {
|
|
case 0 :
|
|
if () {
|
|
|
|
}
|
|
break;
|
|
|
|
default:
|
|
<--------------cursor stops here
|
|
}
|
|
< Now cursor stops after "default:" and we get out back to the "switch"
|
|
snippet.
|
|
|
|
==============================================================================
|
|
|
|
|
|
*`...^* *xpt-...* *xpt-repetition*
|
|
Some segments can be defined as repeatable, for example the "case"s in
|
|
"switch". Specifying the repetition part is easy, just wrap the part
|
|
you want it to repeat with `...n^. n is a number and can be omitted if
|
|
only one repetition part is used.
|
|
Take the case from "switch": >
|
|
XPT switch
|
|
switch (`^) {
|
|
`...^ | repetition part
|
|
case `^0^ : |
|
|
`^ |
|
|
break; |
|
|
`...^ |
|
|
|
|
default:
|
|
`^
|
|
}
|
|
<
|
|
When you trigger a repetition template it works as below: >
|
|
switch () { <------- cursor stays here
|
|
`...^
|
|
|
|
default:
|
|
`^
|
|
}
|
|
< Press <Tab>, the |`...^| is selected. Press <Tab> again to expand the
|
|
repetition part. Or press <Cr> |xpt-key-clear| to cancel the
|
|
repetition part. These 4 lines are expanded: >
|
|
switch () {
|
|
|
|
case `^ : | expanded
|
|
`^ |
|
|
break; |
|
|
`...^ |
|
|
|
|
default:
|
|
`^
|
|
}
|
|
< Enter the repetition part. You may have noticed there is another
|
|
|`...^|, that is the another repeat trigger.
|
|
|
|
Press <Tab> 3 times: >
|
|
switch () {
|
|
|
|
case 0 :
|
|
|
|
break;
|
|
|
|
case `^ : | selected repetition part
|
|
`^ |
|
|
break; |
|
|
`...^ |
|
|
|
|
default:
|
|
`^
|
|
}
|
|
<
|
|
See also |xpt-snippet-repetition|.
|
|
|
|
|
|
*xpt-wrapper-snippet*
|
|
Wrapper snippets can be triggered in visual mode, place holder marked
|
|
as "wrap" is replaced with the text selected in visual mode.
|
|
|
|
Definition of wrapper snippet has no differences from normal
|
|
snippet except it declaring a place holder as wrapping holder. For
|
|
example: >
|
|
________/---------------------| wrapper declaration
|
|
XPT if wrap=job
|
|
if (`condition^){
|
|
`job^
|
|
}
|
|
<
|
|
For example the following snippet: >
|
|
XPT call_ wrap=wrapped
|
|
`name^(`wrapped^`, `^)`cursor^
|
|
< Use command |V| to select some text and press <C-\>. The selected text
|
|
is yanked and popup menu shows.
|
|
|
|
For example we have one line of text as below: >
|
|
a, b
|
|
< Select this line with command |V|.
|
|
And then press <C-\>, choose "call_" in the popup menu.
|
|
And finally it results in : >
|
|
name(a, b)
|
|
<
|
|
NOTE Wrapper snippet declared with "wraponly" can only be triggered
|
|
in visual mode, not in insert mode
|
|
|
|
|
|
|
|
*xpt-context*
|
|
You can define snippets that can only be triggered in certain
|
|
circumstances, for example in certain syntax items. Defining context
|
|
depended snippets is done by adding another parameter to the
|
|
XPTemplate call "{'syn' : 'the context name'}" : >
|
|
XPT para syn=comment
|
|
@param {`Object^} `name^ `desc^
|
|
< Now the snippet "para" can be only triggered in syntax items named
|
|
"comment".
|
|
|
|
==============================================================================
|
|
|
|
*xpt-key-bind*
|
|
Options can be set in |.vimrc| to modify XPTemplate's behaviors.
|
|
|
|
Key mappings:
|
|
|<Plug>XPTrawKey|
|
|
|
|
|g:xptemplate_key|
|
|
|g:xptemplate_key_pum_only|
|
|
|g:xptemplate_key_force_pum|
|
|
|g:xptemplate_key_visual|
|
|
|g:xptemplate_nav_next|
|
|
|g:xptemplate_nav_prev|
|
|
|g:xptemplate_nav_cancel|
|
|
|g:xptemplate_goback|
|
|
|g:xptemplate_to_right|
|
|
|g:xptemplate_fallback|
|
|
|
|
See also: |xpt-option|.
|
|
|
|
*<Plug>XPTrawKey*
|
|
Key mapping defined as: >
|
|
exe "inoremap <silent> <Plug>XPTrawKey " g:xptemplate_key
|
|
<
|
|
|
|
*i_<C-\>* *v_<C-\>* *xpt-key-trigger* *g:xptemplate_key*
|
|
{default:<C-\>}
|
|
The key to trigger snippets in insert mode.
|
|
Use |g:xptemplate_key| to change this mapping. Example: >
|
|
let g:xptemplate_key = '<Tab>'
|
|
<
|
|
NOTE: You can set this key to <Tab>, as most users do, for
|
|
convenience. In this case pressing <Tab> twice results in a normal
|
|
<Tab> if there is no snippet key matched.
|
|
|
|
|
|
*i_<C-r><C-r><C-\>* *xpt-key-pum* *g:xptemplate_key_pum_only*
|
|
{default:<C-r><C-r>g:xptemplate_key}
|
|
Show pop up menu at cursor position. Example: >
|
|
let g:xptemplate_key_pum_only = '<S-Tab>'
|
|
< By default, this key map is set to '<C-r><C-r>' concatenated with
|
|
|g:xptemplate_key| : '<C-r><C-r><C-\>'.
|
|
|
|
|
|
*g:xptemplate_key_force_pum*
|
|
{default:<C-r>g:xptemplate_key}
|
|
Behave like that with |g:xptemplate_always_show_pum| set.
|
|
|
|
If more than one snippet starts with( or exactly equals to ) the text
|
|
before cursor, pop up menu shows.
|
|
|
|
This key triggers snippet only when there is only one snippet of name
|
|
starts with the text before cursor.
|
|
|
|
See also: |g:xptemplate_always_show_pum|.
|
|
|
|
|
|
*s_<C-\>* *xpt-key-visual* *g:xptemplate_visual
|
|
{default:g:xptemplate_key}
|
|
The key to trigger snippets in visual mode.
|
|
Use |g:xptemplate_key_visual| to change this mapping. Example: >
|
|
let g:xptemplate_key_visual = '<Tab>'
|
|
<
|
|
|
|
|
|
*i_<tab>* *s_<tab>* *xpt-key-navigate* *g:xptemplate_nav_next*
|
|
{default:<Tab>}
|
|
After a snippet was triggered, this key navigates to the next item.
|
|
Use |g:xptemplate_nav_next| to change this mapping. Example: >
|
|
let g:xptemplate_nav_next = '<C-j>'
|
|
<
|
|
|
|
*i_<S-tab>* *s_<S-tab>* *g:xptemplate_nav_prev*
|
|
{default:<S-Tab>}
|
|
After a snippet was triggered, press this key to navigate back to the
|
|
previous item.
|
|
Use |g:xptemplate_nav_prev| to change this mapping. Example: >
|
|
let g:xptemplate_nav_prev = '<C-k>'
|
|
<
|
|
*s_<CR>* *xpt-key-clear* *g:xptemplate_nav_cancel*
|
|
{default:<Cr>}
|
|
Press to clear current place holder and jump to next.
|
|
Use |g:xptemplate_nav_cancel| to change this mapping. Example: >
|
|
let g:xptemplate_nav_cancel = '<C-c>'
|
|
<
|
|
|
|
*s_<C-l>* *xpt-key-goto-right* *g:xptemplate_to_right*
|
|
{default:<C-l>}
|
|
When a place holder is initially selected jump to the end of current
|
|
place holder and go into insert mode.
|
|
|
|
Use |g:xptemplate_to_right| to change this mapping. Example: >
|
|
let g:xptemplate_to_right = '<C-;>'
|
|
<
|
|
*g:xptemplate_fallback*
|
|
{default:<Plug>XPTrawKey}
|
|
If a try to trigger snippet( by pressing |g:xptemplate_key| ) does not
|
|
produce any match( full or partial ), contents of this setting is
|
|
output instead.
|
|
|
|
NOTE: Contents output is similar to user typing. And they CAN be
|
|
remapped. This may produce a invoke loop.
|
|
|
|
The default value of this setting is the literal text of
|
|
|g:xptemplate_key|, which is defined by |<Plug>XPTrawKey|.
|
|
|
|
For example, if you want a completion-popup menu to show when no snippet
|
|
matched, you can have this line added into your |.vimrc|: >
|
|
let g:xptemplate_fallback = '<C-n>'
|
|
<
|
|
|
|
|
|
*n_<C-g>* *i_<C-g>* *xpt-key-goback* *g:xptemplate_goback*
|
|
{default:<C-g>}
|
|
When you move the cursor outside of place holder you are editing,
|
|
pressing this key (in insert mode or normal mode) moves cursor back to
|
|
current place holder and selects the place holder text in select mode.
|
|
|
|
Use |g:xptemplate_goback| to change this mapping. Example: >
|
|
let g:xptemplate_goback = '<C-g>'
|
|
<
|
|
|
|
*xpt-customize-highlight*
|
|
You can specify which highlight Group to use for each kind of
|
|
highlight.
|
|
|
|
|
|
*XPTcurrentPH*
|
|
{default:DiffChange}
|
|
The highlight group of place holder you are editing. Example: >
|
|
highlight link XPTcurrentPH Visual
|
|
< This statement tells XPTemplate to use the highlight group "Visual" to
|
|
highlight "current" items. See |g:xptemplate_highlight|.
|
|
|
|
You can also define your highlight group directly. Example: >
|
|
highlight XPTcurrentPH gui=none guibg=blue
|
|
<
|
|
*XPTfollowingPH*
|
|
{default:CursorLine}
|
|
The highlight group of slave place holders you are editing. Like
|
|
|XPTcurrentPH|.
|
|
|
|
|
|
*XPTnextItem*
|
|
{default:IncSearch}
|
|
The highlight group of item you are going to edit. Like
|
|
|XPTcurrentPH|.
|
|
|
|
|
|
*xpt-bundle*
|
|
A bundle is a collection of snippets for a certain purpose. For
|
|
example a library support bundle like
|
|
"ftplugin/javascript/jquery.xpt.vim".
|
|
XPTemplate supplies two ways to load bundles: |g:xptemplate_bundle|
|
|
and |g:XPTaddBundle()|.
|
|
|
|
|
|
==============================================================================
|
|
|
|
*xpt-tips*
|
|
Want to use XPTemplate with ... together?
|
|
|xpt-with-supertab|
|
|
|
|
|
|
*xpt-with-supertab*
|
|
If you want to use supertab's <TAB> but you have also set XPT to use
|
|
<TAB>.
|
|
|
|
==============================================================================
|
|
|
|
*xpt-customize*
|
|
|
|
Global customization can be done with |xpt-option|.
|
|
|
|
Two options relate to personal settings:
|
|
|
|
|g:xptemplate_vars|
|
|
This is a easy way to set up your personal information like your name
|
|
and email address.
|
|
This option actually sets up two variables "$author" and "$email". See
|
|
|xpt-snippet-variable|
|
|
|
|
|g:xptemplate_bundle|
|
|
This option sets up which library you want to load.
|
|
|
|
|
|
*xpt-customize-variable*
|
|
|xpt-snippet-variable| are used to configure the snippet format.
|
|
|
|
Customization variables should be defined in a snippet file( like a
|
|
file in |xpt-personal-folder|) with "personal" priority, to guarantee
|
|
it will not be overrided by other snippet with lower priority. See
|
|
|xpt-priority-value|.
|
|
|
|
To create a snippet file to define your variables, see
|
|
|xpt-write-lang-snippet|.
|
|
|
|
|
|
See also: |xpt-customize-variable-format|
|
|
|xpt-customize-variable-space|
|
|
|xpt-customize-variable-datetime|
|
|
|
|
|
|
*xpt-customize-variable-format*
|
|
Each snippet has some variable defined to configure language format.
|
|
This is useful when some snippet are shared between languages, like
|
|
for loops in C and CPP or to accommodate different user preferences.
|
|
|
|
Brackets style variables may be defined as below: >
|
|
" if () ** {
|
|
" else ** {
|
|
XPTvar $BRif ' '
|
|
|
|
" } ** else {
|
|
XPTvar $BRel \n
|
|
|
|
" for () ** {
|
|
" while () ** {
|
|
" do ** {
|
|
XPTvar $BRloop ' '
|
|
|
|
" struct name ** {
|
|
XPTvar $BRstc ' '
|
|
|
|
" int fun() ** {
|
|
" class name ** {
|
|
XPTvar $BRfun ' '
|
|
|
|
< The "**" in comment marks where this variable should be used.
|
|
For example following is "for" snippet for both C and CPP: >
|
|
XPT for hint=for\ (..;..;++)
|
|
for (`i^ = `0^; `i^ < `len^; ++`i^)`$BRloop^{
|
|
`cursor^ ******************
|
|
}
|
|
< In C language "$BRloop" is set to ' '. In CPP "$BRloop" is set to
|
|
"\n". You can find them in "ftplugin/c/c.xpt.vim" and
|
|
"ftplugin/cpp/cpp.xpt.vim".
|
|
|
|
In C this snippet results in: >
|
|
for ( i = 0; i < 10; ++i ) {
|
|
|
|
}
|
|
< In CPP this snippet results in: >
|
|
for ( i = 0; i < 10; ++i )
|
|
{
|
|
|
|
}
|
|
<
|
|
|
|
*xpt-customize-variable-space*
|
|
Another set of variables is defined to customize spaces. They are: >
|
|
" int fun ** (
|
|
" class name ** (
|
|
XPTvar $SPfun ''
|
|
|
|
" int fun( ** arg ** )
|
|
" if ( ** condition ** )
|
|
" for ( ** statement ** )
|
|
" [ ** a, b ** ]
|
|
" { ** 'k' : 'v' ** }
|
|
XPTvar $SParg ' '
|
|
|
|
" if ** (
|
|
" while ** (
|
|
" for ** (
|
|
XPTvar $SPcmd ' '
|
|
|
|
" a = a ** + ** 1
|
|
" (a, ** b, ** )
|
|
" a ** = ** b
|
|
XPTvar $SPop ' '
|
|
|
|
< For example function snippet defined as below: >
|
|
XPT fun
|
|
int fun(`$SParg^`args^`$SParg^)
|
|
< If "$SParg" is set to ' ', snippet results in: >
|
|
int fun( args )
|
|
< If "$SParg" is set to '', snippet results in: >
|
|
int fun(args)
|
|
<
|
|
|
|
*xpt-customize-variable-datetime*
|
|
Variables discussed in this section defines how "date" and "time"
|
|
snippet displayed.
|
|
|
|
"$DATE_FMT" defines "date" snippet format. Default format is: >
|
|
XPTvar $DATE_FMT '%Y %b %d'
|
|
<
|
|
"$TIME_FMT" defines "time snippet format. Default format is: >
|
|
XPTvar $TIME_FMT '"%H:%M:%S"'
|
|
<
|
|
"$DATETIME_FMT" defines "datetime()" function format. Default format is: >
|
|
XPTvar $DATETIME_FMT '%c'
|
|
<
|
|
"datetime()" has no default snippet using it.
|
|
|
|
|
|
|
|
|
|
|
|
*xpt-personal-folder* *xpt-write-snippet*
|
|
Snippet file is actually |ftplugin| and with file extension
|
|
".xpt.vim", like "c.xpt.vim". So you can manage snippet files just
|
|
like the way you manage |ftplugin|.
|
|
|
|
You have THREE place to put your own snippets:
|
|
|
|
Path_to_xpt/personal
|
|
Recommended. Enough for most users. What you need to do is
|
|
putting snippet files into this folder.
|
|
|
|
Folders in |g:xptemplate_snippet_folders|
|
|
Deprecated, use 'runtimepath'.
|
|
|
|
Other 'runtimepath'
|
|
Need to manage 'runtimepath' yourself.
|
|
|
|
Details are discussed in following section.
|
|
|
|
|
|
*xpt-write-lang-snippet*
|
|
You can add snippets of new language, or add snippets to currently
|
|
supplied languages, in the same way.
|
|
|
|
Create a new file in some |ftplugin| directory. For example, if you want
|
|
to add some PHP snippet, you can create file: >
|
|
path_to_xpt/personal/ftplugin/php/your_snippets.xpt.vim
|
|
< Or: >
|
|
&runtimepath/ftplugin/php/your_snippets.xpt.vim
|
|
< &runtimepath can be ~/.vim in Unix like system, or ~/vimfiles/ folder
|
|
in Windows. See 'runtimepath'.
|
|
|
|
NOTE It is strongly recommended to add your own snippets in
|
|
"path_to_xpt/personal".
|
|
|
|
The file name "your_snippets.xpt.vim" has no limitation except it must
|
|
end with ".xpt.vim".
|
|
|
|
And then write your snippets in that file. Restart Vim to load them.
|
|
See |xpt-snippet-syntax| and |xpt-snippet-tutorial|.
|
|
|
|
|
|
*xpt-write-common-snippet*
|
|
If you want to add some snippets which don't belong to any language,
|
|
or you want to set multiple variables, you can use the "personal
|
|
common" snippet file.
|
|
|
|
1. Rename "personal/ftplugin/_common/personal_example.xpt.vim" to
|
|
"personal/ftplugin/_common/personal.xpt.vim". Or create one from
|
|
scratch.
|
|
|
|
2. Add your snippets into the "personal.xpt.vim".
|
|
|
|
"personal.xpt.vim" is loaded by _common/common.xpt.vim and has the
|
|
highest priority. Thus it's always loaded and there are no other
|
|
snippets overriding yours.
|
|
|
|
Example personal/ftplugin/_common/personal.xpt.vim : >
|
|
XPTemplate priority=personal
|
|
|
|
XPTvar $author your_name
|
|
XPTvar $email your_email
|
|
|
|
XPT yoursnippet " tips here
|
|
bla bla
|
|
|
|
< See |xpt-snippet-syntax| and |xpt-snippet-tutorial|.
|
|
|
|
==============================================================================
|
|
" vim:tw=78:ts=8:sw=8:sts=8:noet:ft=help:norl:
|