mirror of
https://github.com/joaotavora/yasnippet.git
synced 2026-02-04 06:32:24 +00:00
doc almost complete. Drawing closer to 0.6.1b
This commit is contained in:
capitaomorte
@@ -3,10 +3,8 @@
|
||||
<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/" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<title>Writing snippets</title>
|
||||
<meta name="author" content="pluskid, joaotavora" />
|
||||
<meta name="date" content="2009-08-18" />
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
@@ -52,28 +50,61 @@
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#quickly-finding-defining-snippets" id="id6">Quickly finding/defining snippets</a></li>
|
||||
<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id7">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a><ul>
|
||||
<li><a class="reference internal" href="#the-syntax-of-the-template" id="id8">The Syntax of the Template</a></li>
|
||||
<li><a class="reference internal" href="#snippet-development" id="id3">Snippet development</a><ul>
|
||||
<li><a class="reference internal" href="#quickly-finding-snippets" id="id4">Quickly finding snippets</a></li>
|
||||
<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#file-content" id="id6">File content</a><ul>
|
||||
<li><a class="reference internal" href="#key-snippet-abbrev" id="id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></li>
|
||||
<li><a class="reference internal" href="#name-snippet-name" id="id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></li>
|
||||
<li><a class="reference internal" href="#condition-snippet-condition" id="id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></li>
|
||||
<li><a class="reference internal" href="#expand-env-expand-environment" id="id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></li>
|
||||
<li><a class="reference internal" href="#binding-direct-keybinding" id="id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt>: direct keybinding</a></li>
|
||||
<li><a class="reference internal" href="#contributor-snippet-author" id="id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt>: snippet author</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#template-syntax" id="id13">Template syntax</a><ul>
|
||||
<li><a class="reference internal" href="#plain-text" id="id14">Plain Text</a></li>
|
||||
<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id15">Embedded Emacs-lisp code</a></li>
|
||||
<li><a class="reference internal" href="#tab-stop-fields" id="id16">Tab stop fields</a></li>
|
||||
<li><a class="reference internal" href="#placeholder-fields" id="id17">Placeholder fields</a></li>
|
||||
<li><a class="reference internal" href="#id2" id="id18">Mirrors</a></li>
|
||||
<li><a class="reference internal" href="#mirrors-with-transformations" id="id19">Mirrors with transformations</a></li>
|
||||
<li><a class="reference internal" href="#fields-with-transformations" id="id20">Fields with transformations</a></li>
|
||||
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id21">Choosing fields value from a list</a></li>
|
||||
<li><a class="reference internal" href="#nested-placeholder-fields" id="id22">Nested placeholder fields</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#customizable-variables" id="id23">Customizable variables</a><ul>
|
||||
<li><a class="reference internal" href="#yas-trigger-key" id="id24"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-next-field-key" id="id25"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-prev-field-key" id="id26"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-skip-and-clear-key" id="id27"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-good-grace" id="id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-indent-line" id="id29"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-wrap-around-region" id="id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-triggers-in-field" id="id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-snippet-revival" id="id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook" id="id33"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#plain-text" id="id9">Plain Text</a></li>
|
||||
<li><a class="reference internal" href="#embedded-elisp-code" id="id10">Embedded elisp code</a></li>
|
||||
<li><a class="reference internal" href="#tab-stop-fields" id="id11">Tab stop fields</a></li>
|
||||
<li><a class="reference internal" href="#placeholder-fields" id="id12">Placeholder fields</a></li>
|
||||
<li><a class="reference internal" href="#id2" id="id13">Mirrors</a></li>
|
||||
<li><a class="reference internal" href="#mirrors-with-transformations" id="id14">Mirrors with transformations</a></li>
|
||||
<li><a class="reference internal" href="#fields-with-transformations" id="id15">Fields with transformations</a></li>
|
||||
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id16">Choosing fields value from a list</a></li>
|
||||
<li><a class="reference internal" href="#nested-placeholder-fields" id="id17">Nested placeholder fields</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="quickly-finding-defining-snippets">
|
||||
<h1><a class="toc-backref" href="#id6">Quickly finding/defining snippets</a></h1>
|
||||
<p>From version 0.6 upwards there are two ways you can quickly find a
|
||||
snippet file. Once you find this file it will be set to
|
||||
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead)</p>
|
||||
<div class="section" id="snippet-development">
|
||||
<h1><a class="toc-backref" href="#id3">Snippet development</a></h1>
|
||||
<div class="section" id="quickly-finding-snippets">
|
||||
<h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2>
|
||||
<p>There are some ways you can quickly find a snippet file. Once you find
|
||||
this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead) and you can
|
||||
start editing your snippet.</p>
|
||||
<ul>
|
||||
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt></p>
|
||||
<p>Prompts you for a snippet name, then tries to guess a suitable
|
||||
directory to store it, prompting you for creation if it does not
|
||||
exist. Finally, places you in a new buffer set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt>
|
||||
so you can write your snippet.</p>
|
||||
</li>
|
||||
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/find-snippets</span></tt></p>
|
||||
<p>Lets you find the snippet file in the directory the snippet was
|
||||
loaded from (if it exists) like <tt class="docutils literal"><span class="pre">find-file-other-window</span></tt>.</p>
|
||||
@@ -86,10 +117,10 @@ directly to the snippet definition's file, if it exists.</p>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="using-the-snippet-mode-major-mode">
|
||||
<h1><a class="toc-backref" href="#id7">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h1>
|
||||
<p>From version 0.6 upwards there is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to
|
||||
edit snippets. You can set the buffer to this mode with <tt class="docutils literal"><span class="pre">M-x</span>
|
||||
<span class="pre">snippet-mode</span></tt>. It provides reasonably useful syntax highlighting.</p>
|
||||
<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>
|
||||
@@ -110,22 +141,148 @@ can see what it looks like. This is bound to <tt class="docutils literal"><span
|
||||
</ul>
|
||||
<p>There are also snippets for making snippets: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">field</span></tt> and
|
||||
<tt class="docutils literal"><span class="pre">mirror</span></tt>.</p>
|
||||
<div class="section" id="the-syntax-of-the-template">
|
||||
<h2><a class="toc-backref" href="#id8">The Syntax of the Template</a></h2>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="file-content">
|
||||
<h1><a class="toc-backref" href="#id6">File content</a></h1>
|
||||
<p>A file defining a snippet may just contain the template for the
|
||||
snippet. Optionally it can also contains some meta data for the
|
||||
snippet as well as comments.</p>
|
||||
<p>Generally speaking, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, then all
|
||||
contents above that line are considered directives (meta data) and
|
||||
comments; below that line lies the snippet template.</p>
|
||||
<p>If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found, the whole file content is considered as the
|
||||
template.</p>
|
||||
<p>Here's a typical example:</p>
|
||||
<div class="highlight"><pre>#contributor : pluskid <pluskid@gmail.com>
|
||||
#name : __...__
|
||||
# --
|
||||
__${init}__
|
||||
</pre></div>
|
||||
<p>Meta data are specified in the syntax of</p>
|
||||
<div class="highlight"><pre>#data-name : data value
|
||||
</pre></div>
|
||||
<p>Any other text above <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is considered as comment and
|
||||
ignored. Here's a list of currently supported directives:</p>
|
||||
<div class="section" id="key-snippet-abbrev">
|
||||
<h2><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></h2>
|
||||
<p>This is the probably the most important directive, it's the
|
||||
abbreviation you type to expand a snippet just before hitting
|
||||
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p>
|
||||
<p>If you don't specify this it will default to the name of the file the
|
||||
snippet is being loaded from, unless YASnippet is ignoring file names
|
||||
as triggers (see <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> in <a class="reference external" href="snippet-organization.html">Organizing
|
||||
snippets</a>), in which case this snippet
|
||||
will not be expandable through the key mechanism.</p>
|
||||
<p>Sometimes the key of a snippet is non-ASCII or not valid filename
|
||||
(e.g. contains <tt class="docutils literal"><span class="pre">/</span></tt>). One can then define the <tt class="docutils literal"><span class="pre">key</span></tt> property which
|
||||
will overwrite the filename as the key to expand the snippet.</p>
|
||||
</div>
|
||||
<div class="section" id="name-snippet-name">
|
||||
<h2><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></h2>
|
||||
<p>This is a one-line description of the snippet. It will be displayed in
|
||||
the menu. It's a good idea to select a descriptive name for a
|
||||
snippet -- especially distinguishable among similar snippets.</p>
|
||||
<p>If you omit this name it will default to the file name the snippet was
|
||||
loaded from.</p>
|
||||
</div>
|
||||
<div class="section" id="condition-snippet-condition">
|
||||
<h2><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></h2>
|
||||
<p>This is a piece of Emacs-lisp code. If a snippet has a condition, then it
|
||||
will only be expanded when the condition code evaluate to some non-nil
|
||||
value.</p>
|
||||
<p>See also <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> in <a class="reference external" href="snippet-expansion.html">Expanding snippets</a></p>
|
||||
<p><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group</span></tt> snippet menu grouping</p>
|
||||
<p>When expanding/visiting snippets from the menu-bar menu, snippets for a
|
||||
given mode can be grouped into sub-menus . This is useful if one has
|
||||
too many snippets for a mode which will make the menu too
|
||||
long.</p>
|
||||
<p>The <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> property only affect menu construction (See <a class="reference external" href="snippet-menu.html">the
|
||||
YASnippet menu</a>) and the same effect can be achieved by grouping
|
||||
snippets into sub-directories and using the <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt>
|
||||
special file (for this see <a class="reference external" href="snippet-organization.html">Organizing Snippets</a></p>
|
||||
<p>Refer to the bundled snippets for <tt class="docutils literal"><span class="pre">ruby-mode</span></tt> for examples on the
|
||||
<tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> directive. Group can also be nested, e.g. <tt class="docutils literal"><span class="pre">control</span>
|
||||
<span class="pre">structure.loops</span></tt> tells that the snippet is under the <tt class="docutils literal"><span class="pre">loops</span></tt> group
|
||||
which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt> group.</p>
|
||||
</div>
|
||||
<div class="section" id="expand-env-expand-environment">
|
||||
<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></h2>
|
||||
<p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt> <em>varlist</em>
|
||||
form, i.e. a list of lists assigning values to variables. It can be
|
||||
used to override variable values while the snippet is being expanded.</p>
|
||||
<p>Interesting variables to override are <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> and
|
||||
<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> (see <a class="reference external" href="snippet-expansion.html">Expanding Snippets</a>).</p>
|
||||
<p>As an example, you might normally have <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> set to
|
||||
<tt class="docutils literal"><span class="pre">'auto</span></tt> and <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> set to <tt class="docutils literal"><span class="pre">t</span></tt>, but for this
|
||||
particularly brilliant piece of ASCII art these values would mess up
|
||||
your hard work. You can then use:</p>
|
||||
<div class="highlight"><pre># name : ASCII home
|
||||
# expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil))
|
||||
# --
|
||||
welcome to my
|
||||
X humble
|
||||
/ \ home,
|
||||
/ \ $0
|
||||
/ \
|
||||
/-------\
|
||||
| |
|
||||
| +-+ |
|
||||
| | | |
|
||||
+--+-+--+
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="binding-direct-keybinding">
|
||||
<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt>: direct keybinding</a></h2>
|
||||
<p>You can use this directive to expand a snippet directly from a normal
|
||||
Emacs keybinding. The keybinding will be registered in the Emacs
|
||||
keymap named after the major mode the snippet is active
|
||||
for.</p>
|
||||
<p>Additionally a variable <tt class="docutils literal"><span class="pre">yas/prefix</span></tt> is set to to the prefix
|
||||
argument you normally use for a command. This allows for small
|
||||
variations on the same snippet, for example in this "html-mode"
|
||||
snippet.</p>
|
||||
<div class="highlight"><pre>#name : <p>...</p>
|
||||
#binding: "C-c C-c C-m"
|
||||
# --
|
||||
<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
|
||||
</pre></div>
|
||||
<p>This binding will be recorded in the keymap <tt class="docutils literal"><span class="pre">html-mode-map</span></tt>. To
|
||||
expand a paragraph tag newlines, just press "C-u C-c C-c
|
||||
C-m". Omitting the "C-u" will expand the paragraph tag without
|
||||
newlines.</p>
|
||||
<p>To override the keymap choice based on the major mode name. Use a cons
|
||||
cell where the first element specifies the name of the keymap where
|
||||
you want to record the keybinding.</p>
|
||||
<div class="highlight"><pre>
|
||||
</pre></div>
|
||||
<p>Note that this feature is still experimental and should be used with
|
||||
caution: It is easy to override important keybindings for many basic
|
||||
modes and it is hard to undefine them. In particular, the variable
|
||||
<tt class="docutils literal"><span class="pre">yas/active-keybinding</span></tt> can tell you what snippet keybindings are
|
||||
active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will try to
|
||||
undefine all the keybindings.</p>
|
||||
</div>
|
||||
<div class="section" id="contributor-snippet-author">
|
||||
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt>: snippet author</a></h2>
|
||||
<p>This is optional and has no effect whatsoever on snippet
|
||||
functionality, but it looks nice.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="template-syntax">
|
||||
<h1><a class="toc-backref" href="#id13">Template syntax</a></h1>
|
||||
<p>The syntax of the snippet template is simple but powerful, very
|
||||
similar to TextMate's.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="plain-text">
|
||||
<h1><a class="toc-backref" href="#id9">Plain Text</a></h1>
|
||||
<h2><a class="toc-backref" href="#id14">Plain Text</a></h2>
|
||||
<p>Arbitrary text can be included as the content of a template. They are
|
||||
usually interpreted as plain text, except <tt class="docutils literal"><span class="pre">$</span></tt> and <tt class="docutils literal"><span class="pre">`</span></tt>. You need to
|
||||
use <tt class="docutils literal"><span class="pre">\</span></tt> to escape them: <tt class="docutils literal"><span class="pre">\$</span></tt> and <tt class="docutils literal"><span class="pre">\`</span></tt>. The <tt class="docutils literal"><span class="pre">\</span></tt> itself may also
|
||||
needed to be escaped as <tt class="docutils literal"><span class="pre">\\</span></tt> sometimes.</p>
|
||||
</div>
|
||||
<div class="section" id="embedded-elisp-code">
|
||||
<h1><a class="toc-backref" href="#id10">Embedded elisp code</a></h1>
|
||||
<p>Elisp code can be embedded inside the template. They are written
|
||||
<div class="section" id="embedded-emacs-lisp-code">
|
||||
<h2><a class="toc-backref" href="#id15">Embedded Emacs-lisp code</a></h2>
|
||||
<p>Emacs-Lisp code can be embedded inside the template. They are written
|
||||
inside back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>):</p>
|
||||
<p>They are evaluated when the snippet is being expanded. The evaluation
|
||||
is done in the same buffer as the snippet being expanded. Here's an
|
||||
@@ -138,7 +295,7 @@ $0
|
||||
#endif /* $1 */
|
||||
</pre></div>
|
||||
<p>From version 0.6.0, snippets expansions are run with some special
|
||||
emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You
|
||||
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
|
||||
@@ -149,9 +306,9 @@ snippet. Alternatively, you can also customize the variable
|
||||
<tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt> which will do this automatically.</p>
|
||||
</div>
|
||||
<div class="section" id="tab-stop-fields">
|
||||
<h1><a class="toc-backref" href="#id11">Tab stop fields</a></h1>
|
||||
<h2><a class="toc-backref" href="#id16">Tab stop fields</a></h2>
|
||||
<p>Tab stops are fields that you can navigate back and forth by <tt class="docutils literal"><span class="pre">TAB</span></tt>
|
||||
and <tt class="docutils literal"><span class="pre">S-TAB</span></tt> <a class="footnote-reference" href="#id5" id="id1">[3]</a>. They are written by <tt class="docutils literal"><span class="pre">$</span></tt> followed with a
|
||||
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>
|
||||
@@ -161,7 +318,7 @@ fields. Here's a typical example:</p>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="placeholder-fields">
|
||||
<h1><a class="toc-backref" href="#id12">Placeholder fields</a></h1>
|
||||
<h2><a class="toc-backref" href="#id17">Placeholder fields</a></h2>
|
||||
<p>Tab stops can have default values -- a.k.a placeholders. The syntax is
|
||||
like this:</p>
|
||||
<div class="highlight"><pre>${N:default value}
|
||||
@@ -172,7 +329,7 @@ typing. The number can be omitted if you don't want to create
|
||||
<a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p>
|
||||
</div>
|
||||
<div class="section" id="id2">
|
||||
<span id="mirrors"></span><h1><a class="toc-backref" href="#id13">Mirrors</a></h1>
|
||||
<span id="mirrors"></span><h2><a class="toc-backref" href="#id18">Mirrors</a></h2>
|
||||
<p>We refer the tab stops with placeholders as a <em>field</em>. A field can have
|
||||
mirrors. Its mirrors will get updated when you change the text of a
|
||||
field. Here's an example:</p>
|
||||
@@ -188,10 +345,10 @@ none of the tab stops has an initial value, the first one is selected
|
||||
as the field and others mirrors.</p>
|
||||
</div>
|
||||
<div class="section" id="mirrors-with-transformations">
|
||||
<span id="transformations"></span><h1><a class="toc-backref" href="#id14">Mirrors with transformations</a></h1>
|
||||
<span id="transformations"></span><h2><a class="toc-backref" href="#id19">Mirrors with transformations</a></h2>
|
||||
<p>If the default value of a field starts with <tt class="docutils literal"><span class="pre">$</span></tt>, then it is interpreted
|
||||
as the transformation code instead of default value. A transformation
|
||||
is some arbitrary elisp code that will get evaluated in an environment
|
||||
is some arbitrary Emacs-lisp code that will get evaluated in an environment
|
||||
when the variable text is bind to the inputted text of the
|
||||
field. Here's an example for Objective-C:</p>
|
||||
<div class="highlight"><pre>- (${1:id})${2:foo}
|
||||
@@ -210,8 +367,8 @@ $0
|
||||
a placeholder. The actual placeholder is at the first line:
|
||||
<tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the transformation
|
||||
will be evaluated and the result will be placed there as the
|
||||
transformated text. So in this example, if you type baz in the field,
|
||||
the transformed text will be Baz. This example is also available in
|
||||
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 "==="
|
||||
@@ -232,27 +389,9 @@ ${1:$(make-string (string-width text) ?\=)}
|
||||
|
||||
$0
|
||||
</pre></div>
|
||||
<table class="docutils footnote" frame="void" id="id3" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label">[1]</td><td>With some minor change, mainly for fixing some trivial bugs.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table class="docutils footnote" frame="void" id="id4" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label">[2]</td><td>This is done when you call <tt class="docutils literal"><span class="pre">yas/initialize</span></tt>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table class="docutils footnote" frame="void" id="id5" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label"><a class="fn-backref" href="#id1">[3]</a></td><td>Of course, this can be customized.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<div class="section" id="fields-with-transformations">
|
||||
<h1><a class="toc-backref" href="#id15">Fields with transformations</a></h1>
|
||||
<h2><a class="toc-backref" href="#id20">Fields with transformations</a></h2>
|
||||
<p>From version 0.6 on, you can also have lisp transformation inside
|
||||
fields. These work mostly mirror transformations but are evaluated
|
||||
when you first enter the field, after each change you make to the
|
||||
@@ -264,8 +403,8 @@ distinguish between fields and mirrors. In the following example</p>
|
||||
<p><tt class="docutils literal"><span class="pre">mydefine</span></tt> gets automatically upcased to <tt class="docutils literal"><span class="pre">MYDEFINE</span></tt> once you enter
|
||||
the field. As you type text, it gets filtered through the
|
||||
transformation every time.</p>
|
||||
<p>Note that this is differentiated from a mirror with a transformation
|
||||
by the existance of extra text between the <tt class="docutils literal"><span class="pre">:</span></tt> and the
|
||||
<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)}"
|
||||
@@ -276,7 +415,7 @@ the value of the field and sets it its internal modification state to
|
||||
fields does not take place. This is by design.</p>
|
||||
</div>
|
||||
<div class="section" id="choosing-fields-value-from-a-list">
|
||||
<h1><a class="toc-backref" href="#id16">Choosing fields value from a list</a></h1>
|
||||
<h2><a class="toc-backref" href="#id21">Choosing fields value from a list</a></h2>
|
||||
<p>As mentioned, the field transformation is invoked just after you enter
|
||||
the field, and with some useful variables bound, notably
|
||||
<tt class="docutils literal"><span class="pre">yas/field-modified-p</span></tt> and <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Because of this
|
||||
@@ -292,7 +431,7 @@ using the two variables. Also check out <tt class="docutils literal"><span class
|
||||
another neat trick.</p>
|
||||
</div>
|
||||
<div class="section" id="nested-placeholder-fields">
|
||||
<h1><a class="toc-backref" href="#id17">Nested placeholder fields</a></h1>
|
||||
<h2><a class="toc-backref" href="#id22">Nested placeholder fields</a></h2>
|
||||
<p>From version 0.6 on, you can also have nested placeholders of the type:</p>
|
||||
<div class="highlight"><pre><div${1: id="${2:some_id}"}>$0</div>
|
||||
</pre></div>
|
||||
@@ -304,6 +443,103 @@ straight to the exit marker.</p>
|
||||
<p>By the way, <tt class="docutils literal"><span class="pre">C-d</span></tt> will only clear the field if you cursor is at the
|
||||
beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it
|
||||
performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="customizable-variables">
|
||||
<h1><a class="toc-backref" href="#id23">Customizable variables</a></h1>
|
||||
<div class="section" id="yas-trigger-key">
|
||||
<h2><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2>
|
||||
<p>The key bound to <tt class="docutils literal"><span class="pre">yas/expand</span></tt> when function <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is
|
||||
active.</p>
|
||||
<p>Value is a string that is converted to the internal Emacs key
|
||||
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
|
||||
<p>Default value is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-next-field-key">
|
||||
<h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2>
|
||||
<p>The key to navigate to next field when a snippet is active.</p>
|
||||
<p>Value is a string that is converted to the internal Emacs key
|
||||
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
|
||||
<p>Can also be a list of keys.</p>
|
||||
<p>Default value is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-prev-field-key">
|
||||
<h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2>
|
||||
<p>The key to navigate to previous field when a snippet is active.</p>
|
||||
<p>Value is a string that is converted to the internal Emacs key
|
||||
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
|
||||
<p>Can also be a list of keys.</p>
|
||||
<p>Default value is <tt class="docutils literal"><span class="pre">("<backtab>"</span> <span class="pre">"<S-tab>)"</span></tt>.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-skip-and-clear-key">
|
||||
<h2><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></h2>
|
||||
<p>The key to clear the currently active field.</p>
|
||||
<p>Value is a string that is converted to the internal Emacs key
|
||||
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
|
||||
<p>Can also be a list of keys.</p>
|
||||
<p>Default value is <tt class="docutils literal"><span class="pre">"C-d"</span></tt>.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-good-grace">
|
||||
<h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2>
|
||||
<p>If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
|
||||
snippet definitions. An error string "[yas] error" is returned instead.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-indent-line">
|
||||
<h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2>
|
||||
<p>The variable <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> controls the indenting. It is bound
|
||||
to <tt class="docutils literal"><span class="pre">'auto</span></tt> by default, which causes your snippet to be indented
|
||||
according to the mode of the buffer it was inserted in.</p>
|
||||
<p>Another variable <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt>, when non-nil
|
||||
does exactly that :-).</p>
|
||||
<p>To use the hard-coded indentation in your snippet template, set this
|
||||
variable to <tt class="docutils literal"><span class="pre">fixed</span></tt>.</p>
|
||||
<p>To control indentation on a per-snippet basis, see also the directive
|
||||
<tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> in <a class="reference external" href="snippet-development.html">Writing Snippets</a>.</p>
|
||||
<p>For backward compatibility with earlier versions of YASnippet, you can
|
||||
also place a <tt class="docutils literal"><span class="pre">$></span></tt> in your snippet, an <tt class="docutils literal"><span class="pre">(indent-according-to-mode)</span></tt>
|
||||
will be executed there to indent the line. This only takes effect when
|
||||
<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> is set to something other than <tt class="docutils literal"><span class="pre">'auto</span></tt>.</p>
|
||||
<div class="highlight"><pre>for (${int i = 0}; ${i < 10}; ${++i})
|
||||
{$>
|
||||
$0$>
|
||||
}$>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="yas-wrap-around-region">
|
||||
<h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2>
|
||||
<p>If non-nil, YASnippet will try to expand the snippet's exit marker
|
||||
around the currently selected region. When this variable is set to t,
|
||||
this has the same effect has using the <tt class="docutils literal"><span class="pre">`yas/selected-text`</span></tt> inline
|
||||
evaluation.</p>
|
||||
<p>Because on most systems starting to type deletes the currently region,
|
||||
this works mostly with the <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> command.</p>
|
||||
<p>However, when the value is of this variable is <tt class="docutils literal"><span class="pre">cua</span></tt> YASnippet will
|
||||
additionally look-up any recently selected that you deleted by starting
|
||||
typing. This allows you select a region, type a snippet key (deleting
|
||||
the region), then press <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to see the deleted region
|
||||
spring back to life inside your new snippet.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-triggers-in-field">
|
||||
<h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2>
|
||||
<p>If non-nil, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> can trigger stacked expansions,
|
||||
that is a snippet expansion inside another snippet
|
||||
expansion. Otherwise, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> just tries to move on to
|
||||
the next field.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-snippet-revival">
|
||||
<h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2>
|
||||
<p>Non-nil means re-activate snippet fields after undo/redo.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook">
|
||||
<h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></h2>
|
||||
<p>These hooks are called, respectively, before the insertion of a
|
||||
snippet and after exiting the snippet. If you find any strange but
|
||||
functional use for them, that's probably a design flaw in YASnippet,
|
||||
so let us know.</p>
|
||||
<!-- LocalWords: html YASnippet yas sourcecode pluskid init filenames filename -->
|
||||
<!-- LocalWords: env varlist keybinding keymap rinari ifndef upcase endif -->
|
||||
<!-- LocalWords: nondirectory autorelease aValue inline -->
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
Reference in New Issue
Block a user