code.delx.au - gnu-emacs-elpa/blob - doc/snippet-development.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
   7 <title>Writing snippets</title>
   8 <link rel="stylesheet" href="styles.css" type="text/css" />
   9 </head>
  10 <body>
  11 <div class="document" id="writing-snippets">
  12 <div id="header-region" class="clear-block"></div>
  13 <div id="wrapper">
  14   <div id="container" class="clear-block">
  15     <div id="header">
  16     <div id="logo-floater">
  17     <h1 class="title">Writing snippets</h1>
  18     </div>
  19     <ul class="primary-links">
  20       <li>
  21         <a title="" href="index.html">Intro and tutorial</a>
  22       </li>
  23       <li>
  24         <a title="" href="snippet-organization.html">Howto: organize</a>
  25       </li>
  26       <li>
  27         <a title="" href="snippet-expansion.html">Howto: expand</a>
  28       </li>
  29       <li>
  30         <a title="" href="snippet-development.html">Howto: write </a>
  31       </li>
  32       <li>
  33         <a title="" href="snippet-menu.html">Howto: menu </a>
  34       </li>
  35       <li>
  36         <a title="" href="faq.html">FAQ</a>
  37       </li>
  38       <li>
  39         <a title="" href="changelog.html">ChangeLog</a>
  40       </li>
  41       <li>
  42         <a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
  43       </li>
  44     </ul>
  45     </div>
  46     <div id="center">
  47       <div id="squeeze">
  48         <div class="right-corner">
  49           <div class="left-corner">
  50             <p>
  51               <b>Important:</b> This documentation applies to
  52               the <b>SVN trunk</b> of YASnippet, which you
  53               get <a href="http://code.google.com/p/yasnippet/source/checkout">here</a>. Documentation
  54               for other versions can be found <a title=""
  55               href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
  56             </p>
  57             <div class="contents topic" id="contents">
  58 <p class="topic-title first">Contents</p>
  59 <ul class="simple">
  60 <li><a class="reference internal" href="#snippet-development" id="id3">Snippet development</a><ul>
  61 <li><a class="reference internal" href="#quickly-finding-snippets" id="id4">Quickly finding snippets</a></li>
  62 <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>
  63 </ul>
  64 </li>
  65 <li><a class="reference internal" href="#file-content" id="id6">File content</a><ul>
  66 <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>
  67 <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>
  68 <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>
  69 <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>
  70 <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>
  71 <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>
  72 <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>
  73 </ul>
  74 </li>
  75 <li><a class="reference internal" href="#template-syntax" id="id14">Template syntax</a><ul>
  76 <li><a class="reference internal" href="#plain-text" id="id15">Plain Text</a></li>
  77 <li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id16">Embedded Emacs-lisp code</a></li>
  78 <li><a class="reference internal" href="#tab-stop-fields" id="id17">Tab stop fields</a></li>
  79 <li><a class="reference internal" href="#placeholder-fields" id="id18">Placeholder fields</a></li>
  80 <li><a class="reference internal" href="#id2" id="id19">Mirrors</a></li>
  81 <li><a class="reference internal" href="#mirrors-with-transformations" id="id20">Mirrors with transformations</a></li>
  82 <li><a class="reference internal" href="#fields-with-transformations" id="id21">Fields with transformations</a></li>
  83 <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>
  84 <li><a class="reference internal" href="#nested-placeholder-fields" id="id23">Nested placeholder fields</a></li>
  85 </ul>
  86 </li>
  87 <li><a class="reference internal" href="#customizable-variables" id="id24">Customizable variables</a><ul>
  88 <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>
  89 <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>
  90 <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>
  91 <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>
  92 <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>
  93 <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>
  94 <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>
  95 <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>
  96 <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>
  97 <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>
  98 </ul>
  99 </li>
 100 <li><a class="reference internal" href="#importing-textmate-snippets" id="id35">Importing TextMate snippets</a></li>
 101 </ul>
 102 </div>
 103 <div class="section" id="snippet-development">
 104 <h1><a class="toc-backref" href="#id3">Snippet development</a></h1>
 105 <div class="section" id="quickly-finding-snippets">
 106 <h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2>
 107 <p>There are some ways you can quickly find a snippet file:</p>
 108 <ul>
 109 <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt></p>
 110 <p>Prompts you for a snippet name, then tries to guess a suitable
 111 directory to store it, prompting you for creation if it does not
 112 exist. Finally, places you in a new buffer set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt>
 113 so you can write your snippet.</p>
 114 </li>
 115 <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/find-snippets</span></tt></p>
 116 <p>Lets you find the snippet file in the directory the snippet was
 117 loaded from (if it exists) like <tt class="docutils literal"><span class="pre">find-file-other-window</span></tt>. The
 118 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>
 119 </li>
 120 <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/visit-snippet-file</span></tt></p>
 121 <p>Prompts you for possible snippet expansions like
 122 <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt>, but instead of expanding it, takes you
 123 directly to the snippet definition's file, if it exists.</p>
 124 </li>
 125 </ul>
 126 <p>Once you find this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead)
 127 and you can start editing your snippet.</p>
 128 </div>
 129 <div class="section" id="using-the-snippet-mode-major-mode">
 130 <h2><a class="toc-backref" href="#id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h2>
 131 <p>There is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to edit snippets. You can set
 132 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
 133 reasonably useful syntax highlighting.</p>
 134 <p>Two commands are defined in this mode:</p>
 135 <ul>
 136 <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p>
 137 <blockquote>
 138 <p>When editing a snippet, this loads the snippet into the correct
 139 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
 140 <tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p>
 141 </blockquote>
 142 </li>
 143 <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/tryout-snippet</span></tt></p>
 144 <blockquote>
 145 <p>When editing a snippet, this opens a new empty buffer, sets it to
 146 the appropriate major mode and inserts the snippet there, so you
 147 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
 148 <tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p>
 149 </blockquote>
 150 </li>
 151 </ul>
 152 <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
 153 <tt class="docutils literal"><span class="pre">$m</span></tt> :-).</p>
 154 </div>
 155 </div>
 156 <div class="section" id="file-content">
 157 <h1><a class="toc-backref" href="#id6">File content</a></h1>
 158 <p>A file defining a snippet generally contains the template to be
 159 expanded.</p>
 160 <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
 161 it count as comments, some of which can be <em>directives</em> (or meta
 162 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
 163 certain snippets properties described below. If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found,
 164 the whole file is considered the snippet template.</p>
 165 <p>Here's a typical example:</p>
 166 <div class="highlight"><pre>#contributor : pluskid &lt;pluskid@gmail.com&gt;
 167 #name : __...__
 168 # --
 169 __${init}__
 170 </pre></div>
 171 <p>Here's a list of currently supported directives:</p>
 172 <div class="section" id="key-snippet-abbrev">
 173 <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>
 174 <p>This is the probably the most important directive, it's the
 175 abbreviation you type to expand a snippet just before hitting
 176 <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p>
 177 <p>If you don't specify this it will default to the name of the file the
 178 snippet is being loaded from, unless YASnippet is ignoring file names
 179 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
 180 snippets</a>), in which case this snippet
 181 will not be expandable through the key mechanism.</p>
 182 <p>Sometimes the key of a snippet is non-ASCII or not valid filename
 183 (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
 184 will overwrite the filename as the key to expand the snippet.</p>
 185 </div>
 186 <div class="section" id="name-snippet-name">
 187 <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>
 188 <p>This is a one-line description of the snippet. It will be displayed in
 189 the menu. It's a good idea to select a descriptive name for a
 190 snippet -- especially distinguishable among similar snippets.</p>
 191 <p>If you omit this name it will default to the file name the snippet was
 192 loaded from.</p>
 193 </div>
 194 <div class="section" id="condition-snippet-condition">
 195 <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>
 196 <p>This is a piece of Emacs-lisp code. If a snippet has a condition, then it
 197 will only be expanded when the condition code evaluate to some non-nil
 198 value.</p>
 199 <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>
 200 </div>
 201 <div class="section" id="group-snippet-menu-grouping">
 202 <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>
 203 <p>When expanding/visiting snippets from the menu-bar menu, snippets for a
 204 given mode can be grouped into sub-menus . This is useful if one has
 205 too many snippets for a mode which will make the menu too
 206 long.</p>
 207 <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
 208 YASnippet menu</a>) and the same effect can be achieved by grouping
 209 snippets into sub-directories and using the <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt>
 210 special file (for this see <a class="reference external" href="snippet-organization.html">Organizing Snippets</a></p>
 211 <p>Refer to the bundled snippets for <tt class="docutils literal"><span class="pre">ruby-mode</span></tt> for examples on the
 212 <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>
 213 <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
 214 which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt> group.</p>
 215 </div>
 216 <div class="section" id="expand-env-expand-environment">
 217 <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>
 218 <p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt>
 219 <em>varlist form</em>, i.e. a list of lists assigning values to variables. It
 220 can be used to override variable values while the snippet is being
 221 expanded.</p>
 222 <p>Interesting variables to override are <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> and
 223 <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>
 224 <p>As an example, you might normally have <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> set to
 225 <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
 226 particularly brilliant piece of ASCII art these values would mess up
 227 your hard work. You can then use:</p>
 228 <div class="highlight"><pre># name : ASCII home
 229 # expand-env: ((yas/indent-line &#39;fixed) (yas/wrap-around-region &#39;nil))
 230 # --
 231                 welcome to my
 232             X      humble
 233            / \      home,
 234           /   \      $0
 235          /     \
 236         /-------\
 237         |       |
 238         |  +-+  |
 239         |  | |  |
 240         +--+-+--+
 241 </pre></div>
 242 </div>
 243 <div class="section" id="binding-direct-keybinding">
 244 <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>
 245 <p>You can use this directive to expand a snippet directly from a normal
 246 Emacs keybinding. The keybinding will be registered in the Emacs
 247 keymap named after the major mode the snippet is active
 248 for.</p>
 249 <p>Additionally a variable <tt class="docutils literal"><span class="pre">yas/prefix</span></tt> is set to to the prefix
 250 argument you normally use for a command. This allows for small
 251 variations on the same snippet, for example in this &quot;html-mode&quot;
 252 snippet.</p>
 253 <div class="highlight"><pre>#name : &lt;p&gt;...&lt;/p&gt;
 254 #binding: &quot;C-c C-c C-m&quot;
 255 # --
 256 &lt;p&gt;`(when yas/prefix &quot;\n&quot;)`$0`(when yas/prefix &quot;\n&quot;)`&lt;/p&gt;
 257 </pre></div>
 258 <p>This binding will be recorded in the keymap <tt class="docutils literal"><span class="pre">html-mode-map</span></tt>. To
 259 expand a paragraph tag newlines, just press &quot;C-u C-c C-c
 260 C-m&quot;. Omitting the &quot;C-u&quot; will expand the paragraph tag without
 261 newlines.</p>
 262 <p>To override the keymap choice based on the major mode name. Use a cons
 263 cell where the first element specifies the name of the keymap where
 264 you want to record the keybinding.</p>
 265 <div class="highlight"><pre>#name : &lt;p&gt;...&lt;/p&gt;
 266 #binding: (rinari-minor-mode-map . &quot;C-c C-c C-m&quot;)
 267 # --
 268 &lt;p&gt;`(when yas/prefix &quot;\n&quot;)`$0`(when yas/prefix &quot;\n&quot;)`&lt;/p&gt;
 269 </pre></div>
 270 <p><strong>Note</strong>: this feature is still <strong>experimental</strong>, it might go away, be
 271 changed in future release, and should be used with caution: It is easy
 272 to override important keybindings for many basic modes and it is hard
 273 to undefine them. For the moment, the variable
 274 <tt class="docutils literal"><span class="pre">yas/active-keybindings</span></tt> can tell you what snippet keybindings are
 275 active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt
 276 to undefine all the keybindings.</p>
 277 </div>
 278 <div class="section" id="contributor-snippet-author">
 279 <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>
 280 <p>This is optional and has no effect whatsoever on snippet
 281 functionality, but it looks nice.</p>
 282 </div>
 283 </div>
 284 <div class="section" id="template-syntax">
 285 <h1><a class="toc-backref" href="#id14">Template syntax</a></h1>
 286 <p>The syntax of the snippet template is simple but powerful, very
 287 similar to TextMate's.</p>
 288 <div class="section" id="plain-text">
 289 <h2><a class="toc-backref" href="#id15">Plain Text</a></h2>
 290 <p>Arbitrary text can be included as the content of a template. They are
 291 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
 292 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
 293 needed to be escaped as <tt class="docutils literal"><span class="pre">\\</span></tt> sometimes.</p>
 294 </div>
 295 <div class="section" id="embedded-emacs-lisp-code">
 296 <h2><a class="toc-backref" href="#id16">Embedded Emacs-lisp code</a></h2>
 297 <p>Emacs-Lisp code can be embedded inside the template, written inside
 298 back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>). The lisp forms are evaluated when the snippet is
 299 being expanded. The evaluation is done in the same buffer as the
 300 snippet being expanded.</p>
 301 <p>Here's an example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard
 302 dynamically:</p>
 303 <div class="highlight"><pre>#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
 304 #define $1
 305
 306 $0
 307
 308 #endif /* $1 */
 309 </pre></div>
 310 <p>From version 0.6, snippets expansions are run with some special
 311 Emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You
 312 can therefore define a snippet like:</p>
 313 <div class="highlight"><pre>for ($1;$2;$3) {
 314   `yas/selected-text`$0
 315 }
 316 </pre></div>
 317 <p>to &quot;wrap&quot; the selected region inside your recently inserted
 318 snippet. Alternatively, you can also customize the variable
 319 <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>
 320 </div>
 321 <div class="section" id="tab-stop-fields">
 322 <h2><a class="toc-backref" href="#id17">Tab stop fields</a></h2>
 323 <p>Tab stops are fields that you can navigate back and forth by <tt class="docutils literal"><span class="pre">TAB</span></tt>
 324 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
 325 number. <tt class="docutils literal"><span class="pre">$0</span></tt> has the special meaning of the <em>exit point</em> of a
 326 snippet. That is the last place to go when you've traveled all the
 327 fields. Here's a typical example:</p>
 328 <div class="highlight"><pre>&lt;div$1&gt;
 329     $0
 330 &lt;/div&gt;
 331 </pre></div>
 332 </div>
 333 <div class="section" id="placeholder-fields">
 334 <h2><a class="toc-backref" href="#id18">Placeholder fields</a></h2>
 335 <p>Tab stops can have default values -- a.k.a placeholders. The syntax is
 336 like this:</p>
 337 <div class="highlight"><pre>${N:default value}
 338 </pre></div>
 339 <p>They acts as the default value for a tab stop. But when you firstly
 340 type at a tab stop, the default value will be replaced by your
 341 typing. The number can be omitted if you don't want to create
 342 <a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p>
 343 </div>
 344 <div class="section" id="id2">
 345 <span id="mirrors"></span><h2><a class="toc-backref" href="#id19">Mirrors</a></h2>
 346 <p>We refer the tab stops with placeholders as a <em>field</em>. A field can have
 347 mirrors. Its mirrors will get updated when you change the text of a
 348 field. Here's an example:</p>
 349 <div class="highlight"><pre>\begin{${1:enumerate}}
 350     $0
 351 \end{$1}
 352 </pre></div>
 353 <p>When you type <tt class="docutils literal"><span class="pre">&quot;document&quot;</span></tt> at <tt class="docutils literal"><span class="pre">${1:enumerate}</span></tt>, the word
 354 <tt class="docutils literal"><span class="pre">&quot;document&quot;</span></tt> will also be inserted at <tt class="docutils literal"><span class="pre">\end{$1}</span></tt>. The best
 355 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>
 356 <p>The tab stops with the same number to the field act as its mirrors. If
 357 none of the tab stops has an initial value, the first one is selected
 358 as the field and others mirrors.</p>
 359 </div>
 360 <div class="section" id="mirrors-with-transformations">
 361 <span id="transformations"></span><h2><a class="toc-backref" href="#id20">Mirrors with transformations</a></h2>
 362 <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>,
 363 then it is interpreted as a mirror for field <tt class="docutils literal"><span class="pre">n</span></tt> with a
 364 transformation. The mirror's text content is calculated according to
 365 this transformation, which is Emacs-lisp code that gets evaluated in
 366 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
 367 to the text content (string) contained in the field <tt class="docutils literal"><span class="pre">n</span></tt>.Here's an
 368 example for Objective-C:</p>
 369 <div class="highlight"><pre>- (${1:id})${2:foo}
 370 {
 371     return $2;
 372 }
 373
 374 - (void)set${2:$(capitalize text)}:($1)aValue
 375 {
 376     [$2 autorelease];
 377     $2 = [aValue retain];
 378 }
 379 $0
 380 </pre></div>
 381 <p>Look at <tt class="docutils literal"><span class="pre">${2:$(capitalize</span> <span class="pre">text)}</span></tt>, it is a mirror with
 382 transformation instead of a field. The actual field is at the first
 383 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
 384 transformation will be evaluated and the result will be placed there
 385 as the transformed text. So in this example, if you type &quot;baz&quot; in the
 386 field, the transformed text will be &quot;Baz&quot;. This example is also
 387 available in the screencast.</p>
 388 <p>Another example is for <tt class="docutils literal"><span class="pre">rst-mode</span></tt>. In reStructuredText, the document
 389 title can be some text surrounded by &quot;===&quot; below and above. The &quot;===&quot;
 390 should be at least as long as the text. So</p>
 391 <div class="highlight"><pre>=====
 392 Title
 393 =====
 394 </pre></div>
 395 <p>is a valid title but</p>
 396 <div class="highlight"><pre>===
 397 Title
 398 ===
 399 </pre></div>
 400 <p>is not. Here's an snippet for rst title:</p>
 401 <div class="highlight"><pre>${1:$(make-string (string-width text) ?\=)}
 402 ${1:Title}
 403 ${1:$(make-string (string-width text) ?\=)}
 404
 405 $0
 406 </pre></div>
 407 </div>
 408 <div class="section" id="fields-with-transformations">
 409 <h2><a class="toc-backref" href="#id21">Fields with transformations</a></h2>
 410 <p>From version 0.6 on, you can also have lisp transformation inside
 411 fields. These work mostly mirror transformations but are evaluated
 412 when you first enter the field, after each change you make to the
 413 field and also just before you exit the field.</p>
 414 <p>The syntax is also a tiny bit different, so that the parser can
 415 distinguish between fields and mirrors. In the following example</p>
 416 <div class="highlight"><pre>#define &quot;${1:mydefine$(upcase yas/text)}&quot;
 417 </pre></div>
 418 <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
 419 the field. As you type text, it gets filtered through the
 420 transformation every time.</p>
 421 <p>Note that to tell this kind of expression from a mirror with a
 422 transformation, YASnippet needs extra text between the <tt class="docutils literal"><span class="pre">:</span></tt> and the
 423 transformation's <tt class="docutils literal"><span class="pre">$</span></tt>. If you don't want this extra-text, you can use
 424 two <tt class="docutils literal"><span class="pre">$</span></tt>'s instead.</p>
 425 <div class="highlight"><pre>#define &quot;${1:$$(upcase yas/text)}&quot;
 426 </pre></div>
 427 <p>Please note that as soon as a transformation takes place, it changes
 428 the value of the field and sets it its internal modification state to
 429 <tt class="docutils literal"><span class="pre">true</span></tt>. As a consequence, the auto-deletion behaviour of normal
 430 fields does not take place. This is by design.</p>
 431 </div>
 432 <div class="section" id="choosing-fields-value-from-a-list-and-other-tricks">
 433 <h2><a class="toc-backref" href="#id22">Choosing fields value from a list and other tricks</a></h2>
 434 <p>As mentioned, the field transformation is invoked just after you enter
 435 the field, and with some useful variables bound, notably
 436 <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
 437 feature you can place a transformation in the primary field that lets
 438 you select default values for it.</p>
 439 <p>The <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> does this work for you. For example:</p>
 440 <div class="highlight"><pre>&lt;div align=&quot;${2:$$(yas/choose-value &#39;(&quot;right&quot; &quot;center&quot; &quot;left&quot;))}&quot;&gt;
 441   $0
 442 &lt;/div&gt;
 443 </pre></div>
 444 <p>See the definition of <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> to see how it was written
 445 using the two variables.</p>
 446 <p>Here's another use, for LaTeX-mode, which calls reftex-label just as
 447 you enter snippet field 2. This one makes use of <tt class="docutils literal"><span class="pre">yas/modified-p</span></tt>
 448 directly.</p>
 449 <div class="highlight"><pre>\section{${1:&quot;Titel der Tour&quot;}}%
 450 \index{$1}%
 451 \label{{2:&quot;waiting for reftex-label call...&quot;$(unless yas/modified-p (reftex-label nil &#39;dont-
 452 insert))}}%
 453 </pre></div>
 454 <p>The function <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> has another neat trick, and makes
 455 use of <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Try it and see! Also, check out this
 456 <a class="reference external" href="http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662">thread</a></p>
 457 </div>
 458 <div class="section" id="nested-placeholder-fields">
 459 <h2><a class="toc-backref" href="#id23">Nested placeholder fields</a></h2>
 460 <p>From version 0.6 on, you can also have nested placeholders of the type:</p>
 461 <div class="highlight"><pre>&lt;div${1: id=&quot;${2:some_id}&quot;}&gt;$0&lt;/div&gt;
 462 </pre></div>
 463 <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>
 464 attribute. If you tab forward after expanding it will let you change
 465 &quot;some_id&quot; to whatever you like. Alternatively, you can just press
 466 <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
 467 straight to the exit marker.</p>
 468 <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
 469 beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it
 470 performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p>
 471 </div>
 472 </div>
 473 <div class="section" id="customizable-variables">
 474 <h1><a class="toc-backref" href="#id24">Customizable variables</a></h1>
 475 <div class="section" id="yas-trigger-key">
 476 <h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2>
 477 <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
 478 active.</p>
 479 <p>Value is a string that is converted to the internal Emacs key
 480 representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
 481 <p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
 482 </div>
 483 <div class="section" id="yas-next-field-key">
 484 <h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2>
 485 <p>The key to navigate to next field when a snippet is active.</p>
 486 <p>Value is a string that is converted to the internal Emacs key
 487 representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
 488 <p>Can also be a list of keys.</p>
 489 <p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
 490 </div>
 491 <div class="section" id="yas-prev-field-key">
 492 <h2><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2>
 493 <p>The key to navigate to previous field when a snippet is active.</p>
 494 <p>Value is a string that is converted to the internal Emacs key
 495 representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
 496 <p>Can also be a list of keys.</p>
 497 <p>Default value is <tt class="docutils literal"><span class="pre">(&quot;&lt;backtab&gt;&quot;</span> <span class="pre">&quot;&lt;S-tab&gt;)&quot;</span></tt>.</p>
 498 </div>
 499 <div class="section" id="yas-skip-and-clear-key">
 500 <h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></h2>
 501 <p>The key to clear the currently active field.</p>
 502 <p>Value is a string that is converted to the internal Emacs key
 503 representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
 504 <p>Can also be a list of keys.</p>
 505 <p>Default value is <tt class="docutils literal"><span class="pre">&quot;C-d&quot;</span></tt>.</p>
 506 </div>
 507 <div class="section" id="yas-good-grace">
 508 <h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2>
 509 <p>If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
 510 snippet definitions. An error string &quot;[yas] error&quot; is returned instead.</p>
 511 </div>
 512 <div class="section" id="yas-indent-line">
 513 <h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2>
 514 <p>The variable <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> controls the indenting. It is bound
 515 to <tt class="docutils literal"><span class="pre">'auto</span></tt> by default, which causes your snippet to be indented
 516 according to the mode of the buffer it was inserted in.</p>
 517 <p>Another variable <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt>, when non-nil
 518 does exactly that :-).</p>
 519 <p>To use the hard-coded indentation in your snippet template, set this
 520 variable to <tt class="docutils literal"><span class="pre">fixed</span></tt>.</p>
 521 <p>To control indentation on a per-snippet basis, see also the directive
 522 <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>
 523 <p>For backward compatibility with earlier versions of YASnippet, you can
 524 also place a <tt class="docutils literal"><span class="pre">$&gt;</span></tt> in your snippet, an <tt class="docutils literal"><span class="pre">(indent-according-to-mode)</span></tt>
 525 will be executed there to indent the line. This only takes effect when
 526 <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>
 527 <div class="highlight"><pre>for (${int i = 0}; ${i &lt; 10}; ${++i})
 528 {$&gt;
 529 $0$&gt;
 530 }$&gt;
 531 </pre></div>
 532 </div>
 533 <div class="section" id="yas-wrap-around-region">
 534 <h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2>
 535 <p>If non-nil, YASnippet will try to expand the snippet's exit marker
 536 around the currently selected region. When this variable is set to t,
 537 this has the same effect has using the <tt class="docutils literal"><span class="pre">`yas/selected-text`</span></tt> inline
 538 evaluation.</p>
 539 <p>Because on most systems starting to type deletes the currently region,
 540 this works mostly with the <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> command.</p>
 541 <p>However, when the value is of this variable is <tt class="docutils literal"><span class="pre">cua</span></tt> YASnippet will
 542 additionally look-up any recently selected that you deleted by starting
 543 typing. This allows you select a region, type a snippet key (deleting
 544 the region), then press <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to see the deleted region
 545 spring back to life inside your new snippet.</p>
 546 </div>
 547 <div class="section" id="yas-triggers-in-field">
 548 <h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2>
 549 <p>If non-nil, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> can trigger stacked expansions,
 550 that is a snippet expansion inside another snippet
 551 expansion. Otherwise, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> just tries to move on to
 552 the next field.</p>
 553 </div>
 554 <div class="section" id="yas-snippet-revival">
 555 <h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2>
 556 <p>Non-nil means re-activate snippet fields after undo/redo.</p>
 557 </div>
 558 <div class="section" id="yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook">
 559 <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>
 560 <p>These hooks are called, respectively, before the insertion of a
 561 snippet and after exiting the snippet. If you find any strange but
 562 functional use for them, that's probably a design flaw in YASnippet,
 563 so let us know.</p>
 564 </div>
 565 </div>
 566 <div class="section" id="importing-textmate-snippets">
 567 <h1><a class="toc-backref" href="#id35">Importing TextMate snippets</a></h1>
 568 <p>There are a couple of tools that take TextMate's &quot;.tmSnippet&quot; xml
 569 files and create YASnippet definitions:</p>
 570 <blockquote>
 571 <ul class="simple">
 572 <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>
 573 <li>a <a class="reference external" href="http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb">ruby tool</a>
 574 , <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>,
 575 which I have uploaded to the repository.</li>
 576 </ul>
 577 </blockquote>
 578 <p>In this section, i'll shortly cover the <strong>second</strong> option.</p>
 579 <p>Download the <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> tool and the TextMate
 580 bundle you're interested in.</p>
 581 <div class="highlight"><pre>$ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb
 582 $ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/
 583 </pre></div>
 584 <p>Then invoke <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> like this:</p>
 585 <div class="highlight"><pre>$ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist
 586 </pre></div>
 587 <p>You should end up with a <tt class="docutils literal"><span class="pre">html-mode</span></tt> subdir containing snippets
 588 exported from textmate.</p>
 589 <div class="highlight"><pre>$ tree html-mode # to view dir contents, if you have &#39;tree&#39; installed
 590 </pre></div>
 591 <p>The <tt class="docutils literal"><span class="pre">-g</span></tt> is optional but helps the tool figure out the grouping.
 592 According to <a class="reference external" href="snippet-organization.html">Organizing Snippets</a>, don't forget to touch
 593 <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
 594 <tt class="docutils literal"><span class="pre">html-mode</span></tt> dir.</p>
 595 <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>
 596 <p>Please note that snippet importation is not yet perfect. You'll
 597 probably have some adjustments to some/many snippets. Please
 598 contribute these adjustments to the google group or, better yet, patch
 599 the <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> to automatically perform them and submit
 600 that.</p>
 601 <!-- LocalWords:  html YASnippet yas sourcecode pluskid init filenames filename -->
 602 <!-- LocalWords:  env varlist keybinding keymap rinari ifndef upcase endif -->
 603 <!-- LocalWords:  nondirectory autorelease aValue inline -->
 604 </div>
 605           </div>
 606         </div>
 607       </div>
 608     </div>
 609   </div>
 610 </div>
 611 <script type="text/javascript">
 612   var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
 613   document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
 614 </script>
 615 <script type="text/javascript">
 616   try {
 617   var pageTracker = _gat._getTracker("UA-10536822-1");
 618   pageTracker._trackPageview();
 619   } catch(err) {}
 620 </script>
 621 </div>
 622 </body>
 623 </html>