code.delx.au - gnu-emacs-elpa/blob - packages/yasnippet/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 behaviour
  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 *** Inserting region or register contents into snippet
  87
  88 It's often useful to inject already written text in the middle of a
  89 snippet.  The variable [[sym:yas-wrap-around-region][=yas-wrap-around-region=]] when to t substitute
  90 the region contents into the =$0= placeholder of a snippet expanded by
  91 [[#yas-insert-snippet][=yas-insert-snippet=]].  Setting it to a character value (e.g. =?0=)
  92 will insert the contents of corresponding register.
  93
  94 Older (versions 0.9.1 and below) of Yasnippet, supported a setting of
  95 =cua= that is equivalent to =?0= but only worked with =cua-mode=
  96 turned on.  This setting is still supported for backwards
  97 compatibility, but is now entirely equivalent to =?0=.
  98
  99 ** Snippet keybinding
 100
 101 See the section of the =# binding:= directive in
 102 [[./snippet-development.org][Writing Snippets]].
 103
 104 ** Expanding from the menu
 105
 106 See [[./snippet-menu.org][the YASnippet Menu]].
 107
 108 ** Expanding with =hippie-expand=
 109
 110 To integrate with =hippie-expand=, just put
 111 [[sym:yas-hippie-try-expand][=yas-hippie-try-expand=]] in
 112 =hippie-expand-try-functions-list=. This probably makes more sense
 113 when placed at the top of the list, but it can be put anywhere you
 114 prefer.
 115
 116 ** Expanding from emacs-lisp code
 117
 118 Sometimes you might want to expand a snippet directly from your own
 119 elisp code. You should call [[sym:yas-expand-snippet][=yas-expand-snippet=]] instead of
 120 [[sym:yas-expand][=yas-expand=]] in this case. [[sym:yas-expand-snippet][=yas-expand-snippet=]] takes a string in
 121 snippet template syntax, if you want to expand an existing snippet you
 122 can use [[sym:yas-lookup-snippet][=yas-lookup-snippet=]] to find its contents by name.
 123
 124 As with expanding from the menubar, the condition system and multiple
 125 candidates doesn't affect expansion (the condition system does affect
 126 [[sym:yas-lookup-snippet][=yas-lookup-snippet=]] though). In fact, expanding from the YASnippet
 127 menu has the same effect of evaluating the follow code:
 128
 129 #+BEGIN_SRC emacs-lisp
 130   (yas-expand-snippet template)
 131 #+END_SRC
 132
 133 See the internal documentation on [[sym:yas-expand-snippet][=yas-expand-snippet=]] and
 134 [[sym:yas-lookup-snippet][=yas-lookup-snippet=]] for more information.
 135
 136 * Controlling expansion
 137
 138 ** Eligible snippets
 139
 140 YASnippet does quite a bit of filtering to find out which snippets are
 141 eligible for expanding at the current cursor position.
 142
 143 In particular, the following things matter:
 144
 145 -  Currently loaded snippets tables
 146
 147    These are loaded from a directory hierarchy in your file system. See
 148    [[./snippet-organization.org][Organizing Snippets]]. They are named
 149    after major modes like =html-mode=, =ruby-mode=, etc...
 150
 151 -  Major mode of the current buffer
 152
 153    If the currrent major mode matches one of the loaded snippet tables,
 154    then all that table's snippets are considered for expansion. Use
 155    =M-x describe-variable RET major-mode RET= to find out which major
 156    mode you are in currently.
 157
 158 -  Parent tables
 159
 160    Snippet tables defined as the parent of some other eligible table are
 161    also considered. This works recursively, i.e. parents of parents of
 162    eligible tables are also considered.
 163
 164 -  Buffer-local list of extra modes
 165
 166    Use [[#yas-activate-extra-mode][=yas-activate-extra-mode=]] to
 167    consider snippet tables whose name does not correspond to a major
 168    mode. Typically, you call this from a minor mode hook, for example:
 169
 170 #+BEGIN_SRC emacs-lisp
 171   ;; When entering rinari-minor-mode, consider also the snippets in the
 172   ;; snippet table "rails-mode"
 173   (add-hook 'rinari-minor-mode-hook
 174             #'(lambda ()
 175                 (yas-activate-extra-mode 'rails-mode)))
 176 #+END_SRC
 177
 178 -  Buffer-local
 179    [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]]
 180    variable
 181
 182    This variable provides finer grained control over what snippets can
 183    be expanded in the current buffer. The default value won't let you
 184    expand snippets inside comments or string literals for example. See
 185    The condition system\_ for more info.
 186
 187 ** The condition system
 188
 189 Consider this scenario: you are an old Emacs hacker. You like the
 190 abbrev-way and bind [[sym:yas-expand][=yas-expand=]] to =SPC=. However, you don't want
 191 =if= to be expanded as a snippet when you are typing in a comment
 192 block or a string (e.g. in =python-mode=).
 193
 194 If you use the =# condition := directive (see
 195 [[./snippet-development.org][Writing Snippets]]) you could just specify
 196 the condition for =if= to be =(not (python-in-string/comment))=. But how
 197 about =while=, =for=, etc. ? Writing the same condition for all the
 198 snippets is just boring. So has a buffer local variable
 199 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]]. You can set this variable to
 200 =(not (python-in-string/comment))= in =python-mode-hook=.
 201
 202 Then, what if you really want some particular snippet to expand even
 203 inside a comment? Set [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] like this
 204
 205 #+BEGIN_SRC emacs-lisp
 206   (add-hook 'python-mode-hook
 207             (lambda ()
 208               (setq yas-buffer-local-condition
 209                     '(if (python-in-string/comment)
 210                          '(require-snippet-condition . force-in-comment)
 211                        t))))
 212 #+END_SRC
 213
 214 ... and specify the condition for a snippet that you're going to expand
 215 in comment to be evaluated to the symbol =force-in-comment=. Then it can
 216 be expanded as you expected, while other snippets like =if= still can't
 217 expanded in comment.
 218
 219 For the full set of possible conditions, see the documentation for
 220 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]].
 221
 222 ** Multiples snippet with the same key
 223
 224 The rules outlined [[Eligible%20snippets][above]] can return more than
 225 one snippet to be expanded at point.
 226
 227 When there are multiple candidates, YASnippet will let you select one.
 228 The UI for selecting multiple candidate can be customized through
 229 [[sym:yas-prompt-functions][=yas-prompt-functions=]] , which defines your preferred methods of being
 230 prompted for snippets.
 231
 232 You can customize it with
 233 =M-x customize-variable RET yas-prompt-functions RET=. Alternatively you
 234 can put in your emacs-file:
 235
 236 #+BEGIN_SRC emacs-lisp
 237   (setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt))
 238 #+END_SRC
 239
 240 Currently there are some alternatives solution with YASnippet.
 241
 242 *** Use the X window system
 243
 244 [[./images/x-menu.png]]
 245
 246 The function [[sym:yas-x-prompt][=yas-x-prompt=]] can be used to show a popup menu for you to
 247 select. This menu will be part of you native window system widget, which
 248 means:
 249
 250 -  It usually looks beautiful. E.g. when you compile Emacs with gtk
 251    support, this menu will be rendered with your gtk theme.
 252 -  Your window system may or may not allow to you use =C-n=, =C-p= to
 253    navigate this menu.
 254 -  This function can't be used when in a terminal.
 255
 256 *** Minibuffer prompting
 257
 258 [[./images/ido-menu.png]]
 259
 260 You can use functions [[sym:yas-completing-prompt][=yas-completing-prompt=]] for the classic emacs
 261 completion method or [[sym:yas-ido-prompt][=yas-ido-prompt=]] for a much nicer looking method.
 262 The best way is to try it. This works in a terminal.
 263
 264 *** Use =dropdown-menu.el=
 265
 266 [[./images/dropdown-menu.png]]
 267
 268 The function [[sym:yas-dropdown-prompt][=yas-dropdown-prompt=]] can also be placed in the
 269 [[sym:yas-prompt-functions][=yas-prompt-functions=]] list.
 270
 271 This works in both window system and terminal and is customizable, you
 272 can use =C-n=, =C-p= to navigate, =q= to quit and even press =6= as a
 273 shortcut to select the 6th candidate.
 274
 275 *** Roll your own
 276
 277 See the documentation on variable [[sym:yas-prompt-functions][=yas-prompt-functions=]]