ld/yasnippet
1
0
Fork 0
mirror of https://github.com/joaotavora/yasnippet.git synced 2026-02-04 06:32:24 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc almost complete. Drawing closer to 0.6.1b

Browse Source
This commit is contained in:
capitaomorte
2009-08-23 19:52:33 +00:00
parent 5b8671f8c3
commit 6c88b24bf8
27 changed files with 1806 additions and 988 deletions
Download Patch File Download Diff File Expand all files Collapse all files

649
doc/snippet-expansion.html
View File

@@ -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>Expanding 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,96 +50,344 @@
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#some-stuff" id="id1">Some stuff</a><ul>
<li><a class="reference internal" href="#file-content" id="id2">File content</a></li>
<li><a class="reference internal" href="#triggering-expansion" id="id2">Triggering expansion</a><ul>
<li><a class="reference internal" href="#trigger-key" id="id3">Trigger key</a><ul>
<li><a class="reference internal" href="#fallback-bahaviour" id="id4">Fallback bahaviour</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-strategy-to-select-a-snippet" id="id3">The strategy to select a snippet</a><ul>
<li><a class="reference internal" href="#finding-the-key" id="id4">Finding the key</a></li>
<li><a class="reference internal" href="#the-condition-system" id="id5">The condition system</a></li>
<li><a class="reference internal" href="#multiple-snippet-with-the-same-key" id="id6">Multiple snippet with the same key</a><ul>
<li><a class="reference internal" href="#use-the-x-window-system" id="id7">Use the X window system</a></li>
<li><a class="reference internal" href="#use-built-in-emacs-selection-methods" id="id8">Use built-in Emacs selection methods</a></li>
<li><a class="reference internal" href="#use-dropdown-menu-el" id="id9">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></li>
<li><a class="reference internal" href="#insert-at-point" id="id5">Insert at point</a></li>
<li><a class="reference internal" href="#snippet-keybinding" id="id6">Snippet keybinding</a></li>
<li><a class="reference internal" href="#expanding-from-the-menu" id="id7">Expanding from the menu</a></li>
<li><a class="reference internal" href="#expanding-with-hippie-expand" id="id8">Expanding with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></li>
<li><a class="reference internal" href="#expanding-from-emacs-lisp-code" id="id9">Expanding from emacs-lisp code</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-trigger-key" id="id10">The Trigger Key</a><ul>
<li><a class="reference internal" href="#the-minor-mode" id="id11">The Minor Mode</a></li>
<li><a class="reference internal" href="#the-fallback" id="id12">The Fallback</a></li>
<li><a class="reference internal" href="#integration-with-hippie-expand" id="id13">Integration with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></li>
<li><a class="reference internal" href="#controlling-expansion" id="id10">Controlling expansion</a><ul>
<li><a class="reference internal" href="#eligible-snippets" id="id11">Eligible snippets</a></li>
<li><a class="reference internal" href="#the-condition-system" id="id12">The condition system</a></li>
<li><a class="reference internal" href="#multiples-snippet-with-the-same-key" id="id13">Multiples snippet with the same key</a><ul>
<li><a class="reference internal" href="#use-the-x-window-system" id="id14">Use the X window system</a></li>
<li><a class="reference internal" href="#use-built-in-emacs-selection-methods" id="id15">Use built-in Emacs selection methods</a></li>
<li><a class="reference internal" href="#use-dropdown-menu-el" id="id16">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></li>
<li><a class="reference internal" href="#roll-your-own" id="id17">Roll your own</a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-way-to-select-a-snippet" id="id14">Other way to select a snippet</a><ul>
<li><a class="reference internal" href="#yas-insert-snippet" id="id15"><tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt></a></li>
<li><a class="reference internal" href="#expanding-from-elisp-code" id="id16">Expanding From Elisp Code</a></li>
</ul>
</li>
<li><a class="reference internal" href="#indenting" id="id17">Indenting</a></li>
<li><a class="reference internal" href="#customizable-variables" id="id18">Customizable Variables</a><ul>
<li><a class="reference internal" href="#yas-prompt-functions" id="id19"><tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt></a></li>
<li><a class="reference internal" href="#yas-fallback-behavior" id="id20"><tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt></a></li>
<li><a class="reference internal" href="#yas-choose-keys-first" id="id21"><tt class="docutils literal"><span class="pre">yas/choose-keys-first</span></tt></a></li>
<li><a class="reference internal" href="#yas-choose-tables-first" id="id22"><tt class="docutils literal"><span class="pre">yas/choose-tables-first</span></tt></a></li>
<li><a class="reference internal" href="#yas-key-syntaxes" id="id23"><tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt></a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="some-stuff">
<h1><a class="toc-backref" href="#id1">Some stuff</a></h1>
<div class="section" id="file-content">
<h2><a class="toc-backref" href="#id2">File content</a></h2>
<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 as meta data and comments;
below are template. Or else the whole file content is considered as
the template.</p>
<p>Here's a typical example:</p>
<div class="highlight"><pre>#contributor : pluskid &lt;pluskid@gmail.com&gt;
#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 meta data:</p>
<img align="right" alt="images/group.png" class="align-right" src="images/group.png" />
<div class="section" id="triggering-expansion">
<h1><a class="toc-backref" href="#id2">Triggering expansion</a></h1>
<p>You can use YASnippet to expand snippets in different ways:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">name</span></tt>: The name of the snippet. This is a one-line description of
the snippet. It will be displayed in the menu. So it's a good idea
to select a descriptive name fo a snippet -- especially
distinguishable among similar snippets.</li>
<li><tt class="docutils literal"><span class="pre">contributor</span></tt>: The contributor of the snippet.</li>
<li><tt class="docutils literal"><span class="pre">condition</span></tt>: The condition of the snippet. This is a piece of
elisp code. If a snippet has a condition, then it will only be
expanded when the condition code evaluate to some non-nil value.</li>
<li><tt class="docutils literal"><span class="pre">key</span></tt>: The key to expand the snippet. 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.</li>
<li><tt class="docutils literal"><span class="pre">group</span></tt>: The snippets for a mode can be grouped. Grouped snippets
will be grouped in sub-menu. This is useful if one has too many
snippets for a mode which will make the menu too long. <tt class="docutils literal"><span class="pre">group</span></tt>
property only affect menu construction (See <a class="reference external" href="snippet-organization.html">Organizing snippets</a>). Refer to
the snippets for <tt class="docutils literal"><span class="pre">ruby-mode</span></tt> for examples. 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.</li>
<li>By typing a snippet abbrev and then pressing the key defined in
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to &quot;TAB&quot;). This works in a
buffer where the minor mode <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active;</li>
<li>By invoking the command <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> (either by typing
<tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/insert-snippet</span></tt> or its keybinding). This does <em>not</em>
require <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active.</li>
<li>By using the keybinding associated with an active snippet. This also
requires <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active;</li>
<li>By expanding directly from the &quot;YASnippet&quot; menu in the menu-bar</li>
<li>By using hippie-expand</li>
<li>Expanding from emacs-lisp code</li>
</ul>
<div class="section" id="trigger-key">
<h2><a class="toc-backref" href="#id3">Trigger key</a></h2>
<p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is enabled, the keybinding taken from
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> will take effect.</p>
<p><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> invokes <tt class="docutils literal"><span class="pre">yas/expand</span></tt>, which tries to expand a
<em>snippet abbrev</em> (also known as <em>snippet key</em>) before point.</p>
<p>The default key is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>, however, you can freely set it to some
other key.</p>
<img align="left" alt="images/minor-mode-indicator.png" class="align-left" src="images/minor-mode-indicator.png" />
<p>To enable the YASnippet minor mode in all buffers globally use the
command <tt class="docutils literal"><span class="pre">yas/global-mode</span></tt>.</p>
<p>When you use <tt class="docutils literal"><span class="pre">yas/global-mode</span></tt> you can also selectively disable
YASnippet in some buffers by setting the buffer-local variable
<tt class="docutils literal"><span class="pre">yas/dont-active</span></tt> in the buffer's mode hook.</p>
<p>Trouble when using or understanding the <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> is easily
the most controversial issue in YASsnippet. See the <a class="reference external" href="faq.html">FAQ</a>.</p>
<div class="section" id="fallback-bahaviour">
<h3><a class="toc-backref" href="#id4">Fallback bahaviour</a></h3>
<p><tt class="docutils literal"><span class="pre">yas/fallback-behaviour</span></tt> is a customization variable bound to
<tt class="docutils literal"><span class="pre">'call-other-command</span></tt> by default. If <tt class="docutils literal"><span class="pre">yas/expand</span></tt> failed to find
any suitable snippet to expand, it will disable the minor mode
temporarily and find if there's any other command bound the
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p>
<p>If found, the command will be called. Usually this works very well --
when there's a snippet, expand it, otherwise, call whatever command
originally bind to the trigger key.</p>
<p>However, you can change this behavior by customizing the
<tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt> variable. If you set this variable to
<tt class="docutils literal"><span class="pre">'return-nil</span></tt>, it will return <tt class="docutils literal"><span class="pre">nil</span></tt> instead of trying to call the
<em>original</em> command when no snippet is found.</p>
</div>
</div>
<div class="section" id="insert-at-point">
<h2><a class="toc-backref" href="#id5">Insert at point</a></h2>
<p>The command <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/insert-snippet</span></tt> lets you insert snippets at
point <em>for you current major mode</em>. It prompts you for the snippet
key first, and then for a snippet template if more than one template
exists for the same key.</p>
<p>The list presented contains the snippets that can be inserted at
point, according to the condition system. If you want to see all
applicable snippets for the major mode, prefix this command with
<tt class="docutils literal"><span class="pre">C-u</span></tt>.</p>
<p>The prompting methods used are again controlled by
<tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt>.</p>
</div>
<div class="section" id="snippet-keybinding">
<h2><a class="toc-backref" href="#id6">Snippet keybinding</a></h2>
<p>See the section of the <tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> directive in <a class="reference external" href="snippet-development.html">Writing
Snippets</a>.</p>
</div>
<div class="section" id="expanding-from-the-menu">
<h2><a class="toc-backref" href="#id7">Expanding from the menu</a></h2>
<p>See <a class="reference external" href="snippet-menu.html">the YASnippet Menu</a>.</p>
</div>
<div class="section" id="expanding-with-hippie-expand">
<h2><a class="toc-backref" href="#id8">Expanding with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></h2>
<p>To integrate with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt>, just put
<tt class="docutils literal"><span class="pre">yas/hippie-try-expand</span></tt> in
<tt class="docutils literal"><span class="pre">hippie-expand-try-functions-list</span></tt>. This probably makes more sense
when placed at the top of the list, but it can be put anywhere you
prefer.</p>
</div>
<div class="section" id="expanding-from-emacs-lisp-code">
<h2><a class="toc-backref" href="#id9">Expanding from emacs-lisp code</a></h2>
<p>Sometimes you might want to expand a snippet directly by calling a
functin from elisp code. You should call <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt>
instead of <tt class="docutils literal"><span class="pre">yas/expand</span></tt> in this case.</p>
<p>As with expanding from the menubar, condition system and multiple
candidates won't exists here. In fact, expanding from menubar has the
same effect of evaluating the follow code:</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/expand-snippet</span> <span style="color: #19177C">template</span>)
</pre></div>
<p>See the internal documentation on <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> for more
information.</p>
</div>
</div>
<div class="section" id="controlling-expansion">
<h1><a class="toc-backref" href="#id10">Controlling expansion</a></h1>
<div class="section" id="eligible-snippets">
<h2><a class="toc-backref" href="#id11">Eligible snippets</a></h2>
<p>YASnippet does quite a bit of filtering to find out which snippets are
eligible for expanding at point.</p>
<p>In particular, the following things matter:</p>
<ul>
<li><p class="first">Currently loaded snippets tables</p>
<p>These are loaded from a directory hierarchy in your file system. See
<a class="reference external" href="snippet-organization.html">Organizing Snippets</a>. They are named after major modes like
<tt class="docutils literal"><span class="pre">html-mode</span></tt>, <tt class="docutils literal"><span class="pre">ruby-mode</span></tt>, etc...</p>
</li>
<li><p class="first">Major mode of the current buffer</p>
<p>If it matches one of the loaded snippet tables, then all that
table's snippets are considered for expansion. Use <tt class="docutils literal"><span class="pre">M-x</span>
<span class="pre">describe-variable</span> <span class="pre">RET</span> <span class="pre">major-mode</span> <span class="pre">RET</span></tt> to find out which mode you
are in currently.</p>
</li>
<li><p class="first">Parent tables</p>
<p>Snippet tables defined as parent of some other table considered in
the previous step are also considered.</p>
</li>
<li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/mode-symbol</span></tt> variable</p>
<p>This can be used to consider snippet tables whose name does not
correspond to a major mode. If you set this variable to a name ,
like <tt class="docutils literal"><span class="pre">rinari-minor-mode</span></tt>, you can have some snippets expand only
in that minor mode. Naturally, you want to set this conditionally,
i.e. only when entering that minor mode, using a hook is a good
idea.</p>
</li>
</ul>
<div class="highlight"><pre><span style="color: #408080; font-style: italic">;; When entering rinari-minor-mode, consider also the snippets in the</span>
<span style="color: #408080; font-style: italic">;; snippet table &quot;rails-mode&quot;</span>
(<span style="color: #19177C">add-hook</span> <span style="color: #19177C">&#39;rinari-minor-mode-hook</span>
<span style="color: #0000FF">#&#39;</span>(<span style="color: #008000; font-weight: bold">lambda</span> ()
(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/mode-symbol</span> <span style="color: #19177C">&#39;rails-mode</span>)))
</pre></div>
<ul>
<li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> variable</p>
<p>This variable provides more fine grained control over what snippets
can be expanded in the current buffer. The default value, won't let
you expand snippets inside comments or string literals for
example. See <a class="reference internal" href="#the-condition-system">The condition system</a> for more info.</p>
</li>
</ul>
</div>
<div class="section" id="the-condition-system">
<h2><a class="toc-backref" href="#id12">The condition system</a></h2>
<p>Consider this scenario: you are an old Emacs hacker. You like the
abbrev-way and set <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to <tt class="docutils literal"><span class="pre">&quot;SPC&quot;</span></tt>. However,
you don't want <tt class="docutils literal"><span class="pre">if</span></tt> to be expanded as a snippet when you are typing
in a comment block or a string (e.g. in <tt class="docutils literal"><span class="pre">python-mode</span></tt>).</p>
<p>If you use the <tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition</span> <span class="pre">:</span></tt> directive (see <a class="reference external" href="snippet-development.html">Writing Snippets</a>)
you could just specify the condition for <tt class="docutils literal"><span class="pre">if</span></tt> to be <tt class="docutils literal"><span class="pre">(not</span>
<span class="pre">(python-in-string/comment))</span></tt>. But how about <tt class="docutils literal"><span class="pre">while</span></tt>, <tt class="docutils literal"><span class="pre">for</span></tt>,
etc. ? Writing the same condition for all the snippets is just
boring. So has a buffer local variable
<tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt>. You can set this variable to <tt class="docutils literal"><span class="pre">(not</span>
<span class="pre">(python-in-string/comment))</span></tt> in <tt class="docutils literal"><span class="pre">python-mode-hook</span></tt>.</p>
<p>Then, what if you really want some particular snippet to expand even
inside a comment? This is also possible! But let's stop telling the
story and look at the rules:</p>
<ul class="simple">
<li>If <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> evaluate to nil, no snippets will
be considered for expansion.</li>
<li>If it evaluates to the a <em>cons cell</em> where the <tt class="docutils literal"><span class="pre">car</span></tt> is the symbol
<tt class="docutils literal"><span class="pre">require-snippet-condition</span></tt> and the <tt class="docutils literal"><span class="pre">cdr</span></tt> is a symbol (let's
call it <tt class="docutils literal"><span class="pre">requirement</span></tt>), then:<ul>
<li>Snippets having no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> directive won't be considered;</li>
<li>Snippets with conditions that evaluate to nil (or produce an
error) won't be considered;</li>
<li>If the snippet has a condition that evaluates to non-nil (let's
call it <tt class="docutils literal"><span class="pre">result</span></tt>):<ul>
<li>If <tt class="docutils literal"><span class="pre">requirement</span></tt> is <tt class="docutils literal"><span class="pre">t</span></tt>, the snippet is ready to be
expanded;</li>
<li>If <tt class="docutils literal"><span class="pre">requirement</span></tt> is <tt class="docutils literal"><span class="pre">eq</span></tt> to <tt class="docutils literal"><span class="pre">result</span></tt>, the snippet is ready
to be expanded;</li>
<li>Otherwise the snippet won't be considered.</li>
</ul>
</li>
</ul>
</li>
<li>If it evaluates to the symbol <tt class="docutils literal"><span class="pre">always</span></tt>, all snippets are
considered for expansion, regardless of any conditions.</li>
<li>If it evaluate to <tt class="docutils literal"><span class="pre">t</span></tt> or some other non-nil value:<ul>
<li>If the snippet has no condition, or has a condition that evaluate
to non-nil, it is ready to be expanded.</li>
<li>Otherwise, it won't be considered.</li>
</ul>
</li>
</ul>
<p>In the mentioned scenario, set <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> like
this</p>
<div class="highlight"><pre>(<span style="color: #19177C">add-hook</span> <span style="color: #19177C">&#39;python-mode-hook</span>
<span style="color: #666666">&#39;</span>(<span style="color: #008000; font-weight: bold">lambda</span> ()
(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/buffer-local-condition</span>
<span style="color: #666666">&#39;</span>(<span style="color: #008000; font-weight: bold">if</span> (<span style="color: #19177C">python-in-string/comment</span>)
<span style="color: #666666">&#39;</span>(<span style="color: #19177C">require-snippet-condition</span> <span style="color: #666666">.</span> <span style="color: #19177C">force-in-comment</span>)
<span style="color: #880000">t</span>))))
</pre></div>
<p>... and specify the condition for a snippet that you're going to
expand in comment to be evaluated to the symbol
<tt class="docutils literal"><span class="pre">force-in-comment</span></tt>. Then it can be expanded as you expected, while
other snippets like <tt class="docutils literal"><span class="pre">if</span></tt> still can't expanded in comment.</p>
</div>
<div class="section" id="the-strategy-to-select-a-snippet">
<h1><a class="toc-backref" href="#id3">The strategy to select a snippet</a></h1>
<p>When user press the <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>, YASnippet try to find a
proper snippet to expand. The strategy to find such a snippet is
explained here.</p>
<div class="section" id="finding-the-key">
<h2><a class="toc-backref" href="#id4">Finding the key</a></h2>
<p>YASnippet search from current point backward trying to find the
snippet to be expanded. The default searching strategy is quite
powerful. For example, in <tt class="docutils literal"><span class="pre">c-mode</span></tt>, <tt class="docutils literal"><span class="pre">&quot;bar&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;foo_bar&quot;</span></tt>,
<tt class="docutils literal"><span class="pre">&quot;#foo_bar&quot;</span></tt> can all be recognized as a template key. Further more,
the searching is in that order. In other words, if <tt class="docutils literal"><span class="pre">&quot;bar&quot;</span></tt> is found
to be a key to some <em>valid</em> snippet, then <tt class="docutils literal"><span class="pre">&quot;foo_bar&quot;</span></tt> and
<tt class="docutils literal"><span class="pre">&quot;#foobar&quot;</span></tt> won't be searched.</p>
<div class="section" id="multiples-snippet-with-the-same-key">
<h2><a class="toc-backref" href="#id13">Multiples snippet with the same key</a></h2>
<p>The rules outlined <a class="reference external" href="Eligiblesnippets">above</a> can return more than
one snippet to be expanded at point.</p>
<p>When there are multiple candidates, YASnippet will let you select
one. The UI for selecting multiple candidate can be customized. A
customization variable, called <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> defines your
preferred method of being prompted for snippets.</p>
<p>You can customize it with <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">customize-variable</span> <span class="pre">RET</span>
<span class="pre">yas/prompt-functions</span> <span class="pre">RET</span></tt>. Alternatively you can put in your
emacs-file:</p>
<div class="highlight"><pre>(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/prompt-functions</span> <span style="color: #666666">&#39;</span>(<span style="color: #19177C">yas/x-prompt</span> <span style="color: #19177C">yas/dropdown-prompt</span>))
</pre></div>
<p>Currently there are some alternatives solution with YASnippet.</p>
<img align="right" alt="images/x-menu.png" class="align-right" src="images/x-menu.png" />
<div class="section" id="use-the-x-window-system">
<h3><a class="toc-backref" href="#id14">Use the X window system</a></h3>
<p>The function <tt class="docutils literal"><span class="pre">yas/x-prompt</span></tt> can be used to show a popup menu for you
to select. This menu will be part of you native window system widget,
which means:</p>
<ul class="simple">
<li>It usually looks beautiful. E.g. when you compile Emacs with gtk
support, this menu will be rendered with your gtk theme.</li>
<li>Emacs have little control over it. E.g. you can't use <tt class="docutils literal"><span class="pre">C-n</span></tt>,
<tt class="docutils literal"><span class="pre">C-p</span></tt> to navigate.</li>
<li>This function can't be used when in a terminal.</li>
</ul>
<img align="right" alt="images/ido-menu.png" class="align-right" src="images/ido-menu.png" />
</div>
<div class="section" id="use-built-in-emacs-selection-methods">
<h3><a class="toc-backref" href="#id15">Use built-in Emacs selection methods</a></h3>
<p>You can use functions <tt class="docutils literal"><span class="pre">yas/completing-prompt</span></tt> for the classic emacs
completion method or <tt class="docutils literal"><span class="pre">yas/ido-prompt</span></tt> for a much nicer looking
method. The best way is to try it. This works in a terminal.</p>
<img align="right" alt="images/dropdown-menu.png" class="align-right" src="images/dropdown-menu.png" />
</div>
<div class="section" id="use-dropdown-menu-el">
<h3><a class="toc-backref" href="#id16">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></h3>
<p>The function <tt class="docutils literal"><span class="pre">yas/dropdown-prompt</span></tt> can also be placed in the
<tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> list.</p>
<p>This works in both window system and terminal and is customizable, you
can use <tt class="docutils literal"><span class="pre">C-n</span></tt>, <tt class="docutils literal"><span class="pre">C-p</span></tt> to navigate, <tt class="docutils literal"><span class="pre">q</span></tt> to quit and even press
<tt class="docutils literal"><span class="pre">6</span></tt> as a shortcut to select the 6th candidate.</p>
</div>
<div class="section" id="roll-your-own">
<h3><a class="toc-backref" href="#id17">Roll your own</a></h3>
<p>See below for the documentation on variable <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt></p>
</div>
</div>
</div>
<div class="section" id="customizable-variables">
<h1><a class="toc-backref" href="#id18">Customizable Variables</a></h1>
<div class="section" id="yas-prompt-functions">
<h2><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt></a></h2>
<p>You can write a function and add it to the <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt>
list. These functions are called with the following arguments:</p>
<ul class="simple">
<li>PROMPT: A string to prompt the user;</li>
<li>CHOICES: A list of strings or objects;</li>
<li>optional DISPLAY-FN : A function. When applied to each of the
objects in CHOICES it will return a string;</li>
</ul>
<p>The return value of any function you put here should be one of
the objects in CHOICES, properly formatted with DISPLAY-FN (if
that is passed).</p>
<ul class="simple">
<li>To signal that your particular style of prompting is unavailable at
the moment, you can also have the function return nil.</li>
<li>To signal that the user quit the prompting process, you can signal
<tt class="docutils literal"><span class="pre">quit</span></tt> with <tt class="docutils literal"><span class="pre">(signal</span> <span class="pre">'quit</span> <span class="pre">&quot;user</span> <span class="pre">quit!&quot;)</span></tt></li>
</ul>
</div>
<div class="section" id="yas-fallback-behavior">
<h2><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt></a></h2>
<p>How to act when <tt class="docutils literal"><span class="pre">yas/expand</span></tt> does <em>not</em> expand a snippet.</p>
<dl class="docutils">
<dt><tt class="docutils literal"><span class="pre">call-other-command</span></tt> means try to temporarily disable YASnippet and</dt>
<dd>call the next command bound to <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</dd>
</dl>
<p><tt class="docutils literal"><span class="pre">return-nil</span></tt> means return nil. (i.e. do nothing)</p>
<p>An entry (apply COMMAND . ARGS) means interactively call COMMAND, if
ARGS is non-nil, call COMMAND non-interactively with ARGS as
arguments.</p>
</div>
<div class="section" id="yas-choose-keys-first">
<h2><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">yas/choose-keys-first</span></tt></a></h2>
<p>If non-nil, prompt for snippet key first, then for template.</p>
<p>Otherwise prompts for all possible snippet names.</p>
<p>This affects <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> and <tt class="docutils literal"><span class="pre">yas/visit-snippet-file</span></tt>.</p>
</div>
<div class="section" id="yas-choose-tables-first">
<h2><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">yas/choose-tables-first</span></tt></a></h2>
<p>If non-nil, and multiple eligible snippet tables, prompts user for
tables first.</p>
<p>Otherwise, user chooses between the merging together of all
eligible tables.</p>
<p>This affects <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt>, <tt class="docutils literal"><span class="pre">yas/visit-snippet-file</span></tt></p>
</div>
<div class="section" id="yas-key-syntaxes">
<h2><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt></a></h2>
<p>The default searching strategy is quite powerful. For example, in
<tt class="docutils literal"><span class="pre">c-mode</span></tt>, <tt class="docutils literal"><span class="pre">&quot;bar&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;foo_bar&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;#foo_bar&quot;</span></tt> can all be
recognized as a snippet key. Furthermore, the searching is in that
order. In other words, if <tt class="docutils literal"><span class="pre">&quot;bar&quot;</span></tt> is found to be a key to some
<em>valid</em> snippet, then <tt class="docutils literal"><span class="pre">&quot;foo_bar&quot;</span></tt> and <tt class="docutils literal"><span class="pre">&quot;#foobar&quot;</span></tt> won't be
searched.</p>
<p>However, this strategy can also be customized easily from the
<tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt> variable. It is a list of syntax rules, the
default value is <tt class="docutils literal"><span class="pre">(&quot;w&quot;</span> <span class="pre">&quot;w_&quot;</span> <span class="pre">&quot;w_.&quot;</span> <span class="pre">&quot;^</span> <span class="pre">&quot;)</span></tt>. Which means search the
@@ -155,255 +401,6 @@ following thing until found one:</p>
<p>But you'd better keep the default value unless you understand what
Emacs's syntax rule mean.</p>
</div>
<div class="section" id="the-condition-system">
<h2><a class="toc-backref" href="#id5">The condition system</a></h2>
<p>I write forked snippet.el to make the smart-snippet.el. I call it
<em>smart</em>-snippet because a condition can be attached to a snippet. This
is really a good idea. However, writing condition for a snippet
usually needs good elisp and Emacs knowledge, so it is strange to many
user.</p>
<p>Later I write YASnippet and persuade people to use it instead of
smart-snippet.el. However, some user still love smart-snippet because
it is smart. So I make YASnippet smart. Even smarter than
smart-snippet.el. :p</p>
<p>Consider this scenario: you are an old Emacs hacker. You like the
abbrev-way and set <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to <tt class="docutils literal"><span class="pre">(kbd</span> <span class="pre">&quot;SPC&quot;)</span></tt>. However,
you don't want <tt class="docutils literal"><span class="pre">if</span></tt> to be expanded as a snippet when you are typing
in a comment block or a string (e.g. in <tt class="docutils literal"><span class="pre">python-mode</span></tt>).</p>
<p>It's OK, just specify the condition for <tt class="docutils literal"><span class="pre">if</span></tt> to be <tt class="docutils literal"><span class="pre">(not</span>
<span class="pre">(python-in-string/comment))</span></tt>. But how about <tt class="docutils literal"><span class="pre">while</span></tt>, <tt class="docutils literal"><span class="pre">for</span></tt>,
etc. ? Writing the same condition for all the snippets is just
boring. So YASnippet introduce a buffer local variable
<tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt>. You can set this variable to <tt class="docutils literal"><span class="pre">(not</span>
<span class="pre">(python-in-string/comment))</span></tt> in <tt class="docutils literal"><span class="pre">python-mode-hook</span></tt>. There's no way
to do this in smart-snippet.el!</p>
<p>Then, what if you really want some snippet even in comment? This is
also possible! But let's stop telling the story and look at the rules:</p>
<ul class="simple">
<li>If <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> evaluate to nil, snippet won't be
expanded.</li>
<li>If it evaluate to the a cons cell where the <tt class="docutils literal"><span class="pre">car</span></tt> is the symbol
<tt class="docutils literal"><span class="pre">require-snippet-condition</span></tt> and the <tt class="docutils literal"><span class="pre">cdr</span></tt> is a symbol (let's
call it <tt class="docutils literal"><span class="pre">requirement</span></tt>):<ul>
<li>If the snippet has no condition, then it won't be expanded.</li>
<li>If the snippet has a condition but evaluate to nil or error
occured during evaluation, it won't be expanded.</li>
<li>If the snippet has a condition that evaluate to non-nil (let's
call it <tt class="docutils literal"><span class="pre">result</span></tt>):<ul>
<li>If <tt class="docutils literal"><span class="pre">requirement</span></tt> is <tt class="docutils literal"><span class="pre">t</span></tt>, the snippet is ready to be
expanded.</li>
<li>If <tt class="docutils literal"><span class="pre">requirement</span></tt> is <tt class="docutils literal"><span class="pre">eq</span></tt> to <tt class="docutils literal"><span class="pre">result</span></tt>, the snippet is ready
to be expanded.</li>
<li>Otherwise the snippet won't be expanded.</li>
</ul>
</li>
</ul>
</li>
<li>If it evaluate to other non-nil value:<ul>
<li>If the snippet has no condition, or has a condition that evaluate
to non-nil, it is ready to be expanded.</li>
<li>Otherwise, it won't be expanded.</li>
</ul>
</li>
</ul>
<p>So set <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> like this</p>
<div class="highlight"><pre>(<span style="color: #19177C">add-hook</span> <span style="color: #19177C">&#39;python-mode-hook</span>
<span style="color: #666666">&#39;</span>(<span style="color: #008000; font-weight: bold">lambda</span> ()
(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/buffer-local-condition</span>
<span style="color: #666666">&#39;</span>(<span style="color: #008000; font-weight: bold">if</span> (<span style="color: #19177C">python-in-string/comment</span>)
<span style="color: #666666">&#39;</span>(<span style="color: #19177C">require-snippet-condition</span> <span style="color: #666666">.</span> <span style="color: #19177C">force-in-comment</span>)
<span style="color: #880000">t</span>))))
</pre></div>
<p>And specify the condition for a snippet that you're going to expand in
comment to be evaluated to the symbol <tt class="docutils literal"><span class="pre">force-in-comment</span></tt>. Then it
can be expanded as you expected, while other snippets like <tt class="docutils literal"><span class="pre">if</span></tt>
still can't expanded in comment.</p>
</div>
<div class="section" id="multiple-snippet-with-the-same-key">
<h2><a class="toc-backref" href="#id6">Multiple snippet with the same key</a></h2>
<p>There can be multiple snippet bind to the same key. If you define a
snippet with a key that is already used, you'll overwrite the original
snippet definition. However, you can add a different <em>postfix</em> to the
key.</p>
<p>In general, the <em>extension</em> (consider a file name) is <em>ignored</em> when
defining a snippet. So <tt class="docutils literal"><span class="pre">def</span></tt>, <tt class="docutils literal"><span class="pre">def.1</span></tt> and <tt class="docutils literal"><span class="pre">def.mine</span></tt> will all be
valid candidates when the key is <tt class="docutils literal"><span class="pre">def</span></tt>.</p>
<p>When there are multiple candidates, YASnippet will let you select
one. The UI for selecting multiple candidate can be
customized. There're two variable related:</p>
<p>From version 0.6 of YASnippet this has changed significantly. A new
customization variable, called <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> defines your
preferred method of being prompted for snippets.</p>
<p>You can customize it with <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">customize-variable</span> <span class="pre">RET</span>
<span class="pre">yas/prompt-functions</span> <span class="pre">RET</span></tt>. Alternatively you can put in your
emacs-file:</p>
<div class="highlight"><pre>(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/prompt-functions</span> <span style="color: #666666">&#39;</span>(<span style="color: #19177C">yas/x-prompt</span> <span style="color: #19177C">yas/dropdown-prompt</span>))
</pre></div>
<p>Currently there are some alternatives solution with YASnippet.</p>
<img align="right" alt="images/popup-menu.png" class="align-right" src="images/popup-menu.png" />
<div class="section" id="use-the-x-window-system">
<h3><a class="toc-backref" href="#id7">Use the X window system</a></h3>
<p>The function <tt class="docutils literal"><span class="pre">yas/x-prompt</span></tt> can be used to show a popup menu for you
to select. This menu will be part of you native window system widget,
which means:</p>
<ul class="simple">
<li>It usually looks beautiful. E.g. when you compile Emacs with gtk
support, this menu will be rendered with your gtk theme.</li>
<li>Emacs have little control over it. E.g. you can't use <tt class="docutils literal"><span class="pre">C-n</span></tt>,
<tt class="docutils literal"><span class="pre">C-p</span></tt> to navigate.</li>
<li>This function can't be used when in a terminal.</li>
</ul>
</div>
<div class="section" id="use-built-in-emacs-selection-methods">
<h3><a class="toc-backref" href="#id8">Use built-in Emacs selection methods</a></h3>
<p>You can use functions <tt class="docutils literal"><span class="pre">yas/completing-prompt</span></tt> for the classic emacs
completion method or <tt class="docutils literal"><span class="pre">yas/ido-prompt</span></tt> for a much nicer looking
method. The best way is to try it. This works in a terminal.</p>
<div align="center" class="align-center"><img alt="images/idrop-menu.png" class="align-center" src="images/idrop-menu.png" /></div>
</div>
<div class="section" id="use-dropdown-menu-el">
<h3><a class="toc-backref" href="#id9">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></h3>
<p>The function <tt class="docutils literal"><span class="pre">yas/dropdown-prompt</span></tt> can also be placed in the
<tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> list.</p>
<img align="right" alt="images/dropdown-menu.png" class="align-right" src="images/dropdown-menu.png" />
<p>Originally, only the above two function is available in
YASnippet. They are difficult to use -- especially in a
terminal. Until later Jaeyoun Chung show me his <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt>,
I say wow! It's wonderful!</p>
<ul class="simple">
<li>It works in both window system and terminal.</li>
<li>It is customizable, you can use <tt class="docutils literal"><span class="pre">C-n</span></tt>, <tt class="docutils literal"><span class="pre">C-p</span></tt> to navigate, <tt class="docutils literal"><span class="pre">q</span></tt>
to quite and even press <tt class="docutils literal"><span class="pre">6</span></tt> as a shortcut to select the 6th
candidate.</li>
</ul>
<p>So I added <tt class="docutils literal"><span class="pre">yas/dropdown-list-popup-for-template</span></tt> to support
<tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt>. And upload <tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> to YASnippet
hompage for an optional download (since Jaeyoun didn't provide a URL).</p>
<p>Then finally, in 0.4.0, I included a copy of the content of
<tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> in <tt class="docutils literal"><span class="pre">yasnippet.el</span></tt> and made it the default
way for selecting multiple candidates.</p>
<p>However, the original functions are still there, you can still use this</p>
<div class="highlight"><pre>(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/window-system-popup-function</span>
<span style="color: #19177C">&#39;yas/x-popup-menu-for-template</span>)
</pre></div>
<p>if you prefer a <em>modern</em> UI. :)</p>
</div>
</div>
<div class="section" id="the-trigger-key">
<h2><a class="toc-backref" href="#id10">The Trigger Key</a></h2>
<p>YASnippet is implemented as a minor-mode (<tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt>). The
trigger key <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> is defined in <tt class="docutils literal"><span class="pre">yas/minor-mode-map</span></tt>
to call <tt class="docutils literal"><span class="pre">yas/expand</span></tt> to try to expand a snippet.</p>
<div class="section" id="the-minor-mode">
<h3><a class="toc-backref" href="#id11">The Minor Mode</a></h3>
<img align="left" alt="images/minor-mode-indicator.png" class="align-left" src="images/minor-mode-indicator.png" />
<p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is enabled, the trigger key will take
effect. The default key is <tt class="docutils literal"><span class="pre">(kbd</span> <span class="pre">&quot;TAB&quot;)</span></tt>, however, you can freely
set it to some other key.</p>
<p>In version 0.5, YASnippet add a hook to
<tt class="docutils literal"><span class="pre">after-change-major-mode-hook</span></tt> to enable <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> in
every buffer. This works fine for most modes, however, some mode
doesn't follow the Emacs convention and doens't call this hook. You
can either explicitly hook for those mode or just add it to
<tt class="docutils literal"><span class="pre">yas/extra-mode-hooks</span></tt> to let YASnippet do it for you:</p>
<div class="highlight"><pre>(<span style="color: #008000">require</span> <span style="color: #19177C">&#39;yasnippet</span>)
(<span style="color: #19177C">add-to-list</span> <span style="color: #19177C">&#39;yas/extra-mode-hooks</span>
<span style="color: #19177C">&#39;ruby-mode-hook</span>)
(<span style="color: #19177C">yas/initialize</span>)
</pre></div>
<p>Note that <strong>should</strong> be put after <tt class="docutils literal"><span class="pre">(require</span> <span class="pre">'yasnippet)</span></tt> and before
<tt class="docutils literal"><span class="pre">(yas/initialize)</span></tt>. Further more, you may report it to me, I'll add
that to the default value.</p>
<p>In version 0.6, just use <tt class="docutils literal"><span class="pre">yas/global-mode</span></tt> to enable YASnippet in
all major modes. Or put <tt class="docutils literal"><span class="pre">yas/minor-mode-on</span></tt> in that modes hook. See
the <a class="reference external" href="faq.html">FAQ</a>.</p>
</div>
<div class="section" id="the-fallback">
<h3><a class="toc-backref" href="#id12">The Fallback</a></h3>
<p>If <tt class="docutils literal"><span class="pre">yas/expand</span></tt> failed to find any suitable snippet to expand, it
will disable the minor mode temporarily and find if there's any other
command bind the <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>. If found, the command will be
called. Usually this works very well -- when there's a snippet, expand
it, otherwise, call whatever command originally bind to the trigger
key.</p>
<p>However, you can change this behavior by customizing the
<tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt> variable. If you set this variable to
<tt class="docutils literal"><span class="pre">'return-nil</span></tt>, it will return <tt class="docutils literal"><span class="pre">nil</span></tt> instead of trying to call the
<em>original</em> command when no snippet is found. This is useful when you
would like YASnippet to work with other extensions,
e.g. <tt class="docutils literal"><span class="pre">hippie-expand</span></tt>. I'm also glad to tell you that integration
with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt> is already included in YASnippet.</p>
</div>
<div class="section" id="integration-with-hippie-expand">
<h3><a class="toc-backref" href="#id13">Integration with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></h3>
<p>To integrate with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt>, just put
<tt class="docutils literal"><span class="pre">yas/hippie-try-expand</span></tt> in
<tt class="docutils literal"><span class="pre">hippie-expand-try-functions-list</span></tt>. Personally I would like to put
in front of the list, but it can be put anywhere you prefer.</p>
</div>
</div>
<div class="section" id="other-way-to-select-a-snippet">
<h2><a class="toc-backref" href="#id14">Other way to select a snippet</a></h2>
<p>When you use the trigger key (so <tt class="docutils literal"><span class="pre">yas/expand</span></tt>) to expand a snippet,
the key for the snippet is deleted before the template for the snippet
is inserted.</p>
<p>However, there're other ways to insert a snippet.</p>
<div class="section" id="yas-insert-snippet">
<h3><a class="toc-backref" href="#id15"><tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt></a></h3>
<p>The command <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/insert-snippet</span></tt> lets you insert snippets at
point <em>for you current major mode</em>. It prompts you for the snippet
key first, and then for a snippet template if more than one template
exists for the same key.</p>
<p>The list presented contains the snippets that can be inserted at
point, according to the condition system. If you want to see all
applicable snippets for the major mode, prefix this command with
<tt class="docutils literal"><span class="pre">C-u</span></tt>.</p>
<p>The prompting methods used are again controlled by
<tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt>.</p>
</div>
<div class="section" id="expanding-from-elisp-code">
<h3><a class="toc-backref" href="#id16">Expanding From Elisp Code</a></h3>
<p>Sometimes you might want to expand a snippet directly by calling a
functin from elisp code. You should call <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt>
instead of <tt class="docutils literal"><span class="pre">yas/expand</span></tt> in this case.</p>
<p>As with expanding from the menubar, condition system and multiple
candidates won't exists here. In fact, expanding from menubar has the
same effect of evaluating the follow code:</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/expand-snippet</span> (<span style="color: #19177C">point</span>) (<span style="color: #19177C">point</span>) <span style="color: #19177C">template</span>)
</pre></div>
<p>Where <tt class="docutils literal"><span class="pre">template</span></tt> is the template of a snippet. It is never required
to belong to any snippet -- you can even make up it on the fly. The
1st and 2nd parameter defines the region to be deleted after YASnippet
inserted the template. It is used by <tt class="docutils literal"><span class="pre">yas/expand</span></tt> to indicate the
region of the key. There's usually no need to delete any region when
we are expanding a snippet from elisp code, so passing two <tt class="docutils literal"><span class="pre">(point)</span></tt>
is fine. Note only <tt class="docutils literal"><span class="pre">(point)</span></tt> will be fine because the 1st parameter
also indicate where to insert and expand the <tt class="docutils literal"><span class="pre">template</span></tt>.</p>
</div>
</div>
<div class="section" id="indenting">
<h2><a class="toc-backref" href="#id17">Indenting</a></h2>
<p>Many people miss the indenting feature of smart-snippet: when you
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> will
be executed there to indent the line. So you'll not need to hard-code
the indenting in the snippet template, and it will be very convenient
when you need to work with several different project where coding
styles are different.</p>
<p>The reason why this feature wasn't added to YASnippet until after
0.5.6 is that it doesn't work well for all modes. In some cases
(e.g. python-mode), calling <tt class="docutils literal"><span class="pre">indent-according-to-mode</span></tt> will break
the overlays created by YASnippet.</p>
<p>However, since many people asked for this feature, I finally added
this to YASnippet. Here's an example of the usage:</p>
<div class="highlight"><pre>for (${int i = 0}; ${i &lt; 10}; ${++i})
{$&gt;
$0$&gt;
}$&gt;
</pre></div>
<p>In 0.6.0 You should <strong>not</strong> need to use this feature although it's
supported for backward compatibility. Just set <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> to
<tt class="docutils literal"><span class="pre">'auto</span></tt>.</p>
</div>
</div>
</div>
</div>