1 #+SETUPFILE: org-setup.inc
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 =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 =yas-expand= tries to expand a /snippet abbrev/ (also known as
35 /snippet key/) before point.
37 When =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 [[./images/minor-mode-indicator.png]]
48 To enable the YASnippet minor mode in all buffers globally use the
49 command =yas-global-mode=.
51 When you use =yas-global-mode= you can also selectively disable
52 YASnippet in some buffers by setting the buffer-local variable
53 =yas-dont-active= in the buffer's mode hook.
55 **** Fallback bahaviour
57 =yas-fallback-behaviour= is a customization variable bound to
58 ='call-other-command= by default. If =yas-expand= failed to find any
59 suitable snippet to expand, it will disable the minor mode temporarily
60 and find if there's any other command bound the =yas-trigger-key=.
62 If found, the command will be called. Usually this works very well
63 --when there's a snippet, expand it, otherwise, call whatever command
64 originally bind to the trigger key.
66 However, you can change this behavior by customizing the
67 =yas-fallback-behavior= variable. If you set this variable to
68 ='return-nil=, it will return =nil= instead of trying to call the
69 /original/ command when no snippet is found.
73 The command =M-x yas-insert-snippet= lets you insert snippets at point
74 /for you current major mode/. It prompts you for the snippet key first,
75 and then for a snippet template if more than one template exists for the
78 The list presented contains the snippets that can be inserted at point,
79 according to the condition system. If you want to see all applicable
80 snippets for the major mode, prefix this command with =C-u=.
82 The prompting methods used are again controlled by
83 =yas-prompt-functions=.
85 *** Snippet keybinding
87 See the section of the =# binding:= directive in
88 [[snippet-development.html][Writing Snippets]].
90 *** Expanding from the menu
92 See [[snippet-menu.html][the YASnippet Menu]].
94 *** Expanding with =hippie-expand=
96 To integrate with =hippie-expand=, just put =yas-hippie-try-expand= in
97 =hippie-expand-try-functions-list=. This probably makes more sense when
98 placed at the top of the list, but it can be put anywhere you prefer.
100 *** Expanding from emacs-lisp code
102 Sometimes you might want to expand a snippet directly from you own elisp
103 code. You should call =yas-expand-snippet= instead of =yas-expand= in
106 As with expanding from the menubar, the condition system and multiple
107 candidates doesn't affect expansion. In fact, expanding from the
108 YASnippet menu has the same effect of evaluating the follow code:
110 See the internal documentation on =yas-expand-snippet= for more
113 ** Controlling expansion
115 *** Eligible snippets
117 YASnippet does quite a bit of filtering to find out which snippets are
118 eligible for expanding at the current cursor position.
120 In particular, the following things matter:
122 - Currently loaded snippets tables
124 These are loaded from a directory hierarchy in your file system. See
125 [[snippet-organization.html][Organizing Snippets]]. They are named
126 after major modes like =html-mode=, =ruby-mode=, etc...
128 - Major mode of the current buffer
130 If the currrent major mode matches one of the loaded snippet tables,
131 then all that table's snippets are considered for expansion. Use
132 =M-x describe-variable RET major-mode RET= to find out which major
133 mode you are in currently.
137 Snippet tables defined as the parent of some other eligible table are
138 also considered. This works recursively, i.e. parents of parents of
139 eligible tables are also considered.
141 - Buffer-local =yas-mode-symbol= variable
143 This can be used to consider snippet tables whose name does not
144 correspond to a major mode. If you set this variable to a name , like
145 =rinari-minor-mode=, you can have some snippets expand only in that
146 minor mode. Naturally, you want to set this conditionally, i.e. only
147 when entering that minor mode, so using a hook is a good idea.
149 - Buffer-local =yas-buffer-local-condition= variable
151 This variable provides finer grained control over what snippets can
152 be expanded in the current buffer. The default value won't let you
153 expand snippets inside comments or string literals for example. See
154 The condition system\_ for more info.
156 *** The condition system
158 Consider this scenario: you are an old Emacs hacker. You like the
159 abbrev-way and set =yas-trigger-key= to ="SPC"=. However, you don't want
160 =if= to be expanded as a snippet when you are typing in a comment block
161 or a string (e.g. in =python-mode=).
163 If you use the =# condition := directive (see
164 [[snippet-development.html][Writing Snippets]]) you could just specify
165 the condition for =if= to be =(not (python-in-string/comment))=. But how
166 about =while=, =for=, etc. ? Writing the same condition for all the
167 snippets is just boring. So has a buffer local variable
168 =yas-buffer-local-condition=. You can set this variable to
169 =(not (python-in-string/comment))= in =python-mode-hook=.
171 Then, what if you really want some particular snippet to expand even
172 inside a comment? This is also possible! But let's stop telling the
173 story and look at the rules:
175 - If =yas-buffer-local-condition= evaluate to nil, no snippets will be
176 considered for expansion.
178 - If it evaluates to the a /cons cell/ where the =car= is the symbol
179 =require-snippet-condition= and the =cdr= is a symbol (let's call it
180 =requirement=), then:
182 - Snippets having no =# condition:= directive won't be considered;
184 - Snippets with conditions that evaluate to nil (or produce an
185 error) won't be considered;
187 - If the snippet has a condition that evaluates to non-nil (let's
190 - If =requirement= is =t=, the snippet is ready to be expanded;
192 - If =requirement= is =eq= to =result=, the snippet is ready to
195 - Otherwise the snippet won't be considered.
197 - If it evaluates to the symbol =always=, all snippets are considered
198 for expansion, regardless of any conditions.
200 - If it evaluate to =t= or some other non-nil value:
202 - If the snippet has no condition, or has a condition that evaluate
203 to non-nil, it is ready to be expanded.
205 - Otherwise, it won't be considered.
207 In the mentioned scenario, set =yas-buffer-local-condition= like this
209 ... and specify the condition for a snippet that you're going to expand
210 in comment to be evaluated to the symbol =force-in-comment=. Then it can
211 be expanded as you expected, while other snippets like =if= still can't
214 *** Multiples snippet with the same key
216 The rules outlined [[Eligible%20snippets][above]] can return more than
217 one snippet to be expanded at point.
219 When there are multiple candidates, YASnippet will let you select one.
220 The UI for selecting multiple candidate can be customized through
221 =yas-prompt-functions= , which defines your preferred methods of being
222 prompted for snippets.
224 You can customize it with
225 =M-x customize-variable RET yas-prompt-functions RET=. Alternatively you
226 can put in your emacs-file:
228 Currently there are some alternatives solution with YASnippet.
230 [[images/x-menu.png]]
232 **** Use the X window system
234 The function =yas-x-prompt= can be used to show a popup menu for you to
235 select. This menu will be part of you native window system widget, which
238 - It usually looks beautiful. E.g. when you compile Emacs with gtk
239 support, this menu will be rendered with your gtk theme.
240 - Your window system may or may not allow to you use =C-n=, =C-p= to
242 - This function can't be used when in a terminal.
244 [[images/ido-menu.png]]
246 **** Minibuffer prompting
248 You can use functions =yas-completing-prompt= for the classic emacs
249 completion method or =yas-ido-prompt= for a much nicer looking method.
250 The best way is to try it. This works in a terminal.
252 [[images/dropdown-menu.png]]
254 **** Use =dropdown-menu.el=
256 The function =yas-dropdown-prompt= can also be placed in the
257 =yas-prompt-functions= list.
259 This works in both window system and terminal and is customizable, you
260 can use =C-n=, =C-p= to navigate, =q= to quit and even press =6= as a
261 shortcut to select the 6th candidate.
265 See below for the documentation on variable =yas-prompt-functions=
267 ** Customizable Variables
269 *** =yas-prompt-functions=
271 You can write a function and add it to the =yas-prompt-functions= list.
272 These functions are called with the following arguments:
274 - PROMPT: A string to prompt the user;
276 - CHOICES: A list of strings or objects;
278 - optional DISPLAY-FN : A function. When applied to each of the objects
279 in CHOICES it will return a string;
281 The return value of any function you put here should be one of the
282 objects in CHOICES, properly formatted with DISPLAY-FN (if that is
285 - To signal that your particular style of prompting is unavailable at
286 the moment, you can also have the function return nil.
288 - To signal that the user quit the prompting process, you can signal
289 =quit= with =(signal 'quit "user quit!")=
291 *** =yas-fallback-behavior=
293 How to act when =yas-expand= does /not/ expand a snippet.
295 - =call-other-command= means try to temporarily disable YASnippet
296 and :: call the next command bound to =yas-trigger-key=.
298 =return-nil= means return nil. (i.e. do nothing)
300 An entry (apply COMMAND . ARGS) means interactively call COMMAND, if
301 ARGS is non-nil, call COMMAND non-interactively with ARGS as arguments.
303 *** =yas-choose-keys-first=
305 If non-nil, prompt for snippet key first, then for template.
307 Otherwise prompts for all possible snippet names.
309 This affects =yas-insert-snippet= and =yas-visit-snippet-file=.
311 *** =yas-choose-tables-first=
313 If non-nil, and multiple eligible snippet tables, prompts user for
316 Otherwise, user chooses between the merging together of all eligible
319 This affects =yas-insert-snippet=, =yas-visit-snippet-file=
321 *** =yas-key-syntaxes=
323 The default searching strategy is quite powerful. For example, in
324 =c-mode=, =bar=, =foo_bar=, ="#foo_bar"= can all be recognized as a
325 snippet key. Furthermore, the searching is in that order. In other
326 words, if =bar= is found to be a key to some /valid/ snippet, then that
327 snippet is expanded and replaces the =bar=. Snippets pointed to by
328 =foo_bar= and ="#foobar= won't be considered.
330 However, this strategy can also be customized easily from the
331 =yas-key-syntaxes= variable. It is a list of syntax rules, the default
332 value is =("w" "w_" "w_." "^ ")=. Which means search the following thing
336 - a symbol. In lisp, =-= and =?= can all be part of a symbol.
337 - a sequence of characters of either word, symbol or punctuation.
338 - a sequence of characters of non-whitespace characters.
340 But you'd better keep the default value unless you want to understand
341 how Emacs's syntax rules work...