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

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