1 #+SETUPFILE: org-setup.inc
6 This section describes how YASnippet chooses snippets for expansion at point.
8 Maybe, you'll want some snippets to be expanded in a particular
9 mode, or only under certain conditions, or be prompted using
11 ** Triggering expansion
13 You can use YASnippet to expand snippets in different ways:
15 - When [[sym:yas-minor-mode][=yas-minor-mode=]] is active:
16 - Type the snippet's *trigger key* then calling [[sym:yas-expand][=yas-expand=]]
17 (bound to =TAB= by default).
19 - Use the snippet's *keybinding*.
21 - By expanding directly from the "YASnippet" menu in the menu-bar
25 - Call [[sym:yas-insert-snippet][=yas-insert-snippet=]] (use =M-x yas-insert-snippet== or its
26 keybinding =C-c & C-s=).
28 - Use m2m's excellent auto-complete
29 TODO: example for this
31 - Expanding from emacs-lisp code
35 [[sym:yas-expand][=yas-expand=]] tries to expand a /snippet abbrev/ (also known as
36 /snippet key/) before point.
38 When [[sym:yas-minor-mode][=yas-minor-mode=]] is enabled, it binds [[sym:yas-expand][=yas-expand=]] to =TAB= and
39 =<tab>= by default, however, you can freely set it to some other key:
41 #+begin_src emacs-lisp :exports code
42 (define-key yas-minor-mode-map (kbd "<tab>") nil)
43 (define-key yas-minor-mode-map (kbd "TAB") nil)
44 (define-key yas-minor-mode-map (kbd "<the new key>") 'yas-expand)
47 To enable the YASnippet minor mode in all buffers globally use the
48 command [[sym:yas-global-mode][=yas-global-mode=]]. This will enable a modeline indicator,
51 [[./images/minor-mode-indicator.png]]
53 When you use [[sym:yas-global-mode][=yas-global-mode=]] you can also selectively disable
54 YASnippet in some buffers by setting the buffer-local variable
55 [[sym:yas-dont-active][=yas-dont-active=]] in the buffer's mode hook.
57 **** Fallback bahaviour
59 [[sym:yas-fallback-behaviour][=yas-fallback-behaviour=]] is a customization variable bound to
60 '=call-other-command= by default. If [[sym:yas-expand][=yas-expand=]] failed to find any
61 suitable snippet to expand, it will disable the minor mode temporarily
62 and find if there's any other command bound to the same key.
64 If found, the command will be called. Usually this works very well
65 --when there's a snippet, expand it, otherwise, call whatever command
66 originally bind to the trigger key.
68 However, you can change this behavior by customizing the
69 [[sym:yas-fallback-behavior][=yas-fallback-behavior=]] variable. If you set this variable to
70 '=return-nil=, it will return =nil= instead of trying to call the
71 /original/ command when no snippet is found.
75 The command =M-x yas-insert-snippet= lets you insert snippets at point
76 /for you current major mode/. It prompts you for the snippet key first,
77 and then for a snippet template if more than one template exists for the
80 The list presented contains the snippets that can be inserted at point,
81 according to the condition system. If you want to see all applicable
82 snippets for the major mode, prefix this command with =C-u=.
84 The prompting methods used are again controlled by
85 [[sym:yas-prompt-functions][=yas-prompt-functions=]].
87 *** Snippet keybinding
89 See the section of the =# binding:= directive in
90 [[./snippet-development.org][Writing Snippets]].
92 *** Expanding from the menu
94 See [[./snippet-menu.org][the YASnippet Menu]].
96 *** Expanding with =hippie-expand=
98 To integrate with =hippie-expand=, just put [[sym:yas-hippie-try-expand][=yas-hippie-try-expand=]] in
99 =hippie-expand-try-functions-list=. This probably makes more sense when
100 placed at the top of the list, but it can be put anywhere you prefer.
102 *** Expanding from emacs-lisp code
104 Sometimes you might want to expand a snippet directly from you own elisp
105 code. You should call [[sym:yas-expand-snippet][=yas-expand-snippet=]] instead of [[sym:yas-expand][=yas-expand=]] in
108 As with expanding from the menubar, the condition system and multiple
109 candidates doesn't affect expansion. In fact, expanding from the
110 YASnippet menu has the same effect of evaluating the follow code:
112 #+BEGIN_SRC emacs-lisp
113 (yas-expand-snippet template)
116 See the internal documentation on [[sym:yas-expand-snippet][=yas-expand-snippet=]] for more
119 ** Controlling expansion
121 *** Eligible snippets
123 YASnippet does quite a bit of filtering to find out which snippets are
124 eligible for expanding at the current cursor position.
126 In particular, the following things matter:
128 - Currently loaded snippets tables
130 These are loaded from a directory hierarchy in your file system. See
131 [[./snippet-organization.org][Organizing Snippets]]. They are named
132 after major modes like =html-mode=, =ruby-mode=, etc...
134 - Major mode of the current buffer
136 If the currrent major mode matches one of the loaded snippet tables,
137 then all that table's snippets are considered for expansion. Use
138 =M-x describe-variable RET major-mode RET= to find out which major
139 mode you are in currently.
143 Snippet tables defined as the parent of some other eligible table are
144 also considered. This works recursively, i.e. parents of parents of
145 eligible tables are also considered.
147 - Buffer-local list of extra modes
149 Use [[#yas-activate-extra-mode][=yas-activate-extra-mode=]] to consider snippet tables whose name
150 does not correspond to a major mode. Typically, you call this from
151 a minor mode hook, for example:
153 #+BEGIN_SRC emacs-lisp
154 ;; When entering rinari-minor-mode, consider also the snippets in the
155 ;; snippet table "rails-mode"
156 (add-hook 'rinari-minor-mode-hook
158 (yas-activate-extra-mode 'rails-mode)))
161 - Buffer-local [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] variable
163 This variable provides finer grained control over what snippets can
164 be expanded in the current buffer. The default value won't let you
165 expand snippets inside comments or string literals for example. See
166 The condition system\_ for more info.
168 *** The condition system
170 Consider this scenario: you are an old Emacs hacker. You like the
171 abbrev-way and bind [[sym:yas-expand][=yas-expand=]] to =SPC=. However, you don't want
172 =if= to be expanded as a snippet when you are typing in a comment
173 block or a string (e.g. in =python-mode=).
175 If you use the =# condition := directive (see
176 [[./snippet-development.org][Writing Snippets]]) you could just specify
177 the condition for =if= to be =(not (python-in-string/comment))=. But how
178 about =while=, =for=, etc. ? Writing the same condition for all the
179 snippets is just boring. So has a buffer local variable
180 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]]. You can set this variable to
181 =(not (python-in-string/comment))= in =python-mode-hook=.
183 Then, what if you really want some particular snippet to expand even
184 inside a comment? This is also possible! But let's stop telling the
185 story and look at the rules:
187 - If [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] evaluate to nil, no snippets will be
188 considered for expansion.
190 - If it evaluates to the a /cons cell/ where the =car= is the symbol
191 =require-snippet-condition= and the =cdr= is a symbol (let's call it
192 =requirement=), then:
194 - Snippets having no =# condition:= directive won't be considered;
196 - Snippets with conditions that evaluate to nil (or produce an
197 error) won't be considered;
199 - If the snippet has a condition that evaluates to non-nil (let's
202 - If =requirement= is =t=, the snippet is ready to be expanded;
204 - If =requirement= is =eq= to =result=, the snippet is ready to
207 - Otherwise the snippet won't be considered.
209 - If it evaluates to the symbol =always=, all snippets are considered
210 for expansion, regardless of any conditions.
212 - If it evaluate to =t= or some other non-nil value:
214 - If the snippet has no condition, or has a condition that evaluate
215 to non-nil, it is ready to be expanded.
217 - Otherwise, it won't be considered.
219 In the mentioned scenario, set [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] like this
221 #+BEGIN_SRC emacs-lisp
222 (add-hook 'python-mode-hook
224 (setq yas-buffer-local-condition
225 '(if (python-in-string/comment)
226 '(require-snippet-condition . force-in-comment)
230 ... and specify the condition for a snippet that you're going to expand
231 in comment to be evaluated to the symbol =force-in-comment=. Then it can
232 be expanded as you expected, while other snippets like =if= still can't
235 *** Multiples snippet with the same key
237 The rules outlined [[Eligible%20snippets][above]] can return more than
238 one snippet to be expanded at point.
240 When there are multiple candidates, YASnippet will let you select one.
241 The UI for selecting multiple candidate can be customized through
242 [[sym:yas-prompt-functions][=yas-prompt-functions=]] , which defines your preferred methods of being
243 prompted for snippets.
245 You can customize it with
246 =M-x customize-variable RET yas-prompt-functions RET=. Alternatively you
247 can put in your emacs-file:
249 #+BEGIN_SRC emacs-lisp
250 (setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt))
253 Currently there are some alternatives solution with YASnippet.
255 **** Use the X window system
257 [[./images/x-menu.png]]
259 The function [[sym:yas-x-prompt][=yas-x-prompt=]] can be used to show a popup menu for you to
260 select. This menu will be part of you native window system widget, which
263 - It usually looks beautiful. E.g. when you compile Emacs with gtk
264 support, this menu will be rendered with your gtk theme.
265 - Your window system may or may not allow to you use =C-n=, =C-p= to
267 - This function can't be used when in a terminal.
269 **** Minibuffer prompting
271 [[./images/ido-menu.png]]
273 You can use functions [[sym:yas-completing-prompt][=yas-completing-prompt=]] for the classic emacs
274 completion method or [[sym:yas-ido-prompt][=yas-ido-prompt=]] for a much nicer looking method.
275 The best way is to try it. This works in a terminal.
277 **** Use =dropdown-menu.el=
279 [[./images/dropdown-menu.png]]
281 The function [[sym:yas-dropdown-prompt][=yas-dropdown-prompt=]] can also be placed in the
282 [[sym:yas-prompt-functions][=yas-prompt-functions=]] list.
284 This works in both window system and terminal and is customizable, you
285 can use =C-n=, =C-p= to navigate, =q= to quit and even press =6= as a
286 shortcut to select the 6th candidate.
290 See the documentation on variable [[sym:yas-prompt-functions][=yas-prompt-functions=]]