hasufell/neosnippet.vim
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #77 from cpfaff/doc_improvement

Browse Source 
improves the documentation
This commit is contained in:
Shougo 2012-10-30 18:45:57 -07:00
commit 558883734d
1 changed files with 222 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

358
doc/neosnippet.txt
View File

@ -41,9 +41,9 @@ Changelog |neosnippet-changelog|
INTRODUCTION *neosnippet-introduction* INTRODUCTION *neosnippet-introduction*
This plugin analyzes snippet files which you can use for completion. It offers This plugin analyzes snippet files which you can use for completion. It offers
functionality similar to |snipMate.vim| or |snippetsEmu.vim|. Since you can functionality similar to snipMate.vim or snippetsEmu.vim. Since you can choose
choose snippets with the neocomplcache interface, you might have less trouble snippets with the neocomplcache interface, you might have less trouble using
using them, because you do not have to remember each snippet name. them, because you do not have to remember each snippet name.
============================================================================== ==============================================================================
INSTALL *neosnippet-install* INSTALL *neosnippet-install*
@ -63,7 +63,7 @@ COMMANDS *neosnippet-commands*
:NeoSnippetMakeCache [filetype] :NeoSnippetMakeCache [filetype]
*:NeoSnippetMakeCache* *:NeoSnippetMakeCache*
Creates a cache for the given [filetype] snippets. It automatically Creates a cache for the given [filetype] snippets. It automatically
choses the current buffer's file type unless you specify one by choses the current buffer's file type unless you specify one by
[filetype]. [filetype].
@ -126,15 +126,20 @@ VARIABLES *neosnippet-variables*
g:neosnippet#snippets_directory *g:neosnippet#snippets_directory* g:neosnippet#snippets_directory *g:neosnippet#snippets_directory*
This variable appoints a path to user-defined snippet files. This variable appoints a path to user-defined snippet files.
You can set multiple values in comma-separated form. You can set multiple values in comma-separated form. Non existing
If the directory doesn't exist, it is ignored. directories are ignored.
User defined snippets are read after built-in snippet files, User defined snippet files are read after the built-in snippet files.
and redundant snippets get overwritten. If redundant snippets occur they get overwritten and only the last
one remains.
Note: Neosnippet loads the file type snippet files as follows. Note: The neosnippet plug-in loads file type snippets from several
If you edit "vim" file types files, neosnippet loads files if available. For example if you edit a "Vim" file then it loads the
"vim.snip*", "vim_*.snip*" and "vim/**/*.snip" snippet files. snippets from:
- "vim.snip*"
- "vim_*.snip*"
- "vim/**/*.snip"
*g:neocomplcache_snippets_dir* *g:neocomplcache_snippets_dir*
Note: |g:neocomplcache_snippets_dir| is an obsolete name. Note: |g:neocomplcache_snippets_dir| is an obsolete name.
@ -143,10 +148,10 @@ g:neosnippet#snippets_directory *g:neosnippet#snippets_directory*
g:neosnippet#disable_select_mode_mappings g:neosnippet#disable_select_mode_mappings
*g:neosnippet#disable_select_mode_mappings* *g:neosnippet#disable_select_mode_mappings*
This variable disables key-mappings in |Select-mode| where This variable disables key-mappings in |Select-mode| where the
snippets_complete performs the snippet completion. Usually it snippets_complete performs the snippet completion. Usually it
it better to leave it as it is. But if you have troubles with it better to leave it as it is. But if you have troubles with
the buffer switcher LustyJuggler it helps to disable them. the buffer switcher LustyJuggler you can switch them of.
*g:neocomplcache_disable_select_mode_mappings* *g:neocomplcache_disable_select_mode_mappings*
Note: |g:neocomplcache_disable_select_mode_mappings| is an Note: |g:neocomplcache_disable_select_mode_mappings| is an
@ -156,13 +161,13 @@ g:neosnippet#disable_select_mode_mappings
g:neosnippet#disable_runtime_snippets g:neosnippet#disable_runtime_snippets
*g:neosnippet#disable_runtime_snippets* *g:neosnippet#disable_runtime_snippets*
This is a dictionary variable which uses the file type as key. This is a dictionary variable which uses file types as key.
To set the value of a file type entry to 1 prevents loading all If you set the value of a file type entry to 1, this prevents
built-in snippets for that file type. This is very useful to loading all the file type specific built-in snippets. This is
prevent snippet conflicts between self defined snippet files very useful to to prevent snippet conflicts between self defined
and the built-in snippet files of neosnippet. If you use "_" as snippet files and the built-in snippet files of neosnippet.
key for an entry, this will be treated as default for all If you use a "_" as key for an entry this will treat the value of
file types. the entry as default value for all file types.
Note: This dictionary must be set in your .vimrc. Note: This dictionary must be set in your .vimrc.
@ -191,8 +196,8 @@ 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)
*s_<Plug>(neosnippet_expand_or_jump)* *s_<Plug>(neosnippet_expand_or_jump)*
Expands a cursor snippet of plural lines. When there is no Expand a snippet in the current cursor position. If there is no snippet
snippet, it jumps to the next placeholder. available it jumps to the next placeholder of the buffer.
*<Plug>(neocomplcache_snippets_expand)* *<Plug>(neocomplcache_snippets_expand)*
Note: |<Plug>(neocomplcache_snippets_expand)| is an obsolete Note: |<Plug>(neocomplcache_snippets_expand)| is an obsolete
@ -202,8 +207,8 @@ s_<Plug>(neosnippet_expand_or_jump)
*<Plug>(neosnippet_jump_or_expand)* *<Plug>(neosnippet_jump_or_expand)*
s_<Plug>(neosnippet_jump_or_expand) s_<Plug>(neosnippet_jump_or_expand)
*s_<Plug>(neosnippet_jump_or_expand)* *s_<Plug>(neosnippet_jump_or_expand)*
Jump to the next placeholder. If there is no placeholder, it expands a Jump to the next available placeholder in the buffer. If there is no
multi line cursor snippet. placeholder it expands a snippet in the current cursor position.
*<Plug>(neocomplcache_snippets_jump)* *<Plug>(neocomplcache_snippets_jump)*
Note: |<Plug>(neocomplcache_snippets_jump)| is an obsolete Note: |<Plug>(neocomplcache_snippets_jump)| is an obsolete
@ -213,7 +218,9 @@ s_<Plug>(neosnippet_jump_or_expand)
*<Plug>(neosnippet_expand)* *<Plug>(neosnippet_expand)*
s_<Plug>(neosnippet_expand) s_<Plug>(neosnippet_expand)
*s_<Plug>(neosnippet_expand)* *s_<Plug>(neosnippet_expand)*
Expand a cursor snippet. It does nothing if there is no snippet. 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)* *<Plug>(neocomplcache_snippets_force_expand)*
Note: |<Plug>(neocomplcache_snippets_force_expand)| is Note: |<Plug>(neocomplcache_snippets_force_expand)| is
@ -223,8 +230,7 @@ s_<Plug>(neosnippet_expand)
*<Plug>(neosnippet_jump)* *<Plug>(neosnippet_jump)*
s_<Plug>(neosnippet_jump) s_<Plug>(neosnippet_jump)
*s_<Plug>(neosnippet_jump)* *s_<Plug>(neosnippet_jump)*
Jump to the next place holder. Do not expand any snippet. When Jump to the next placeholder key. It does not expand any snippets.
you do not want to expand a snippet name, use this key mapping.
*<Plug>(neocomplcache_snippets_force_jump)* *<Plug>(neocomplcache_snippets_force_jump)*
Note: |<Plug>(neocomplcache_snippets_force_jump)| is Note: |<Plug>(neocomplcache_snippets_force_jump)| is
@ -233,8 +239,8 @@ s_<Plug>(neosnippet_jump)
i_<Plug>(neosnippet_start_unite_snippet) i_<Plug>(neosnippet_start_unite_snippet)
*i_<Plug>(neosnippet_start_unite_snippet)* *i_<Plug>(neosnippet_start_unite_snippet)*
Starts the unite snippet source. You can expand a snippet by the Starts the unite snippet source. You can expand a snippet by the
unite interface. Note: The plugin |unite.vim| is required for unite interface. Note: The plug-in |unite.vim| is required for
that. that feature.
*<Plug>(neocomplcache_start_unite_snippet)* *<Plug>(neocomplcache_start_unite_snippet)*
Note: |<Plug>(neocomplcache_start_unite_snippet)| is an obsolete Note: |<Plug>(neocomplcache_start_unite_snippet)| is an obsolete
@ -318,116 +324,215 @@ EXAMPLES *neosnippet-examples*
============================================================================== ==============================================================================
SNIPPET SYNTAX *neosnippet-snippet-syntax* SNIPPET SYNTAX *neosnippet-snippet-syntax*
The snippet syntax is similar to |snipMate|. It is quite easy to create your own snippets starting with the example below.
The snippet syntax is close to the one of |snipMate|.
Example: Example:
> >
snippet if snippet [name]
abbr if endif abbr [abbreviation]
options head alias [aliases]
if ${1:condition} prev_word '^'
${2} if ${1:condition}
endif ${2}
endif
< <
snippet {snippet_name} syntax is the snippet name.
abbr {abbr_name} is the completion abbrevation (same to completion "abbr"
key).
By the way, it is warned that the snippet name was already defined by other Snippet Keywords:
snippet file. If you want to overwrite it explicitly, please use:
- snippet [name] (obligatory)
Each snippet starts with the keyword "snippet". This keyword is directly
followed by the snippet name. The snippet name is used for the expansion of
the snippet.
- abbr [name] (optional)
Here you can define an abbreviation of the snippet which will be used in the
drop down menu of neocomplcache.
- alias [aliases] (optional)
If you specify an alias it will be also used to expand a snippet. You can
define multiple aliases either using the separators ' ' or ','.
Example
> >
delete snippets_name alias hoge hogera hogehoge
< <
and redefine the snippet.
When including external files or other snippet file's snippets are overwrited, - prev_word [definition] (optional)
you will not be warned.
In the next line, here already starts the snippet which gets expanded. After
snippet expansion you can jump to the placeholders and replace them with desired
text.
The structure of a placeholder can be:
- ${number:placeholder text}
Here the number of the placeholder and the placeholder text that are
seperated by a ":" are embraced by a pair of "{}". The text is displayed
after the snippet expansion and gets replaced by your text. If you jump over
the snippet and do not insert any text in that position the placeholder text
remains there. This can be used as a standard value for a certain position.
Example
>
snippet if
if ${1:condition}
${2}
endif
<
- ${number:#:placeholder text}
Here the number is followd by the "#" character. If you jump over this
placeholder and do not insert any text, the placeholder text will be removed.
Example
>
snippet if
if ${1:#:condition}
${2}
endif
<
- ${number:TARGET}
This is the target placeholder which will be replaced by the text which is
selected before snippet expansion. Note: You need to expand you snippet with
the key mapping below for this to work.
|<Plug>(neosnippet_expand_target)|.
This is very useful if you edit text and decide to put something in an
environment or some sort of brackets.
Example
>
snippet if
if ${1:#:condition}
${2:TARGET}
endif
<
- ${number}
This is a placeholder which you can use as a simple jump position. This
can be useful if you edit a placeholder inside of some sort of brackets or
environment and after that want to go on behind that.
Example
>
snippet if
if ${1:#:condition}
${2:do}
endif
${3}
<
- $number
This is the synchronized placeholder. Sometimes it is required to repat a value in
several places inside a snippet. If you set the number of this placeholder
to the same number as one of the other placeholders in the snippet it will
repeat its content if you insert something. $1 is synchronized to ${1} and
so on. $0 will be the final jump placeholder.
Example
>
snippet if
if ${1:#:condition}
${2:do}
endif
${3}
<
Note: If you like to include characters in snippets that already have a special
meaning to neosnippet you need to escape them with a backslash.
>
snippet code
\`${1}\`${2}
snippet test
${1:escape \} value}
<
A placeholder value can not contain new lines. The snippet below isn't valid.
>
snippet invalid
${1:constructor: (${2:args\}) ->
${3:# do smth}}
<
Vim has a built-in expression evaluation. You can also use this feature inside
of snippets if you use back ticks like in the example below where "%:t" gets
expanded to name of the current active file when the snippet gets expanded and
the current time gets inserted by the expansion of the strftime command.
>
snippet header
File: ${1:`expand('%:t')`}
${2:Created at: `strftime("%B %d, %Y")`}
<
You can also nest the placeholders if you escape the special characters.
>
snippet div
<div ${1:id="${2:someid\}"}>${3}</div>${4}
<
In some cases you need to escape the "}" twice as the example below shows.
>
snippet catch
options head
catch ${1:/${2:pattern: empty, E484, Vim(cmdname):{errmsg\\}\}/}
<
This is 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 create a snippet file and prepend the filename with a "_" neosnippet
treats the snippets inside the file as global. This means that they will be
available for all file types (e.g _.snip). You can include snippet files with
Snippet include feature is available.
> >
include c.snip include c.snip
< <
If you want to include a whole filetype directory snippets.
or if you want to include a whole directory with file type snippets.
> >
include javascript/* include javascript/*
< <
Eval snippet feature is available. If you include snippet files it can happen that the same snippet name is used
> multiple times in different snippet files. Neosnippet produces a warning if it
snippet hoge detects this. If you want to overwrite a snippet explicitly, please use:
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) delete snippets_name
smap <C-l> <Plug>(neosnippet_expand_or_jump)
< <
Placeholder feature is available. The string after ":" is default value. After that you can redefine the snippet. But this does not work if you include
> external snippet files. There will be no warning when snippets get overwritten.
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. Multi snippet feature in snipMate is available.
Neosnippet substitutes trigger and descriptions spaces to '_'. Neosnippet substitutes trigger and descriptions spaces to '_'.
> >
@ -436,24 +541,6 @@ Neosnippet substitutes trigger and descriptions spaces to '_'.
snippet trigger description2 snippet trigger description2
piyo 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 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 'shiftwidth' instead of Vim indent plugin. This feature is useful while some
@ -540,7 +627,6 @@ CHANGELOG *neosnippet-changelog*
- Added indent option. - Added indent option.
- Added <Plug>(neosnippet_register_oneshot_snippet). - Added <Plug>(neosnippet_register_oneshot_snippet).
- Refactored snippets files. - Refactored snippets files.
- Fixed indentation.
2012-10-29 2012-10-29
- Improved parse of snippets file. - Improved parse of snippets file.