mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 13:13:03 +00:00
314 lines
17 KiB
HTML
314 lines
17 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.6: http://docutils.sourceforge.net/" />
|
|
<title>Writing snippets</title>
|
|
<meta name="author" content="pluskid, joaotavora" />
|
|
<meta name="date" content="2009-08-18" />
|
|
<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">Home</a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="snippet-organization.html">Organize</a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="snippet-expansion.html">Expand</a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="snippet-development.html">Write</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="#quickly-finding-defining-snippets" id="id6">Quickly finding/defining snippets</a></li>
|
|
<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id7">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a><ul>
|
|
<li><a class="reference internal" href="#the-syntax-of-the-template" id="id8">The Syntax of the Template</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#plain-text" id="id9">Plain Text</a></li>
|
|
<li><a class="reference internal" href="#embedded-elisp-code" id="id10">Embedded elisp code</a></li>
|
|
<li><a class="reference internal" href="#tab-stop-fields" id="id11">Tab stop fields</a></li>
|
|
<li><a class="reference internal" href="#placeholder-fields" id="id12">Placeholder fields</a></li>
|
|
<li><a class="reference internal" href="#id2" id="id13">Mirrors</a></li>
|
|
<li><a class="reference internal" href="#mirrors-with-transformations" id="id14">Mirrors with transformations</a></li>
|
|
<li><a class="reference internal" href="#fields-with-transformations" id="id15">Fields with transformations</a></li>
|
|
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id16">Choosing fields value from a list</a></li>
|
|
<li><a class="reference internal" href="#nested-placeholder-fields" id="id17">Nested placeholder fields</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="quickly-finding-defining-snippets">
|
|
<h1><a class="toc-backref" href="#id6">Quickly finding/defining snippets</a></h1>
|
|
<p>From version 0.6 upwards there are two 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)</p>
|
|
<ul>
|
|
<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">
|
|
<h1><a class="toc-backref" href="#id7">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h1>
|
|
<p>From version 0.6 upwards 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 class="section" id="the-syntax-of-the-template">
|
|
<h2><a class="toc-backref" href="#id8">The Syntax of the Template</a></h2>
|
|
<p>The syntax of the snippet template is simple but powerful, very
|
|
similar to TextMate's.</p>
|
|
</div>
|
|
</div>
|
|
<div class="section" id="plain-text">
|
|
<h1><a class="toc-backref" href="#id9">Plain Text</a></h1>
|
|
<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-elisp-code">
|
|
<h1><a class="toc-backref" href="#id10">Embedded elisp code</a></h1>
|
|
<p>Elisp 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">
|
|
<h1><a class="toc-backref" href="#id11">Tab stop fields</a></h1>
|
|
<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> <a class="footnote-reference" href="#id5" id="id1">[3]</a>. 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">
|
|
<h1><a class="toc-backref" href="#id12">Placeholder fields</a></h1>
|
|
<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><h1><a class="toc-backref" href="#id13">Mirrors</a></h1>
|
|
<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><h1><a class="toc-backref" href="#id14">Mirrors with transformations</a></h1>
|
|
<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 elisp 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
|
|
transformated 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>
|
|
<table class="docutils footnote" frame="void" id="id3" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label">[1]</td><td>With some minor change, mainly for fixing some trivial bugs.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="id4" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label">[2]</td><td>This is done when you call <tt class="docutils literal"><span class="pre">yas/initialize</span></tt>.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
<table class="docutils footnote" frame="void" id="id5" rules="none">
|
|
<colgroup><col class="label" /><col /></colgroup>
|
|
<tbody valign="top">
|
|
<tr><td class="label"><a class="fn-backref" href="#id1">[3]</a></td><td>Of course, this can be customized.</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<div class="section" id="fields-with-transformations">
|
|
<h1><a class="toc-backref" href="#id15">Fields with transformations</a></h1>
|
|
<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 this is differentiated from a mirror with a transformation
|
|
by the existance of 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">
|
|
<h1><a class="toc-backref" href="#id16">Choosing fields value from a list</a></h1>
|
|
<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">
|
|
<h1><a class="toc-backref" href="#id17">Nested placeholder fields</a></h1>
|
|
<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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|