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