neosnippet.vim/doc/neocomplcache-snippets-complete.txt

*neocomplcache-snippets-complete-snippets-complete.txt*
				neocomplcache complete snippets source

Version: 2.0
Author : Shougo <Shougo.Matsu@gmail.com>
License: MIT license  {{{
    Permission is hereby granted, free of charge, to any person obtaining
    a copy of this software and associated documentation files (the
    "Software"), to deal in the Software without restriction, including
    without limitation the rights to use, copy, modify, merge, publish,
    distribute, sublicense, and/or sell copies of the Software, and to
    permit persons to whom the Software is furnished to do so, subject to
    the following conditions:
    The above copyright notice and this permission notice shall be included
    in all copies or substantial portions of the Software.

    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
    OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
    IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
    TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
    SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}}}

CONTENTS					*neocomplcache-snippets-complete-contents*

Introduction		|neocomplcache-snippets-complete-introduction|
Install			|neocomplcache-snippets-complete-install|
Interface		|neocomplcache-snippets-complete-interface|
  Commands		  |neocomplcache-snippets-complete-commands|
  Variables		  |neocomplcache-snippets-complete-variables|
  Key mappings		  |neocomplcache-snippets-complete-key-mappings|
Examples		|neocomplcache-snippets-complete-examples|
Snippet syntax		|neocomplcache-snippets-complete-snippet-syntax|
Changelog		|neocomplcache-snippets-complete-changelog|

==============================================================================
INTRODUCTION					*neocomplcache-snippets-complete-introduction*

This source analyzes snippet files for completion, offers functionality
similar to snipMate.vim or snippetsEmu.vim.  Since you can choose snippet with
neocomplcache interface, you might have less trouble learning it.

==============================================================================
INSTALL						*neocomplcache-snippets-complete-install*

