1 #+SETUPFILE: org-setup.inc
3 #+TITLE: Expanding snippets
5 This section describes how YASnippet chooses snippets for expansion at point.
7 Maybe, you'll want some snippets to be expanded in a particular
8 mode, or only under certain conditions, or be prompted using
10 * Triggering expansion
12 You can use YASnippet to expand snippets in different ways:
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).
18 - Use the snippet's *keybinding*.
20 - By expanding directly from the "YASnippet" menu in the menu-bar
24 - Call [[sym:yas-insert-snippet][=yas-insert-snippet=]] (use =M-x yas-insert-snippet== or its
25 keybinding =C-c & C-s=).
27 - Use m2m's excellent auto-complete
28 TODO: example for this
30 - Expanding from emacs-lisp code
34 [[sym:yas-expand][=yas-expand=]] tries to expand a /snippet abbrev/ (also known as
35 /snippet key/) before point.
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:
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)
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,
50 [[./images/minor-mode-indicator.png]]
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.
56 *** Fallback behaviour
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.
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.
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.
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.
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=.
83 The prompting methods used are again controlled by
84 [[sym:yas-prompt-functions][=yas-prompt-functions=]].
88 See the section of the =# binding:= directive in
89 [[./snippet-development.org][Writing Snippets]].
91 ** Expanding from the menu
93 See [[./snippet-menu.org][the YASnippet Menu]].
95 ** Expanding with =hippie-expand=
97 To integrate with =hippie-expand=, just put
98 [[sym:yas-hippie-try-expand][=yas-hippie-try-expand=]] in
99 =hippie-expand-try-functions-list=. This probably makes more sense
100 when placed at the top of the list, but it can be put anywhere you
103 ** Expanding from emacs-lisp code
105 Sometimes you might want to expand a snippet directly from you own
106 elisp code. You should call
107 [[sym:yas-expand-snippet][=yas-expand-snippet=]] instead of
108 [[sym:yas-expand][=yas-expand=]] in this case.
110 As with expanding from the menubar, the condition system and multiple
111 candidates doesn't affect expansion. In fact, expanding from the
112 YASnippet menu has the same effect of evaluating the follow code:
114 #+BEGIN_SRC emacs-lisp
115 (yas-expand-snippet template)
118 See the internal documentation on [[sym:yas-expand-snippet][=yas-expand-snippet=]] for more
121 * Controlling expansion
125 YASnippet does quite a bit of filtering to find out which snippets are
126 eligible for expanding at the current cursor position.
128 In particular, the following things matter:
130 - Currently loaded snippets tables
132 These are loaded from a directory hierarchy in your file system. See
133 [[./snippet-organization.org][Organizing Snippets]]. They are named
134 after major modes like =html-mode=, =ruby-mode=, etc...
136 - Major mode of the current buffer
138 If the currrent major mode matches one of the loaded snippet tables,
139 then all that table's snippets are considered for expansion. Use
140 =M-x describe-variable RET major-mode RET= to find out which major
141 mode you are in currently.
145 Snippet tables defined as the parent of some other eligible table are
146 also considered. This works recursively, i.e. parents of parents of
147 eligible tables are also considered.
149 - Buffer-local list of extra modes
151 Use [[#yas-activate-extra-mode][=yas-activate-extra-mode=]] to
152 consider snippet tables whose name does not correspond to a major
153 mode. Typically, you call this from a minor mode hook, for example:
155 #+BEGIN_SRC emacs-lisp
156 ;; When entering rinari-minor-mode, consider also the snippets in the
157 ;; snippet table "rails-mode"
158 (add-hook 'rinari-minor-mode-hook
160 (yas-activate-extra-mode 'rails-mode)))
164 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]]
167 This variable provides finer grained control over what snippets can
168 be expanded in the current buffer. The default value won't let you
169 expand snippets inside comments or string literals for example. See
170 The condition system\_ for more info.
172 ** The condition system
174 Consider this scenario: you are an old Emacs hacker. You like the
175 abbrev-way and bind [[sym:yas-expand][=yas-expand=]] to =SPC=. However, you don't want
176 =if= to be expanded as a snippet when you are typing in a comment
177 block or a string (e.g. in =python-mode=).
179 If you use the =# condition := directive (see
180 [[./snippet-development.org][Writing Snippets]]) you could just specify
181 the condition for =if= to be =(not (python-in-string/comment))=. But how
182 about =while=, =for=, etc. ? Writing the same condition for all the
183 snippets is just boring. So has a buffer local variable
184 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]]. You can set this variable to
185 =(not (python-in-string/comment))= in =python-mode-hook=.
187 Then, what if you really want some particular snippet to expand even
188 inside a comment? Set [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] like this
190 #+BEGIN_SRC emacs-lisp
191 (add-hook 'python-mode-hook
193 (setq yas-buffer-local-condition
194 '(if (python-in-string/comment)
195 '(require-snippet-condition . force-in-comment)
199 ... and specify the condition for a snippet that you're going to expand
200 in comment to be evaluated to the symbol =force-in-comment=. Then it can
201 be expanded as you expected, while other snippets like =if= still can't
204 For the full set of possible conditions, see the documentation for
205 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]].
207 ** Multiples snippet with the same key
209 The rules outlined [[Eligible%20snippets][above]] can return more than
210 one snippet to be expanded at point.
212 When there are multiple candidates, YASnippet will let you select one.
213 The UI for selecting multiple candidate can be customized through
214 [[sym:yas-prompt-functions][=yas-prompt-functions=]] , which defines your preferred methods of being
215 prompted for snippets.
217 You can customize it with
218 =M-x customize-variable RET yas-prompt-functions RET=. Alternatively you
219 can put in your emacs-file:
221 #+BEGIN_SRC emacs-lisp
222 (setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt))
225 Currently there are some alternatives solution with YASnippet.
227 *** Use the X window system
229 [[./images/x-menu.png]]
231 The function [[sym:yas-x-prompt][=yas-x-prompt=]] can be used to show a popup menu for you to
232 select. This menu will be part of you native window system widget, which
235 - It usually looks beautiful. E.g. when you compile Emacs with gtk
236 support, this menu will be rendered with your gtk theme.
237 - Your window system may or may not allow to you use =C-n=, =C-p= to
239 - This function can't be used when in a terminal.
241 *** Minibuffer prompting
243 [[./images/ido-menu.png]]
245 You can use functions [[sym:yas-completing-prompt][=yas-completing-prompt=]] for the classic emacs
246 completion method or [[sym:yas-ido-prompt][=yas-ido-prompt=]] for a much nicer looking method.
247 The best way is to try it. This works in a terminal.
249 *** Use =dropdown-menu.el=
251 [[./images/dropdown-menu.png]]
253 The function [[sym:yas-dropdown-prompt][=yas-dropdown-prompt=]] can also be placed in the
254 [[sym:yas-prompt-functions][=yas-prompt-functions=]] list.
256 This works in both window system and terminal and is customizable, you
257 can use =C-n=, =C-p= to navigate, =q= to quit and even press =6= as a
258 shortcut to select the 6th candidate.
262 See the documentation on variable [[sym:yas-prompt-functions][=yas-prompt-functions=]]