neosnippet.vim/doc/neosnippet.txt

*neosnippet.txt*
		The neo-snippet plugin contains the neocomplcache snippet source

Version: 3.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			*neosnippet-contents*

Introduction		|neosnippet-introduction|
Install			|neosnippet-install|
Interface		|neosnippet-interface|
  Commands		  |neosnippet-commands|
  Variables		  |neosnippet-variables|
  Key mappings		  |neosnippet-key-mappings|
  Functions		  |neosnippet-functions|
Examples		|neosnippet-examples|
Snippet syntax		|neosnippet-snippet-syntax|
FAQ			|neosnippet-faq|
Changelog		|neosnippet-changelog|

==============================================================================
INTRODUCTION					*neosnippet-introduction*

This plugin analyzes snippet files which you can use for completion. It offers
functionality similar to snipMate.vim or snippetsEmu.vim. Since you can choose
snippets with the neocomplcache interface, you might have less trouble using
them, because you do not have to remember each snippet name.

==============================================================================
INSTALL						*neosnippet-install*

1: Extract the file and put files in your Vim directory
   (usually ~/.vim/ or Program Files/Vim/vimfiles on Windows).

Note: If you want to complete snippets, you must install neocomplcache
(https://github.com/Shougo/neocomplcache).

==============================================================================
INTERFACE					*neosnippet-interface*

------------------------------------------------------------------------------
COMMANDS 					*neosnippet-commands*

:NeoSnippetMakeCache [filetype]
						*:NeoSnippetMakeCache*

	        Creates a cache for the given [filetype] snippets. It automatically 
	        choses the current buffer's file type unless you specify one by
		[filetype].

					*:NeoComplCacheCachingSnippets*
		Note: |:NeoComplCacheCachingSnippets| is an obsolete name.

:NeoSnippetEdit [{options}] [filetype]
					*:NeoSnippetEdit*
		Opens the [filetype] snippets to edit. It automatically selects
		the current buffer's filetype unless you specify another one by [filetype].
		
		If the path to [filetype] snippets is a directory, it automatically selects 
		the "[filetype].snip" in the [filetype] subdirectory.

		It edits a snippet file in |g:neosnippet#snippets_directory|
		with precedence. The snippets are re-cached automatically 
		when you save the file after edit.

					*:NeoComplCacheEditSnippets*
		The following parameters can be used as {options} to modify the behavior of 
		the command. Note: You must escape spaces with a backslash "\".

					*neosnippet-edit-options-vertical*
		-vertical
		Split the window vertically.

					*neosnippet-edit-options-horizontal*
		-horizontal
		Split the window horizontally.
		
		Note: The behavior is undefined when both options are set.

					*neosnippet-edit-options-direction*
		-direction={direction}
		Define the split position rule. The default value is "belowleft".

					*neosnippet-edit-options-split*
		-split
		Split the buffer.

					*neosnippet-edit-options-runtime*
		-runtime
		Edit the runtime (built-in standard) snippets instead of the user 
		snippets defined by 'g:neosnippet#snippets_directory'.

		Note: |:NeoComplCacheEditSnippets| is an obsolete name.

:NeoComplCacheEdit -runtime [filetype]

		Opens the [filetype] standard snippets to edit. It automatically 
		selects the current buffer's file type snippets unless you specify 
		a file type by [filetype]. The snippets are re-cached automatically 
		when you save the file after edit.

					*:NeoComplCacheEditRuntimeSnippets*
		Note: |:NeoComplCacheEditRuntimeSnippets| is an obsolete name.

------------------------------------------------------------------------------
VARIABLES 					*neosnippet-variables*

g:neosnippet#snippets_directory		*g:neosnippet#snippets_directory*
		This variable appoints a path to user-defined snippet files.
		You can set multiple values in comma-separated form. Non existing 
		directories are ignored.

		User defined snippet files are read after the built-in snippet files.
		If redundant snippets occur they get overwritten and only the last 
		one remains.
		
		Note: The neosnippet plug-in loads file type snippets from several 
		files if available. For example if you edit a "Vim" file then it loads the 
		snippets from:

		- "vim.snip*"
		- "vim_*.snip*" 
	        - "vim/**/*.snip" 

						*g:neocomplcache_snippets_dir*
		Note: |g:neocomplcache_snippets_dir| is an obsolete name.

		This variable doesn't exist unless you declare it.

g:neosnippet#disable_select_mode_mappings
				*g:neosnippet#disable_select_mode_mappings*
		This variable disables key-mappings in |Select-mode| where the 
		snippets_complete performs the snippet completion. Usually it
		it better to leave it as it is. But if you have troubles with 
		the buffer switcher LustyJuggler you can switch them of.
		
				*g:neocomplcache_disable_select_mode_mappings*
		Note: |g:neocomplcache_disable_select_mode_mappings| is an
		obsolete name.

		The default value is 1.

g:neosnippet#disable_runtime_snippets
				*g:neosnippet#disable_runtime_snippets*
		This is a dictionary variable which uses file types as key.
		If you set the value of a file type entry to 1, this prevents 
		loading all the file type specific built-in snippets. This is 
		very useful to to prevent snippet conflicts between self defined 
		snippet files and the built-in snippet files of neosnippet. 
		If you use a "_" as key for an entry this will treat the value of 
		the entry as default value for all file types.

		Note: This dictionary must be set in your .vimrc.

		For example:
>
		let g:neosnippet#disable_runtime_snippets = {
		\   'c' : 1, 'cpp' : 1,
		\ }
		
		" Works like g:neocomplcache_snippets_disable_runtime_snippets
		" which disables all runtime snippets
		let g:neosnippet#disable_runtime_snippets = {
		\   '_' : 1,
		\ }
<
			*g:neocomplcache_snippets_disable_runtime_snippets*
		Note: |g:neocomplcache_snippets_disable_runtime_snippets| is
		an obsolete name.

		The default value is {}.

------------------------------------------------------------------------------
KEY MAPPINGS 					*neosnippet-key-mappings*

<Plug>(neosnippet_expand_or_jump)
					*<Plug>(neosnippet_expand_or_jump)*
s_<Plug>(neosnippet_expand_or_jump)
					*s_<Plug>(neosnippet_expand_or_jump)*
		Expand a snippet in the current cursor position. If there is no snippet 
		available it jumps to the next placeholder of the buffer.

				*<Plug>(neocomplcache_snippets_expand)*
		Note: |<Plug>(neocomplcache_snippets_expand)| is an obsolete
		name.

<Plug>(neosnippet_jump_or_expand)
				*<Plug>(neosnippet_jump_or_expand)*
s_<Plug>(neosnippet_jump_or_expand)
				*s_<Plug>(neosnippet_jump_or_expand)*
		Jump to the next available placeholder in the buffer. If there is no 
		placeholder it expands a snippet in the current cursor position. 

				*<Plug>(neocomplcache_snippets_jump)*
		Note: |<Plug>(neocomplcache_snippets_jump)| is an obsolete
		name.

<Plug>(neosnippet_expand)
						*<Plug>(neosnippet_expand)*
s_<Plug>(neosnippet_expand)
						*s_<Plug>(neosnippet_expand)*
		Expand a snippet in current cursor position. It only takes effect 
		if there is a snippet text to expand or if you have chosen one from
	        the neocomplcache drop down menu.

				*<Plug>(neocomplcache_snippets_force_expand)*
		Note: |<Plug>(neocomplcache_snippets_force_expand)| is
		an obsolete name.

<Plug>(neosnippet_jump)
						*<Plug>(neosnippet_jump)*
s_<Plug>(neosnippet_jump)
						*s_<Plug>(neosnippet_jump)*
		Jump to the next placeholder key. It does not expand any snippets.

				*<Plug>(neocomplcache_snippets_force_jump)*
		Note: |<Plug>(neocomplcache_snippets_force_jump)| is
		an obsolete name.

i_<Plug>(neosnippet_start_unite_snippet)
				*i_<Plug>(neosnippet_start_unite_snippet)*
		Starts the unite snippet source. You can expand a snippet by the 
		unite interface. Note: The plug-in |unite.vim| is required for
		that feature.

				*<Plug>(neocomplcache_start_unite_snippet)*
		Note: |<Plug>(neocomplcache_start_unite_snippet)| is an obsolete
		name.

x_<Plug>(neosnippet_expand_target)
					*x_<Plug>(neosnippet_expand_target)*
		Expand the input trigger by a selected target text.

x_<Plug>(neosnippet_register_oneshot_snippet)
				*x_<Plug>(neosnippet_register_oneshot_snippet)*
		Register oneshot snippet in the current buffer.

neosnippet#expandable()
						*neosnippet#expandable()*
		You can use this function with imap <expr>. It checks whether the 
		cursor text is a snippet trigger or a placeholder. This is is useful 
		to save key mappings. The return values of the function are:
	
	        0: not found
		1: the cursor text is a snippet trigger
		2: a placeholder exists in the current buffer
		3: both found
>
		imap <expr><C-l> neosnippet#expandable() ?
		\ "\<Plug>(neosnippet_expand_or_jump)" : "\<C-n>"
<
		*neocomplcache#sources#snippets_complete#expandable()*
		*neocomplcache#sources#snippets_complete#force_expandable()*
		Note:
		|neocomplcache#sources#snippets_complete#expandable()|
		and
		|neocomplcache#sources#snippets_complete#force_expandable()|
		are obsolete names.

neosnippet#jumpable()
						*neosnippet#jumpable()*
		Use this function with imap <expr>. It checks if the cursor
		text is an existing placeholder in current buffer. This is 
		useful to save key mappings.

		*neocomplcache#sources#snippets_complete#jumpable()*
		Note: |neocomplcache#sources#snippets_complete#jumpable()| is
		an obsolete name.

------------------------------------------------------------------------------
FUNCTIONS					*neosnippet-functions*

neosnippet#get_snippets_directory()
					*neosnippet#get_snippets_directory()*
		Gets snippet directories. This directories contain runtime
		snippets directories and |g:neosnippet#snippets_directory|
		directories.

		*neocomplcache#sources#snippets_complete#get_snippets_dir()*
		Note:
		|neocomplcache#sources#snippets_complete#get_snippets_dir()|
		is an obsolete name.

==============================================================================
EXAMPLES					*neosnippet-examples*
>
	" Plugin key-mappings.
	imap <C-k>     <Plug>(neosnippet_expand_or_jump)
	smap <C-k>     <Plug>(neosnippet_expand_or_jump)
	xmap <C-k>     <Plug>(neosnippet_expand_target)

	" SuperTab like snippets behavior.
	"imap <expr><TAB> neosnippet#expandable() ?
	" \ "\<Plug>(neosnippet_expand_or_jump)"
	" \: pumvisible() ? "\<C-n>" : "\<TAB>"
	"smap <expr><TAB> neosnippet#expandable() ?
	" \ "\<Plug>(neosnippet_expand_or_jump)"
	" \: "\<TAB>"

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

The neosnippet snippet syntax is quite similar to the snippet syntax 
of |snipMate|.

Example:
>
	snippet     if
	abbr        if endif
	options     head
	    if ${1:condition}
	        ${2}
	    endif
<

The example above displays the structure of the syntax. Each snippet starts with
the keyword "snippet" which is directly followed by the snippet name. After
that you can define an abbreviation which will be used for the drop down menu
of neocomplcache. The options line restricts the environment the snippet gets
expanded. In this case it is restricted to the head of the line.

Note: If a snippets is defined multiple times in different snippet files,
neosnippet produces a warning. If you want to overwrite a snippet explicitly,
please use:

>
	delete snippets_name
<

After that you can redefine the snippet. But this does not work if you include
other files or external snippet files. If you include external snippet file's
there will be no warning when snippets of those files get overwritten.

Snippet include feature is available.

>
	include c.snip
<

If you want to include a whole filetype directory snippets.

