*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: