3 ** Triggering expansion
5 You can use YASnippet to expand snippets in different ways:
7 - By typing an abbrev, the snippet /trigger key/, and then pressing the
8 key defined in =yas-trigger-key= (which defaults to "TAB"). This
9 works in buffers where the minor mode =yas-minor-mode= is active;
11 - By invoking the command =yas-insert-snippet= (either by typing
12 =M-x yas-insert-snippet= or its keybinding). This does /not/ require
13 =yas-minor-mode= to be active.
15 - By using the keybinding associated with an active snippet. This also
16 requires =yas-minor-mode= to be active;
18 - By expanding directly from the "YASnippet" menu in the menu-bar
20 - By using hippie-expand
22 - Expanding from emacs-lisp code
26 When =yas-minor-mode= is enabled, the keybinding taken from
27 =yas-trigger-key= will take effect.
29 =yas-trigger-key= invokes =yas-expand=, which tries to expand a /snippet
30 abbrev/ (also known as /snippet key/) before point.
32 The default key is ="TAB"=, however, you can freely set it to some other
35 [[images/minor-mode-indicator.png]]
37 To enable the YASnippet minor mode in all buffers globally use the
38 command =yas-global-mode=.
40 When you use =yas-global-mode= you can also selectively disable
41 YASnippet in some buffers by setting the buffer-local variable
42 =yas-dont-active= in the buffer's mode hook.
44 Trouble when using or understanding the =yas-trigger-key= is easily the
45 most controversial issue in YASsnippet. See the [[faq.html][FAQ]].
47 **** Fallback bahaviour
49 =yas-fallback-behaviour= is a customization variable bound to
50 ='call-other-command= by default. If =yas-expand= failed to find any
51 suitable snippet to expand, it will disable the minor mode temporarily
52 and find if there's any other command bound the =yas-trigger-key=.
54 If found, the command will be called. Usually this works very well
55 --when there's a snippet, expand it, otherwise, call whatever command
56 originally bind to the trigger key.
58 However, you can change this behavior by customizing the
59 =yas-fallback-behavior= variable. If you set this variable to
60 ='return-nil=, it will return =nil= instead of trying to call the
61 /original/ command when no snippet is found.
65 The command =M-x yas-insert-snippet= lets you insert snippets at point
66 /for you current major mode/. It prompts you for the snippet key first,
67 and then for a snippet template if more than one template exists for the
70 The list presented contains the snippets that can be inserted at point,
71 according to the condition system. If you want to see all applicable
72 snippets for the major mode, prefix this command with =C-u=.
74 The prompting methods used are again controlled by
75 =yas-prompt-functions=.
77 *** Snippet keybinding
79 See the section of the =# binding:= directive in
80 [[snippet-development.html][Writing Snippets]].
82 *** Expanding from the menu
84 See [[snippet-menu.html][the YASnippet Menu]].
86 *** Expanding with =hippie-expand=
88 To integrate with =hippie-expand=, just put =yas-hippie-try-expand= in
89 =hippie-expand-try-functions-list=. This probably makes more sense when
90 placed at the top of the list, but it can be put anywhere you prefer.
92 *** Expanding from emacs-lisp code
94 Sometimes you might want to expand a snippet directly from you own elisp
95 code. You should call =yas-expand-snippet= instead of =yas-expand= in
98 As with expanding from the menubar, the condition system and multiple
99 candidates doesn't affect expansion. In fact, expanding from the
100 YASnippet menu has the same effect of evaluating the follow code:
102 See the internal documentation on =yas-expand-snippet= for more
105 ** Controlling expansion
107 *** Eligible snippets
109 YASnippet does quite a bit of filtering to find out which snippets are
110 eligible for expanding at the current cursor position.
112 In particular, the following things matter:
114 - Currently loaded snippets tables
116 These are loaded from a directory hierarchy in your file system. See
117 [[snippet-organization.html][Organizing Snippets]]. They are named
118 after major modes like =html-mode=, =ruby-mode=, etc...
120 - Major mode of the current buffer
122 If the currrent major mode matches one of the loaded snippet tables,
123 then all that table's snippets are considered for expansion. Use
124 =M-x describe-variable RET major-mode RET= to find out which major
125 mode you are in currently.
129 Snippet tables defined as the parent of some other eligible table are
130 also considered. This works recursively, i.e. parents of parents of
131 eligible tables are also considered.
133 - Buffer-local =yas-mode-symbol= variable
135 This can be used to consider snippet tables whose name does not
136 correspond to a major mode. If you set this variable to a name , like
137 =rinari-minor-mode=, you can have some snippets expand only in that
138 minor mode. Naturally, you want to set this conditionally, i.e. only
139 when entering that minor mode, so using a hook is a good idea.
141 - Buffer-local =yas-buffer-local-condition= variable
143 This variable provides finer grained control over what snippets can
144 be expanded in the current buffer. The default value won't let you
145 expand snippets inside comments or string literals for example. See
146 The condition system\_ for more info.
148 *** The condition system
150 Consider this scenario: you are an old Emacs hacker. You like the
151 abbrev-way and set =yas-trigger-key= to ="SPC"=. However, you don't want
152 =if= to be expanded as a snippet when you are typing in a comment block
153 or a string (e.g. in =python-mode=).
155 If you use the =# condition := directive (see
156 [[snippet-development.html][Writing Snippets]]) you could just specify
157 the condition for =if= to be =(not (python-in-string/comment))=. But how
158 about =while=, =for=, etc. ? Writing the same condition for all the
159 snippets is just boring. So has a buffer local variable
160 =yas-buffer-local-condition=. You can set this variable to
161 =(not (python-in-string/comment))= in =python-mode-hook=.
163 Then, what if you really want some particular snippet to expand even
164 inside a comment? This is also possible! But let's stop telling the
165 story and look at the rules:
167 - If =yas-buffer-local-condition= evaluate to nil, no snippets will be
168 considered for expansion.
170 - If it evaluates to the a /cons cell/ where the =car= is the symbol
171 =require-snippet-condition= and the =cdr= is a symbol (let's call it
172 =requirement=), then:
174 - Snippets having no =# condition:= directive won't be considered;
176 - Snippets with conditions that evaluate to nil (or produce an
177 error) won't be considered;
179 - If the snippet has a condition that evaluates to non-nil (let's
182 - If =requirement= is =t=, the snippet is ready to be expanded;
184 - If =requirement= is =eq= to =result=, the snippet is ready to
187 - Otherwise the snippet won't be considered.
189 - If it evaluates to the symbol =always=, all snippets are considered
190 for expansion, regardless of any conditions.
192 - If it evaluate to =t= or some other non-nil value:
194 - If the snippet has no condition, or has a condition that evaluate
195 to non-nil, it is ready to be expanded.
197 - Otherwise, it won't be considered.
199 In the mentioned scenario, set =yas-buffer-local-condition= like this
201 ... and specify the condition for a snippet that you're going to expand
202 in comment to be evaluated to the symbol =force-in-comment=. Then it can
203 be expanded as you expected, while other snippets like =if= still can't
206 *** Multiples snippet with the same key
208 The rules outlined [[Eligible%20snippets][above]] can return more than
209 one snippet to be expanded at point.
211 When there are multiple candidates, YASnippet will let you select one.
212 The UI for selecting multiple candidate can be customized through
213 =yas-prompt-functions= , which defines your preferred methods of being
214 prompted for snippets.
216 You can customize it with
217 =M-x customize-variable RET yas-prompt-functions RET=. Alternatively you
218 can put in your emacs-file:
220 Currently there are some alternatives solution with YASnippet.
222 [[images/x-menu.png]]
224 **** Use the X window system
226 The function =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
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
234 - This function can't be used when in a terminal.
236 [[images/ido-menu.png]]
238 **** Minibuffer prompting
240 You can use functions =yas-completing-prompt= for the classic emacs
241 completion method or =yas-ido-prompt= for a much nicer looking method.
242 The best way is to try it. This works in a terminal.
244 [[images/dropdown-menu.png]]
246 **** Use =dropdown-menu.el=
248 The function =yas-dropdown-prompt= can also be placed in the
249 =yas-prompt-functions= list.
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.
257 See below for the documentation on variable =yas-prompt-functions=
259 ** Customizable Variables
261 *** =yas-prompt-functions=
263 You can write a function and add it to the =yas-prompt-functions= list.
264 These functions are called with the following arguments:
266 - PROMPT: A string to prompt the user;
268 - CHOICES: A list of strings or objects;
270 - optional DISPLAY-FN : A function. When applied to each of the objects
271 in CHOICES it will return a string;
273 The return value of any function you put here should be one of the
274 objects in CHOICES, properly formatted with DISPLAY-FN (if that is
277 - To signal that your particular style of prompting is unavailable at
278 the moment, you can also have the function return nil.
280 - To signal that the user quit the prompting process, you can signal
281 =quit= with =(signal 'quit "user quit!")=
283 *** =yas-fallback-behavior=
285 How to act when =yas-expand= does /not/ expand a snippet.
287 - =call-other-command= means try to temporarily disable YASnippet
288 and :: call the next command bound to =yas-trigger-key=.
290 =return-nil= means return nil. (i.e. do nothing)
292 An entry (apply COMMAND . ARGS) means interactively call COMMAND, if
293 ARGS is non-nil, call COMMAND non-interactively with ARGS as arguments.
295 *** =yas-choose-keys-first=
297 If non-nil, prompt for snippet key first, then for template.
299 Otherwise prompts for all possible snippet names.
301 This affects =yas-insert-snippet= and =yas-visit-snippet-file=.
303 *** =yas-choose-tables-first=
305 If non-nil, and multiple eligible snippet tables, prompts user for
308 Otherwise, user chooses between the merging together of all eligible
311 This affects =yas-insert-snippet=, =yas-visit-snippet-file=
313 *** =yas-key-syntaxes=
315 The default searching strategy is quite powerful. For example, in
316 =c-mode=, =bar=, =foo_bar=, ="#foo_bar"= can all be recognized as a
317 snippet key. Furthermore, the searching is in that order. In other
318 words, if =bar= is found to be a key to some /valid/ snippet, then that
319 snippet is expanded and replaces the =bar=. Snippets pointed to by
320 =foo_bar= and ="#foobar= won't be considered.
322 However, this strategy can also be customized easily from the
323 =yas-key-syntaxes= variable. It is a list of syntax rules, the default
324 value is =("w" "w_" "w_." "^ ")=. Which means search the following thing
328 - a symbol. In lisp, =-= and =?= can all be part of a symbol.
329 - a sequence of characters of either word, symbol or punctuation.
330 - a sequence of characters of non-whitespace characters.
332 But you'd better keep the default value unless you want to understand
333 how Emacs's syntax rules work...