1: Install neocomplcache (https://github.com/Shougo/neocomplcache).
2: Extract the file and put files in your Vim directory
   (usually ~/.vim/ or Program Files/Vim/vimfiles on Windows).

==============================================================================
INTERFACE					*neocomplcache-snippets-complete-interface*

------------------------------------------------------------------------------
COMMANDS 					*neocomplcache-snippets-complete-commands*

:NeoComplCacheCachingSnippets [filetype]	*:NeoComplCacheCachingSnippets*
		Caching [filetype] snippets.
		Select current buffer's filetype when [filetype] was omitted.

:NeoComplCacheEditSnippets [filetype]		*:NeoComplCacheEditSnippets*
		Edit [filetype] snippets.
		Select current buffer's filetype when [filetype] was omitted.

		If [filetype] snippet file doesn't exist, create it
		automatically.

		This command edits a snippet file in
		|g:neocomplcache_snippets_dir| with precedence.  
		Re-cache will be automatically done when you save the file.

:NeoComplCacheEditRuntimeSnippets [filetype]	*:NeoComplCacheEditRuntimeSnippets*
		Edit [filetype] snippets.
		Select current buffer's filetype when [filetype] was omitted.

		If [filetype] snippet file doesn't exist, create it
		automatically.

		This command edits a runtime snippet file with
		snippets_complete.
		Re-cache will be automatically done when you save the file.

------------------------------------------------------------------------------
VARIABLES 					*neocomplcache-snippets-complete-variables*

g:neocomplcache_snippets_dir			*g:neocomplcache_snippets_dir*
		This variable appoints a path to user-defined snippet files.
		You can set multiple values in comma-serparted form.
		If the directory doesn't exist, it is ignored.

		User defined snippets were read after normal snippet files,
		redundant snippets will be overwritten.

		This variable doesn't exist unless you declare it.

g:neocomplcache_disable_select_mode_mappings	*g:neocomplcache_disable_select_mode_mappings*
		This variable controls whether to disable Key-mappings in
		|Select-mode| when snippets_complete performs.  Usually you
		had better enable it.

		Default value is 1.

g:neocomplcache_snippets_disable_runtime_snippets
						*g:neocomplcache_snippets_disable_runtime_snippets*
		If this variable is 1, runtime snippets isn't loaded.
		This variable is useful to avoid conflicting snippets.

		Default value is 0.

------------------------------------------------------------------------------
KEY MAPPINGS 					*neocomplcache-snippets-complete-key-mappings*

<Plug>(neocomplcache_snippets_expand)		*<Plug>(neocomplcache_snippets_expand)*
		Expand a cursor snippet of plural lines. When there is not a
		snippet, jump to next placeholder.

		Note: cursor snippet must be match keyword patterns.
		For example if snippet name is ".", snippets_complete don't expand it.
		If you expand snippet ".",  Please use
		|<Plug>(neocomplcache_snippets_force_expand)|.

<Plug>(neocomplcache_snippets_jump)		*<Plug>(neocomplcache_snippets_jump)*
		Jump to next placeholder. If there is no placeholder, expand a
		multiline cursor snippet.

<Plug>(neocomplcache_snippets_force_expand)	*<Plug>(neocomplcache_snippets_force_expand)*
		Expand a cursor snippet. Does nothing if there is no snippet.

<Plug>(neocomplcache_snippets_force_jump)	*<Plug>(neocomplcache_snippets_force_jump)*
		Jump to next place holder. Do not expand any snippet. When
		you do not want to expand a snippet name, use this keymapping.

<Plug>(neocomplcache_start_unite_snippet)	*<Plug>(neocomplcache_start_unite_snippet)*
		Start unite snippet source.
		Note: This mappings is available in insert mode.

neocomplcache#sources#snippets_complete#expandable()
						*neocomplcache#sources#snippets_complete#expandable()*
		Use this function with imap <expr>. It checks whether cursor
		text is snippets trigger or existing placeholder in current
		buffer. Useful for saving keymappings.
		Return value is
		0 : not found
		1 : cursor text is snippets trigger
		2 : existing placeholder in current buffer
		3 : both found.
>
		imap <expr><C-l> neocomplcache#sources#snippets_complete#expandable() ?
		\ "\<Plug>(neocomplcache_snippets_expand)" : "\<C-n>"
<
neocomplcache#sources#snippets_complete#force_expandable()
						*neocomplcache#sources#snippets_complete#force_expandable()*
		Use this function with imap <expr>. It checks whether cursor
		text is snippets trigger. Useful for saving keymappings.

neocomplcache#sources#snippets_complete#jumpable()
						*neocomplcache#sources#snippets_complete#jumpable()*
		Use this function with imap <expr>. It checks whether cursor
		text is an existing placeholder in current buffer.
		Useful for saving keymappings.

==============================================================================
EXAMPLES					*neocomplcache-snippets-complete-examples*
>
	" Plugin key-mappings.
	imap <C-k>     <Plug>(neocomplcache_snippets_expand)
	smap <C-k>     <Plug>(neocomplcache_snippets_expand)

	" SuperTab like snippets behavior.
	"imap <expr><TAB> neocomplcache#sources#snippets_complete#expandable() ?
	" \ "\<Plug>(neocomplcache_snippets_expand)" : pumvisible() ? "\<C-n>" : "\<TAB>"

	" For snippet_complete marker.
	if has('conceal')
	  set conceallevel=2 concealcursor=i
	endif
<
==============================================================================
SNIPPET SYNTAX					*neocomplcache-snippets-complete-snippet-syntax*

neocomplcache has built-in snippet feature. The snippet syntax resembles
|snipMate|.

Example:
>
	snippet     if
	abbr        if endif
	prev_word   '^'
	    if $<1:condition>
	        ${2}
	    endif
<
snippet {snippet_name} syntax is the snippet name.
abbr {abbr_name} is the completion abbrevation (same to completion "abbr" key).
prev_word '^' means this snippet is enabled only in line head.

By the way, it is warned that the snippet name was already defined by other
snippet file.  If you want to overwrite it explicitly, please use:
>
	delete snippets_name
<
and redefine the snippet.

When including external files or other snippet file's snippets are overwrited,
you will not be warned.

Snippet include feature is available.
>
	include c.snip
<
Eval snippet feature is available.
>
	snippet     hoge
	prev_word   '^'
	    `expand("%")`
<
If you use |:NeoComplCacheEditSnippets| command for easy snippet editing, the
file will be loaded automatically when you save the file.

Neocomplcache doesn't map snippet-expand key by default. If you want to use
snippet feature, you can define below mappings in your .vimrc:
>
	imap <C-l>    <Plug>(neocomplcache_snippets_expand)
	smap <C-l>    <Plug>(neocomplcache_snippets_expand)
<

Placeholder feature is available.
>
	snippet     if
	abbr        if endif
	prev_word   '^'
	    if ${1:condition}
	        ${2}
	    endif
<
'_' snippet feature is supported. '_' snippet is loaded in all filetypes.
And neocomplcache can load snipMate snippets.

Alias feature is supported. Separator is ' ' or ','.
>
	alias hoge hogera hogehoge
<
Synchronized placeholder feature is supported.  $1 is synchronized to ${1}.
When you jump next, it is synchlonized. $0 is last jump placeholder.

The placeholder value can't contain new lines. Below snippet is illegal:
>
	snippet test
		${1:constructor: (${2:args\}) ->
			${3:# do smth}}
<
Multi snippet feature is supported in snipMate.
neocomplcache substitutes trigger and descriptions spaces to '_'.
>
	snippet trigger description1
		hoge
	snippet trigger description2
		piyo
<
You choose snippet <C-n> or <C-p> and expand it with
|<Plug>(neocomplcache_snippets_expand)| key-mappings.

Nested placeholder feature is supported.
But must escape inner '}'. '\' is eacape sequence.
>
	snippet div
	<div ${1:id="${2:someid\}"}>${3}</div>${4}
<

If you use hard tab for indentation in snippet file, neocomplcache will use
'shiftwidth' instead of original Vim indent function. This feature is useful
while some languages' indent files can not work very well (e.g.: PHP).
>
	snippet if
		if (${1:/* condition */}) {
			${2:// code...}
		}
<
==============================================================================
UNITE SOURCES					*neocomplcache-snippets-complete-unite-sources*

						*neocomplcache-snippets-complete-unite-source-snippet*
snippet
		The candidates are neocomplcache snippets. The kinds are "snippet".
		Normally used in |<Plug>(neocomplcache_start_unite_snippet)| mappings.
		But you can execute it by ":Unite snippet".
		You can edit snippet file in "edit" action.
		Examples:
>
		imap <C-s>  <Plug>(neocomplcache_start_unite_snippet)
<
source actions

snippet						*neocomplcache-snippets-complete-unite-action-snippet*
	expand		Expand snippet (default action)
	edit		Edit snippet
	preview		View snippet definition

==============================================================================
CHANGELOG					*neocomplcache-snippets-complete-changelog*

2012-04-05
- Fixed nested placeholder problem.

2012-03-23
- Fixed substitute pattern bug.

2012-03-19
- Fixed substitute marker.

2012-03-18
- Fixed for expandtab.

2012-03-17
- Fixed for echodoc.

2012-03-16
- Fixed snippets indentation.

2012-03-15
- Improved search snippet markers behavior.
- Don't conceal default codes.

2012-03-14
- Refactored expand snippet behavior.
- Fixed expand bug.
- Refactored substitute patterns.
- Changed marker patterns.

2012-03-08
- Use shiftwidth instead of softabstop.
- Fixed plugin indentation problem.

2012-03-07
- Added snippet source.
- Fixed snippet source behavior.
- Improved snippet source.

2012-03-06
- Improved ftplugin.

2012-03-03
- Added neocomplcache#sources#snippets_complete#force_expandable() and
  neocomplcache#sources#snippets_complete#jumpable().

2012-02-25
- Improved split().

2012-02-24
- Improved a bit.

2012-02-22
- Fixed prev_word behavior.

2012-02-21
- Improved documentation.

2012-02-05
- Fixed variable name.

2012-02-02
- Initial version.
- Improved documentation.

==============================================================================
vim:tw=78:ts=8:ft=help:norl:noet:fen:fdl=0:noet: