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=]].
86 *** Inserting region or register contents into snippet
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.
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=.
101 See the section of the =# binding:= directive in
102 [[./snippet-development.org][Writing Snippets]].
104 ** Expanding from the menu
106 See [[./snippet-menu.org][the YASnippet Menu]].
108 ** Expanding with =hippie-expand=
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
116 ** Expanding from emacs-lisp code
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.
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:
129 #+BEGIN_SRC emacs-lisp
130 (yas-expand-snippet template)
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.
136 * Controlling expansion
140 YASnippet does quite a bit of filtering to find out which snippets are
141 eligible for expanding at the current cursor position.
143 In particular, the following things matter:
145 - Currently loaded snippets tables
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...
151 - Major mode of the current buffer
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.
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.
164 - Buffer-local list of extra modes
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:
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
175 (yas-activate-extra-mode 'rails-mode)))
179 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]]
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.
187 ** The condition system
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=).
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=.
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
205 #+BEGIN_SRC emacs-lisp
206 (add-hook 'python-mode-hook
208 (setq yas-buffer-local-condition
209 '(if (python-in-string/comment)
210 '(require-snippet-condition . force-in-comment)
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
219 For the full set of possible conditions, see the documentation for
220 [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]].
222 ** Multiples snippet with the same key
224 The rules outlined [[Eligible%20snippets][above]] can return more than
225 one snippet to be expanded at point.
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.
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:
236 #+BEGIN_SRC emacs-lisp
237 (setq yas-prompt-functions '(yas-x-prompt yas-dropdown-prompt))
240 Currently there are some alternatives solution with YASnippet.
242 *** Use the X window system
244 [[./images/x-menu.png]]
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
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
254 - This function can't be used when in a terminal.
256 *** Minibuffer prompting
258 [[./images/ido-menu.png]]
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.
264 *** Use =dropdown-menu.el=
266 [[./images/dropdown-menu.png]]
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.
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.
277 See the documentation on variable [[sym:yas-prompt-functions][=yas-prompt-functions=]]