1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Writing snippets</title>
<link rel="stylesheet" href="styles.css" type="text/css" />
</head>
<body>
<div class="document" id="writing-snippets">
<div id="header-region" class="clear-block"></div>
<div id="wrapper">
<div id="container" class="clear-block">
<div id="header">
<div id="logo-floater">
<h1 class="title">Writing snippets</h1>
</div>
<ul class="primary-links">
<li>
<a title="" href="index.html">Intro and tutorial</a>
</li>
<li>
<a title="" href="snippet-organization.html">Howto: organize</a>
</li>
<li>
<a title="" href="snippet-expansion.html">Howto: expand</a>
</li>
<li>
<a title="" href="snippet-development.html">Howto: write </a>
</li>
<li>
<a title="" href="snippet-menu.html">Howto: menu </a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>
</li>
<li>
<a title="" href="changelog.html">ChangeLog</a>
</li>
<li>
<a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
</li>
</ul>
</div>
<div id="center">
<div id="squeeze">
<div class="right-corner">
<div class="left-corner">
<p>
<b>Important:</b> This documentation applies to
the <b>SVN trunk</b> of YASnippet, which you
get <a href="http://code.google.com/p/yasnippet/source/checkout">here</a>. Documentation
for other versions can be found <a title=""
href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
</p>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#snippet-development" id="id3">Snippet development</a><ul>
<li><a class="reference internal" href="#quickly-finding-snippets" id="id4">Quickly finding snippets</a></li>
<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></li>
</ul>
</li>
<li><a class="reference internal" href="#file-content" id="id6">File content</a><ul>
<li><a class="reference internal" href="#key-snippet-abbrev" id="id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></li>
<li><a class="reference internal" href="#name-snippet-name" id="id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></li>
<li><a class="reference internal" href="#condition-snippet-condition" id="id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></li>
<li><a class="reference internal" href="#group-snippet-menu-grouping" id="id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> snippet menu grouping</a></li>
<li><a class="reference internal" href="#expand-env-expand-environment" id="id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></li>
<li><a class="reference internal" href="#binding-direct-keybinding" id="id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></li>
<li><a class="reference internal" href="#contributor-snippet-author" id="id13"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></li>
</ul>
</li>
<li><a class="reference internal" href="#template-syntax" id="id14">Template syntax</a><ul>
<li><a class="reference internal" href="#plain-text" id="id15">Plain Text</a></li>
<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id16">Embedded Emacs-lisp code</a></li>
<li><a class="reference internal" href="#tab-stop-fields" id="id17">Tab stop fields</a></li>
<li><a class="reference internal" href="#placeholder-fields" id="id18">Placeholder fields</a></li>
<li><a class="reference internal" href="#id2" id="id19">Mirrors</a></li>
<li><a class="reference internal" href="#mirrors-with-transformations" id="id20">Mirrors with transformations</a></li>
<li><a class="reference internal" href="#fields-with-transformations" id="id21">Fields with transformations</a></li>
<li><a class="reference internal" href="#choosing-fields-value-from-a-list-and-other-tricks" id="id22">Choosing fields value from a list and other tricks</a></li>
<li><a class="reference internal" href="#nested-placeholder-fields" id="id23">Nested placeholder fields</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizable-variables" id="id24">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-trigger-key" id="id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-next-field-key" id="id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-prev-field-key" id="id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-skip-and-clear-key" id="id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-good-grace" id="id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li>
<li><a class="reference internal" href="#yas-indent-line" id="id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></li>
<li><a class="reference internal" href="#yas-wrap-around-region" id="id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></li>
<li><a class="reference internal" href="#yas-triggers-in-field" id="id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></li>
<li><a class="reference internal" href="#yas-snippet-revival" id="id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></li>
<li><a class="reference internal" href="#yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook" id="id34"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#importing-textmate-snippets" id="id35">Importing TextMate snippets</a></li>
</ul>
</div>
<div class="section" id="snippet-development">
<h1><a class="toc-backref" href="#id3">Snippet development</a></h1>
<div class="section" id="quickly-finding-snippets">
<h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2>
<p>There are some ways you can quickly find a snippet file:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt></p>
<p>Prompts you for a snippet name, then tries to guess a suitable
directory to store it, prompting you for creation if it does not
exist. Finally, places you in a new buffer set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt>
so you can write your snippet.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/find-snippets</span></tt></p>
<p>Lets you find the snippet file in the directory the snippet was
loaded from (if it exists) like <tt class="docutils literal"><span class="pre">find-file-other-window</span></tt>. The
directory searching logic is similar to <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/visit-snippet-file</span></tt></p>
<p>Prompts you for possible snippet expansions like
<tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt>, but instead of expanding it, takes you
directly to the snippet definition's file, if it exists.</p>
</li>
</ul>
<p>Once you find this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead)
and you can start editing your snippet.</p>
</div>
<div class="section" id="using-the-snippet-mode-major-mode">
<h2><a class="toc-backref" href="#id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h2>
<p>There is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to edit snippets. You can set
the buffer to this mode with <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">snippet-mode</span></tt>. It provides
reasonably useful syntax highlighting.</p>
<p>Two commands are defined in this mode:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p>
<blockquote>
<p>When editing a snippet, this loads the snippet into the correct
mode and menu. Bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-c</span></tt> by default while in
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p>
</blockquote>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/tryout-snippet</span></tt></p>
<blockquote>
<p>When editing a snippet, this opens a new empty buffer, sets it to
the appropriate major mode and inserts the snippet there, so you
can see what it looks like. This is bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-t</span></tt> while in
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p>
</blockquote>
</li>
</ul>
<p>There are also <em>snippets for writing snippets</em>: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">$f</span></tt> and
<tt class="docutils literal"><span class="pre">$m</span></tt> :-).</p>
</div>
</div>
<div class="section" id="file-content">
<h1><a class="toc-backref" href="#id6">File content</a></h1>
<p>A file defining a snippet generally contains the template to be
expanded.</p>
<p>Optionally, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, the lines above
it count as comments, some of which can be <em>directives</em> (or meta
data). Snippet directives look like <tt class="docutils literal"><span class="pre">#</span> <span class="pre">property:</span> <span class="pre">value</span></tt> and tweak
certain snippets properties described below. If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found,
the whole file is considered the snippet template.</p>
<p>Here's a typical example:</p>
<div class="highlight"><pre>#contributor : pluskid <pluskid@gmail.com>
#name : __...__
# --
__${init}__
</pre></div>
<p>Here's a list of currently supported directives:</p>
<div class="section" id="key-snippet-abbrev">
<h2><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></h2>
<p>This is the probably the most important directive, it's the
abbreviation you type to expand a snippet just before hitting
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p>
<p>If you don't specify this it will default to the name of the file the
snippet is being loaded from, unless YASnippet is ignoring file names
as triggers (see <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> in <a class="reference external" href="snippet-organization.html">Organizing
snippets</a>), in which case this snippet
will not be expandable through the key mechanism.</p>
<p>Sometimes the key of a snippet is non-ASCII or not valid filename
(e.g. contains <tt class="docutils literal"><span class="pre">/</span></tt>). One can then define the <tt class="docutils literal"><span class="pre">key</span></tt> property which
will overwrite the filename as the key to expand the snippet.</p>
</div>
<div class="section" id="name-snippet-name">
<h2><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></h2>
<p>This is a one-line description of the snippet. It will be displayed in
the menu. It's a good idea to select a descriptive name for a
snippet -- especially distinguishable among similar snippets.</p>
<p>If you omit this name it will default to the file name the snippet was
loaded from.</p>
</div>
<div class="section" id="condition-snippet-condition">
<h2><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></h2>
<p>This is a piece of Emacs-lisp code. If a snippet has a condition, then it
will only be expanded when the condition code evaluate to some non-nil
value.</p>
<p>See also <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> in <a class="reference external" href="snippet-expansion.html">Expanding snippets</a></p>
</div>
<div class="section" id="group-snippet-menu-grouping">
<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> snippet menu grouping</a></h2>
<p>When expanding/visiting snippets from the menu-bar menu, snippets for a
given mode can be grouped into sub-menus . This is useful if one has
too many snippets for a mode which will make the menu too
long.</p>
<p>The <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> property only affect menu construction (See <a class="reference external" href="snippet-menu.html">the
YASnippet menu</a>) and the same effect can be achieved by grouping
snippets into sub-directories and using the <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt>
special file (for this see <a class="reference external" href="snippet-organization.html">Organizing Snippets</a></p>
<p>Refer to the bundled snippets for <tt class="docutils literal"><span class="pre">ruby-mode</span></tt> for examples on the
<tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> directive. Group can also be nested, e.g. <tt class="docutils literal"><span class="pre">control</span>
<span class="pre">structure.loops</span></tt> tells that the snippet is under the <tt class="docutils literal"><span class="pre">loops</span></tt> group
which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt> group.</p>
</div>
<div class="section" id="expand-env-expand-environment">
<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></h2>
<p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt>
<em>varlist form</em>, i.e. a list of lists assigning values to variables. It
can be used to override variable values while the snippet is being
expanded.</p>
<p>Interesting variables to override are <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> and
<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> (see <a class="reference external" href="snippet-expansion.html">Expanding Snippets</a>).</p>
<p>As an example, you might normally have <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> set to
<tt class="docutils literal"><span class="pre">'auto</span></tt> and <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> set to <tt class="docutils literal"><span class="pre">t</span></tt>, but for this
particularly brilliant piece of ASCII art these values would mess up
your hard work. You can then use:</p>
<div class="highlight"><pre># name : ASCII home
# expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil))
# --
welcome to my
X humble
/ \ home,
/ \ $0
/ \
/-------\
| |
| +-+ |
| | | |
+--+-+--+
</pre></div>
</div>
<div class="section" id="binding-direct-keybinding">
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></h2>
<p>You can use this directive to expand a snippet directly from a normal
Emacs keybinding. The keybinding will be registered in the Emacs
keymap named after the major mode the snippet is active
for.</p>
<p>Additionally a variable <tt class="docutils literal"><span class="pre">yas/prefix</span></tt> is set to to the prefix
argument you normally use for a command. This allows for small
variations on the same snippet, for example in this "html-mode"
snippet.</p>
<div class="highlight"><pre>#name : <p>...</p>
#binding: "C-c C-c C-m"
# --
<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
</pre></div>
<p>This binding will be recorded in the keymap <tt class="docutils literal"><span class="pre">html-mode-map</span></tt>. To
expand a paragraph tag newlines, just press "C-u C-c C-c
C-m". Omitting the "C-u" will expand the paragraph tag without
newlines.</p>
<p>To override the keymap choice based on the major mode name. Use a cons
cell where the first element specifies the name of the keymap where
you want to record the keybinding.</p>
<div class="highlight"><pre>#name : <p>...</p>
#binding: (rinari-minor-mode-map . "C-c C-c C-m")
# --
<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
</pre></div>
<p><strong>Note</strong>: this feature is still <strong>experimental</strong>, it might go away, be
changed in future release, and should be used with caution: It is easy
to override important keybindings for many basic modes and it is hard
to undefine them. For the moment, the variable
<tt class="docutils literal"><span class="pre">yas/active-keybindings</span></tt> can tell you what snippet keybindings are
active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt
to undefine all the keybindings.</p>
</div>
<div class="section" id="contributor-snippet-author">
<h2><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></h2>
<p>This is optional and has no effect whatsoever on snippet
functionality, but it looks nice.</p>
</div>
</div>
<div class="section" id="template-syntax">
<h1><a class="toc-backref" href="#id14">Template syntax</a></h1>
<p>The syntax of the snippet template is simple but powerful, very
similar to TextMate's.</p>
<div class="section" id="plain-text">
<h2><a class="toc-backref" href="#id15">Plain Text</a></h2>
<p>Arbitrary text can be included as the content of a template. They are
usually interpreted as plain text, except <tt class="docutils literal"><span class="pre">$</span></tt> and <tt class="docutils literal"><span class="pre">`</span></tt>. You need to
use <tt class="docutils literal"><span class="pre">\</span></tt> to escape them: <tt class="docutils literal"><span class="pre">\$</span></tt> and <tt class="docutils literal"><span class="pre">\`</span></tt>. The <tt class="docutils literal"><span class="pre">\</span></tt> itself may also
needed to be escaped as <tt class="docutils literal"><span class="pre">\\</span></tt> sometimes.</p>
</div>
<div class="section" id="embedded-emacs-lisp-code">
<h2><a class="toc-backref" href="#id16">Embedded Emacs-lisp code</a></h2>
<p>Emacs-Lisp code can be embedded inside the template, written inside
back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>). The lisp forms are evaluated when the snippet is
being expanded. The evaluation is done in the same buffer as the
snippet being expanded.</p>
<p>Here's an example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard
dynamically:</p>
<div class="highlight"><pre>#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
#define $1
$0
#endif /* $1 */
</pre></div>
<p>From version 0.6, snippets expansions are run with some special
Emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You
can therefore define a snippet like:</p>
<div class="highlight"><pre>for ($1;$2;$3) {
`yas/selected-text`$0
}
</pre></div>
<p>to "wrap" the selected region inside your recently inserted
snippet. Alternatively, you can also customize the variable
<tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt> which will do this automatically.</p>
</div>
<div class="section" id="tab-stop-fields">
<h2><a class="toc-backref" href="#id17">Tab stop fields</a></h2>
<p>Tab stops are fields that you can navigate back and forth by <tt class="docutils literal"><span class="pre">TAB</span></tt>
and <tt class="docutils literal"><span class="pre">S-TAB</span></tt>. They are written by <tt class="docutils literal"><span class="pre">$</span></tt> followed with a
number. <tt class="docutils literal"><span class="pre">$0</span></tt> has the special meaning of the <em>exit point</em> of a
snippet. That is the last place to go when you've traveled all the
fields. Here's a typical example:</p>
<div class="highlight"><pre><div$1>
$0
</div>
</pre></div>
</div>
<div class="section" id="placeholder-fields">
<h2><a class="toc-backref" href="#id18">Placeholder fields</a></h2>
<p>Tab stops can have default values -- a.k.a placeholders. The syntax is
like this:</p>
<div class="highlight"><pre>${N:default value}
</pre></div>
<p>They acts as the default value for a tab stop. But when you firstly
type at a tab stop, the default value will be replaced by your
typing. The number can be omitted if you don't want to create
<a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p>
</div>
<div class="section" id="id2">
<span id="mirrors"></span><h2><a class="toc-backref" href="#id19">Mirrors</a></h2>
<p>We refer the tab stops with placeholders as a <em>field</em>. A field can have
mirrors. Its mirrors will get updated when you change the text of a
field. Here's an example:</p>
<div class="highlight"><pre>\begin{${1:enumerate}}
$0
\end{$1}
</pre></div>
<p>When you type <tt class="docutils literal"><span class="pre">"document"</span></tt> at <tt class="docutils literal"><span class="pre">${1:enumerate}</span></tt>, the word
<tt class="docutils literal"><span class="pre">"document"</span></tt> will also be inserted at <tt class="docutils literal"><span class="pre">\end{$1}</span></tt>. The best
explanation is to see the screencast(<a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">YouTube</a> or <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">avi video</a>).</p>
<p>The tab stops with the same number to the field act as its mirrors. If
none of the tab stops has an initial value, the first one is selected
as the field and others mirrors.</p>
</div>
<div class="section" id="mirrors-with-transformations">
<span id="transformations"></span><h2><a class="toc-backref" href="#id20">Mirrors with transformations</a></h2>
<p>If the value of an <tt class="docutils literal"><span class="pre">${n:</span></tt>-construct starts with and contains <tt class="docutils literal"><span class="pre">$(</span></tt>,
then it is interpreted as a mirror for field <tt class="docutils literal"><span class="pre">n</span></tt> with a
transformation. The mirror's text content is calculated according to
this transformation, which is Emacs-lisp code that gets evaluated in
an environment where the variable <tt class="docutils literal"><span class="pre">text</span></tt> (or <tt class="docutils literal"><span class="pre">yas/text</span></tt>) is bound
to the text content (string) contained in the field <tt class="docutils literal"><span class="pre">n</span></tt>.Here's an
example for Objective-C:</p>
<div class="highlight"><pre>- (${1:id})${2:foo}
{
return $2;
}
- (void)set${2:$(capitalize text)}:($1)aValue
{
[$2 autorelease];
$2 = [aValue retain];
}
$0
</pre></div>
<p>Look at <tt class="docutils literal"><span class="pre">${2:$(capitalize</span> <span class="pre">text)}</span></tt>, it is a mirror with
transformation instead of a field. The actual field is at the first
line: <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the
transformation will be evaluated and the result will be placed there
as the transformed text. So in this example, if you type "baz" in the
field, the transformed text will be "Baz". This example is also
available in the screencast.</p>
<p>Another example is for <tt class="docutils literal"><span class="pre">rst-mode</span></tt>. In reStructuredText, the document
title can be some text surrounded by "===" below and above. The "==="
should be at least as long as the text. So</p>
<div class="highlight"><pre>=====
Title
=====
</pre></div>
<p>is a valid title but</p>
<div class="highlight"><pre>===
Title
===
</pre></div>
<p>is not. Here's an snippet for rst title:</p>
<div class="highlight"><pre>${1:$(make-string (string-width text) ?\=)}
${1:Title}
${1:$(make-string (string-width text) ?\=)}
$0
</pre></div>
</div>
<div class="section" id="fields-with-transformations">
<h2><a class="toc-backref" href="#id21">Fields with transformations</a></h2>
<p>From version 0.6 on, you can also have lisp transformation inside
fields. These work mostly mirror transformations but are evaluated
when you first enter the field, after each change you make to the
field and also just before you exit the field.</p>
<p>The syntax is also a tiny bit different, so that the parser can
distinguish between fields and mirrors. In the following example</p>
<div class="highlight"><pre>#define "${1:mydefine$(upcase yas/text)}"
</pre></div>
<p><tt class="docutils literal"><span class="pre">mydefine</span></tt> gets automatically upcased to <tt class="docutils literal"><span class="pre">MYDEFINE</span></tt> once you enter
the field. As you type text, it gets filtered through the
transformation every time.</p>
<p>Note that to tell this kind of expression from a mirror with a
transformation, YASnippet needs extra text between the <tt class="docutils literal"><span class="pre">:</span></tt> and the
transformation's <tt class="docutils literal"><span class="pre">$</span></tt>. If you don't want this extra-text, you can use
two <tt class="docutils literal"><span class="pre">$</span></tt>'s instead.</p>
<div class="highlight"><pre>#define "${1:$$(upcase yas/text)}"
</pre></div>
<p>Please note that as soon as a transformation takes place, it changes
the value of the field and sets it its internal modification state to
<tt class="docutils literal"><span class="pre">true</span></tt>. As a consequence, the auto-deletion behaviour of normal
fields does not take place. This is by design.</p>
</div>
<div class="section" id="choosing-fields-value-from-a-list-and-other-tricks">
<h2><a class="toc-backref" href="#id22">Choosing fields value from a list and other tricks</a></h2>
<p>As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
<tt class="docutils literal"><span class="pre">yas/field-modified-p</span></tt> and <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Because of this
feature you can place a transformation in the primary field that lets
you select default values for it.</p>
<p>The <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> does this work for you. For example:</p>
<div class="highlight"><pre><div align="${2:$$(yas/choose-value '("right" "center" "left"))}">
$0
</div>
</pre></div>
<p>See the definition of <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> to see how it was written
using the two variables.</p>
<p>Here's another use, for LaTeX-mode, which calls reftex-label just as
you enter snippet field 2. This one makes use of <tt class="docutils literal"><span class="pre">yas/modified-p</span></tt>
directly.</p>
<div class="highlight"><pre>\section{${1:"Titel der Tour"}}%
\index{$1}%
\label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont-
insert))}}%
</pre></div>
<p>The function <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> has another neat trick, and makes
use of <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Try it and see! Also, check out this
<a class="reference external" href="http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662">thread</a></p>
</div>
<div class="section" id="nested-placeholder-fields">
<h2><a class="toc-backref" href="#id23">Nested placeholder fields</a></h2>
<p>From version 0.6 on, you can also have nested placeholders of the type:</p>
<div class="highlight"><pre><div${1: id="${2:some_id}"}>$0</div>
</pre></div>
<p>This allows you to choose if you want to give this <tt class="docutils literal"><span class="pre">div</span></tt> an <tt class="docutils literal"><span class="pre">id</span></tt>
attribute. If you tab forward after expanding it will let you change
"some_id" to whatever you like. Alternatively, you can just press
<tt class="docutils literal"><span class="pre">C-d</span></tt> (which executes <tt class="docutils literal"><span class="pre">yas/skip-and-clear-or-delete-char</span></tt>) and go
straight to the exit marker.</p>
<p>By the way, <tt class="docutils literal"><span class="pre">C-d</span></tt> will only clear the field if you cursor is at the
beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it
performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p>
</div>
</div>
<div class="section" id="customizable-variables">
<h1><a class="toc-backref" href="#id24">Customizable variables</a></h1>
<div class="section" id="yas-trigger-key">
<h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2>
<p>The key bound to <tt class="docutils literal"><span class="pre">yas/expand</span></tt> when function <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is
active.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
<p>Default value is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>.</p>
</div>
<div class="section" id="yas-next-field-key">
<h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2>
<p>The key to navigate to next field when a snippet is active.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
<p>Can also be a list of keys.</p>
<p>Default value is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>.</p>
</div>
<div class="section" id="yas-prev-field-key">
<h2><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2>
<p>The key to navigate to previous field when a snippet is active.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
<p>Can also be a list of keys.</p>
<p>Default value is <tt class="docutils literal"><span class="pre">("<backtab>"</span> <span class="pre">"<S-tab>)"</span></tt>.</p>
</div>
<div class="section" id="yas-skip-and-clear-key">
<h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></h2>
<p>The key to clear the currently active field.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
<p>Can also be a list of keys.</p>
<p>Default value is <tt class="docutils literal"><span class="pre">"C-d"</span></tt>.</p>
</div>
<div class="section" id="yas-good-grace">
<h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2>
<p>If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
snippet definitions. An error string "[yas] error" is returned instead.</p>
</div>
<div class="section" id="yas-indent-line">
<h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2>
<p>The variable <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> controls the indenting. It is bound
to <tt class="docutils literal"><span class="pre">'auto</span></tt> by default, which causes your snippet to be indented
according to the mode of the buffer it was inserted in.</p>
<p>Another variable <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt>, when non-nil
does exactly that :-).</p>
<p>To use the hard-coded indentation in your snippet template, set this
variable to <tt class="docutils literal"><span class="pre">fixed</span></tt>.</p>
<p>To control indentation on a per-snippet basis, see also the directive
<tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> in <a class="reference external" href="snippet-development.html">Writing Snippets</a>.</p>
<p>For backward compatibility with earlier versions of YASnippet, you can
also place a <tt class="docutils literal"><span class="pre">$></span></tt> in your snippet, an <tt class="docutils literal"><span class="pre">(indent-according-to-mode)</span></tt>
will be executed there to indent the line. This only takes effect when
<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> is set to something other than <tt class="docutils literal"><span class="pre">'auto</span></tt>.</p>
<div class="highlight"><pre>for (${int i = 0}; ${i < 10}; ${++i})
{$>
$0$>
}$>
</pre></div>
</div>
<div class="section" id="yas-wrap-around-region">
<h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2>
<p>If non-nil, YASnippet will try to expand the snippet's exit marker
around the currently selected region. When this variable is set to t,
this has the same effect has using the <tt class="docutils literal"><span class="pre">`yas/selected-text`</span></tt> inline
evaluation.</p>
<p>Because on most systems starting to type deletes the currently region,
this works mostly with the <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> command.</p>
<p>However, when the value is of this variable is <tt class="docutils literal"><span class="pre">cua</span></tt> YASnippet will
additionally look-up any recently selected that you deleted by starting
typing. This allows you select a region, type a snippet key (deleting
the region), then press <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to see the deleted region
spring back to life inside your new snippet.</p>
</div>
<div class="section" id="yas-triggers-in-field">
<h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2>
<p>If non-nil, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> can trigger stacked expansions,
that is a snippet expansion inside another snippet
expansion. Otherwise, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> just tries to move on to
the next field.</p>
</div>
<div class="section" id="yas-snippet-revival">
<h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2>
<p>Non-nil means re-activate snippet fields after undo/redo.</p>
</div>
<div class="section" id="yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook">
<h2><a class="toc-backref" href="#id34"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></h2>
<p>These hooks are called, respectively, before the insertion of a
snippet and after exiting the snippet. If you find any strange but
functional use for them, that's probably a design flaw in YASnippet,
so let us know.</p>
</div>
</div>
<div class="section" id="importing-textmate-snippets">
<h1><a class="toc-backref" href="#id35">Importing TextMate snippets</a></h1>
<p>There are a couple of tools that take TextMate's ".tmSnippet" xml
files and create YASnippet definitions:</p>
<blockquote>
<ul class="simple">
<li><a class="reference external" href="http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py">a python script by Jeff Wheeler</a></li>
<li>a <a class="reference external" href="http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb">ruby tool</a>
, <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> adapted from <a class="reference external" href="http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/">Rob Christie's</a>,
which I have uploaded to the repository.</li>
</ul>
</blockquote>
<p>In this section, i'll shortly cover the <strong>second</strong> option.</p>
<p>Download the <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> tool and the TextMate
bundle you're interested in.</p>
<div class="highlight"><pre>$ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb
$ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/
</pre></div>
<p>Then invoke <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> like this:</p>
<div class="highlight"><pre>$ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist
</pre></div>
<p>You should end up with a <tt class="docutils literal"><span class="pre">html-mode</span></tt> subdir containing snippets
exported from textmate.</p>
<div class="highlight"><pre>$ tree html-mode # to view dir contents, if you have 'tree' installed
</pre></div>
<p>The <tt class="docutils literal"><span class="pre">-g</span></tt> is optional but helps the tool figure out the grouping.
According to <a class="reference external" href="snippet-organization.html">Organizing Snippets</a>, don't forget to touch
<tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> and <tt class="docutils literal"><span class="pre">.yas-ignore-filename-triggers</span></tt> inside the
<tt class="docutils literal"><span class="pre">html-mode</span></tt> dir.</p>
<p>Also try <tt class="docutils literal"><span class="pre">textmate_import.rb</span> <span class="pre">--help</span></tt> for a list of options.</p>
<p>Please note that snippet importation is not yet perfect. You'll
probably have some adjustments to some/many snippets. Please
contribute these adjustments to the google group or, better yet, patch
the <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> to automatically perform them and submit
that.</p>
<!-- LocalWords: html YASnippet yas sourcecode pluskid init filenames filename -->
<!-- LocalWords: env varlist keybinding keymap rinari ifndef upcase endif -->
<!-- LocalWords: nondirectory autorelease aValue inline -->
</div>
</div>
</div>
</div>
</div>
</div>
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-10536822-1");
pageTracker._trackPageview();
} catch(err) {}
</script>
</div>
</body>
</html>
|
