summaryrefslogblamecommitdiffstats
path: root/emacs.d/lisp/yasnippet/doc/snippet-development.rst
blob: cf14e119879b0a43ad8416803e74fde2c284a913 (plain) (tree)
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
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660



















































































































































































































































































































































































































































































































































































































































































                                                                                                    
================
Writing snippets
================

.. _Organizing Snippets: snippet-organization.html
.. _Expanding Snippets: snippet-expansion.html
.. _Writing Snippets: snippet-development.html
.. _The YASnippet Menu: snippet-menu.html

.. contents::

Snippet development
===================

Quickly finding snippets
------------------------

There are some ways you can quickly find a snippet file:

* ``M-x yas/new-snippet``

  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 ``snippet-mode``
  so you can write your snippet.

* ``M-x yas/find-snippets``

  Lets you find the snippet file in the directory the snippet was
  loaded from (if it exists) like ``find-file-other-window``. The
  directory searching logic is similar to ``M-x yas/new-snippet``.

* ``M-x yas/visit-snippet-file``

  Prompts you for possible snippet expansions like
  ``yas/insert-snippet``, but instead of expanding it, takes you
  directly to the snippet definition's file, if it exists.

Once you find this file it will be set to ``snippet-mode`` (see ahead)
and you can start editing your snippet.


Using the ``snippet-mode`` major mode
-------------------------------------

There is a major mode ``snippet-mode`` to edit snippets. You can set
the buffer to this mode with ``M-x snippet-mode``. It provides
reasonably useful syntax highlighting.

Two commands are defined in this mode:

* ``M-x yas/load-snippet-buffer``

    When editing a snippet, this loads the snippet into the correct
    mode and menu. Bound to ``C-c C-c`` by default while in
    ``snippet-mode``.

* ``M-x yas/tryout-snippet``

    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 ``C-c C-t`` while in
    ``snippet-mode``.

There are also *snippets for writing snippets*: ``vars``, ``$f`` and
``$m`` :-).

File content
============

A file defining a snippet generally contains the template to be
expanded.

Optionally, if the file contains a line of ``# --``, the lines above
it count as comments, some of which can be *directives* (or meta
data). Snippet directives look like ``# property: value`` and tweak
certain snippets properties described below. If no ``# --`` is found,
the whole file is considered the snippet template.

Here's a typical example:

.. sourcecode:: text

  #contributor : pluskid <pluskid@gmail.com>
  #name : __...__
  # --
  __${init}__

Here's a list of currently supported directives:

``# key:`` snippet abbrev
--------------------------

This is the probably the most important directive, it's the
abbreviation you type to expand a snippet just before hitting
``yas/trigger-key``.

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 ``yas/ignore-filenames-as-triggers`` in `Organizing
snippets`_), in which case this snippet
will not be expandable through the key mechanism.

Sometimes the key of a snippet is non-ASCII or not valid filename
(e.g. contains ``/``). One can then define the ``key`` property which
will overwrite the filename as the key to expand the snippet.

``# name:`` snippet name
------------------------

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.

If you omit this name it will default to the file name the snippet was
loaded from.

``# condition:`` snippet condition
----------------------------------
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.

See also ``yas/buffer-local-condition`` in `Expanding snippets`_


``# group:`` snippet menu grouping
----------------------------------

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.

The ``# group:`` property only affect menu construction (See `the
YASnippet menu`_) and the same effect can be achieved by grouping
snippets into sub-directories and using the ``.yas-make-groups``
special file (for this see `Organizing Snippets`_


Refer to the bundled snippets for ``ruby-mode`` for examples on the
``# group:`` directive. Group can also be nested, e.g.  ``control
structure.loops`` tells that the snippet is under the ``loops`` group
which is under the ``control structure`` group.

``# expand-env:`` expand environment
------------------------------------

This is another piece of Emacs-lisp code in the form of a ``let``
*varlist form*, i.e. a list of lists assigning values to variables. It
can be used to override variable values while the snippet is being
expanded.

Interesting variables to override are ``yas/wrap-around-region`` and
``yas/indent-line`` (see `Expanding Snippets`_).

As an example, you might normally have ``yas/indent-line`` set to
``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this
particularly brilliant piece of ASCII art these values would mess up
your hard work. You can then use:

.. sourcecode:: text

  # name : ASCII home
  # expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil))
  # --
                  welcome to my
              X      humble
             / \      home,
            /   \      $0
           /     \
          /-------\
          |       |
          |  +-+  |
          |  | |  |
          +--+-+--+

``# binding:`` direct keybinding
---------------------------------

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. 

Additionally a variable ``yas/prefix`` 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.

.. sourcecode:: text

  #name : <p>...</p>
  #binding: "C-c C-c C-m"
  # --
  <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>

This binding will be recorded in the keymap ``html-mode-map``. 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.

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.

.. sourcecode:: text

  #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>

**Note**: this feature is still **experimental**, 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
``yas/active-keybindings`` can tell you what snippet keybindings are
active and the function ``yas/kill-snippet-keybindings`` will attempt
to undefine all the keybindings.

``# contributor:`` snippet author
---------------------------------------------------

This is optional and has no effect whatsoever on snippet
functionality, but it looks nice.


Template syntax
===============

The syntax of the snippet template is simple but powerful, very
similar to TextMate's.

Plain Text
----------

Arbitrary text can be included as the content of a template. They are
usually interpreted as plain text, except ``$`` and `````. You need to
use ``\`` to escape them: ``\$`` and ``\```. The ``\`` itself may also
needed to be escaped as ``\\`` sometimes.

