doc/NERDSnippets.txt

*NERDSnippets.txt*  Snippets for vim.
*NERDSnippets*


        lock up your daughters! its ...~

        _   ____________  ____     _____       _                  __      ~
       / | / / ____/ __ \/ __ \   / ___/____  (_)___  ____  ___  / /______~
      /  |/ / __/ / /_/ / / / /   \__ \/ __ \/ / __ \/ __ \/ _ \/ __/ ___/~
     / /|  / /___/ _, _/ /_/ /   ___/ / / / / / /_/ / /_/ /  __/ /_(__  ) ~
    /_/ |_/_____/_/ |_/_____/   /____/_/ /_/_/ .___/ .___/\___/\__/____/  ~
                                            /_/   /_/                     ~


                              Reference Manual~

==============================================================================
CONTENTS

    |nerdsnippets-introduction|
    |nerdsnippets-defining-snippets|
        |nerdsnippets-snippet-indentation|
        |nerdsnippets-snippet-magic|
        |nerdsnippets-using-the-global-functions|
        |nerdsnippets-file-based-snippets|
        |nerdsnippets-snippet-magic|
    |nerdsnippets-options|
    |nerdsnippets-license|


==============================================================================
Introduction                                       *nerdsnippets-introduction*

It is a proven scientific fact that typing the same code over and over again
sucks balls. Therefore, the purpose of this plugin is to reduce the amount of
mindless repitition vim users have to do. For science.

This plugin provides an engine for code snippets.

It allows you to to create snippets by placing them in files, or by calling
global functions.

Once you have created a snippet you can insert it into a file by typing the
snippet keyword then pressing <tab>. From there you can jump to the snippet
"markers" by pressing <tab> again.

==============================================================================
Defining snippets                             *nerdsnippets-defining-snippets*

There are two approaches you can take to define your snippets. You can specify
them manually (using global functions), or you can use file based snippets.

File based snippets are generally easier to read and maintain and are
therefore recommended.

Both approaches end up being equivalent since file based snippets are created
using the same global functions anyway.


------------------------------------------------------------------------------
Snippet indentation                         *nerdsnippets-snippet-indentation*

Snippets are stored as sequences of keypresses, therefore, snippets do not
contain any indentation. They are indented on-the-fly when you insert them
into a file. They are indented according to your indent settings at the time
of use.

File based snippets should still be defined with indentation (for
readability), but know that it is removed when they are processed.


------------------------------------------------------------------------------
Snippet magic                                     *nerdsnippets-snippet-magic*

There are several important escape sequences to know about when defining
snippets.

    \<C-R>an_expression\<CR>
    Will insert the value of an_expression into the snippet when it is used.

    \<C-O>a_normal_mode_command\<CR>
    Will execute a_normal_mode_command when the snippet is used.

    \<CR>
    Will insert a new line in the snippet. This is only really useful when
    using the global functions to manually define snippets.


------------------------------------------------------------------------------
Using the global functions           *nerdsnippets-using-the-global-functions*

The script provides a bunch of functions that allow you to specify snippets.

Put all your snippet declarations in ~/.vim/after/plugin/ or split them up for
each filetype and put them in ~/.vim/ftplugin.

                                         *NERDSnippet()* *NERDSnippetGlobal()*
NERDSnippet(filetype, keyword, expansion [, name])
    Use this function to add filetype specific snippets.

NERDSnippetGlobal(keyword, expansion [, name])
    Use this function to add global snippets (available for all filetypes).


Example: a for loop snippet for java~
>
    call NERDSnippet("java", "for",
            \ "for(<+int i=0+>; <+condition+>; <+i+++>){\<CR><++>\<CR>}")
<
    There are 4 markers:
    1. <+int i=0+>
    2. <+condition+>
    3. <+i+++>
    4. <++>

    1, 2 and 3 have default values. When you tab to them, they will be
    replaced with the text "int i=0", "condition" and "i++".

    4 is an empty marker, these markers are removed when the cursor arrives on
    them.


Example: validates_presence_of for rails~
>
    call NERDSnippet("ruby", "vpo",
            \ "validates_presence_of :<++><+, :on => <++>, :if => <++>+>")
<
    Notice how the second marker:
    "<+, :message => '<++>', :on => <++>, :if => <++>+>"
    has 2 markers nested inside it. When you tab to this marker you can either
    hit tab again to "tab into" it, or hit backspace/ctrl-h or enter to delete
    it and move on. This way you can create "optional" parts to a snippet.


Example: global modeline snippet~
>
    function! ModelineSnippet()
      let start = substitute(&cms, '^\([^ ]*\)\s*%s\(.*\)$', '\1', '')
      let end = substitute(&cms, '^.*%s\(.*\)$', '\1', '')
      return start . " vim: set <+settings+>:" . end
    endfunction

    call NERDSnippetGlobal("modeline", "\<c-r>=ModelineSnippet()\<CR>")
<
    Here we have a snippet that uses some more complex logic, so we get a
    function to generate the snippet code for us.


Duplicate Keywords~
  If multiple snippets exist for the same keyword then the script will ask the
  user which one to insert.

  When binding multiple snippets to one keyword, you can assign the snippets a
  name to make it easier for the user to identify which snippet they want.


Example Snippet: two named snippets bound to a single keyword~
>
  call NERDSnippet("html", "table", "<table>\<CR><++></table>", "simple table")
  call NERDSnippet("html", "table", "<table class=\"<++>\">\<CR><++></table>",
                \ "table with class")
<
  Notice that we pass the name in as the last argument.


                                                        *NERDSnippetsReset()*
NERDSnippetsReset()
    Use this function to clear all snippets from memory. This is useful if you
    stick all your snippet declarations in one file. In this case you can call
    this function at the top of the file so you can source the file multiple
    times.


------------------------------------------------------------------------------
File based snippets                         *nerdsnippets-file-based-snippets*

You can specify snippets using files - one file per snippet. The following two
functions are used to read and process the snippets into vim. Call them from
somewhere like ~/.vim/after/plugin/snippet_setup.vim or using an |autocommand|
on |VimEnter|.

        *NERDSnippetsFromDirectory()* *NERDSnippetsFromDirectoryForFiletype()*
NERDSnippetsFromDirectory(dir)
    Extracts snippets from the given directory. The snippet filetype, keyword,
    and possibly name, are all inferred from the path of the .snippet files
    relative to a:dir.

    This assumes a precise file naming scheme:

    For single snippets >
        a:dir/<filetype>/<keyword>.snippet
<
    eg >
        a:dir/html/href.snippet
<
    For multiple snippets bound to a single keyword >
        a:dir/<filetype>/<keyword>/<snippet-name>.snippet
<
    eg >
        a:dir/html/table/simple-table.snippet
        a:dir/html/table/table-with-class.snippet
<

NERDSnippetsFromDirectoryForFiletype(dir, filetype)
    Extracts snippets from the given directory for the given filetype.

    The snippet keywords (and possibly names) are interred from the path of
    the .snippet files relative to a:dir

    This assumes a precise file naming scheme:

    For single snippets >
        a:dir/<keyword>.snippet
<
    eg >
        a:dir/href.snippet
<
    For multiple snippets bound to a single keyword >
        a:dir/<keyword>/<snippet-name>.snippet
<
    eg >
        a:dir/table/simple-table.snippet
        a:dir/table/table-with-class.snippet
<
    The main purpose of this function is to allow users to manually associate
    a collection of snippets with a filetype. For example, you probably want
    all your html snippets to also be used for the xhtml filetype. So
    (somewhere like ~/.vim/after/plugin/snippet_setup.vim) you could call
    this: >

        NERDSnippetsFromDirectoryForFiletype('~/.vim/snippets/html', 'xhtml')
<
Note: for the purposes of these two functions, global snippets are treated as
though their filetype is _. Eg. >
    ~/.vim/snippets/_/aGlobalSnippet.snippet
<
==============================================================================
Options                                                 *nerdsnippets-options*

Variables:
  g:NERDSnippets_key                        default: <tab>
      expands snippets and jumps to markers
  g:NERDSnippets_marker_start               default: <+
      start of marker tags
  g:NERDSnippets_marker_end                 default: +>
      end of marker tags

==============================================================================
9. License                                              *nerdsnippets-license*

NERD Snippets is released under the wtfpl.
See http://sam.zoy.org/wtfpl/COPYING.

/* vim: set ft=help:*/