code.delx.au - gnu-emacs-elpa/blob - doc/manual.org

   1 #+TITLE: Yet another snippet extension
   2 #+OPTIONS: toc:1
   3 #+STARTUP: showall
   4
   5 #+STYLE: <link rel="stylesheet" type="text/css" href="stylesheets/styles.css" />
   6
   7 # External links
   8 #
   9 #+LINK: smart-snippet http://code.google.com/p/smart-snippet
  10 #+LINK: pluskid       http://pluskid.lifegoo.org
  11
  12 #+LINK: screencast         http://www.youtube.com/watch?v=ZCGmZK4V7Sg
  13 #+LINK: docs               http://capitaomorte.github.com/yasnippet
  14 #+LINK: issues             https://github.com/capitaomorte/yasnippet/issues
  15 #+LINK: googlecode-tracker http://code.google.com/p/yasnippet/issues/list
  16 #+LINK: forum              http://groups.google.com/group/smart-snippet
  17
  18
  19 * Quick start
  20
  21   *YASnippet* is a template system for Emacs. It allows you to type an
  22   abbreviation and automatically expand it into function templates. Bundled
  23   language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML,
  24   CSS and more. The snippet syntax is inspired from TextMate's syntax, you can
  25   even [[#import-textmate][import most TextMate snippets]]
  26
  27   YASnippet is an original creation of [[pluskid]] who also wrote its predecessor
  28   [[smart-snippet]].
  29
  30 ** Watch a demo
  31
  32    [[youtube]]
  33
  34 ** Installation
  35
  36    Clone this repository somewhere
  37
  38    #+begin_example
  39    $ cd ~/.emacs.d/plugins
  40    $ git clone https://github.com/capitaomorte/yasnippet
  41    #+end_example
  42
  43    Add the following in your =.emacs= file:
  44
  45    #+begin_src emacs-lisp :exports code
  46    (add-to-list 'load-path
  47                  "~/.emacs.d/plugins/yasnippet")
  48    (require 'yasnippet)
  49    (yas/global-mode 1)
  50    #+end_src
  51
  52    Add your own snippets to =~/.emacs.d/snippets= by placing files there or
  53    invoking [[#yas-new-snippet][=yas-new-snippet=]].
  54
  55 ** Import textmate snippets (rails example)
  56    :PROPERTIES:
  57    :CUSTOM_ID: import-textmate
  58    :END:
  59
  60    YASnippet lets you use TextMate bundles directly:
  61
  62    #+begin_example
  63    $ cd ~/.emacs.d/plugins
  64    $ git clone https://github.com/capitaomorte/yasnippet
  65    $ cd yasnippet
  66    $ git submodule init
  67    $ git submodule update
  68    $ gem install plist trollop
  69    $ rake convert_bundles             # will convert ruby, rails and html bundles from drnic
  70    #+end_example
  71
  72    Then, in your =.emacs= file
  73
  74    #+begin_example
  75    (add-to-list 'load-path
  76                  "~/.emacs.d/plugins/yasnippet")
  77    (require 'yasnippet)
  78    (setq yas/snippet-dirs '("~/.emacs.d/snippets" "~/.emacs.d/extras/imported"))
  79    (yas/global-mode 1)
  80    #+end_example
  81
  82    Open some rails file (model, app, etc) and start using the textmate
  83    snippets. Consider that this is a work-in-progress and many snippets/commands
  84    might not work. Patches welcome!
  85
  86 ** Contributing snippets
  87
  88    Please *do not ask me* to add snippets to the default collection under
  89    =/snippets=. This collection is considered frozen. By customizing
  90    [[#yas-snippet-dirs][=yas-snippet-dirs=]] you can point yasnippet to good
  91    snippet collections out there.
  92
  93    The =extras/textmate-import.rb= tool can import many actual Textmate
  94    snippets.  I'm focusing on developing it and the accompanying =yas-setup.el=
  95    files that guide it with more difficult importations. The idea is to deprecate
  96    =/snippets=  and replace it with =extras/imported=.
  97
  98 ** Documentation, issues, etc
  99
 100    Please refer to the comprehensive [[docs][documentation]] for full
 101    customization and support.  If you think you've found a bug, please report it
 102    on [[issues][the GitHub issue tracker]].  (please **do not** submit new
 103    issues to the old [[googlecode-tracker][googlecode tracker]])
 104
 105    If you run into problems using YASnippet, or have snippets to contribute,
 106    post to the [[forum][yasnippet forum]]. Thank you very much for using
 107    YASnippet!
 108
 109 * Organizing snippets
 110
 111 ** Basic structure
 112
 113    Snippet collections can be stored in plain text files. They are arranged by
 114    sub-directories naming *snippet tables*. These mostly name Emacs major names.
 115
 116    #+begin_example
 117    .
 118    |-- c-mode
 119    |   `-- printf
 120    |-- java-mode
 121    |   `-- println
 122    `-- text-mode
 123        |-- email
 124        `-- time
 125    #+end_example
 126
 127    The collections are loaded into *snippet tables* which the triggering
 128    mechanism (see [[#expand-snippets][Expanding snippets]]) looks up and
 129    (hopefully) cause the right snippet to be expanded for you.
 130
 131 ** Setting up =yas-snippet-dirs=
 132
 133    The emacs variable [[#yas-snippet-dirs][=yas-snippet-dirs=]] tells YASnippet
 134    which collections to consider. It's used when you activate
 135    [[#yas-global-mode][=yas-global-mode=]] or call
 136    [[#yas-reload-all][=yas-reload-all=]] interactively.
 137
 138    The default considers:
 139
 140     - a personal collection that lives in =~/.emacs.d/snippets=
 141     - the bundled collection, taken as a relative path to =yasnippet.el= localtion
 142
 143    When you come across other snippet collections, do the following to try them
 144    out:
 145
 146    #+begin_src emacs-lisp :exports code
 147    ;; Develop in ~/emacs.d/mysnippets, but also
 148    ;; try out snippets in ~/Downloads/interesting-snippets
 149    (setq yas/snippet-dirs '("~/emacs.d/mysnippets"
 150                               "~/Downloads/interesting-snippets"))
 151
 152    ;; OR, keeping yasnippet's defaults try out ~/Downloads/interesting-snippets
 153    (setq yas/snippet-dirs (append yas/snippet-dirs
 154                                   '("~/Downloads/interesting-snippets")))
 155    #+end_src
 156
 157    Collections appearing earlier in the list shadow snippets with same names
 158    appearing in collections later in the list. [[#yas-new-snippet][=yas-new-snippet=]] always stores
 159    snippets in the first collection.
 160
 161 ** The =.yas-parents= file
 162
 163    It's very useful to have certain modes share snippets between themselves. To do
 164    this, choose a mode subdirectory and place a =.yas-parents= containing a
 165    whitespace-separated list of other mode names. When you reload those modes
 166    become parents of the original mode.
 167
 168    #+begin_example
 169    .
 170    |-- c-mode
 171    |   |-- .yas-parents    # contains "cc-mode text-mode"
 172    |   `-- printf
 173    |-- cc-mode
 174    |   |-- for
 175    |   `-- while
 176    |-- java-mode
 177    |   |-- .yas-parents    # contains "cc-mode text-mode"
 178    |   `-- println
 179    `-- text-mode
 180        |-- email
 181        `-- time
 182    #+end_example
 183
 184 ** TODO The =.yas-make-groups= file
 185
 186    If you place an empty plain text file =.yas-make-groups= inside one of the
 187    mode directories, the names of these sub-directories are considered groups of
 188    snippets and [[snippet-menu][the menu]] is organized much more cleanly:
 189
 190    (TODO image)
 191
 192    Another alternative way to achieve this is to place a =# group:= directive
 193    inside the snippet definition. See [[#writing-snippets][Writing Snippets]]
 194
 195    #+begin_example
 196    $ tree ruby-mode/
 197    ruby-mode/
 198    |-- .yas-make-groups
 199    |-- collections
 200    |   |-- each
 201    |   `-- ...
 202    |-- control structure
 203    |   |-- forin
 204    |   `-- ...
 205    |-- definitions
 206    |   `-- ...
 207    `-- general
 208       `-- ...
 209    #+end_example
 210
 211    Yet another way to create a nice snippet menu is to write into
 212    =.yas-make-groups= a menu definition. TODO
 213
 214 ** TODO The =.yas-setup.el= file
 215
 216 *** TODO
 217
 218 ** TODO The =.yas-compiled-snippet.el= file
 219
 220 *** TODO
 221
 222 ** The =.yas-skip= file
 223
 224 * Expanding Snippets
 225
 226    :PROPERTIES:
 227    :CUSTOM_ID: expand-snippets
 228    :END:
 229
 230   This section describes how YASnippet chooses snippets for expansion at point.
 231
 232   Maybe, you'll want some snippets to be expanded in a particular
 233   mode, or only under certain conditions, or be prompted using
 234
 235 ** Triggering expansion
 236
 237    To make a snippet expand after the cursor:
 238
 239    * Type an the snippet's *trigger key* then press the key defined in
 240      [[#yas-trigger-key][=yas-trigger-key=]] (usually to "TAB").
 241
 242    * Use the snippet's *keybinding*.
 243
 244    * Call [[#yas-insert-snippet][=yas-insert-snippet=]] (use =M-x
 245      yas-insert-snippet== or its keybinding =C-c & C-s=).
 246
 247    * By expanding directly from the "YASnippet" menu in the menu-bar
 248
 249    * Using hippie-expand
 250
 251    * Use m2m's excellent auto-complete
 252
 253 * Reference
 254 #+BEGIN_SRC emacs-lisp :exports results :results value raw
 255 (yas--document-symbols 2 `("Interactive functions" . ,#'interactive-form)
 256                          `("Customization variables" . ,#'(lambda (sym)
 257                                                             (and (boundp sym)
 258                                                                  (get sym 'standard-value))))
 259                          `("Useful functions" . ,#'fboundp)
 260                          `("Useful variables" . ,#'boundp))
 261 #+END_SRC
 262 # Local Variables:
 263 # mode: org
 264 # fill-column: 80
 265 # coding: utf-8
 266 # End: