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

   1 #+SETUPFILE: org-setup.inc
   2
   3 #+TITLE: Expanding snippets
   4
   5   This section describes how YASnippet chooses snippets for expansion at point.
   6
   7   Maybe, you'll want some snippets to be expanded in a particular
   8   mode, or only under certain conditions, or be prompted using
   9
  10 * Triggering expansion
  11
  12    You can use YASnippet to expand snippets in different ways:
  13
  14    - When [[sym:yas-minor-mode][=yas-minor-mode=]] is active:
  15      - Type the snippet's *trigger key* then calling [[sym:yas-expand][=yas-expand=]]
  16        (bound to =TAB= by default).
  17
  18      - Use the snippet's *keybinding*.
  19
  20      - By expanding directly from the "YASnippet" menu in the menu-bar
  21
  22      - Using hippie-expand
  23
  24    - Call [[sym:yas-insert-snippet][=yas-insert-snippet=]] (use =M-x yas-insert-snippet== or its
  25      keybinding =C-c & C-s=).
  26
  27    - Use m2m's excellent auto-complete
  28      TODO: example for this
  29
  30    - Expanding from emacs-lisp code
  31
  32 ** Trigger key
  33
  34 [[sym:yas-expand][=yas-expand=]] tries to expand a /snippet abbrev/ (also known as
  35 /snippet key/) before point.
  36
  37 When [[sym:yas-minor-mode][=yas-minor-mode=]] is enabled, it binds [[sym:yas-expand][=yas-expand=]] to =TAB= and
  38 =<tab>= by default, however, you can freely set it to some other key:
  39
  40 #+begin_src emacs-lisp :exports code
  41    (define-key yas-minor-mode-map (kbd "<tab>") nil)
  42    (define-key yas-minor-mode-map (kbd "TAB") nil)
  43    (define-key yas-minor-mode-map (kbd "<the new key>") 'yas-expand)
  44 #+end_src
  45
  46 To enable the YASnippet minor mode in all buffers globally use the
  47 command [[sym:yas-global-mode][=yas-global-mode=]]. This will enable a modeline indicator,
  48 =yas=:
  49
  50 [[./images/minor-mode-indicator.png]]
  51
  52 When you use [[sym:yas-global-mode][=yas-global-mode=]] you can also selectively disable
  53 YASnippet in some buffers by setting the buffer-local variable
  54 [[sym:yas-dont-active][=yas-dont-active=]] in the buffer's mode hook.
  55
  56 *** Fallback bahaviour
  57
  58 [[sym:yas-fallback-behaviour][=yas-fallback-behaviour=]] is a customization variable bound to
  59 '=call-other-command= by default. If [[sym:yas-expand][=yas-expand=]] failed to find any
  60 suitable snippet to expand, it will disable the minor mode temporarily
  61 and find if there's any other command bound to the same key.
  62
  63 If found, the command will be called. Usually this works very well
  64 --when there's a snippet, expand it, otherwise, call whatever command
  65 originally bind to the trigger key.
  66
  67 However, you can change this behavior by customizing the
  68 [[sym:yas-fallback-behavior][=yas-fallback-behavior=]] variable. If you set this variable to
  69 '=return-nil=, it will return =nil= instead of trying to call the
  70 /original/ command when no snippet is found.
  71
  72 ** Insert at point
  73
  74 The command [[#yas-insert-snippet][=yas-insert-snippet=]] lets you insert snippets at point
  75 /for your current major mode/. It prompts you for the snippet key
  76 first, and then for a snippet template if more than one template
  77 exists for the same key.
  78
  79 The list presented contains the snippets that can be inserted at point,
  80 according to the condition system. If you want to see all applicable
  81 snippets for the major mode, prefix this command with =C-u=.
  82
  83 The prompting methods used are again controlled by
  84 [[sym:yas-prompt-functions][=yas-prompt-functions=]].
  85
  86 ** Snippet keybinding
  87
  88 See the section of the =# binding:= directive in
  89 [[./snippet-development.org][Writing Snippets]].
  90
  91 ** Expanding from the menu
  92
  93 See [[./snippet-menu.org][the YASnippet Menu]].
  94
  95 ** Expanding with =hippie-expand=
  96
  97 To integrate with =hippie-expand=, just put [[sym:yas-hippie-try-expand][=yas-hippie-try-expand=]] in
  98 =hippie-expand-try-functions-list=. This probably makes more sense when
  99 placed at the top of the list, but it can be put anywhere you prefer.
 100
 101 ** Expanding from emacs-lisp code
 102
 103 Sometimes you might want to expand a snippet directly from you own elisp
 104 code. You should call [[sym:yas-expand-snippet][=yas-expand-snippet=]] instead of [[sym:yas-expand][=yas-expand=]] in
 105 this case.
 106
 107 As with expanding from the menubar, the condition system and multiple
 108 candidates doesn't affect expansion. In fact, expanding from the
 109 YASnippet menu has the same effect of evaluating the follow code:
 110
 111 #+BEGIN_SRC emacs-lisp
 112   (yas-expand-snippet template)
 113 #+END_SRC
 114
 115 See the internal documentation on [[sym:yas-expand-snippet][=yas-expand-snippet=]] for more
 116 information.
 117
 118 * Controlling expansion
 119
 120 ** Eligible snippets
 121
 122 YASnippet does quite a bit of filtering to find out which snippets are
 123 eligible for expanding at the current cursor position.
 124
 125 In particular, the following things matter:
 126
 127 -  Currently loaded snippets tables
 128
 129    These are loaded from a directory hierarchy in your file system. See
 130    [[./snippet-organization.org][Organizing Snippets]]. They are named
 131    after major modes like =html-mode=, =ruby-mode=, etc...
 132
 133 -  Major mode of the current buffer
 134
 135    If the currrent major mode matches one of the loaded snippet tables,
 136    then all that table's snippets are considered for expansion. Use
 137    =M-x describe-variable RET major-mode RET= to find out which major
 138    mode you are in currently.
 139
 140 -  Parent tables
 141
 142    Snippet tables defined as the parent of some other eligible table are
 143    also considered. This works recursively, i.e. parents of parents of
 144    eligible tables are also considered.
 145
 146 -  Buffer-local list of extra modes
 147
 148    Use [[#yas-activate-extra-mode][=yas-activate-extra-mode=]] to consider snippet tables whose name
 149    does not correspond to a major mode. Typically, you call this from
 150    a minor mode hook, for example:
 151
 152 #+BEGIN_SRC emacs-lisp
 153   ;; When entering rinari-minor-mode, consider also the snippets in the
 154   ;; snippet table "rails-mode"
 155   (add-hook 'rinari-minor-mode-hook
 156             #'(lambda ()
 157                 (yas-activate-extra-mode 'rails-mode)))
 158 #+END_SRC
 159
 160 -  Buffer-local [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] variable
 161
 162    This variable provides finer grained control over what snippets can
 163    be expanded in the current buffer. The default value won't let you
 164    expand snippets inside comments or string literals for example. See
 165    The condition system\_ for more info.
 166
 167 ** The condition system
 168
 169 Consider this scenario: you are an old Emacs hacker. You like the
 170 abbrev-way and bind [[sym:yas-expand][=yas-expand=]] to =SPC=. However, you don't want
 171 =if= to be expanded as a snippet when you are typing in a comment
 172 block or a string (e.g. in =python-mode=).
 173
 174 If you use the =# condition := directive (see
 175 [[./snippet-development.org][Writing Snippets]]) you could just specify
 176 the condition for =if= to be =(not (python-in-string/comment))=. But how
 177 about =while=, =for=, etc. ? Writing the same condition for all the
 178 snippets is just boring. So has a buffer local variable
 179 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]]. You can set this variable to
 180 =(not (python-in-string/comment))= in =python-mode-hook=.
 181
 182 Then, what if you really want some particular snippet to expand even
 183 inside a comment? Set [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] like this
 184
 185 #+BEGIN_SRC emacs-lisp
 186   (add-hook 'python-mode-hook
 187             (lambda ()
 188               (setq yas-buffer-local-condition
 189                     '(if (python-in-string/comment)
 190                          '(require-snippet-condition . force-in-comment)
 191                        t))))
 192 #+END_SRC
 193
 194 ... and specify the condition for a snippet that you're going to expand
 195 in comment to be evaluated to the symbol =force-in-comment=. Then it can
 196 be expanded as you expected, while other snippets like =if= still can't
 197 expanded in comment.
 198
 199 For the full set of possible conditions, see the documentation for
 200 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]].
 201
 202 ** Multiples snippet with the same key
 203
 204 The rules outlined [[Eligible%20snippets][above]] can return more than
 205 one snippet to be expanded at point.
 206
 207 When there are multiple candidates, YASnippet will let you select one.
 208 The UI for selecting multiple candidate can be customized through
 209 [[sym:yas-prompt-functions][=yas-prompt-functions=]] , which defines your preferred methods of being
 210 prompted for snippets.
 211
 212 You can customize it with
 213 =M-x customize-variable RET yas-prompt-functions RET=. Alternatively you
 214 can put in your emacs-file:
 215
 216 #+BEGIN_SRC emacs-lisp
 217   (setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt))
 218 #+END_SRC
 219
 220 Currently there are some alternatives solution with YASnippet.
 221
 222 *** Use the X window system
 223
 224 [[./images/x-menu.png]]
 225
 226 The function [[sym:yas-x-prompt][=yas-x-prompt=]] can be used to show a popup menu for you to
 227 select. This menu will be part of you native window system widget, which
 228 means:
 229
 230 -  It usually looks beautiful. E.g. when you compile Emacs with gtk
 231    support, this menu will be rendered with your gtk theme.
 232 -  Your window system may or may not allow to you use =C-n=, =C-p= to
 233    navigate this menu.
 234 -  This function can't be used when in a terminal.
 235
 236 *** Minibuffer prompting
 237
 238 [[./images/ido-menu.png]]
 239
 240 You can use functions [[sym:yas-completing-prompt][=yas-completing-prompt=]] for the classic emacs
 241 completion method or [[sym:yas-ido-prompt][=yas-ido-prompt=]] for a much nicer looking method.
 242 The best way is to try it. This works in a terminal.
 243
 244 *** Use =dropdown-menu.el=
 245
 246 [[./images/dropdown-menu.png]]
 247
 248 The function [[sym:yas-dropdown-prompt][=yas-dropdown-prompt=]] can also be placed in the
 249 [[sym:yas-prompt-functions][=yas-prompt-functions=]] list.
 250
 251 This works in both window system and terminal and is customizable, you
 252 can use =C-n=, =C-p= to navigate, =q= to quit and even press =6= as a
 253 shortcut to select the 6th candidate.
 254
 255 *** Roll your own
 256
 257 See the documentation on variable [[sym:yas-prompt-functions][=yas-prompt-functions=]]
 258