Embedded Emacs-lisp code
------------------------

Emacs-Lisp code can be embedded inside the template, written inside
back-quotes (`````). The lisp forms are evaluated when the snippet is
being expanded. The evaluation is done in the same buffer as the
snippet being expanded. 

Here's an example for ``c-mode`` to calculate the header file guard
dynamically:

.. sourcecode:: text

  #ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
  #define $1

  $0

  #endif /* $1 */

From version 0.6, snippets expansions are run with some special
Emacs-lisp variables bound. One of this is ``yas/selected-text``. You
can therefore define a snippet like:

.. sourcecode:: text

   for ($1;$2;$3) {
     `yas/selected-text`$0
   }

to "wrap" the selected region inside your recently inserted
snippet. Alternatively, you can also customize the variable
``yas/wrap-around-region`` to ``t`` which will do this automatically.

Tab stop fields
---------------

Tab stops are fields that you can navigate back and forth by ``TAB``
and ``S-TAB``. They are written by ``$`` followed with a
number. ``$0`` has the special meaning of the *exit point* of a
snippet. That is the last place to go when you've traveled all the
fields. Here's a typical example:

.. sourcecode:: text

  <div$1>
      $0
  </div>

Placeholder fields
------------------

Tab stops can have default values -- a.k.a placeholders. The syntax is
like this:

.. sourcecode:: text

  ${N:default value}

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
`mirrors`_ or `transformations`_ for this field.

.. _mirrors:

Mirrors
-------

We refer the tab stops with placeholders as a *field*. A field can have
mirrors. Its mirrors will get updated when you change the text of a
field. Here's an example:

.. sourcecode:: text

  \begin{${1:enumerate}}
      $0
  \end{$1}

When you type ``"document"`` at ``${1:enumerate}``, the word
``"document"`` will also be inserted at ``\end{$1}``. The best
explanation is to see the screencast(`YouTube
<http://www.youtube.com/watch?v=vOj7btx3ATg>`_ or `avi video
<http://yasnippet.googlecode.com/files/yasnippet.avi>`_).

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.

.. _transformations:

Mirrors with transformations
----------------------------

If the value of an ``${n:``-construct starts with and contains ``$(``,
then it is interpreted as a mirror for field ``n`` 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 ``text`` (or ``yas/text``) is bound
to the text content (string) contained in the field ``n``.Here's an
example for Objective-C:

.. sourcecode:: text

  - (${1:id})${2:foo}
  {
      return $2;
  }

  - (void)set${2:$(capitalize text)}:($1)aValue
  {
      [$2 autorelease];
      $2 = [aValue retain];
  }
  $0

Look at ``${2:$(capitalize text)}``, it is a mirror with
transformation instead of a field. The actual field is at the first
line: ``${2:foo}``. When you type text in ``${2:foo}``, 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.

Another example is for ``rst-mode``. 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

.. sourcecode:: text

  =====
  Title
  =====

is a valid title but

.. sourcecode:: text

  ===
  Title
  ===

is not. Here's an snippet for rst title:

.. sourcecode:: text

  ${1:$(make-string (string-width text) ?\=)}
  ${1:Title}
  ${1:$(make-string (string-width text) ?\=)}

  $0

Fields with transformations
---------------------------

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.

The syntax is also a tiny bit different, so that the parser can
distinguish between fields and mirrors. In the following example

.. sourcecode:: text

  #define "${1:mydefine$(upcase yas/text)}"

``mydefine`` gets automatically upcased to ``MYDEFINE`` once you enter
the field. As you type text, it gets filtered through the
transformation every time.

Note that to tell this kind of expression from a mirror with a
transformation, YASnippet needs extra text between the ``:`` and the
transformation's ``$``. If you don't want this extra-text, you can use
two ``$``'s instead.

.. sourcecode:: text

  #define "${1:$$(upcase yas/text)}"

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
``true``. As a consequence, the auto-deletion behaviour of normal
fields does not take place. This is by design.

Choosing fields value from a list and other tricks
--------------------------------------------------

As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
``yas/field-modified-p`` and ``yas/moving-away-p``. Because of this
feature you can place a transformation in the primary field that lets
you select default values for it.

The ``yas/choose-value`` does this work for you. For example:

.. sourcecode:: text

  <div align="${2:$$(yas/choose-value '("right" "center" "left"))}">
    $0
  </div>

See the definition of ``yas/choose-value`` to see how it was written
using the two variables.

Here's another use, for LaTeX-mode, which calls reftex-label just as
you enter snippet field 2. This one makes use of ``yas/modified-p``
directly.

.. sourcecode:: text 

  \section{${1:"Titel der Tour"}}%
  \index{$1}%
  \label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont-
  insert))}}%  

