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