1 #+SETUPFILE: org-setup.inc
3 #+TITLE: Writing snippets
7 ** Quickly finding snippets
9 There are some ways you can quickly find a snippet file or create a new one:
11 - =M-x yas-new-snippet=
13 Creates a new buffer with a template for making a new snippet.
14 The buffer is in =snippet-mode= (see below). When you are done
15 editing the new snippet, use =C-c C-c= to save it. This will
16 prompt for a directory two steps: first, the snippet table
17 (with a default based on the major mode you started in), and then
18 then snippet collection directory (defaults to the first directory
19 in =yas-snippet-dirs=. (See [[file:snippet-organization.org][Organizing Snippets]]
20 for more detail on how snippets are organized.)
22 - =M-x yas-find-snippets=
24 Lets you find the snippet file in the directory the snippet was
25 loaded from (if it exists) like =find-file-other-window=. The
26 directory searching logic is similar to =M-x yas-new-snippet=.
28 - =M-x yas-visit-snippet-file=
30 Prompts you for possible snippet expansions like
31 [[sym:yas-insert-snippet][=yas-insert-snippet=]], but instead of expanding it, takes you directly
32 to the snippet definition's file, if it exists.
34 Once you find this file it will be set to =snippet-mode= (see ahead) and
35 you can start editing your snippet.
37 ** Using the =snippet-mode= major mode
39 There is a major mode =snippet-mode= to edit snippets. You can set the
40 buffer to this mode with =M-x snippet-mode=. It provides reasonably
41 useful syntax highlighting.
43 Two commands are defined in this mode:
45 - =M-x yas-load-snippet-buffer=
47 When editing a snippet, this loads the snippet into the correct
48 mode and menu. Bound to =C-c C-c= by default while in
51 - =M-x yas-tryout-snippet=
53 When editing a snippet, this opens a new empty buffer, sets it to
54 the appropriate major mode and inserts the snippet there, so you
55 can see what it looks like. This is bound to =C-c C-t= while in
58 There are also /snippets for writing snippets/: =vars=, =$f= and =$m=
63 A file defining a snippet generally contains the template to be
66 Optionally, if the file contains a line of =# --=, the lines above it
67 count as comments, some of which can be /directives/ (or meta data).
68 Snippet directives look like =# property: value= and tweak certain
69 snippets properties described below. If no =# --= is found, the whole
70 file is considered the snippet template.
72 Here's a typical example:
75 # contributor: pluskid <pluskid@gmail.com>
81 Here's a list of currently supported directives:
83 ** =# key:= snippet abbrev
85 This is the probably the most important directive, it's the
86 abbreviation you type to expand a snippet just before hitting the key
87 that runs [[sym:yas-expand][=yas-expand=]]. If you don't specify this
88 the snippet will not be expandable through the trigger mechanism.
90 ** =# name:= snippet name
92 This is a one-line description of the snippet. It will be displayed in
93 the menu. It's a good idea to select a descriptive name for a snippet --
94 especially distinguishable among similar snippets.
96 If you omit this name it will default to the file name the snippet was
99 ** =# condition:= snippet condition
101 This is a piece of Emacs-lisp code. If a snippet has a condition, then
102 it will only be expanded when the condition code evaluate to some
105 See also [[sym:yas-buffer-local-condition][=yas-buffer-local-condition=]] in
106 [[./snippet-expansion.org][Expanding snippets]]
108 ** =# group:= snippet menu grouping
110 When expanding/visiting snippets from the menu-bar menu, snippets for a
111 given mode can be grouped into sub-menus . This is useful if one has too
112 many snippets for a mode which will make the menu too long.
114 The =# group:= property only affect menu construction (See
115 [[./snippet-menu.org][the YASnippet menu]]) and the same effect can be
116 achieved by grouping snippets into sub-directories and using the
117 =.yas-make-groups= special file (for this see
118 [[./snippet-organization.org][Organizing Snippets]]
120 Refer to the bundled snippets for =ruby-mode= for examples on the
121 =# group:= directive. Group can also be nested, e.g.
122 =control structure.loops= tells that the snippet is under the =loops=
123 group which is under the =control structure= group.
125 ** =# expand-env:= expand environment
127 This is another piece of Emacs-lisp code in the form of a =let= /varlist
128 form/, i.e. a list of lists assigning values to variables. It can be
129 used to override variable values while the snippet is being expanded.
131 Interesting variables to override are [[sym:yas-wrap-around-region][=yas-wrap-around-region=]] and
132 [[sym:yas-indent-line][=yas-indent-line=]] (see [[./snippet-expansion.org][Expanding Snippets]]).
134 As an example, you might normally have [[sym:yas-indent-line][=yas-indent-line=]] set to '=auto=
135 and [[sym:yas-wrap-around-region][=yas-wrap-around-region=]] set to =t=, but for this particularly
136 brilliant piece of ASCII art these values would mess up your hard work.
141 # expand-env: ((yas-indent-line 'fixed) (yas-wrap-around-region 'nil))
155 ** =# binding:= direct keybinding
157 You can use this directive to expand a snippet directly from a normal
158 Emacs keybinding. The keybinding will be registered in the Emacs keymap
159 named after the major mode the snippet is active for.
161 Additionally a variable [[sym:yas-prefix][=yas-prefix=]] is set to to the prefix argument
162 you normally use for a command. This allows for small variations on the
163 same snippet, for example in this "html-mode" snippet.
167 # binding: C-c C-c C-m
169 <p>`(when yas-prefix "\n")`$0`(when yas-prefix "\n")`</p>
172 This binding will be recorded in the keymap =html-mode-map=. To expand a
173 paragraph tag newlines, just press =C-u C-c C-c C-m=. Omitting the =C-u=
174 will expand the paragraph tag without newlines.
176 ** =# type:= =snippet= or =command=
178 If the =type= directive is set to =command=, the body of the snippet
179 is interpreted as lisp code to be evaluated when the snippet is
182 If it's =snippet= (the default when there is no =type= directive), the
183 snippet body will be parsed according to the [[Template Syntax]],
186 ** =# uuid:= unique identifier
188 This provides to a way to identify a snippet, independent of its name.
189 Loading a second snippet file with the same uuid would replace the
192 ** =# contributor:= snippet author
194 This is optional and has no effect whatsoever on snippet functionality,
197 * <<Template syntax>>
199 The syntax of the snippet template is simple but powerful, very similar
204 Arbitrary text can be included as the content of a template. They are
205 usually interpreted as plain text, except =$= and =`=. You need to
206 use =\= to escape them: =\$= and =\`=. The =\= itself may also needed to be
207 escaped as =\\= sometimes.
209 ** Embedded Emacs-lisp code
211 Emacs-Lisp code can be embedded inside the template, written inside
212 back-quotes (=`=). The lisp forms are evaluated when the snippet is
213 being expanded. The evaluation is done in the same buffer as the
214 snippet being expanded.
216 Here's an example for c-mode` to calculate the header file guard
220 #ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
228 From version 0.6, snippets expansions are run with some special
229 Emacs-lisp variables bound. One of this is [[sym:yas-selected-text][=yas-selected-text=]]. You can
230 therefore define a snippet like:
234 `yas-selected-text`$0
238 to "wrap" the selected region inside your recently inserted snippet.
239 Alternatively, you can also customize the variable
240 [[sym:yas-wrap-around-region][=yas-wrap-around-region=]] to =t= which will do this automatically.
244 Tab stops are fields that you can navigate back and forth by =TAB= and
245 =S-TAB=. They are written by =$= followed with a number. =$0= has the
246 special meaning of the /exit point/ of a snippet. That is the last place
247 to go when you've traveled all the fields. Here's a typical example:
254 ** Placeholder fields
256 Tab stops can have default values -- a.k.a placeholders. The syntax is
263 They acts as the default value for a tab stop. But when you firstly
264 type at a tab stop, the default value will be replaced by your typing.
265 The number can be omitted if you don't want to create [[mirrors]] or
266 [[transformations]] for this field.
270 We refer the tab stops with placeholders as a /field/. A field can have
271 mirrors. Its mirrors will get updated when you change the text of a
272 field. Here's an example:
275 \begin{${1:enumerate}}
280 When you type "document" at =${1:enumerate}=, the word "document" will
281 also be inserted at =\end{$1}=. The best explanation is to see the
282 screencast([[http://www.youtube.com/watch?v=vOj7btx3ATg][YouTube]] or [[http://yasnippet.googlecode.com/files/yasnippet.avi][avi video]]).
284 The tab stops with the same number to the field act as its mirrors. If
285 none of the tab stops has an initial value, the first one is selected as
286 the field and others mirrors.
288 ** Mirrors with <<transformations>>
290 If the value of an =${n:=-construct starts with and contains =$(=,
291 then it is interpreted as a mirror for field =n= with a
292 transformation. The mirror's text content is calculated according to
293 this transformation, which is Emacs-lisp code that gets evaluated in
294 an environment where the variable [[sym:yas-text][=yas-text=]] is bound to the text
295 content (string) contained in the field =n=. Here's an example for
304 - (void)set${2:$(capitalize yas-text)}:($1)aValue
307 $2 = [aValue retain];
312 Look at =${2:$(capitalize yas-text)}=, it is a mirror with
313 transformation instead of a field. The actual field is at the first
314 line: =${2:foo}=. When you type text in =${2:foo}=, the transformation
315 will be evaluated and the result will be placed there as the
316 transformed text. So in this example, if you type "baz" in the field,
317 the transformed text will be "Baz". This example is also available in
320 Another example is for =rst-mode=. In reStructuredText, the document
321 title can be some text surrounded by "===" below and above. The "==="
322 should be at least as long as the text. So
338 is not. Here's an snippet for rst title:
341 ${1:$(make-string (string-width yas-text) ?\=)}
343 ${1:$(make-string (string-width yas-text) ?\=)}
348 ** Fields with transformations
350 From version 0.6 on, you can also have lisp transformation inside
351 fields. These work mostly mirror transformations but are evaluated when
352 you first enter the field, after each change you make to the field and
353 also just before you exit the field.
355 The syntax is also a tiny bit different, so that the parser can
356 distinguish between fields and mirrors. In the following example
358 : #define "${1:mydefine$(upcase yas-text)}"
360 =mydefine= gets automatically upcased to =MYDEFINE= once you enter the
361 field. As you type text, it gets filtered through the transformation
364 Note that to tell this kind of expression from a mirror with a
365 transformation, YASnippet needs extra text between the =:= and the
366 transformation's =$=. If you don't want this extra-text, you can use two
369 : #define "${1:$$(upcase yas-text)}"
371 Please note that as soon as a transformation takes place, it changes the
372 value of the field and sets it its internal modification state to
373 =true=. As a consequence, the auto-deletion behaviour of normal fields
374 does not take place. This is by design.
376 ** Choosing fields value from a list and other tricks
378 As mentioned, the field transformation is invoked just after you enter
379 the field, and with some useful variables bound, notably
380 [[sym:yas-modified-p][=yas-modified-p=]] and [[sym:yas-moving-away-p][=yas-moving-away-p=]]. Because of this feature you
381 can place a transformation in the primary field that lets you select
382 default values for it.
384 The [[sym:yas-choose-value][=yas-choose-value=]] does this work for you. For example:
387 <div align="${2:$$(yas-choose-value '("right" "center" "left"))}">
392 See the definition of [[sym:yas-choose-value][=yas-choose-value=]] to see how it was written using
395 Here's another use, for LaTeX-mode, which calls reftex-label just as you
396 enter snippet field 2. This one makes use of [[sym:yas-modified-p][=yas-modified-p=]] directly.
399 \section{${1:"Titel der Tour"}}%
401 \label{{2:"waiting for reftex-label call..."$(unless yas-modified-p (reftex-label nil 'dont-
405 The function [[sym:yas-verify-value][=yas-verify-value=]] has another neat trick, and makes use
406 of [[sym:yas-moving-away-p][=yas-moving-away-p=]]. Try it and see! Also, check out this [[http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662][thread]]
408 ** Nested placeholder fields
410 From version 0.6 on, you can also have nested placeholders of the type:
413 <div${1: id="${2:some_id}"}>$0</div>
416 This allows you to choose if you want to give this =div= an =id=
417 attribute. If you tab forward after expanding it will let you change
418 "some\_id" to whatever you like. Alternatively, you can just press =C-d=
419 (which executes [[sym:yas-skip-and-clear-or-delete-char][=yas-skip-and-clear-or-delete-char=]]) and go straight to
422 By the way, =C-d= will only clear the field if you cursor is at the
423 beginning of the field /and/ it hasn't been changed yet. Otherwise, it
424 performs the normal Emacs =delete-char= command.