/usr/share/doc/elpa-yasnippet/html/snippet-development.html

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<title>Writing snippets</title>
<meta  http-equiv="Content-Type" content="text/html;charset=utf-8" />
<meta  name="generator" content="Org-mode" />
<style type="text/css">
 <!--/*--><![CDATA[/*><!--*/
  .title  { text-align: center; }
  .todo   { font-family: monospace; color: red; }
  .done   { color: green; }
  .tag    { background-color: #eee; font-family: monospace;
            padding: 2px; font-size: 80%; font-weight: normal; }
  .timestamp { color: #bebebe; }
  .timestamp-kwd { color: #5f9ea0; }
  .right  { margin-left: auto; margin-right: 0px;  text-align: right; }
  .left   { margin-left: 0px;  margin-right: auto; text-align: left; }
  .center { margin-left: auto; margin-right: auto; text-align: center; }
  .underline { text-decoration: underline; }
  #postamble p, #preamble p { font-size: 90%; margin: .2em; }
  p.verse { margin-left: 3%; }
  pre {
    border: 1px solid #ccc;
    box-shadow: 3px 3px 3px #eee;
    padding: 8pt;
    font-family: monospace;
    overflow: auto;
    margin: 1.2em;
  }
  pre.src {
    position: relative;
    overflow: visible;
    padding-top: 1.2em;
  }
  pre.src:before {
    display: none;
    position: absolute;
    background-color: white;
    top: -10px;
    right: 10px;
    padding: 3px;
    border: 1px solid black;
  }
  pre.src:hover:before { display: inline;}
  pre.src-sh:before    { content: 'sh'; }
  pre.src-bash:before  { content: 'sh'; }
  pre.src-emacs-lisp:before { content: 'Emacs Lisp'; }
  pre.src-R:before     { content: 'R'; }
  pre.src-perl:before  { content: 'Perl'; }
  pre.src-java:before  { content: 'Java'; }
  pre.src-sql:before   { content: 'SQL'; }

  table { border-collapse:collapse; }
  caption.t-above { caption-side: top; }
  caption.t-bottom { caption-side: bottom; }
  td, th { vertical-align:top;  }
  th.right  { text-align: center;  }
  th.left   { text-align: center;   }
  th.center { text-align: center; }
  td.right  { text-align: right;  }
  td.left   { text-align: left;   }
  td.center { text-align: center; }
  dt { font-weight: bold; }
  .footpara:nth-child(2) { display: inline; }
  .footpara { display: block; }
  .footdef  { margin-bottom: 1em; }
  .figure { padding: 1em; }
  .figure p { text-align: center; }
  .inlinetask {
    padding: 10px;
    border: 2px solid gray;
    margin: 10px;
    background: #ffffcc;
  }
  #org-div-home-and-up
   { text-align: right; font-size: 70%; white-space: nowrap; }
  textarea { overflow-x: auto; }
  .linenr { font-size: smaller }
  .code-highlighted { background-color: #ffff00; }
  .org-info-js_info-navigation { border-style: none; }
  #org-info-js_console-label
    { font-size: 10px; font-weight: bold; white-space: nowrap; }
  .org-info-js_search-highlight
    { background-color: #ffff00; color: #000000; font-weight: bold; }
  /*]]>*/-->
</style>
<link rel="stylesheet" type="text/css" href="stylesheets/manual.css" />
<script type="text/javascript">
/*
@licstart  The following is the entire license notice for the
JavaScript code in this tag.

Copyright (C) 2012-2013 Free Software Foundation, Inc.

The JavaScript code in this tag is free software: you can
redistribute it and/or modify it under the terms of the GNU
General Public License (GNU GPL) as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version.  The code is distributed WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS
FOR A PARTICULAR PURPOSE.  See the GNU GPL for more details.

As additional permission under GNU GPL version 3 section 7, you
may distribute non-source (e.g., minimized or compacted) forms of
that code without the copy of the GNU GPL normally required by
section 4, provided you include this license notice and a URL
through which recipients can access the Corresponding Source.


@licend  The above is the entire license notice
for the JavaScript code in this tag.
*/
<!--/*--><![CDATA[/*><!--*/
 function CodeHighlightOn(elem, id)
 {
   var target = document.getElementById(id);
   if(null != target) {
     elem.cacheClassElem = elem.className;
     elem.cacheClassTarget = target.className;
     target.className = "code-highlighted";
     elem.className   = "code-highlighted";
   }
 }
 function CodeHighlightOff(elem, id)
 {
   var target = document.getElementById(id);
   if(elem.cacheClassElem)
     elem.className = elem.cacheClassElem;
   if(elem.cacheClassTarget)
     target.className = elem.cacheClassTarget;
 }
/*]]>*///-->
</script>
</head>
<body>
<div id="preamble" class="status">
<nav>
  <ul class="center">
    <li> <a href="index.html">Overview</a>
    <li> <a href="https://github.com/joaotavora/yasnippet/blob/master/README.mdown">
        Intro and Tutorial</a>
    <li class="center">Snippet
      <ul>
        <li> <a href="snippet-organization.html">Organization</a>
        <li> <a href="snippet-expansion.html">Expansion</a>
        <li> <a href="snippet-development.html">Development</a>
        <li> <a href="snippet-menu.html">Menu</a>
      </ul>
    <li> <a href="faq.html">FAQ</a>
    <li> <a href="snippet-reference.html">Reference</a>
  </ul>
</nav>
</div>
<div id="content">
<h1 class="title">Writing snippets</h1>
<div id="table-of-contents">
<h2>Table of Contents</h2>
<div id="text-table-of-contents">
<ul>
<li><a href="#sec-1">Snippet development</a>
<ul>
<li><a href="#sec-1-1">Quickly finding snippets</a></li>
<li><a href="#sec-1-2">Using the <code>snippet-mode</code> major mode </a></li>
</ul>
</li>
<li><a href="#sec-2">File content</a>
<ul>
<li><a href="#sec-2-1"><code># key:</code> snippet abbrev</a></li>
<li><a href="#sec-2-2"><code># name:</code> snippet name</a></li>
<li><a href="#sec-2-3"><code># condition:</code> snippet condition</a></li>
<li><a href="#sec-2-4"><code># group:</code> snippet menu grouping</a></li>
<li><a href="#sec-2-5"><code># expand-env:</code> expand environment</a></li>
<li><a href="#sec-2-6"><code># binding:</code> direct keybinding</a></li>
<li><a href="#sec-2-7"><code># type:</code> <code>snippet</code> or <code>command</code></a></li>
<li><a href="#sec-2-8"><code># uuid:</code> unique identifier</a></li>
<li><a href="#sec-2-9"><code># contributor:</code> snippet author</a></li>
</ul>
</li>
<li><a href="#sec-3">Template Syntax</a>
<ul>
<li><a href="#sec-3-1">Plain Text</a></li>
<li><a href="#sec-3-2">Embedded Emacs-lisp code</a>
<ul>
<li><a href="#sec-3-2-1">Note: backquote expressions should not modify the buffer</a></li>
</ul>
</li>
<li><a href="#sec-3-3">Tab stop fields</a></li>
<li><a href="#sec-3-4">Placeholder fields</a></li>
<li><a href="#sec-3-5">Mirrors </a></li>
<li><a href="#sec-3-6">Mirrors with transformations </a></li>
<li><a href="#sec-3-7">Fields with transformations</a></li>
<li><a href="#sec-3-8">Choosing fields value from a list and other tricks</a></li>
<li><a href="#sec-3-9">Nested placeholder fields</a></li>
<li><a href="#sec-3-10">Indentation markers</a></li>
</ul>
</li>
</ul>
</div>
</div>

<div id="outline-container-sec-1" class="outline-2">
<h2 id="sec-1">Snippet development</h2>
<div class="outline-text-2" id="text-1">
</div><div id="outline-container-sec-1-1" class="outline-3">
<h3 id="sec-1-1">Quickly finding snippets</h3>
<div class="outline-text-3" id="text-1-1">
<p>
There are some ways you can quickly find a snippet file or create a new one:
</p>

<ul class="org-ul">
<li><code>M-x yas-new-snippet</code>, key bindind: <code>C-c &amp; C-n</code>

<p>
Creates a new buffer with a template for making a new snippet.  The
buffer is in <code>snippet-mode</code> (see <a href="#snippet-mode">below</a>).  When you are done editing
the new snippet, use <a href="#yas-load-snippet-buffer-and-close"><code>C-c C-c</code></a> to save it.
</p>
</li>

<li><code>M-x yas-visit-snippet-file</code>, key binding: <code>C-c &amp; C-v</code>

<p>
Prompts you for possible snippet expansions like
<a href="snippet-reference.html#yas-insert-snippet"><code>yas-insert-snippet</code></a>, 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 <code>snippet-mode</code> (see <a href="#snippet-mode">ahead</a>)
and you can start editing your snippet.
</p>
</div>
</div>

<div id="outline-container-sec-1-2" class="outline-3">
<h3 id="sec-1-2">Using the <code>snippet-mode</code> major mode <a id="snippet-mode" name="snippet-mode"></a></h3>
<div class="outline-text-3" id="text-1-2">
<p>
There is a major mode <code>snippet-mode</code> to edit snippets. You can set the
buffer to this mode with <code>M-x snippet-mode</code>. It provides reasonably
useful syntax highlighting.
</p>

<p>
Three commands are defined in this mode:
</p>

<ul class="org-ul">
<li><code>M-x yas-load-snippet-buffer</code>, key binding: <code>C-c C-l</code>

<p>
Prompts for a snippet table (with a default based on snippet's
major mode) and loads the snippet currently being edited.
</p>
</li>

<li><code>M-x yas-load-snippet-buffer-and-close</code>, key binding: <code>C-c C-c</code>
   <a id="yas-load-snippet-buffer-and-close" name="yas-load-snippet-buffer-and-close"></a>

<p>
Like <code>yas-load-snippet-buffer</code>, but also saves the snippet and
calls <code>quit-window</code>.  The destination is decided based on the
chosen snippet table and snippet collection directly (defaulting to
the first directory in <code>yas-snippet-dirs</code> (see <a href="snippet-organization.html">Organizing Snippets</a>
for more detail on how snippets are organized).
</p>
</li>

<li><code>M-x yas-tryout-snippet</code>, key binding: <code>C-c C-t</code>

<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.
</p>
</li>
</ul>

<p>
There are also <i>snippets for writing snippets</i>: <code>vars</code>, <code>$f</code> and <code>$m</code>
:-).
</p>
</div>
</div>
</div>

<div id="outline-container-sec-2" class="outline-2">
<h2 id="sec-2">File content</h2>
<div class="outline-text-2" id="text-2">
<p>
A file defining a snippet generally contains the template to be
expanded.
</p>

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

<p>
Here's a typical example:
</p>

<div class="org-src-container">

<pre class="src src-snippet"># contributor: pluskid &lt;pluskid@gmail.com&gt;
# name: __...__
# --
__${init}__
</pre>
</div>

<p>
Here's a list of currently supported directives:
</p>
</div>

<div id="outline-container-sec-2-1" class="outline-3">
<h3 id="sec-2-1"><code># key:</code> snippet abbrev</h3>
<div class="outline-text-3" id="text-2-1">
<p>
This is the probably the most important directive, it's the
abbreviation you type to expand a snippet just before hitting the key
that runs <a href="snippet-reference.html#yas-expand"><code>yas-expand</code></a>. If you don't specify this
the snippet will not be expandable through the trigger mechanism.
</p>
</div>
</div>

<div id="outline-container-sec-2-2" class="outline-3">
<h3 id="sec-2-2"><code># name:</code> snippet name</h3>
<div class="outline-text-3" id="text-2-2">
<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 &#x2013;
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>

<div id="outline-container-sec-2-3" class="outline-3">
<h3 id="sec-2-3"><code># condition:</code> snippet condition</h3>
<div class="outline-text-3" id="text-2-3">
<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 <a href="snippet-reference.html#yas-buffer-local-condition"><code>yas-buffer-local-condition</code></a> in
<a href="./snippet-expansion.html">Expanding snippets</a>
</p>
</div>
</div>

<div id="outline-container-sec-2-4" class="outline-3">
<h3 id="sec-2-4"><code># group:</code> snippet menu grouping</h3>
<div class="outline-text-3" id="text-2-4">
<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 <code># group:</code> property only affect menu construction (See
<a href="./snippet-menu.html">the YASnippet menu</a>) and the same effect can be
achieved by grouping snippets into sub-directories and using the
<code>.yas-make-groups</code> special file (for this see
<a href="./snippet-organization.html">Organizing Snippets</a>
</p>

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

<div id="outline-container-sec-2-5" class="outline-3">
<h3 id="sec-2-5"><code># expand-env:</code> expand environment</h3>
<div class="outline-text-3" id="text-2-5">
<p>
This is another piece of Emacs-lisp code in the form of a <code>let</code> <i>varlist
form</i>, 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 <a href="snippet-reference.html#yas-wrap-around-region"><code>yas-wrap-around-region</code></a> and
<a href="snippet-reference.html#yas-indent-line"><code>yas-indent-line</code></a> (see <a href="./snippet-expansion.html">Expanding Snippets</a>).
</p>

<p>
As an example, you might normally have <a href="snippet-reference.html#yas-indent-line"><code>yas-indent-line</code></a> set to '<code>auto</code>
and <a href="snippet-reference.html#yas-wrap-around-region"><code>yas-wrap-around-region</code></a> set to <code>t</code>, but for this particularly
brilliant piece of ASCII art these values would mess up your hard work.
You can then use:
</p>

<div class="org-src-container">

<pre class="src src-snippet"># 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>

<div id="outline-container-sec-2-6" class="outline-3">
<h3 id="sec-2-6"><code># binding:</code> direct keybinding</h3>
<div class="outline-text-3" id="text-2-6">
<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 <a href="snippet-reference.html#yas-prefix"><code>yas-prefix</code></a> 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="org-src-container">

<pre class="src src-snippet"># name: &lt;p&gt;...&lt;/p&gt;
# binding: C-c C-c C-m
# --
&lt;p&gt;`(when yas-prefix "\n")`$0`(when yas-prefix "\n")`&lt;/p&gt;
</pre>
</div>

<p>
This binding will be recorded in the keymap <code>html-mode-map</code>. To expand a
paragraph tag newlines, just press <code>C-u C-c C-c C-m</code>. Omitting the <code>C-u</code>
will expand the paragraph tag without newlines.
</p>
</div>
</div>

<div id="outline-container-sec-2-7" class="outline-3">
<h3 id="sec-2-7"><code># type:</code> <code>snippet</code> or <code>command</code></h3>
<div class="outline-text-3" id="text-2-7">
<p>
If the <code>type</code> directive is set to <code>command</code>, the body of the snippet
is interpreted as lisp code to be evaluated when the snippet is
triggered.
</p>

<p>
If it's <code>snippet</code> (the default when there is no <code>type</code> directive), the
snippet body will be parsed according to the <a href="#sec-3">Template Syntax</a>,
described below.
</p>
</div>
</div>

<div id="outline-container-sec-2-8" class="outline-3">
<h3 id="sec-2-8"><code># uuid:</code> unique identifier</h3>
<div class="outline-text-3" id="text-2-8">
<p>
This provides to a way to identify a snippet, independent of its name.
Loading a second snippet file with the same uuid would replace the
previous snippet.
</p>
</div>
</div>

<div id="outline-container-sec-2-9" class="outline-3">
<h3 id="sec-2-9"><code># contributor:</code> snippet author</h3>
<div class="outline-text-3" id="text-2-9">
<p>
This is optional and has no effect whatsoever on snippet functionality,
but it looks nice.
</p>
</div>
</div>
</div>

<div id="outline-container-sec-3" class="outline-2">
<h2 id="sec-3">Template Syntax</h2>
<div class="outline-text-2" id="text-3">
<p>
The syntax of the snippet template is simple but powerful, very similar
to TextMate's.
</p>
</div>

<div id="outline-container-sec-3-1" class="outline-3">
<h3 id="sec-3-1">Plain Text</h3>
<div class="outline-text-3" id="text-3-1">
<p>
Arbitrary text can be included as the content of a template. They are
usually interpreted as plain text, except <code>$</code> and <code>`</code>. You need to
use <code>\</code> to escape them: <code>\$</code> and <code>\`</code>. The <code>\</code> itself may also needed to be
escaped as <code>\\</code> sometimes.
</p>
</div>
</div>

<div id="outline-container-sec-3-2" class="outline-3">
<h3 id="sec-3-2">Embedded Emacs-lisp code</h3>
<div class="outline-text-3" id="text-3-2">
<p>
Emacs-Lisp code can be embedded inside the template, written inside
back-quotes (<code>`</code>). 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 c-mode to calculate the header file guard
dynamically:
</p>

<div class="org-src-container">

<pre class="src src-snippet">#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 <a href="snippet-reference.html#yas-selected-text"><code>yas-selected-text</code></a>. You can
therefore define a snippet like:
</p>

<div class="org-src-container">

<pre class="src src-snippet">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
<a href="snippet-reference.html#yas-wrap-around-region"><code>yas-wrap-around-region</code></a> to <code>t</code> which will do this automatically.
</p>
</div>

<div id="outline-container-sec-3-2-1" class="outline-4">
<h4 id="sec-3-2-1">Note: backquote expressions should not modify the buffer</h4>
<div class="outline-text-4" id="text-3-2-1">
<p>
Please note that the lisp forms in backquotes should <b>not</b> modify the
buffer, doing so will trigger a warning.  For example, instead of
doing
</p>

<div class="org-src-container">

<pre class="src src-snippet">Timestamp: `(insert (current-time-string))`
</pre>
</div>

<p>
do this:
</p>
<div class="org-src-container">

<pre class="src src-snippet">Timestamp: `(current-time-string)`
</pre>
</div>

<p>
The warning may be suppressed with the following code in your init file:
</p>
<div class="org-src-container">

<pre class="src src-emacs-lisp">(add-to-list 'warning-suppress-types '(yasnippet backquote-change))
</pre>
</div>
</div>
</div>
</div>


<div id="outline-container-sec-3-3" class="outline-3">
<h3 id="sec-3-3">Tab stop fields</h3>
<div class="outline-text-3" id="text-3-3">
<p>
Tab stops are fields that you can navigate back and forth by <code>TAB</code> and
<code>S-TAB</code>. They are written by <code>$</code> followed with a number. <code>$0</code> has the
special meaning of the <i>exit point</i> 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="org-src-container">

<pre class="src src-snippet">&lt;div$1&gt;
    $0
&lt;/div&gt;
</pre>
</div>
</div>
</div>
<div id="outline-container-sec-3-4" class="outline-3">
<h3 id="sec-3-4">Placeholder fields</h3>
<div class="outline-text-3" id="text-3-4">
<p>
Tab stops can have default values &#x2013; a.k.a placeholders. The syntax is
like this:
</p>

<div class="org-src-container">

<pre class="src src-snippet">${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 href="#mirrors-fields">mirrors</a> or
<a href="#mirror-transformations">transformations</a> for this field.
</p>
</div>
</div>

<div id="outline-container-sec-3-5" class="outline-3">
<h3 id="sec-3-5">Mirrors <a id="mirrors-fields" name="mirrors-fields"></a></h3>
<div class="outline-text-3" id="text-3-5">
<p>
We refer the tab stops with placeholders as a <i>field</i>. 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="org-src-container">

<pre class="src src-snippet">\begin{${1:enumerate}}
    $0
\end{$1}
</pre>
</div>

<p>
When you type "document" at <code>${1:enumerate}</code>, the word "document" will
also be inserted at <code>\end{$1}</code>. The best explanation is to see the
screencast(<a href="http://www.youtube.com/watch?v=vOj7btx3ATg">YouTube</a> or <a 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>

<div id="outline-container-sec-3-6" class="outline-3">
<h3 id="sec-3-6">Mirrors with transformations <a id="mirror-transformations" name="mirror-transformations"></a></h3>
<div class="outline-text-3" id="text-3-6">
<p>
If the value of an <code>${n:</code>-construct starts with and contains <code>$(</code>,
then it is interpreted as a mirror for field <code>n</code> 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 <a href="snippet-reference.html#yas-text"><code>yas-text</code></a> is bound to the text
content (string) contained in the field <code>n</code>. Here's an example for
Objective-C:
</p>

<div class="org-src-container">

<pre class="src src-snippet">- (${1:id})${2:foo}
{
    return $2;
}

- (void)set${2:$(capitalize yas-text)}:($1)aValue
{
    [$2 autorelease];
    $2 = [aValue retain];
}
$0
</pre>
</div>

<p>
Look at <code>${2:$(capitalize yas-text)}</code>, it is a mirror with
transformation instead of a field. The actual field is at the first
line: <code>${2:foo}</code>. When you type text in <code>${2:foo}</code>, 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 <code>rst-mode</code>. In reStructuredText, the document
title can be some text surrounded by "<code>=</code>" below and above. The "<code>=</code>"
should be at least as long as the text. So
</p>

<div class="org-src-container">

<pre class="src src-rst">=====
Title
=====
</pre>
</div>

<p>
is a valid title but
</p>

<div class="org-src-container">

<pre class="src src-rst">===
Title
===
</pre>
</div>

<p>
is not. Here's an snippet for rst title:
</p>

<div class="org-src-container">

<pre class="src src-snippet">${1:$(make-string (string-width yas-text) ?\=)}
${1:Title}
${1:$(make-string (string-width yas-text) ?\=)}

$0
</pre>
</div>
</div>
</div>

<div id="outline-container-sec-3-7" class="outline-3">
<h3 id="sec-3-7">Fields with transformations</h3>
<div class="outline-text-3" id="text-3-7">
<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>

<pre class="example">
#define "${1:mydefine$(upcase yas-text)}"
</pre>

<p>
<code>mydefine</code> gets automatically upcased to <code>MYDEFINE</code> 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 <code>:</code> and the
transformation's <code>$</code>. If you don't want this extra-text, you can use two
<code>$</code>'s instead.
</p>

<pre class="example">
#define "${1:$$(upcase yas-text)}"
</pre>

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

<div id="outline-container-sec-3-8" class="outline-3">
<h3 id="sec-3-8">Choosing fields value from a list and other tricks</h3>
<div class="outline-text-3" id="text-3-8">
<p>
As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
<a href="snippet-reference.html#yas-modified-p"><code>yas-modified-p</code></a> and <a href="snippet-reference.html#yas-moving-away-p"><code>yas-moving-away-p</code></a>. Because of this feature you
can place a transformation in the primary field that lets you select
default values for it.
</p>

<p>
The <a href="snippet-reference.html#yas-choose-value"><code>yas-choose-value</code></a> does this work for you. For example:
</p>

<div class="org-src-container">

<pre class="src src-snippet">&lt;div align="${2:$$(yas-choose-value '("right" "center" "left"))}"&gt;
  $0
&lt;/div&gt;
</pre>
</div>

<p>
See the definition of <a href="snippet-reference.html#yas-choose-value"><code>yas-choose-value</code></a> 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 <a href="snippet-reference.html#yas-modified-p"><code>yas-modified-p</code></a> directly.
</p>

<div class="org-src-container">

<pre class="src src-snippet">\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 <a href="snippet-reference.html#yas-verify-value"><code>yas-verify-value</code></a> has another neat trick, and makes use
of <a href="snippet-reference.html#yas-moving-away-p"><code>yas-moving-away-p</code></a>. Try it and see! Also, check out this <a href="http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662">thread</a>
</p>
</div>
</div>

<div id="outline-container-sec-3-9" class="outline-3">
<h3 id="sec-3-9">Nested placeholder fields</h3>
<div class="outline-text-3" id="text-3-9">
<p>
From version 0.6 on, you can also have nested placeholders of the type:
</p>

<div class="org-src-container">

<pre class="src src-snippet">&lt;div${1: id="${2:some_id}"}&gt;$0&lt;/div&gt;
</pre>
</div>

<p>
This allows you to choose if you want to give this <code>div</code> an <code>id</code>
attribute. If you tab forward after expanding it will let you change
"some\<sub>id</sub>" to whatever you like. Alternatively, you can just press <code>C-d</code>
(which executes <a href="snippet-reference.html#yas-skip-and-clear-or-delete-char"><code>yas-skip-and-clear-or-delete-char</code></a>) and go straight to
the exit marker.
</p>

<p>
By the way, <code>C-d</code> will only clear the field if you cursor is at the
beginning of the field <i>and</i> it hasn't been changed yet. Otherwise, it
performs the normal Emacs <code>delete-char</code> command.
</p>
</div>
</div>

<div id="outline-container-sec-3-10" class="outline-3">
<h3 id="sec-3-10">Indentation markers</h3>
<div class="outline-text-3" id="text-3-10">
<p>
If <a href="snippet-reference.html#yas-indent-line"><code>yas-indent-line</code></a> is <b>not</b> set to '<code>auto</code>, it's still possible to
indent specific lines by adding an indentation marker, <code>$&gt;</code>, somewhere
on the line.
</p>
</div>
</div>
</div>
</div>
<div id="postamble" class="status">
<hr><p class='creator'>Generated by <a href="http://www.gnu.org/software/emacs/">Emacs</a> 25.2.2 (<a href="http://orgmode.org">Org</a> mode 8.2.10) from 0.12.2 (2017-12-22 10:07:25)</p>
<p class='xhtml-validation'><a href="http://validator.w3.org/check?uri=referer">Validate</a></p>
</div>
</body>
</html>
elpa-yasnippet 0.12.2-2 / usr / share / doc / elpa-yasnippet / html / snippet-development.html
