mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 21:13:04 +00:00
553 lines
36 KiB
HTML
553 lines
36 KiB
HTML
<?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.5: 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">
|
|
<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="#expand-env-expand-environment" id="id10"><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="id11"><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="id12"><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="id13">Template syntax</a><ul>
|
|
<li><a class="reference internal" href="#plain-text" id="id14">Plain Text</a></li>
|
|
<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id15">Embedded Emacs-lisp code</a></li>
|
|
<li><a class="reference internal" href="#tab-stop-fields" id="id16">Tab stop fields</a></li>
|
|
<li><a class="reference internal" href="#placeholder-fields" id="id17">Placeholder fields</a></li>
|
|
<li><a class="reference internal" href="#id2" id="id18">Mirrors</a></li>
|
|
<li><a class="reference internal" href="#mirrors-with-transformations" id="id19">Mirrors with transformations</a></li>
|
|
<li><a class="reference internal" href="#fields-with-transformations" id="id20">Fields with transformations</a></li>
|
|
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id21">Choosing fields value from a list</a></li>
|
|
<li><a class="reference internal" href="#nested-placeholder-fields" id="id22">Nested placeholder fields</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#customizable-variables" id="id23">Customizable variables</a><ul>
|
|
<li><a class="reference internal" href="#yas-trigger-key" id="id24"><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="id25"><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="id26"><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="id27"><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="id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li>
|
|
<li><a class="reference internal" href="#yas-indent-line" id="id29"><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="id30"><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="id31"><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="id32"><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="id33"><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>
|
|
</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. 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>
|
|
<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>.</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>
|
|
</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 snippets for making snippets: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">field</span></tt> and
|
|
<tt class="docutils literal"><span class="pre">mirror</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 may just contain the template for the
|
|
snippet. Optionally it can also contains some meta data for the
|
|
snippet as well as comments.</p>
|
|
<p>Generally speaking, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, then all
|
|
contents above that line are considered directives (meta data) and
|
|
comments; below that line lies the snippet template.</p>
|
|
<p>If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found, the whole file content is considered as the
|
|
template.</p>
|
|
<p>Here's a typical example:</p>
|
|
<div class="highlight"><pre>#contributor : pluskid <pluskid@gmail.com>
|
|
#name : __...__
|
|
# --
|
|
__${init}__
|
|
</pre></div>
|
|
<p>Meta data are specified in the syntax of</p>
|
|
<div class="highlight"><pre>#data-name : data value
|
|
</pre></div>
|
|
<p>Any other text above <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is considered as comment and
|
|
ignored. 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>
|
|
<p><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group</span></tt> snippet menu grouping</p>
|
|
<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="#id10"><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</em>
|
|
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.</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="#id11"><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>
|
|
</pre></div>
|
|
<p>Note that this feature is still experimental and should be used with
|
|
caution: It is easy to override important keybindings for many basic
|
|
modes and it is hard to undefine them. In particular, the variable
|
|
<tt class="docutils literal"><span class="pre">yas/active-keybinding</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 try to
|
|
undefine all the keybindings.</p>
|
|
</div>
|
|
<div class="section" id="contributor-snippet-author">
|
|
<h2><a class="toc-backref" href="#id12"><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="#id13">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="#id14">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="#id15">Embedded Emacs-lisp code</a></h2>
|
|
<p>Emacs-Lisp code can be embedded inside the template. They are written
|
|
inside back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>):</p>
|
|
<p>They 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 <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.0, 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="#id16">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="#id17">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="#id18">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="#id19">Mirrors with transformations</a></h2>
|
|
<p>If the default value of a field starts with <tt class="docutils literal"><span class="pre">$</span></tt>, then it is interpreted
|
|
as the transformation code instead of default value. A transformation
|
|
is some arbitrary Emacs-lisp code that will get evaluated in an environment
|
|
when the variable text is bind to the inputted text of the
|
|
field. 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 transformation instead of
|
|
a placeholder. The actual placeholder 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="#id20">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">
|
|
<h2><a class="toc-backref" href="#id21">Choosing fields value from a list</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. Also check out <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> for
|
|
another neat trick.</p>
|
|
</div>
|
|
<div class="section" id="nested-placeholder-fields">
|
|
<h2><a class="toc-backref" href="#id22">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="#id23">Customizable variables</a></h1>
|
|
<div class="section" id="yas-trigger-key">
|
|
<h2><a class="toc-backref" href="#id24"><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="#id25"><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="#id26"><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="#id27"><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="#id28"><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="#id29"><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="#id30"><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="#id31"><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="#id32"><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="#id33"><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>
|
|
<!-- 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>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|