The function ``yas/verify-value`` has another neat trick, and makes
use of ``yas/moving-away-p``. Try it and see! Also, check out this
`thread
<http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662>`_

Nested placeholder fields
-------------------------

From version 0.6 on, you can also have nested placeholders of the type:

.. sourcecode:: text

   <div${1: id="${2:some_id}"}>$0</div>

This allows you to choose if you want to give this ``div`` an ``id``
attribute. If you tab forward after expanding it will let you change
"some_id" to whatever you like. Alternatively, you can just press
``C-d`` (which executes ``yas/skip-and-clear-or-delete-char``) and go
straight to the exit marker.

By the way, ``C-d`` will only clear the field if you cursor is at the
beginning of the field *and* it hasn't been changed yet. Otherwise, it
performs the normal Emacs ``delete-char`` command.

Customizable variables
======================

``yas/trigger-key``
-------------------

The key bound to ``yas/expand`` when function ``yas/minor-mode`` is
active.

Value is a string that is converted to the internal Emacs key
representation using ``read-kbd-macro``.

Default value is ``"TAB"``.

``yas/next-field-key``
----------------------

The key to navigate to next field when a snippet is active.

Value is a string that is converted to the internal Emacs key
representation using ``read-kbd-macro``.

Can also be a list of keys.

Default value is ``"TAB"``.

``yas/prev-field-key``
----------------------
  
The key to navigate to previous field when a snippet is active.

Value is a string that is converted to the internal Emacs key
representation using ``read-kbd-macro``.

Can also be a list of keys.

Default value is ``("<backtab>" "<S-tab>)"``.

``yas/skip-and-clear-key``
--------------------------

The key to clear the currently active field.

Value is a string that is converted to the internal Emacs key
representation using ``read-kbd-macro``.

Can also be a list of keys.

Default value is ``"C-d"``.

``yas/good-grace``
------------------

If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
snippet definitions. An error string "[yas] error" is returned instead.

``yas/indent-line``
-------------------

The variable ``yas/indent-line`` controls the indenting. It is bound
to ``'auto`` by default, which causes your snippet to be indented
according to the mode of the buffer it was inserted in.

Another variable ``yas/also-auto-indent-first-line``, when non-nil
does exactly that :-).

To use the hard-coded indentation in your snippet template, set this
variable to ``fixed``.

To control indentation on a per-snippet basis, see also the directive
``# expand-env:`` in `Writing Snippets`_.

For backward compatibility with earlier versions of YASnippet, you can
also place a ``$>`` in your snippet, an ``(indent-according-to-mode)``
will be executed there to indent the line. This only takes effect when
``yas/indent-line`` is set to something other than ``'auto``.

.. sourcecode:: text

  for (${int i = 0}; ${i < 10}; ${++i})
  {$>
  $0$>
  }$>

``yas/wrap-around-region``
--------------------------

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 ```yas/selected-text``` inline
evaluation.

Because on most systems starting to type deletes the currently
selected region, this works mostly for snippets with direct
keybindings or with the ``yas/insert-snippet`` command.

However, when the value is of this variable is ``cua`` 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 ``yas/trigger-key`` to see the deleted region
spring back to life inside your new snippet.

``yas/triggers-in-field``
--------------------------

If non-nil, ``yas/next-field-key`` can trigger stacked expansions,
that is a snippet expansion inside another snippet
expansion. Otherwise, ``yas/next-field-key`` just tries to move on to
the next field.

``yas/snippet-revival``
-----------------------

Non-nil means re-activate snippet fields after undo/redo.

``yas/after-exit-snippet-hook`` and ``yas/before-expand-snippet-hook``
----------------------------------------------------------------------

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.

Importing TextMate snippets
===========================

There are a couple of tools that take TextMate's ".tmSnippet" xml
files and create YASnippet definitions:

 * `a python script by Jeff Wheeler
   <http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py>`_

 * a `ruby tool
   <http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb>`_
   , ``textmate_import.rb`` adapted from `Rob Christie's
   <http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/>`_,
   which I have uploaded to the repository.

In this section, i'll shortly cover the **second** option. 

Download the ``textmate_import.rb`` tool and the TextMate
bundle you're interested in.

.. sourcecode:: text

  $ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb
  $ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/


Then invoke ``textmate_import.rb`` like this:

.. sourcecode:: text

  $ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist

You should end up with a ``html-mode`` subdir containing snippets
exported from textmate.

.. sourcecode:: text 

  $ tree html-mode # to view dir contents, if you have 'tree' installed

The ``-g`` is optional but helps the tool figure out the grouping.
According to `Organizing Snippets`_, don't forget to touch
``.yas-make-groups`` and ``.yas-ignore-filename-triggers`` inside the
``html-mode`` dir.

Also try ``textmate_import.rb --help`` for a list of options.

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 ``textmate_import.rb`` to automatically perform them and submit
that.
 
..  LocalWords:  html YASnippet yas sourcecode pluskid init filenames filename
..  LocalWords:  env varlist keybinding keymap rinari ifndef upcase endif
..  LocalWords:  nondirectory autorelease aValue inline