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:
#contributor : pluskid <pluskid@gmail.com>
#name : __...__
# --
__${init}__
Here’s a list of currently supported directives:
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.
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.
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
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.
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:
# 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.
#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.
#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.
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.
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:
#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:
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 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:
<div$1>
$0
</div>
Tab stops can have default values – a.k.a placeholders. The syntax is like this:
${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.
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:
\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 or avi video).
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.
If the value of an yas/text
) is
bound to the text content (string) contained in the field n.Here’s an example
for Objective-C:
- (${1:id})${2:foo}
{
return $2;
}
- (void)set${2:$(capitalize text)}:($1)aValue
{
[$2 autorelease];
$2 = [aValue retain];
}
$0
Look at
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
=====
Title
=====
is a valid title but
=== Title ===
is not. Here’s an snippet for rst title:
${1:$(make-string (string-width text) ?\=)} ${1:Title} ${1:$(make-string (string-width text) ?\=)} $0
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
#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
#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.
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:
<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.
\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
From version 0.6 on, you can also have nested placeholders of the type:
<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.
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”.
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”.
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>)”.
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”.
If non-nil, don’t raise errors in inline Emacs-lisp evaluation inside snippet definitions. An error string “[yas] error” is returned instead.
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.
for (${int i = 0}; ${i < 10}; ${++i}) {$> $0$> }$>
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 region, this
works mostly 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.
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.
There are a couple of tools that take TextMate’s “.tmSnippet” xml files and create YASnippet definitions:
- a python script by Jeff Wheeler
- a ruby tool , textmate_import.rb adapted from Rob Christie’s, 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.
$ 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:
$ ./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.
$ 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.