*neosnippet.txt* neo-snippet plugin contains neocomplcache snippets source Version: 3.0 Author: Shougo 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 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 *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* Makes cache of [filetype] snippets. It automatically selects current buffer's filetype unless you specify [filetype]. *:NeoComplCacheCachingSnippets* Note: |:NeoComplCacheCachingSnippets| is obsolete name. :NeoSnippetEdit [{options}] [filetype] *:NeoSnippetEdit* Opens [filetype] snippets to edit. It automatically selects current buffer's filetype unless you specify [filetype]. If [filetype] snippets has a directory, it automatically edit "[filetype].snip" in [filetype] subdirectory. It edits a snippet file in |g:neosnippet#snippets_directory| with precedence. Re-make cache will be done automatically when you save the file. *:NeoComplCacheEditSnippets* {options} are options for the command. You may give the following parameters for a option; you must escape with "\" when it contains spaces. *neosnippet-edit-options-vertical* -vertical Splits window vertically. *neosnippet-edit-options-horizontal* -horizontal Splits window horizontally. The behavior is undefined when both options are defined. *neosnippet-edit-options-direction* -direction={direction} Defines split position rule. The default value is "belowleft". *neosnippet-edit-options-split* -split Split buffer. *neosnippet-edit-options-runtime* -runtime Edit runtime snippets instead of user snippets. Note: |:NeoComplCacheEditSnippets| is obsolete name. :NeoComplCacheEdit -runtime [filetype] It edits a runtime snippet file with neosnippet. Re-make cache will be done automatically when you save the file. *:NeoComplCacheEditRuntimeSnippets* Note: |:NeoComplCacheEditRuntimeSnippets| is 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. If the directory doesn't exist, it is ignored. User defined snippets were read after normal snippet files, so redundant snippets will be overwritten. Note: Neosnippet loads filetype snippet files. If you are editing "vim" filetypes files, neosnippet wll load "vim.snip*" and "vim_*.snip*" and "vim/**/*.snip" snippet files. *g:neocomplcache_snippets_dir* Note: |g:neocomplcache_snippets_dir| is 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 controls whether to disable Key-mappings in |Select-mode| when snippets_complete performs. Usually you had better enable it. *g:neocomplcache_disable_select_mode_mappings* Note: |g:neocomplcache_disable_select_mode_mappings| is obsolete name. Default value is 1. g:neosnippet#disable_runtime_snippets *g:neosnippet#disable_runtime_snippets* This is dictionary variable. The key is filetype. If the value is 1, all runtime snippets won't be loaded in the specified filetype. If the key is "_", it will be used for default filetype. This variable is useful to avoid snippets conflictions. Note: It must be set in .vimrc. For example: > let g:neosnippet#disable_runtime_snippets = { \ 'c' : 1, 'cpp' : 1, \ } " Like g:neocomplcache_snippets_disable_runtime_snippets " behavior(all runtime snippets are disabled). let g:neosnippet#disable_runtime_snippets = { \ '_' : 1, \ } < *g:neocomplcache_snippets_disable_runtime_snippets* Note: |g:neocomplcache_snippets_disable_runtime_snippets| is obsolete name. Default value is {}. ------------------------------------------------------------------------------ KEY MAPPINGS *neosnippet-key-mappings* (neosnippet_expand_or_jump) *(neosnippet_expand_or_jump)* s_(neosnippet_expand_or_jump) *s_(neosnippet_expand_or_jump)* Expands a cursor snippet of plural lines. When there is no snippet, jumps to the next placeholder. *(neocomplcache_snippets_expand)* Note: |(neocomplcache_snippets_expand)| is obsolete name. (neosnippet_jump_or_expand) *(neosnippet_jump_or_expand)* s_(neosnippet_jump_or_expand) *s_(neosnippet_jump_or_expand)* Jump to next placeholder. If there is no placeholder, expand a multiline cursor snippet. *(neocomplcache_snippets_jump)* Note: |(neocomplcache_snippets_jump)| is obsolete name. (neosnippet_expand) *(neosnippet_expand)* s_(neosnippet_expand) *s_(neosnippet_expand)* Expand a cursor snippet. Does nothing if there is no snippet. *(neocomplcache_snippets_force_expand)* Note: |(neocomplcache_snippets_force_expand)| is obsolete name. (neosnippet_jump) *(neosnippet_jump)* s_(neosnippet_jump) *s_(neosnippet_jump)* Jump to next place holder. Do not expand any snippet. When you do not want to expand a snippet name, use this keymapping. *(neocomplcache_snippets_force_jump)* Note: |(neocomplcache_snippets_force_jump)| is obsolete name. i_(neosnippet_start_unite_snippet) *i_(neosnippet_start_unite_snippet)* Start unite snippet source. You can expand a snippet by unite interface. Note: |unite.vim| is required. *(neocomplcache_start_unite_snippet)* Note: |(neocomplcache_start_unite_snippet)| is obsolete name. x_(neosnippet_expand_target) *x_(neosnippet_expand_target)* Expand inputted trigger by selected target text. x_(neosnippet_register_oneshot_snippet) *x_(neosnippet_register_oneshot_snippet)* Register oneshot snippet in current buffer. neosnippet#expandable() *neosnippet#expandable()* Use this function with imap . It checks whether cursor text is a snippet trigger or a placeholder exists in the current buffer. It's useful for saving keymappings. Return value is not just a boolean but either 0: not found 1: cursor text is a snippet trigger 2: a placeholder exists in the current buffer 3: both found > imap neosnippet#expandable() ? \ "\(neosnippet_expand_or_jump)" : "\" < *neocomplcache#sources#snippets_complete#expandable()* *neocomplcache#sources#snippets_complete#force_expandable()* Note: |neocomplcache#sources#snippets_complete#expandable()| and |neocomplcache#sources#snippets_complete#force_expandable()| is obsolete name. neosnippet#jumpable() *neosnippet#jumpable()* Use this function with imap . It checks whether cursor text is an existing placeholder in current buffer. Useful for saving keymappings. *neocomplcache#sources#snippets_complete#jumpable()* Note: |neocomplcache#sources#snippets_complete#jumpable()| is 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 obsolete name. ============================================================================== EXAMPLES *neosnippet-examples* > " Plugin key-mappings. imap (neosnippet_expand_or_jump) smap (neosnippet_expand_or_jump) xmap (neosnippet_expand_target) " SuperTab like snippets behavior. "imap neosnippet#expandable() ? " \ "\(neosnippet_expand_or_jump)" " \: pumvisible() ? "\" : "\" "smap neosnippet#expandable() ? " \ "\(neosnippet_expand_or_jump)" " \: "\" " For snippet_complete marker. if has('conceal') set conceallevel=2 concealcursor=i endif < ============================================================================== SNIPPET SYNTAX *neosnippet-snippet-syntax* The snippet syntax is similar to |snipMate|. Example: > snippet if abbr if endif options head 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). 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 < 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 (neosnippet_expand_or_jump) smap (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 |(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 or and expand it with |(neosnippet_expand_or_jump)| key-mappings. Nested placeholder feature is available, But you must escape inner "}". "\" is the eacape sequence. > snippet div
${3}
${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 |(neosnippet_start_unite_snippet)| mappings. But you can execute it by ":Unite snippet". You can edit snippet file in "edit" action. Examples: > imap (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 (neosnippet_register_oneshot_snippet). 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 (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: