diff options
Diffstat (limited to '')
| -rw-r--r-- | emacs.d/lisp/yasnippet/doc/snippet-development.html | 623 |
1 files changed, 623 insertions, 0 deletions
diff --git a/emacs.d/lisp/yasnippet/doc/snippet-development.html b/emacs.d/lisp/yasnippet/doc/snippet-development.html new file mode 100644 index 0000000..6b55b4c --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-development.html @@ -0,0 +1,623 @@ +<?xml version="1.0" encoding="utf-8" ?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> +<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> +<title>Writing snippets</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="writing-snippets"> +<div id="header-region" class="clear-block"></div> +<div id="wrapper"> + <div id="container" class="clear-block"> + <div id="header"> + <div id="logo-floater"> + <h1 class="title">Writing snippets</h1> + </div> + <ul class="primary-links"> + <li> + <a title="" href="index.html">Intro and tutorial</a> + </li> + <li> + <a title="" href="snippet-organization.html">Howto: organize</a> + </li> + <li> + <a title="" href="snippet-expansion.html">Howto: expand</a> + </li> + <li> + <a title="" href="snippet-development.html">Howto: write </a> + </li> + <li> + <a title="" href="snippet-menu.html">Howto: menu </a> + </li> + <li> + <a title="" href="faq.html">FAQ</a> + </li> + <li> + <a title="" href="changelog.html">ChangeLog</a> + </li> + <li> + <a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a> + </li> + </ul> + </div> + <div id="center"> + <div id="squeeze"> + <div class="right-corner"> + <div class="left-corner"> + <p> + <b>Important:</b> This documentation applies to + the <b>SVN trunk</b> of YASnippet, which you + get <a href="http://code.google.com/p/yasnippet/source/checkout">here</a>. Documentation + for other versions can be found <a title="" + href="http://code.google.com/p/yasnippet/downloads/list">here</a>. + </p> + <div class="contents topic" id="contents"> +<p class="topic-title first">Contents</p> +<ul class="simple"> +<li><a class="reference internal" href="#snippet-development" id="id3">Snippet development</a><ul> +<li><a class="reference internal" href="#quickly-finding-snippets" id="id4">Quickly finding snippets</a></li> +<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></li> +</ul> +</li> +<li><a class="reference internal" href="#file-content" id="id6">File content</a><ul> +<li><a class="reference internal" href="#key-snippet-abbrev" id="id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></li> +<li><a class="reference internal" href="#name-snippet-name" id="id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></li> +<li><a class="reference internal" href="#condition-snippet-condition" id="id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></li> +<li><a class="reference internal" href="#group-snippet-menu-grouping" id="id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> snippet menu grouping</a></li> +<li><a class="reference internal" href="#expand-env-expand-environment" id="id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></li> +<li><a class="reference internal" href="#binding-direct-keybinding" id="id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></li> +<li><a class="reference internal" href="#contributor-snippet-author" id="id13"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></li> +</ul> +</li> +<li><a class="reference internal" href="#template-syntax" id="id14">Template syntax</a><ul> +<li><a class="reference internal" href="#plain-text" id="id15">Plain Text</a></li> +<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id16">Embedded Emacs-lisp code</a></li> +<li><a class="reference internal" href="#tab-stop-fields" id="id17">Tab stop fields</a></li> +<li><a class="reference internal" href="#placeholder-fields" id="id18">Placeholder fields</a></li> +<li><a class="reference internal" href="#id2" id="id19">Mirrors</a></li> +<li><a class="reference internal" href="#mirrors-with-transformations" id="id20">Mirrors with transformations</a></li> +<li><a class="reference internal" href="#fields-with-transformations" id="id21">Fields with transformations</a></li> +<li><a class="reference internal" href="#choosing-fields-value-from-a-list-and-other-tricks" id="id22">Choosing fields value from a list and other tricks</a></li> +<li><a class="reference internal" href="#nested-placeholder-fields" id="id23">Nested placeholder fields</a></li> +</ul> +</li> +<li><a class="reference internal" href="#customizable-variables" id="id24">Customizable variables</a><ul> +<li><a class="reference internal" href="#yas-trigger-key" id="id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></li> +<li><a class="reference internal" href="#yas-next-field-key" id="id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></li> +<li><a class="reference internal" href="#yas-prev-field-key" id="id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></li> +<li><a class="reference internal" href="#yas-skip-and-clear-key" id="id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></li> +<li><a class="reference internal" href="#yas-good-grace" id="id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li> +<li><a class="reference internal" href="#yas-indent-line" id="id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></li> +<li><a class="reference internal" href="#yas-wrap-around-region" id="id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></li> +<li><a class="reference internal" href="#yas-triggers-in-field" id="id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></li> +<li><a class="reference internal" href="#yas-snippet-revival" id="id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></li> +<li><a class="reference internal" href="#yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook" id="id34"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></li> +</ul> +</li> +<li><a class="reference internal" href="#importing-textmate-snippets" id="id35">Importing TextMate snippets</a></li> +</ul> +</div> +<div class="section" id="snippet-development"> +<h1><a class="toc-backref" href="#id3">Snippet development</a></h1> +<div class="section" id="quickly-finding-snippets"> +<h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2> +<p>There are some ways you can quickly find a snippet file:</p> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt></p> +<p>Prompts you for a snippet name, then tries to guess a suitable +directory to store it, prompting you for creation if it does not +exist. Finally, places you in a new buffer set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> +so you can write your snippet.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/find-snippets</span></tt></p> +<p>Lets you find the snippet file in the directory the snippet was +loaded from (if it exists) like <tt class="docutils literal"><span class="pre">find-file-other-window</span></tt>. The +directory searching logic is similar to <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt>.</p> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/visit-snippet-file</span></tt></p> +<p>Prompts you for possible snippet expansions like +<tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt>, but instead of expanding it, takes you +directly to the snippet definition's file, if it exists.</p> +</li> +</ul> +<p>Once you find this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead) +and you can start editing your snippet.</p> +</div> +<div class="section" id="using-the-snippet-mode-major-mode"> +<h2><a class="toc-backref" href="#id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h2> +<p>There is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to edit snippets. You can set +the buffer to this mode with <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">snippet-mode</span></tt>. It provides +reasonably useful syntax highlighting.</p> +<p>Two commands are defined in this mode:</p> +<ul> +<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p> +<blockquote> +<p>When editing a snippet, this loads the snippet into the correct +mode and menu. Bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-c</span></tt> by default while in +<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p> +</blockquote> +</li> +<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/tryout-snippet</span></tt></p> +<blockquote> +<p>When editing a snippet, this opens a new empty buffer, sets it to +the appropriate major mode and inserts the snippet there, so you +can see what it looks like. This is bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-t</span></tt> while in +<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p> +</blockquote> +</li> +</ul> +<p>There are also <em>snippets for writing snippets</em>: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">$f</span></tt> and +<tt class="docutils literal"><span class="pre">$m</span></tt> :-).</p> +</div> +</div> +<div class="section" id="file-content"> +<h1><a class="toc-backref" href="#id6">File content</a></h1> +<p>A file defining a snippet generally contains the template to be +expanded.</p> +<p>Optionally, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, the lines above +it count as comments, some of which can be <em>directives</em> (or meta +data). Snippet directives look like <tt class="docutils literal"><span class="pre">#</span> <span class="pre">property:</span> <span class="pre">value</span></tt> and tweak +certain snippets properties described below. If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found, +the whole file is considered the snippet template.</p> +<p>Here's a typical example:</p> +<div class="highlight"><pre>#contributor : pluskid <pluskid@gmail.com> +#name : __...__ +# -- +__${init}__ +</pre></div> +<p>Here's a list of currently supported directives:</p> +<div class="section" id="key-snippet-abbrev"> +<h2><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></h2> +<p>This is the probably the most important directive, it's the +abbreviation you type to expand a snippet just before hitting +<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p> +<p>If you don't specify this it will default to the name of the file the +snippet is being loaded from, unless YASnippet is ignoring file names +as triggers (see <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> in <a class="reference external" href="snippet-organization.html">Organizing +snippets</a>), in which case this snippet +will not be expandable through the key mechanism.</p> +<p>Sometimes the key of a snippet is non-ASCII or not valid filename +(e.g. contains <tt class="docutils literal"><span class="pre">/</span></tt>). One can then define the <tt class="docutils literal"><span class="pre">key</span></tt> property which +will overwrite the filename as the key to expand the snippet.</p> +</div> +<div class="section" id="name-snippet-name"> +<h2><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></h2> +<p>This is a one-line description of the snippet. It will be displayed in +the menu. It's a good idea to select a descriptive name for a +snippet -- especially distinguishable among similar snippets.</p> +<p>If you omit this name it will default to the file name the snippet was +loaded from.</p> +</div> +<div class="section" id="condition-snippet-condition"> +<h2><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></h2> +<p>This is a piece of Emacs-lisp code. If a snippet has a condition, then it +will only be expanded when the condition code evaluate to some non-nil +value.</p> +<p>See also <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> in <a class="reference external" href="snippet-expansion.html">Expanding snippets</a></p> +</div> +<div class="section" id="group-snippet-menu-grouping"> +<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> snippet menu grouping</a></h2> +<p>When expanding/visiting snippets from the menu-bar menu, snippets for a +given mode can be grouped into sub-menus . This is useful if one has +too many snippets for a mode which will make the menu too +long.</p> +<p>The <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> property only affect menu construction (See <a class="reference external" href="snippet-menu.html">the +YASnippet menu</a>) and the same effect can be achieved by grouping +snippets into sub-directories and using the <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> +special file (for this see <a class="reference external" href="snippet-organization.html">Organizing Snippets</a></p> +<p>Refer to the bundled snippets for <tt class="docutils literal"><span class="pre">ruby-mode</span></tt> for examples on the +<tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> directive. Group can also be nested, e.g. <tt class="docutils literal"><span class="pre">control</span> +<span class="pre">structure.loops</span></tt> tells that the snippet is under the <tt class="docutils literal"><span class="pre">loops</span></tt> group +which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt> group.</p> +</div> +<div class="section" id="expand-env-expand-environment"> +<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></h2> +<p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt> +<em>varlist form</em>, i.e. a list of lists assigning values to variables. It +can be used to override variable values while the snippet is being +expanded.</p> +<p>Interesting variables to override are <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> and +<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> (see <a class="reference external" href="snippet-expansion.html">Expanding Snippets</a>).</p> +<p>As an example, you might normally have <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> set to +<tt class="docutils literal"><span class="pre">'auto</span></tt> and <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> set to <tt class="docutils literal"><span class="pre">t</span></tt>, but for this +particularly brilliant piece of ASCII art these values would mess up +your hard work. You can then use:</p> +<div class="highlight"><pre># name : ASCII home +# expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil)) +# -- + welcome to my + X humble + / \ home, + / \ $0 + / \ + /-------\ + | | + | +-+ | + | | | | + +--+-+--+ +</pre></div> +</div> +<div class="section" id="binding-direct-keybinding"> +<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></h2> +<p>You can use this directive to expand a snippet directly from a normal +Emacs keybinding. The keybinding will be registered in the Emacs +keymap named after the major mode the snippet is active +for.</p> +<p>Additionally a variable <tt class="docutils literal"><span class="pre">yas/prefix</span></tt> is set to to the prefix +argument you normally use for a command. This allows for small +variations on the same snippet, for example in this "html-mode" +snippet.</p> +<div class="highlight"><pre>#name : <p>...</p> +#binding: "C-c C-c C-m" +# -- +<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p> +</pre></div> +<p>This binding will be recorded in the keymap <tt class="docutils literal"><span class="pre">html-mode-map</span></tt>. To +expand a paragraph tag newlines, just press "C-u C-c C-c +C-m". Omitting the "C-u" will expand the paragraph tag without +newlines.</p> +<p>To override the keymap choice based on the major mode name. Use a cons +cell where the first element specifies the name of the keymap where +you want to record the keybinding.</p> +<div class="highlight"><pre>#name : <p>...</p> +#binding: (rinari-minor-mode-map . "C-c C-c C-m") +# -- +<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p> +</pre></div> +<p><strong>Note</strong>: this feature is still <strong>experimental</strong>, it might go away, be +changed in future release, and should be used with caution: It is easy +to override important keybindings for many basic modes and it is hard +to undefine them. For the moment, the variable +<tt class="docutils literal"><span class="pre">yas/active-keybindings</span></tt> can tell you what snippet keybindings are +active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt +to undefine all the keybindings.</p> +</div> +<div class="section" id="contributor-snippet-author"> +<h2><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></h2> +<p>This is optional and has no effect whatsoever on snippet +functionality, but it looks nice.</p> +</div> +</div> +<div class="section" id="template-syntax"> +<h1><a class="toc-backref" href="#id14">Template syntax</a></h1> +<p>The syntax of the snippet template is simple but powerful, very +similar to TextMate's.</p> +<div class="section" id="plain-text"> +<h2><a class="toc-backref" href="#id15">Plain Text</a></h2> +<p>Arbitrary text can be included as the content of a template. They are +usually interpreted as plain text, except <tt class="docutils literal"><span class="pre">$</span></tt> and <tt class="docutils literal"><span class="pre">`</span></tt>. You need to +use <tt class="docutils literal"><span class="pre">\</span></tt> to escape them: <tt class="docutils literal"><span class="pre">\$</span></tt> and <tt class="docutils literal"><span class="pre">\`</span></tt>. The <tt class="docutils literal"><span class="pre">\</span></tt> itself may also +needed to be escaped as <tt class="docutils literal"><span class="pre">\\</span></tt> sometimes.</p> +</div> +<div class="section" id="embedded-emacs-lisp-code"> +<h2><a class="toc-backref" href="#id16">Embedded Emacs-lisp code</a></h2> +<p>Emacs-Lisp code can be embedded inside the template, written inside +back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>). The lisp forms are evaluated when the snippet is +being expanded. The evaluation is done in the same buffer as the +snippet being expanded.</p> +<p>Here's an example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard +dynamically:</p> +<div class="highlight"><pre>#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_} +#define $1 + +$0 + +#endif /* $1 */ +</pre></div> +<p>From version 0.6, snippets expansions are run with some special +Emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You +can therefore define a snippet like:</p> +<div class="highlight"><pre>for ($1;$2;$3) { + `yas/selected-text`$0 +} +</pre></div> +<p>to "wrap" the selected region inside your recently inserted +snippet. Alternatively, you can also customize the variable +<tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt> which will do this automatically.</p> +</div> +<div class="section" id="tab-stop-fields"> +<h2><a class="toc-backref" href="#id17">Tab stop fields</a></h2> +<p>Tab stops are fields that you can navigate back and forth by <tt class="docutils literal"><span class="pre">TAB</span></tt> +and <tt class="docutils literal"><span class="pre">S-TAB</span></tt>. They are written by <tt class="docutils literal"><span class="pre">$</span></tt> followed with a +number. <tt class="docutils literal"><span class="pre">$0</span></tt> has the special meaning of the <em>exit point</em> of a +snippet. That is the last place to go when you've traveled all the +fields. Here's a typical example:</p> +<div class="highlight"><pre><div$1> + $0 +</div> +</pre></div> +</div> +<div class="section" id="placeholder-fields"> +<h2><a class="toc-backref" href="#id18">Placeholder fields</a></h2> +<p>Tab stops can have default values -- a.k.a placeholders. The syntax is +like this:</p> +<div class="highlight"><pre>${N:default value} +</pre></div> +<p>They acts as the default value for a tab stop. But when you firstly +type at a tab stop, the default value will be replaced by your +typing. The number can be omitted if you don't want to create +<a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p> +</div> +<div class="section" id="id2"> +<span id="mirrors"></span><h2><a class="toc-backref" href="#id19">Mirrors</a></h2> +<p>We refer the tab stops with placeholders as a <em>field</em>. A field can have +mirrors. Its mirrors will get updated when you change the text of a +field. Here's an example:</p> +<div class="highlight"><pre>\begin{${1:enumerate}} + $0 +\end{$1} +</pre></div> +<p>When you type <tt class="docutils literal"><span class="pre">"document"</span></tt> at <tt class="docutils literal"><span class="pre">${1:enumerate}</span></tt>, the word +<tt class="docutils literal"><span class="pre">"document"</span></tt> will also be inserted at <tt class="docutils literal"><span class="pre">\end{$1}</span></tt>. The best +explanation is to see the screencast(<a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">YouTube</a> or <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">avi video</a>).</p> +<p>The tab stops with the same number to the field act as its mirrors. If +none of the tab stops has an initial value, the first one is selected +as the field and others mirrors.</p> +</div> +<div class="section" id="mirrors-with-transformations"> +<span id="transformations"></span><h2><a class="toc-backref" href="#id20">Mirrors with transformations</a></h2> +<p>If the value of an <tt class="docutils literal"><span class="pre">${n:</span></tt>-construct starts with and contains <tt class="docutils literal"><span class="pre">$(</span></tt>, +then it is interpreted as a mirror for field <tt class="docutils literal"><span class="pre">n</span></tt> with a +transformation. The mirror's text content is calculated according to +this transformation, which is Emacs-lisp code that gets evaluated in +an environment where the variable <tt class="docutils literal"><span class="pre">text</span></tt> (or <tt class="docutils literal"><span class="pre">yas/text</span></tt>) is bound +to the text content (string) contained in the field <tt class="docutils literal"><span class="pre">n</span></tt>.Here's an +example for Objective-C:</p> +<div class="highlight"><pre>- (${1:id})${2:foo} +{ + return $2; +} + +- (void)set${2:$(capitalize text)}:($1)aValue +{ + [$2 autorelease]; + $2 = [aValue retain]; +} +$0 +</pre></div> +<p>Look at <tt class="docutils literal"><span class="pre">${2:$(capitalize</span> <span class="pre">text)}</span></tt>, it is a mirror with +transformation instead of a field. The actual field is at the first +line: <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the +transformation will be evaluated and the result will be placed there +as the transformed text. So in this example, if you type "baz" in the +field, the transformed text will be "Baz". This example is also +available in the screencast.</p> +<p>Another example is for <tt class="docutils literal"><span class="pre">rst-mode</span></tt>. In reStructuredText, the document +title can be some text surrounded by "===" below and above. The "===" +should be at least as long as the text. So</p> +<div class="highlight"><pre>===== +Title +===== +</pre></div> +<p>is a valid title but</p> +<div class="highlight"><pre>=== +Title +=== +</pre></div> +<p>is not. Here's an snippet for rst title:</p> +<div class="highlight"><pre>${1:$(make-string (string-width text) ?\=)} +${1:Title} +${1:$(make-string (string-width text) ?\=)} + +$0 +</pre></div> +</div> +<div class="section" id="fields-with-transformations"> +<h2><a class="toc-backref" href="#id21">Fields with transformations</a></h2> +<p>From version 0.6 on, you can also have lisp transformation inside +fields. These work mostly mirror transformations but are evaluated +when you first enter the field, after each change you make to the +field and also just before you exit the field.</p> +<p>The syntax is also a tiny bit different, so that the parser can +distinguish between fields and mirrors. In the following example</p> +<div class="highlight"><pre>#define "${1:mydefine$(upcase yas/text)}" +</pre></div> +<p><tt class="docutils literal"><span class="pre">mydefine</span></tt> gets automatically upcased to <tt class="docutils literal"><span class="pre">MYDEFINE</span></tt> once you enter +the field. As you type text, it gets filtered through the +transformation every time.</p> +<p>Note that to tell this kind of expression from a mirror with a +transformation, YASnippet needs extra text between the <tt class="docutils literal"><span class="pre">:</span></tt> and the +transformation's <tt class="docutils literal"><span class="pre">$</span></tt>. If you don't want this extra-text, you can use +two <tt class="docutils literal"><span class="pre">$</span></tt>'s instead.</p> +<div class="highlight"><pre>#define "${1:$$(upcase yas/text)}" +</pre></div> +<p>Please note that as soon as a transformation takes place, it changes +the value of the field and sets it its internal modification state to +<tt class="docutils literal"><span class="pre">true</span></tt>. As a consequence, the auto-deletion behaviour of normal +fields does not take place. This is by design.</p> +</div> +<div class="section" id="choosing-fields-value-from-a-list-and-other-tricks"> +<h2><a class="toc-backref" href="#id22">Choosing fields value from a list and other tricks</a></h2> +<p>As mentioned, the field transformation is invoked just after you enter +the field, and with some useful variables bound, notably +<tt class="docutils literal"><span class="pre">yas/field-modified-p</span></tt> and <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Because of this +feature you can place a transformation in the primary field that lets +you select default values for it.</p> +<p>The <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> does this work for you. For example:</p> +<div class="highlight"><pre><div align="${2:$$(yas/choose-value '("right" "center" "left"))}"> + $0 +</div> +</pre></div> +<p>See the definition of <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> to see how it was written +using the two variables.</p> +<p>Here's another use, for LaTeX-mode, which calls reftex-label just as +you enter snippet field 2. This one makes use of <tt class="docutils literal"><span class="pre">yas/modified-p</span></tt> +directly.</p> +<div class="highlight"><pre>\section{${1:"Titel der Tour"}}% +\index{$1}% +\label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont- +insert))}}% +</pre></div> +<p>The function <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> has another neat trick, and makes +use of <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Try it and see! Also, check out this +<a class="reference external" href="http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662">thread</a></p> +</div> +<div class="section" id="nested-placeholder-fields"> +<h2><a class="toc-backref" href="#id23">Nested placeholder fields</a></h2> +<p>From version 0.6 on, you can also have nested placeholders of the type:</p> +<div class="highlight"><pre><div${1: id="${2:some_id}"}>$0</div> +</pre></div> +<p>This allows you to choose if you want to give this <tt class="docutils literal"><span class="pre">div</span></tt> an <tt class="docutils literal"><span class="pre">id</span></tt> +attribute. If you tab forward after expanding it will let you change +"some_id" to whatever you like. Alternatively, you can just press +<tt class="docutils literal"><span class="pre">C-d</span></tt> (which executes <tt class="docutils literal"><span class="pre">yas/skip-and-clear-or-delete-char</span></tt>) and go +straight to the exit marker.</p> +<p>By the way, <tt class="docutils literal"><span class="pre">C-d</span></tt> will only clear the field if you cursor is at the +beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it +performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p> +</div> +</div> +<div class="section" id="customizable-variables"> +<h1><a class="toc-backref" href="#id24">Customizable variables</a></h1> +<div class="section" id="yas-trigger-key"> +<h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2> +<p>The key bound to <tt class="docutils literal"><span class="pre">yas/expand</span></tt> when function <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is +active.</p> +<p>Value is a string that is converted to the internal Emacs key +representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p> +<p>Default value is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>.</p> +</div> +<div class="section" id="yas-next-field-key"> +<h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2> +<p>The key to navigate to next field when a snippet is active.</p> +<p>Value is a string that is converted to the internal Emacs key +representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p> +<p>Can also be a list of keys.</p> +<p>Default value is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>.</p> +</div> +<div class="section" id="yas-prev-field-key"> +<h2><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2> +<p>The key to navigate to previous field when a snippet is active.</p> +<p>Value is a string that is converted to the internal Emacs key +representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p> +<p>Can also be a list of keys.</p> +<p>Default value is <tt class="docutils literal"><span class="pre">("<backtab>"</span> <span class="pre">"<S-tab>)"</span></tt>.</p> +</div> +<div class="section" id="yas-skip-and-clear-key"> +<h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></h2> +<p>The key to clear the currently active field.</p> +<p>Value is a string that is converted to the internal Emacs key +representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p> +<p>Can also be a list of keys.</p> +<p>Default value is <tt class="docutils literal"><span class="pre">"C-d"</span></tt>.</p> +</div> +<div class="section" id="yas-good-grace"> +<h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2> +<p>If non-nil, don't raise errors in inline Emacs-lisp evaluation inside +snippet definitions. An error string "[yas] error" is returned instead.</p> +</div> +<div class="section" id="yas-indent-line"> +<h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2> +<p>The variable <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> controls the indenting. It is bound +to <tt class="docutils literal"><span class="pre">'auto</span></tt> by default, which causes your snippet to be indented +according to the mode of the buffer it was inserted in.</p> +<p>Another variable <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt>, when non-nil +does exactly that :-).</p> +<p>To use the hard-coded indentation in your snippet template, set this +variable to <tt class="docutils literal"><span class="pre">fixed</span></tt>.</p> +<p>To control indentation on a per-snippet basis, see also the directive +<tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> in <a class="reference external" href="snippet-development.html">Writing Snippets</a>.</p> +<p>For backward compatibility with earlier versions of YASnippet, you can +also place a <tt class="docutils literal"><span class="pre">$></span></tt> in your snippet, an <tt class="docutils literal"><span class="pre">(indent-according-to-mode)</span></tt> +will be executed there to indent the line. This only takes effect when +<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> is set to something other than <tt class="docutils literal"><span class="pre">'auto</span></tt>.</p> +<div class="highlight"><pre>for (${int i = 0}; ${i < 10}; ${++i}) +{$> +$0$> +}$> +</pre></div> +</div> +<div class="section" id="yas-wrap-around-region"> +<h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2> +<p>If non-nil, YASnippet will try to expand the snippet's exit marker +around the currently selected region. When this variable is set to t, +this has the same effect has using the <tt class="docutils literal"><span class="pre">`yas/selected-text`</span></tt> inline +evaluation.</p> +<p>Because on most systems starting to type deletes the currently region, +this works mostly with the <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> command.</p> +<p>However, when the value is of this variable is <tt class="docutils literal"><span class="pre">cua</span></tt> YASnippet will +additionally look-up any recently selected that you deleted by starting +typing. This allows you select a region, type a snippet key (deleting +the region), then press <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to see the deleted region +spring back to life inside your new snippet.</p> +</div> +<div class="section" id="yas-triggers-in-field"> +<h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2> +<p>If non-nil, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> can trigger stacked expansions, +that is a snippet expansion inside another snippet +expansion. Otherwise, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> just tries to move on to +the next field.</p> +</div> +<div class="section" id="yas-snippet-revival"> +<h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2> +<p>Non-nil means re-activate snippet fields after undo/redo.</p> +</div> +<div class="section" id="yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook"> +<h2><a class="toc-backref" href="#id34"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></h2> +<p>These hooks are called, respectively, before the insertion of a +snippet and after exiting the snippet. If you find any strange but +functional use for them, that's probably a design flaw in YASnippet, +so let us know.</p> +</div> +</div> +<div class="section" id="importing-textmate-snippets"> +<h1><a class="toc-backref" href="#id35">Importing TextMate snippets</a></h1> +<p>There are a couple of tools that take TextMate's ".tmSnippet" xml +files and create YASnippet definitions:</p> +<blockquote> +<ul class="simple"> +<li><a class="reference external" href="http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py">a python script by Jeff Wheeler</a></li> +<li>a <a class="reference external" href="http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb">ruby tool</a> +, <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> adapted from <a class="reference external" href="http://www.neutronflux.net/2009/07/28/shoulda-snippets-for-emacs/">Rob Christie's</a>, +which I have uploaded to the repository.</li> +</ul> +</blockquote> +<p>In this section, i'll shortly cover the <strong>second</strong> option.</p> +<p>Download the <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> tool and the TextMate +bundle you're interested in.</p> +<div class="highlight"><pre>$ curl -O http://yasnippet.googlecode.com/svn/trunk/extras/textmate_import.rb +$ svn export http://svn.textmate.org/trunk/Bundles/HTML.tmbundle/ +</pre></div> +<p>Then invoke <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> like this:</p> +<div class="highlight"><pre>$ ./textmate_import.rb -d HTML.tmbundle/Snippets/ -o html-mode -g HTML.tmbundle/info.plist +</pre></div> +<p>You should end up with a <tt class="docutils literal"><span class="pre">html-mode</span></tt> subdir containing snippets +exported from textmate.</p> +<div class="highlight"><pre>$ tree html-mode # to view dir contents, if you have 'tree' installed +</pre></div> +<p>The <tt class="docutils literal"><span class="pre">-g</span></tt> is optional but helps the tool figure out the grouping. +According to <a class="reference external" href="snippet-organization.html">Organizing Snippets</a>, don't forget to touch +<tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> and <tt class="docutils literal"><span class="pre">.yas-ignore-filename-triggers</span></tt> inside the +<tt class="docutils literal"><span class="pre">html-mode</span></tt> dir.</p> +<p>Also try <tt class="docutils literal"><span class="pre">textmate_import.rb</span> <span class="pre">--help</span></tt> for a list of options.</p> +<p>Please note that snippet importation is not yet perfect. You'll +probably have some adjustments to some/many snippets. Please +contribute these adjustments to the google group or, better yet, patch +the <tt class="docutils literal"><span class="pre">textmate_import.rb</span></tt> to automatically perform them and submit +that.</p> +<!-- LocalWords: html YASnippet yas sourcecode pluskid init filenames filename --> +<!-- LocalWords: env varlist keybinding keymap rinari ifndef upcase endif --> +<!-- LocalWords: nondirectory autorelease aValue inline --> +</div> + </div> + </div> + </div> + </div> + </div> +</div> +<script type="text/javascript"> + var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); + document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-10536822-1"); + pageTracker._trackPageview(); + } catch(err) {} +</script> +</div> +</body> +</html> |