>
	include javascript/*
<

Eval snippet feature is available.

>
	snippet     hoge
	options     head
	    `expand("%")`
<

Note: You want to use backticks in snippet, you must escape backticks.

>
	snippet code
	abbr code
	    \`${1}\`${2}
<

If you use |:NeoSnippetEdit| command for easy snippet editing, the file will
be loaded automatically when you save the file.

Neosnippet 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>(neosnippet_expand_or_jump)
	smap <C-l>    <Plug>(neosnippet_expand_or_jump)
<

Placeholder feature is available. The string after ":" is default value.
>
	snippet     if
	abbr        if endif
	options     head
	    if ${1:condition}
	        ${2}
	    endif
<
Commented placeholder feature is available. If the default value starts with
"#:", neosnippet will the delete default value when jump to next placeholder.
>
	snippet     if
	abbr        if endif
	options     head
	    if ${1:#:condition}
	        ${2}
	    endif
<
Targetted placeholder feature is available. If the default value starts with
"TARGET:", neosnippet will insert selected text in
|<Plug>(neosnippet_expand_target)|.
>
	snippet     if
	abbr        if endif
	options     head
	    if ${1:#:condition}
	        ${2:TARGET}
	    endif
<
Note: To contain "}" character in default value, you must escape "}".
>
	snippet test
	    ${1:escape \} value}
<
'_' (global) snippet feature is available. Neosnippet loads '_' snippet for
all filetypes.

Neosnippet can load snipMate snippets as well.

Alias feature is available. The separator is either ' ' or ','.
>
	alias hoge hogera hogehoge
<
Synchronized placeholder feature is supported.  $1 is synchronized to ${1}.
When you jump next, it will be synchronized. $0 will be the final jump
placeholder.

The placeholder value can't contain new lines. The snippet below isn't valid:
>
	snippet test
	    ${1:constructor: (${2:args\}) ->
	        ${3:# do smth}}
<
Multi snippet feature in snipMate is available.
Neosnippet substitutes trigger and descriptions spaces to '_'.
>
	snippet trigger description1
	    hoge
	snippet trigger description2
	    piyo
<
Choose snippets using <C-n> or <C-p> and expand it with
|<Plug>(neosnippet_expand_or_jump)| key-mappings.

Nested placeholder feature is available, But you must escape inner "}". "\" is
the eacape sequence.
>
	snippet div
	    <div ${1:id="${2:someid\}"}>${3}</div>${4}
<
You must escape "}" twice in following case.
>
	snippet  catch
	options  head
	    catch ${1:/${2:pattern: empty, E484, Vim(cmdname):{errmsg\\}\}/}
<
Because ${1:} substitutes the pattern to "/${2:pattern: empty, E484,
Vim(cmdname):{errmsg\}}" and ${2:} substitutes the pattern to "pattern:
empty, E484, Vim(cmdname):{errmsg}"

If you use hard-tab for indentation in snippet file, neosnippet will use
'shiftwidth' instead of Vim indent plugin. This feature is useful while some
languages' indent files can not work very well (e.g.: PHP, Python).
>
	snippet if
		if (${1:/* condition */}) {
			${2:// code...}
		}
<
SNIPPET SYNTAX OPTIONS			*neosnippet-snippet-syntax-options*

"options head" means this snippet is enabled only in line head.
Note: prev_word '^' is duplicated keyword.

"options word" means this snippet is expanded by word boundary.
Note: To complete the trigger in snippets_complete, it must be word(digits or
alphabet characters or "_") characters.
>
	snippet     date
	options     word
	    `strftime("%d %b %Y")`
<
"options indent" means neosnippet indents in expanded line.

==============================================================================
UNITE SOURCES					*neosnippet-unite-sources*

					*neosnippet-unite-source-snippet*
snippet
		The candidates are neosnippet snippets. The kinds are
		"snippet".  Normally used in
		|<Plug>(neosnippet_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>(neosnippet_start_unite_snippet)
<
source actions

snippet					*neosnippet-unite-action-snippet*
	expand		Expand snippet (default action)
	edit		Edit snippet
	preview		View snippet definition

==============================================================================
FAQ						*neosnippet-faq*

Q: Don't expanded snippet trigger after (, [, " etc...:

A: You should use "options word" in snippet definition.  "options word" means
this snippet is expanded by word boundary.
>
	snippet     date
	options     word
	    `strftime("%d %b %Y")`
<

Q: Doesn't indent in expanded line:

A: You should use "options indent" in snippet definition. In default,
neosnippet doesn't indent in expanded line.

Q: Neosnippet conflicts with |LustyJuggler|.
http://www.vim.org/scripts/script.php?script_id=2050

A: Please try below settings:
Note: But you must unmap in select mode mappings manually.
>
	let g:neosnippet#disable_select_mode_mappings = 0
<

==============================================================================
CHANGELOG			*neosnippet-changelog*

2012-10-30
- Implemented commented placeholder.
- Improved python snippets.
- Fixed for alias.
- Implemented targetted placeholder.
- Improved documentation.
- Added FAQ section.
- Added indent option.
- Added <Plug>(neosnippet_register_oneshot_snippet).
- Refactored snippets files.

2012-10-29
- Improved parse of snippets file.
- Improved syntax of markers.
- Improved clear select mode mappings.
- Added get_selected_text().

2012-10-28
- Improved snipMate compatibility.
- Improved expand behavior.
- Improved filter behavior.

2012-10-27
- Fixed for :SnippetEdit.
- Improved g:neosnippet#disable_select_mode_mappings behavior.

2012-10-26
- Improved javascript snippet file.

2012-10-25
- Deleted sandbox execution.

2012-10-23
- Improved neosnippet#util#expand().

2012-10-21
- Added options head.
- Added options word.
- Improved options word behavior.
- Use head instead of prev_word.

2012-10-20
- Improved scala snip.
- Added haskell snip.
- Added vim/vital snip.

2012-10-19
- Fixed syntax highlight.
- Improved documentation.
- Search snippets recursively.
- Fixed make cache behavior.

2012-10-18
- Fixed s:get_sources_list().
- Added unite__new_candidate action in snippet source.
- Fixed menu pattern.

2012-10-17
- Fixed alias problem.
- Improved escape placeholder.

2012-10-15
- Improved lua snip.
- Improved c++ snip.

2012-10-07
- Improved vim snip.
- Improved c snip.

2012-10-06
- Improved indent snippet behavior.
- Fixed substitute marker.
- Fixed for E749.

2012-10-04
- Refactored snippets filter.
- Changed :NeoSnippetEdit behavior.
- Added scala snip.
- Fixed s:get_cursor_snippet().
- Changed g:neosnippet#disable_runtime_snippets behavior.
- Changed prev_word behavior.

2012-10-01
- Deleted neosnippet#force_expandable().
- Improved python snippets.

2012-09-30
- Changed runtime directory.
- Vitalized.
- Deleted neocomplcache#util functions.
- Refactored variables.
- Deleted s:get_cursor_keyword_snippet().
- Improved for filetype.
- Improved filetype complete.
- Improved documentation.
- Changed neocomplcache source behavior.
- Renamed commands.
- Fixed snippet source errors.

2012-09-27
- Ver.3 development is started.
- Renamed documentation.
- Renamed keymappings.

------------------------------------------------------------------------------
ChangeLog 2.0:

2012-09-27
- Improved add placeholder behavior.
- Fixed wrong indentation when 'expandtab'.

2012-09-23
- Fixed substitute tab character.
- Improved cursor position.
- Fixed column in select mode.
- Added lua snip.
- Improved javascript snip.
- Improved ruby snip.

2012-09-06
- Added neocomplcache__convertable attribute.

2012-08-30
- Changed <Plug>(neocomplcache_snippets_expand) behavior.

2012-08-27
- Fixed neocomplcache#sources#snippets_complete#force_expandable().

2012-08-02
- Improved caching snippet files.

2012-06-06
- Added neocomplcache#sources#snippets_complete#get_snippets_dir().

2012-06-02
- Fixed exapnd indentation.

2012-05-16
- Added ftdetect file.

2012-05-12
- Improved c snip.

2012-05-03
- Released ver.2.0.

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: