ld/yasnippet
1
0
Fork 0
mirror of https://github.com/joaotavora/yasnippet.git synced 2025-10-13 13:13:03 +00:00
Code Issues Packages Projects Releases Wiki Activity

added skeleton of new documentation

Browse Source
This commit is contained in:
capitaomorte 2009-08-19 16:19:06 +00:00
parent 9541218756
commit 938e3a6eb8
14 changed files with 2436 additions and 1966 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

214
doc/changelog.html
View File

@ -3,7 +3,7 @@
<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.4: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>ChangeLog</title>
<meta name="author" content="pluskid" />
<meta name="date" content="2008-03-22" />
@ -11,30 +11,52 @@
</head>
<body>
<div class="document" id="changelog">
<h1 class="title">ChangeLog</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>pluskid</td></tr>
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference" href="mailto:pluskid&#64;gmail.com">pluskid&#64;gmail.com</a></td></tr>
<tr><th class="docinfo-name">Date:</th>
<td>2008-03-22</td></tr>
</tbody>
</table>
<div class="section">
<h1><a id="c-2009-07-27" name="c-2009-07-27">0.6.0c / 2009-07-27</a></h1>
<div id="header-region" class="clear-block"></div>
<div id="wrapper">
<div id="container" class="clear-block">
<div id="header">
<div id="logo-floater">
<h1 class="title">ChangeLog</h1>
</div>
<ul class="primary-links">
<li>
<a title="" href="index.html">Home</a>
</li>
<li>
<a title="" href="snippet-organization.html">Organize</a>
</li>
<li>
<a title="" href="snippet-expansion.html">Expand</a>
</li>
<li>
<a title="" href="snippet-development.html">Write</a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>
</li>
<li>
<a title="" href="changelog.html">ChangeLog</a>
</li>
<li>
<a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
</li>
</ul>
</div>
<div id="center">
<div id="squeeze">
<div class="right-corner">
<div class="left-corner">
<div class="section" id="c-2009-07-27">
<h1>0.6.0c / 2009-07-27</h1>
<ul class="simple">
<li>Now byte compiles correctly with no warnings.</li>
<li>Fixed <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=68">Issue 68</a> with
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=68">Issue 68</a> with
mouse-clicking alternatives in <tt class="docutils literal"><span class="pre">ido-mode</span></tt>.</li>
<li>Added <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt> customization variable.</li>
</ul>
</div>
<div class="section">
<h1><a id="b-2009-07-25" name="b-2009-07-25">0.6.0b / 2009-07-25</a></h1>
<div class="section" id="b-2009-07-25">
<h1>0.6.0b / 2009-07-25</h1>
<ul class="simple">
<li>Nested placeholders of the type <tt class="docutils literal"><span class="pre">&lt;div${1:</span> <span class="pre">id=&quot;${2:someid}&quot;}&gt;</span> <span class="pre">$0</span></tt>.</li>
<li>More robust undo/redo support.</li>
@ -51,63 +73,63 @@ primary field transformation.</li>
<li>Customization group <tt class="docutils literal"><span class="pre">yasnippet</span></tt>.</li>
<li>Overriding customization variables in snippets. Use the <tt class="docutils literal"><span class="pre">env:</span>
<span class="pre">let-form</span></tt> template keyword.</li>
<li>Fixed <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=60">Issue 60</a></li>
<li>Fixed <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=65">Issue 65</a></li>
<li>Fixed <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=56">Issue 56</a></li>
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=60">Issue 60</a></li>
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=65">Issue 65</a></li>
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=56">Issue 56</a></li>
</ul>
</div>
<div class="section">
<h1><a id="id1" name="id1">0.5.10 / 2009-02-11</a></h1>
<div class="section" id="id1">
<h1>0.5.10 / 2009-02-11</h1>
<ul class="simple">
<li>Added <em>grouping</em> support so that the snippets in the menu can be
groupped together.</li>
<li>Make the bundle <a class="reference" href="http://tromey.com/elpa/index.html">ELPA</a>
<li>Make the bundle <a class="reference external" href="http://tromey.com/elpa/index.html">ELPA</a>
compatible.</li>
</ul>
</div>
<div class="section">
<h1><a id="id2" name="id2">0.5.9 / 2009-01-21</a></h1>
<div class="section" id="id2">
<h1>0.5.9 / 2009-01-21</h1>
<ul class="simple">
<li>Fixed the bug of disabling the auto-indenting of <tt class="docutils literal"><span class="pre">cc-mode</span></tt>.</li>
</ul>
</div>
<div class="section">
<h1><a id="id3" name="id3">0.5.8 / 2009-01-15</a></h1>
<div class="section" id="id3">
<h1>0.5.8 / 2009-01-15</h1>
<ul class="simple">
<li>Added a <tt class="docutils literal"><span class="pre">key</span></tt> property in snippet definition for snippet names
that are not valid path name.</li>
<li>Fixed some bugs of indenting (<a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=44">Issue 44</a>, <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=46">Issue
<li>Fixed some bugs of indenting (<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=44">Issue 44</a>, <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=46">Issue
46</a>).</li>
<li>Fixed <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=45">Issue 45</a> by
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=45">Issue 45</a> by
providing a proper default value for <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt>.</li>
<li>Added helper function <tt class="docutils literal"><span class="pre">yas/substr</span></tt> for convenient mirror
transformation.</li>
<li>Make variable <tt class="docutils literal"><span class="pre">yas/registered-snippet</span></tt> properly initialized.</li>
<li>Fixed the overlay error when overlay becomes empty (<a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=49">Issue 49</a> and
<a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=48">Issue 48</a>). This
<li>Fixed the overlay error when overlay becomes empty (<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=49">Issue 49</a> and
<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=48">Issue 48</a>). This
bug has occurred and been fixed earlier, and should not have
happened if we have proper regression test.</li>
<li>Added a workaround for <tt class="docutils literal"><span class="pre">c-electric-</span></tt> serial commands (<a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=27">Issue 27</a>).</li>
<li>Added a workaround for <tt class="docutils literal"><span class="pre">c-electric-</span></tt> serial commands (<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=27">Issue 27</a>).</li>
</ul>
</div>
<div class="section">
<h1><a id="id4" name="id4">0.5.7 / 2008-12-03</a></h1>
<div class="section" id="id4">
<h1>0.5.7 / 2008-12-03</h1>
<ul class="simple">
<li>Fixed <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=28">Issue 28</a> of
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=28">Issue 28</a> of
properly clean up snippet (by joaotavora).</li>
<li>Added a new section &quot;Field-level undo functionality&quot; to correct
<a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=33">Issue 33</a>
<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=33">Issue 33</a>
(by joaotavora).</li>
<li>Added some snippets from users for sql, erlang, scala, html, xml, latex, etc.</li>
<li>Fixed <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=16">Issue 16</a> by adding
<tt class="docutils literal"><span class="pre">$&gt;</span></tt> support. Here's the <a class="reference" href="http://pluskid.lifegoo.com/upload/project/yasnippet/doc/define_snippet.html#indenting">doc for $&gt; indenting</a>.</li>
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=16">Issue 16</a> by adding
<tt class="docutils literal"><span class="pre">$&gt;</span></tt> support. Here's the <a class="reference external" href="http://pluskid.lifegoo.com/upload/project/yasnippet/doc/define_snippet.html#indenting">doc for $&gt; indenting</a>.</li>
</ul>
</div>
<div class="section">
<h1><a id="id5" name="id5">0.5.6 / 2008-08-07</a></h1>
<div class="section" id="id5">
<h1>0.5.6 / 2008-08-07</h1>
<ul class="simple">
<li>Added a buffer local variable <tt class="docutils literal"><span class="pre">yas/dont-activate</span></tt> to turn off
<tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> in some major modes. See <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=29">Issue 29</a>.</li>
<tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> in some major modes. See <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=29">Issue 29</a>.</li>
<li>Make the environment of elisp evaluation more friendly to
<tt class="docutils literal"><span class="pre">(current-column)</span></tt>.</li>
<li>Fixed the regular expression bug in python-mode snippets.</li>
@ -115,8 +137,8 @@ properly clean up snippet (by joaotavora).</li>
property is defined.</li>
</ul>
</div>
<div class="section">
<h1><a id="id6" name="id6">0.5.5 / 2008-05-29</a></h1>
<div class="section" id="id6">
<h1>0.5.5 / 2008-05-29</h1>
<ul class="simple">
<li>Tweak <tt class="docutils literal"><span class="pre">yas/extra-mode-hooks</span></tt> so that it can be more easily
customized.</li>
@ -124,38 +146,38 @@ customized.</li>
modes.</li>
</ul>
</div>
<div class="section">
<h1><a id="id7" name="id7">0.5.4 / 2008-05-15</a></h1>
<div class="section" id="id7">
<h1>0.5.4 / 2008-05-15</h1>
<ul class="simple">
<li>Added <tt class="docutils literal"><span class="pre">ox-mode-hook</span></tt> and <tt class="docutils literal"><span class="pre">python-mode-hook</span></tt> to
<tt class="docutils literal"><span class="pre">yas/extra-mode-hooks</span></tt> to fix the problem YASnippet is not enabled
in those modes.</li>
</ul>
</div>
<div class="section">
<h1><a id="id8" name="id8">0.5.3 / 2008-05-07</a></h1>
<div class="section" id="id8">
<h1>0.5.3 / 2008-05-07</h1>
<ul class="simple">
<li>Fix indent of python-mode snippets.</li>
<li>Fix a bug of dropdown-list: conflicts with color-theme (<a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=23">Issue 23</a>). Thanks
<li>Fix a bug of dropdown-list: conflicts with color-theme (<a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=23">Issue 23</a>). Thanks
Mike.</li>
<li>Fix a bug of condition system.</li>
</ul>
</div>
<div class="section">
<h1><a id="id9" name="id9">0.5.2 / 2008-04-20</a></h1>
<div class="section" id="id9">
<h1>0.5.2 / 2008-04-20</h1>
<ul class="simple">
<li>Fix a bug for comparing string to symbol using <tt class="docutils literal"><span class="pre">string=</span></tt> (which
will fire an error).</li>
</ul>
</div>
<div class="section">
<h1><a id="id10" name="id10">0.5.1 / 2008-04-14</a></h1>
<div class="section" id="id10">
<h1>0.5.1 / 2008-04-14</h1>
<ul class="simple">
<li>Use a beautiful css style in the document.</li>
</ul>
</div>
<div class="section">
<h1><a id="id11" name="id11">0.5.0 / 2008-04-10</a></h1>
<div class="section" id="id11">
<h1>0.5.0 / 2008-04-10</h1>
<ul class="simple">
<li>Integrate with hippie-expand. Just add <tt class="docutils literal"><span class="pre">yas/hippie-try-expand</span></tt> to
<tt class="docutils literal"><span class="pre">hippie-expand-try-functions-list</span></tt>.</li>
@ -169,76 +191,76 @@ problem now.</li>
distribution.</li>
</ul>
</div>
<div class="section">
<h1><a id="id12" name="id12">0.4.5 / 2008-04-07</a></h1>
<div class="section" id="id12">
<h1>0.4.5 / 2008-04-07</h1>
<ul class="simple">
<li>Merge the latest dropdown-list.el.</li>
<li>Add snippets for f90-mode from Li Zhu.</li>
<li>Bug fix: l-safe-expr-p: Lisp nesting exceeds <tt class="docutils literal"><span class="pre">max-lisp-eval-depth</span></tt>
error when several (more than two) snippets overlaps. Thanks
<a class="reference" href="mailto:sunwaybupt&#64;newsmth">sunwaybupt&#64;newsmth</a> for reporting this bug.</li>
<a class="reference external" href="mailto:sunwaybupt&#64;newsmth">sunwaybupt&#64;newsmth</a> for reporting this bug.</li>
</ul>
</div>
<div class="section">
<h1><a id="id13" name="id13">0.4.4 / 2008-03-24</a></h1>
<div class="section" id="id13">
<h1>0.4.4 / 2008-03-24</h1>
<ul class="simple">
<li>Bug fix: dropdown-list.el doesn't recognize [return] properly.</li>
</ul>
</div>
<div class="section">
<h1><a id="id14" name="id14">0.4.3 / 2008-03-23</a></h1>
<div class="section" id="id14">
<h1>0.4.3 / 2008-03-23</h1>
<ul class="simple">
<li>Bug fix: failed to recognize user customized yas/trigger-key.</li>
</ul>
</div>
<div class="section">
<h1><a id="id15" name="id15">0.4.2 / 2008-03-22</a></h1>
<div class="section" id="id15">
<h1>0.4.2 / 2008-03-22</h1>
<ul class="simple">
<li>Make a separate document package for release. Also make document
available online.</li>
</ul>
</div>
<div class="section">
<h1><a id="id16" name="id16">0.4.1 / 2008-03-21</a></h1>
<div class="section" id="id16">
<h1>0.4.1 / 2008-03-21</h1>
<ul class="simple">
<li>Make sure <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt>'s key bindings always take priority to
other minor modes.</li>
</ul>
</div>
<div class="section">
<h1><a id="id17" name="id17">0.4.0 / 2008-03-20</a></h1>
<div class="section" id="id17">
<h1>0.4.0 / 2008-03-20</h1>
<ul class="simple">
<li>Document refinement and released with YASnippet. Most of the Online
wiki document will be deprecated soon.</li>
<li>Powerful condition system added to yasnippet!</li>
<li>Incorporate <tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> and make it default way for
selecting multiple candidates. Thanks to <a class="reference" href="http://groups.google.com/group/smart-snippet/browse_thread/thread/c869158b76addeb3/e7c6372ba457189e">Jaeyoun Chung</a>.</li>
selecting multiple candidates. Thanks to <a class="reference external" href="http://groups.google.com/group/smart-snippet/browse_thread/thread/c869158b76addeb3/e7c6372ba457189e">Jaeyoun Chung</a>.</li>
<li>yas/before-expand-snippet-hook</li>
</ul>
</div>
<div class="section">
<h1><a id="id18" name="id18">0.3.2 / 2008-03-19</a></h1>
<div class="section" id="id18">
<h1>0.3.2 / 2008-03-19</h1>
<ul class="simple">
<li>Enhancement: A better way to define minor-mode. Thanks to Kentaro
Kuribayashi. See <a class="reference" href="https://groups.google.com/group/smart-snippet/browse_thread/thread/65cb3b5583eda887?hl=en">this thread</a>
Kuribayashi. See <a class="reference external" href="https://groups.google.com/group/smart-snippet/browse_thread/thread/65cb3b5583eda887?hl=en">this thread</a>
for more details.</li>
</ul>
</div>
<div class="section">
<h1><a id="id19" name="id19">0.3.1 / 2008-03-17</a></h1>
<div class="section" id="id19">
<h1>0.3.1 / 2008-03-17</h1>
<ul class="simple">
<li>Bug fix: Emacs get confused when a field is deleted. See <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=10">issue 10</a>.</li>
<li>Bug fix: Emacs get confused when a field is deleted. See <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=10">issue 10</a>.</li>
</ul>
</div>
<div class="section">
<h1><a id="id20" name="id20">0.3.0 / 2008-03-16</a></h1>
<div class="section" id="id20">
<h1>0.3.0 / 2008-03-16</h1>
<ul class="simple">
<li>Add a <tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> so that you can do something like
<tt class="docutils literal"><span class="pre">indent-region</span></tt> or <tt class="docutils literal"><span class="pre">fill-region</span></tt> after finish the snippet.</li>
<li>Use minor-mode instead of <tt class="docutils literal"><span class="pre">global-set-key</span></tt> to bind the trigger
key. Now the trigger key and fall-back behavior can be more
flexible. Not constrained to <tt class="docutils literal"><span class="pre">&lt;tab&gt;</span></tt>. Thanks to Trey Jackson. See
this <a class="reference" href="https://groups.google.com/group/smart-snippet/browse_thread/thread/937f32a2a6dea4f2?hl=en">thread</a>
this <a class="reference external" href="https://groups.google.com/group/smart-snippet/browse_thread/thread/937f32a2a6dea4f2?hl=en">thread</a>
for more details.</li>
<li>Now user can customize the popup function for selecting multiple
candidate for the same snippet key.</li>
@ -246,48 +268,48 @@ candidate for the same snippet key.</li>
candidate when in text mode.</li>
</ul>
</div>
<div class="section">
<h1><a id="id21" name="id21">0.2.3 / 2008-03-15</a></h1>
<div class="section" id="id21">
<h1>0.2.3 / 2008-03-15</h1>
<ul class="simple">
<li>Bug in non-window (-nw) mode when there's multiple candidate to
expand. See <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=7">issue 7</a>.</li>
expand. See <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=7">issue 7</a>.</li>
<li>Allow expanding another snippet as long as not currently inside a
field.</li>
</ul>
</div>
<div class="section">
<h1><a id="id22" name="id22">0.2.2 / 2008-03-13</a></h1>
<div class="section" id="id22">
<h1>0.2.2 / 2008-03-13</h1>
<ul class="simple">
<li>Added customized face for fields and mirrors. Better in dark
background. And users can customize it.</li>
</ul>
</div>
<div class="section">
<h1><a id="id23" name="id23">0.2.1 / 2008-03-10</a></h1>
<div class="section" id="id23">
<h1>0.2.1 / 2008-03-10</h1>
<ul class="simple">
<li>Fix the insert-behind problem under both Emacs 22 and Emacs 23.</li>
</ul>
</div>
<div class="section">
<h1><a id="id24" name="id24">0.2.0 / 2008-03-10</a></h1>
<div class="section" id="id24">
<h1>0.2.0 / 2008-03-10</h1>
<ul class="simple">
<li>Use big keymap overlay to detect <tt class="docutils literal"><span class="pre">insert-behind</span></tt> event manually to
avoid sometimes missed hook calls. See <a class="reference" href="http://code.google.com/p/yasnippet/issues/detail?id=3">issue 3</a> for more
avoid sometimes missed hook calls. See <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=3">issue 3</a> for more
details.</li>
<li>Support parent snippet table. Now you can set (for example)
<tt class="docutils literal"><span class="pre">cc-mode</span></tt> as common mode for <tt class="docutils literal"><span class="pre">c++-mode</span></tt>, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and
<tt class="docutils literal"><span class="pre">java-mode</span></tt>. They'll share snippets defined for <tt class="docutils literal"><span class="pre">cc-mode</span></tt>.</li>
</ul>
</div>
<div class="section">
<h1><a id="id25" name="id25">0.1.1 / 2008-03-08</a></h1>
<div class="section" id="id25">
<h1>0.1.1 / 2008-03-08</h1>
<ul class="simple">
<li>Add a rake task to upload to google code.</li>
<li>Use elisp compile-bundle function instead of python scrip</li>
</ul>
</div>
<div class="section">
<h1><a id="id26" name="id26">0.1.0 / 2008-03-07</a></h1>
<div class="section" id="id26">
<h1>0.1.0 / 2008-03-07</h1>
<ul class="simple">
<li>Embedded elisp support.</li>
<li>Fields navigation support.</li>
@ -299,6 +321,12 @@ details.</li>
<li>Load directory support.</li>
<li>Compile bundle support.</li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</body>

900
doc/define_snippet.html
View File

@ -1,900 +0,0 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>How to define a snippet ?</title>
<meta name="author" content="pluskid, joaotavora" />
<meta name="date" content="2009-07-24" />
<link rel="stylesheet" href="styles.css" type="text/css" />
</head>
<body>
<div class="document" id="how-to-define-a-snippet">
<div id="header-region" class="clear-block"></div>
<div id="wrapper">
<div id="container" class="clear-block">
<div id="header">
<div id="logo-floater">
<h1 class="title">How to define a snippet ?</h1>
</div>
<ul class="primary-links">
<li>
<a title="" href="index.html">Home</a>
</li>
<li>
<a title="" href="define_snippet.html">Howto</a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>
</li>
<li>
<a title="" href="changelog.html">ChangeLog</a>
</li>
<li>
<a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
</li>
</ul>
</div>
<div id="center">
<div id="squeeze">
<div class="right-corner">
<div class="left-corner">
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#define-snippets-in-files" id="id8">Define snippets in files</a><ul>
<li><a class="reference internal" href="#directory-hierarchy" id="id9">Directory hierarchy</a></li>
<li><a class="reference internal" href="#file-content" id="id10">File content</a></li>
<li><a class="reference internal" href="#quickly-finding-defining-snippets" id="id11">Quickly finding/defining snippets</a></li>
<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id12">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></li>
<li><a class="reference internal" href="#define-snippets-using-elisp-code" id="id13">Define snippets using elisp code</a><ul>
<li><a class="reference internal" href="#yas-define-snippets" id="id14">yas/define-snippets</a></li>
<li><a class="reference internal" href="#yas-compile-bundle" id="id15">yas/compile-bundle</a></li>
<li><a class="reference internal" href="#yas-define" id="id16">yas/define</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#the-strategy-to-select-a-snippet" id="id17">The strategy to select a snippet</a><ul>
<li><a class="reference internal" href="#finding-the-key" id="id18">Finding the key</a></li>
<li><a class="reference internal" href="#the-condition-system" id="id19">The condition system</a></li>
<li><a class="reference internal" href="#multiple-snippet-with-the-same-key" id="id20">Multiple snippet with the same key</a><ul>
<li><a class="reference internal" href="#use-the-x-window-system" id="id21">Use the X window system</a></li>
<li><a class="reference internal" href="#use-built-in-emacs-selection-methods" id="id22">Use built-in Emacs selection methods</a></li>
<li><a class="reference internal" href="#use-dropdown-menu-el" id="id23">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-trigger-key" id="id24">The Trigger Key</a><ul>
<li><a class="reference internal" href="#the-minor-mode" id="id25">The Minor Mode</a></li>
<li><a class="reference internal" href="#the-fallback" id="id26">The Fallback</a></li>
<li><a class="reference internal" href="#integration-with-hippie-expand" id="id27">Integration with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#other-way-to-select-a-snippet" id="id28">Other way to select a snippet</a><ul>
<li><a class="reference internal" href="#yas-insert-snippet" id="id29"><tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt></a></li>
<li><a class="reference internal" href="#the-menu" id="id30">The Menu</a></li>
<li><a class="reference internal" href="#expanding-from-elisp-code" id="id31">Expanding From Elisp Code</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#the-syntax-of-the-template" id="id32">The Syntax of the Template</a><ul>
<li><a class="reference internal" href="#plain-text" id="id33">Plain Text</a></li>
<li><a class="reference internal" href="#embedded-elisp-code" id="id34">Embedded elisp code</a></li>
<li><a class="reference internal" href="#tab-stop-fields" id="id35">Tab stop fields</a></li>
<li><a class="reference internal" href="#placeholder-fields" id="id36">Placeholder fields</a></li>
<li><a class="reference internal" href="#id4" id="id37">Mirrors</a></li>
<li><a class="reference internal" href="#mirrors-with-transformations" id="id38">Mirrors with transformations</a></li>
<li><a class="reference internal" href="#fields-with-transformations" id="id39">Fields with transformations</a></li>
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id40">Choosing fields value from a list</a></li>
<li><a class="reference internal" href="#nested-placeholder-fields" id="id41">Nested placeholder fields</a></li>
<li><a class="reference internal" href="#indenting" id="id42">Indenting</a></li>
</ul>
</li>
</ul>
</div>
<p>The most convenient way to define snippets for YASnippet is to put
them in a directory arranged by the mode and use
<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> to load them.</p>
<p>However, this might slow down the Emacs startup speed if you have many
snippets. You can use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to define a bunch of
snippets for a perticular mode. But this is hard to maintain! So,
there's a better way: define your snippets in directory and use
<tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> to compile it into a bundle file when you
modified your snippets.</p>
<p>The release bundle of YASnippet is produced by
<tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>. The bundle use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to
define snippets. This avoid the IO and parsing overhead when loading
snippets.</p>
<p>Finally, you can use <tt class="docutils literal"><span class="pre">yas/define</span></tt> to define a single snippet at your
convenience. I ofthen use this to do some testing.</p>
<div class="section" id="define-snippets-in-files">
<h1><a class="toc-backref" href="#id8">Define snippets in files</a></h1>
<div class="section" id="directory-hierarchy">
<h2><a class="toc-backref" href="#id9">Directory hierarchy</a></h2>
<p>Here's the directory hierarchy of the <tt class="docutils literal"><span class="pre">snippets</span></tt> directory comes
with YASnippet:</p>
<div class="highlight"><pre>snippets
`-- text-mode/
|-- cc-mode/
| |-- c++-mode/
| | |-- beginend
| | |-- class
| | `-- using
| |-- c-mode/
| | `-- fopen
| |-- do
| |-- for
| |-- if
| |-- inc
| |-- inc.1
| |-- main
| |-- once
| `-- struct
|-- css-mode/
| |-- background
| |-- background.1
| `-- border
|-- email
|-- html-mode/
| |-- div
| |-- doctype
| |-- doctype.xhml1
| |-- doctype.xhtml1_1
| |-- doctype.xhtml1_strict
| `-- doctype.xhtml1_transitional
|-- objc-mode/
| `-- prop
|-- perl-mode/
| |-- cperl-mode/
| |-- eval
| |-- for
| |-- fore
| |-- if
| |-- ife
| |-- ifee
| |-- sub
| |-- unless
| |-- while
| |-- xfore
| |-- xif
| |-- xunless
| `-- xwhile
|-- python-mode/
| |-- __
| |-- class
| |-- def
| |-- for
| |-- ifmain
| `-- while
|-- rst-mode/
| |-- chapter
| |-- section
| `-- title
|-- ruby-mode/
| |-- #
| |-- =b
| |-- Comp
| |-- all
| |-- am
| |-- any
| |-- app
| |-- bm
| |-- case
| |-- cla
| |-- classify
| |-- cls
| |-- collect
| |-- dee
| |-- deli
| |-- det
| |-- ea
| |-- eac
| |-- eai
| |-- eav
| |-- eawi
| |-- forin
| |-- if
| |-- ife
| |-- inject
| |-- mm
| |-- r
| |-- rb
| |-- reject
| |-- req
| |-- rreq
| |-- rw
| |-- select
| |-- w
| |-- y
| `-- zip
`-- time
</pre></div>
<p>Snippet definitions are put in plain text files. They are arranged by
subdirectories. For example, snippets for <tt class="docutils literal"><span class="pre">c-mode</span></tt> are put in the
<tt class="docutils literal"><span class="pre">c-mode</span></tt> directory.</p>
<p>The parent directory acts as the <em>parent mode</em>. This is the way of
YASnippet to share snippet definitions among different modes. As you
can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and <tt class="docutils literal"><span class="pre">c++-mode</span></tt> share the same parents
<tt class="docutils literal"><span class="pre">cc-mode</span></tt>, while all modes are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>. This can
be also used to as an <em>alias</em> -- <tt class="docutils literal"><span class="pre">cperl-mode</span></tt> is an empty directory
whose parent is <tt class="docutils literal"><span class="pre">perl-mode</span></tt>.</p>
<p>File names act as the snippet trigger key. Note files starting with a
dot (<tt class="docutils literal"><span class="pre">.</span></tt>) are ignored.</p>
</div>
<div class="section" id="file-content">
<h2><a class="toc-backref" href="#id10">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" />
<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 internal" href="#the-menu">The Menu</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>
</ul>
</div>
<div class="section" id="quickly-finding-defining-snippets">
<h2><a class="toc-backref" href="#id11">Quickly finding/defining snippets</a></h2>
<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>
<ul>
<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>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/visit-snippet-file</span></tt></p>
<p>Prompts you for possible snippet expansions like
<tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt>, but instead of expanding it, takes you
directly to the snippet definition's file, if it exists.</p>
</li>
</ul>
</div>
<div class="section" id="using-the-snippet-mode-major-mode">
<h2><a class="toc-backref" href="#id12">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h2>
<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>
<p>Two commands are defined in this mode:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p>
<blockquote>
<p>When editing a snippet, this loads the snippet into the correct
mode and menu. Bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-c</span></tt> by default while in
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p>
</blockquote>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/tryout-snippet</span></tt></p>
<blockquote>
<p>When editing a snippet, this opens a new empty buffer, sets it to
the appropriate major mode and inserts the snippet there, so you
can see what it looks like. This is bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-t</span></tt> while in
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p>
</blockquote>
</li>
</ul>
<p>There are also 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>
<div class="section" id="define-snippets-using-elisp-code">
<h2><a class="toc-backref" href="#id13">Define snippets using elisp code</a></h2>
<p>As I mentioned above, you can define snippets directly by writing
elisp code.</p>
<div class="section" id="yas-define-snippets">
<h3><a class="toc-backref" href="#id14">yas/define-snippets</a></h3>
<p>The basic syntax of <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> is</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">MODE</span> <span style="color: #19177C">SNIPPETS</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">PARENT</span>)
</pre></div>
<p>The parameters are self-descriptive. If you specify a <tt class="docutils literal"><span class="pre">PARENT</span></tt>, then
the snippets of the parents may be shared by <tt class="docutils literal"><span class="pre">MODE</span></tt>. Note if you use
this function several times, the later specified <tt class="docutils literal"><span class="pre">PARENT</span></tt> will
overwrite the original one. However, not specifying a <tt class="docutils literal"><span class="pre">PARENT</span></tt> won't
erase the original parent.</p>
<p>The <tt class="docutils literal"><span class="pre">SNIPPETS</span></tt> parameter is a list of snippet definitions. Each
element should have the following form:</p>
<div class="highlight"><pre>(<span style="color: #19177C">KEY</span> <span style="color: #19177C">TEMPLATE</span> <span style="color: #19177C">NAME</span> <span style="color: #19177C">CONDITION</span> <span style="color: #19177C">GROUP</span>)
</pre></div>
<p>The <tt class="docutils literal"><span class="pre">NAME</span></tt>, <tt class="docutils literal"><span class="pre">CONDITION</span></tt> and <tt class="docutils literal"><span class="pre">GROUP</span></tt> can be omitted if you don't
want to provide one. Here's an example:</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">&#39;c++-mode</span>
<span style="color: #666666">&#39;</span>(
(<span style="color: #BA2121">&quot;using&quot;</span> <span style="color: #BA2121">&quot;using namespace ${std};</span>
<span style="color: #BA2121">$0&quot;</span> <span style="color: #BA2121">&quot;using namespace ... &quot;</span> <span style="color: #880000">nil</span>)
(<span style="color: #BA2121">&quot;class&quot;</span> <span style="color: #BA2121">&quot;class ${1:Name}</span>
<span style="color: #BA2121">{</span>
<span style="color: #BA2121">public:</span>
<span style="color: #BA2121"> $1($2);</span>
<span style="color: #BA2121"> virtual ~$1();</span>
<span style="color: #BA2121">};&quot;</span> <span style="color: #BA2121">&quot;class ... { ... }&quot;</span> <span style="color: #880000">nil</span>)
(<span style="color: #BA2121">&quot;beginend&quot;</span> <span style="color: #BA2121">&quot;${1:v}.begin(), $1.end&quot;</span> <span style="color: #BA2121">&quot;v.begin(), v.end()&quot;</span> <span style="color: #880000">nil</span>)
)
<span style="color: #19177C">&#39;cc-mode</span>)
</pre></div>
<p>The example above is auto-generated code by <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>.</p>
</div>
<div class="section" id="yas-compile-bundle">
<h3><a class="toc-backref" href="#id15">yas/compile-bundle</a></h3>
<p><tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> can be used to parse the snippets from a
directory hierarchy and translate them into the elisp form. The
translated code is faster to load. Further more, the generated bundle
is a stand-alone file not depending on <tt class="docutils literal"><span class="pre">yasnippet.el</span></tt>. The released
bundles of YASnippet are all generated this way.</p>
<p>The basic syntax of <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> is</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/compile-bundle</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">yasnippet</span> <span style="color: #19177C">yasnippet-bundle</span> <span style="color: #19177C">snippet-roots</span> <span style="color: #19177C">code</span> <span style="color: #19177C">dropdown</span>)
</pre></div>
<p>As you can see, all the parameters are optional. The default values
for those parameters are convenient for me to produce the default
release bundle:</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/compile-bundle</span> <span style="color: #BA2121">&quot;yasnippet.el&quot;</span>
<span style="color: #BA2121">&quot;./yasnippet-bundle.el&quot;</span>
<span style="color: #666666">&#39;</span>(<span style="color: #BA2121">&quot;snippets&quot;</span>)
<span style="color: #BA2121">&quot;(yas/initialize)&quot;</span>
<span style="color: #BA2121">&quot;dropdown-list.el&quot;</span>)
</pre></div>
<p>The <tt class="docutils literal"><span class="pre">snippet-roots</span></tt> can be a list of root directories. This is
useful when you have multiple snippet directories (maybe from other
users). The <tt class="docutils literal"><span class="pre">code</span></tt> parameter can be used to specify your own
customization code instead of the default <tt class="docutils literal"><span class="pre">(yas/initialize)</span></tt>. For
example, you can 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> here if
you like.</p>
<p>From release 0.6 you have to specify the <tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> file if
you want it to be a part of the generated bundle.</p>
</div>
<div class="section" id="yas-define">
<h3><a class="toc-backref" href="#id16">yas/define</a></h3>
<p>The basic syntax for <tt class="docutils literal"><span class="pre">yas/define</span></tt> is</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/define</span> <span style="color: #19177C">mode</span> <span style="color: #19177C">key</span> <span style="color: #19177C">template</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">name</span> <span style="color: #B00040">condition</span> <span style="color: #19177C">group</span>)
</pre></div>
<p>This is only a syntax sugar for</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">mode</span>
(<span style="color: #008000">list</span> (<span style="color: #008000">list</span> <span style="color: #19177C">key</span> <span style="color: #19177C">template</span> <span style="color: #19177C">name</span> <span style="color: #B00040">condition</span> <span style="color: #19177C">group</span>)))
</pre></div>
</div>
</div>
</div>
<div class="section" id="the-strategy-to-select-a-snippet">
<h1><a class="toc-backref" href="#id17">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="#id18">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>
<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
following thing until found one:</p>
<ul class="simple">
<li>a word.</li>
<li>a symbol. In lisp, <tt class="docutils literal"><span class="pre">-</span></tt> and <tt class="docutils literal"><span class="pre">?</span></tt> can all be part of a symbol.</li>
<li>a sequence of characters of either word, symbol or punctuation.</li>
<li>a sequence of characters of non-whitespace characters.</li>
</ul>
<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="#id19">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="#id20">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="#id21">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="#id22">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="#id23">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> <a class="footnote-reference" href="#id5" id="id1">[1]</a> 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="#id24">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="#id25">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> <a class="footnote-reference" href="#id6" id="id2">[2]</a> 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="#id26">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="#id27">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="#id28">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="#id29"><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="the-menu">
<h3><a class="toc-backref" href="#id30">The Menu</a></h3>
<p>YASnippet will setup a menu just after the <em>Buffers</em> Menu in the
menubar. The snippets for all <em>real</em> modes are listed there under the
menu. You can select a snippet from the menu to expand it. Since you
select manually from the menu, you can expand any snippet. For
example, you can expand a snippet defined for <tt class="docutils literal"><span class="pre">python-mode</span></tt> in a
<tt class="docutils literal"><span class="pre">c-mode</span></tt> buffer by selecting it from the menu:</p>
<img align="right" alt="images/menubar.png" class="align-right" src="images/menubar.png" />
<ul class="simple">
<li>Condition system is ignored since you select to expand it
explicitly.</li>
<li>There will be no muliple candidates since they are listed in the
menu as different items.</li>
</ul>
<p>This can be convenient sometimes. However, if you don't like the
menubar of Emacs and never use it. You can tell YASnippet don't boring
to build a menu by setting <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to nil.</p>
<p>Another thing to note is that only <em>real</em> modes are listed under the
menu. As you know, common snippets can be shared by making up a
<em>virtual</em> parent mode. It's too bad if the menu is floored by those
<em>virtual</em> modes. So YASnippet only show menus for those <em>real</em>
modes. But the snippets fo the <em>virtual</em> modes can still be accessed
through the <tt class="docutils literal"><span class="pre">parent</span></tt> submenu of some <em>real</em> mode.</p>
<p>YASnippet use a simple way to check whether a mode is <em>real</em> or
<em>virtual</em>: <tt class="docutils literal"><span class="pre">(fboundp</span> <span class="pre">mode)</span></tt>. For example, the symbol <tt class="docutils literal"><span class="pre">c-mode</span></tt> is
bound to a function while <tt class="docutils literal"><span class="pre">cc-mode</span></tt> is not. But this is not enough,
some modes aren't part of Emacs, and maybe when initializing
YASnippet, those modes haven't been initialized. So YASnippet also
maintain a list of known modes (<tt class="docutils literal"><span class="pre">yas/known-modes</span></tt>). You can add item
to that list if you need.</p>
</div>
<div class="section" id="expanding-from-elisp-code">
<h3><a class="toc-backref" href="#id31">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>
<div class="section" id="the-syntax-of-the-template">
<h1><a class="toc-backref" href="#id32">The Syntax of the Template</a></h1>
<p>The syntax of the snippet template is simple but powerful, very
similar to TextMate's.</p>
<div class="section" id="plain-text">
<h2><a class="toc-backref" href="#id33">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">
<h2><a class="toc-backref" href="#id34">Embedded elisp code</a></h2>
<p>Elisp 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
example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard dynamically:</p>
<div class="highlight"><pre>#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
#define $1
$0
#endif /* $1 */
</pre></div>
<p>From version 0.6.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
can therefore define a snippet like:</p>
<div class="highlight"><pre>for ($1;$2;$3) {
`yas/selected-text`$0
}
</pre></div>
<p>to &quot;wrap&quot; the selected region inside your recently inserted
snippet. Alternatively, you can also customize the variable
<tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt> which will do this automatically.</p>
</div>
<div class="section" id="tab-stop-fields">
<h2><a class="toc-backref" href="#id35">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="#id7" id="id3">[3]</a>. They are written by <tt class="docutils literal"><span class="pre">$</span></tt> followed with a
number. <tt class="docutils literal"><span class="pre">$0</span></tt> has the special meaning of the <em>exit point</em> of a
snippet. That is the last place to go when you've traveled all the
fields. Here's a typical example:</p>
<div class="highlight"><pre>&lt;div$1&gt;
$0
&lt;/div&gt;
</pre></div>
</div>
<div class="section" id="placeholder-fields">
<h2><a class="toc-backref" href="#id36">Placeholder fields</a></h2>
<p>Tab stops can have default values -- a.k.a placeholders. The syntax is
like this:</p>
<div class="highlight"><pre>${N:default value}
</pre></div>
<p>They acts as the default value for a tab stop. But when you firstly
type at a tab stop, the default value will be replaced by your
typing. The number can be omitted if you don't want to create
<a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p>
</div>
<div class="section" id="id4">
<span id="mirrors"></span><h2><a class="toc-backref" href="#id37">Mirrors</a></h2>
<p>We refer the tab stops with placeholders as a <em>field</em>. A field can have
mirrors. Its mirrors will get updated when you change the text of a
field. Here's an example:</p>
<div class="highlight"><pre>\begin{${1:enumerate}}
$0
\end{$1}
</pre></div>
<p>When you type <tt class="docutils literal"><span class="pre">&quot;document&quot;</span></tt> at <tt class="docutils literal"><span class="pre">${1:enumerate}</span></tt>, the word
<tt class="docutils literal"><span class="pre">&quot;document&quot;</span></tt> will also be inserted at <tt class="docutils literal"><span class="pre">\end{$1}</span></tt>. The best
explanation is to see the screencast(<a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">YouTube</a> or <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">avi video</a>).</p>
<p>The tab stops with the same number to the field act as its mirrors. If
none of the tab stops has an initial value, the first one is selected
as the field and others mirrors.</p>
</div>
<div class="section" id="mirrors-with-transformations">
<span id="transformations"></span><h2><a class="toc-backref" href="#id38">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
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}
{
return $2;
}
- (void)set${2:$(capitalize text)}:($1)aValue
{
[$2 autorelease];
$2 = [aValue retain];
}
$0
</pre></div>
<p>Look at <tt class="docutils literal"><span class="pre">${2:$(capitalize</span> <span class="pre">text)}</span></tt>, it is a transformation instead of
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
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 &quot;===&quot; below and above. The &quot;===&quot;
should be at least as long as the text. So</p>
<div class="highlight"><pre>=====
Title
=====
</pre></div>
<p>is a valid title but</p>
<div class="highlight"><pre>===
Title
===
</pre></div>
<p>is not. Here's an snippet for rst title:</p>
<div class="highlight"><pre>${1:$(make-string (string-width text) ?\=)}
${1:Title}
${1:$(make-string (string-width text) ?\=)}
$0
</pre></div>
<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">[1]</a></td><td>With some minor change, mainly for fixing some trivial bugs.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id6" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></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="id7" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>Of course, this can be customized.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="fields-with-transformations">
<h2><a class="toc-backref" href="#id39">Fields with transformations</a></h2>
<p>From version 0.6 on, you can also have lisp transformation inside
fields. These work mostly mirror transformations but are evaluated
when you first enter the field, after each change you make to the
field and also just before you exit the field.</p>
<p>The syntax is also a tiny bit different, so that the parser can
distinguish between fields and mirrors. In the following example</p>
<div class="highlight"><pre>#define &quot;${1:mydefine$(upcase yas/text)}&quot;
</pre></div>
<p><tt class="docutils literal"><span class="pre">mydefine</span></tt> gets automatically upcased to <tt class="docutils literal"><span class="pre">MYDEFINE</span></tt> once you enter
the field. As you type text, it gets filtered through the
transformation every time.</p>
<p>Note that 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
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 &quot;${1:$$(upcase yas/text)}&quot;
</pre></div>
<p>Please note that as soon as a transformation takes place, it changes
the value of the field and sets it its internal modification state to
<tt class="docutils literal"><span class="pre">true</span></tt>. As a consequence, the auto-deletion behaviour of normal
fields does not take place. This is by design.</p>
</div>
<div class="section" id="choosing-fields-value-from-a-list">
<h2><a class="toc-backref" href="#id40">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
feature you can place a transformation in the primary field that lets
you select default values for it.</p>
<p>The <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> does this work for you. For example:</p>
<div class="highlight"><pre>&lt;div align=&quot;${2:$$(yas/choose-value &#39;(&quot;right&quot; &quot;center&quot; &quot;left&quot;))}&quot;&gt;
$0
&lt;/div&gt;
</pre></div>
<p>See the definition of <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> to see how it was written
using the two variables. Also check out <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> for
another neat trick.</p>
</div>
<div class="section" id="nested-placeholder-fields">
<h2><a class="toc-backref" href="#id41">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>&lt;div${1: id=&quot;${2:some_id}&quot;}&gt;$0&lt;/div&gt;
</pre></div>
<p>This allows you to choose if you want to give this <tt class="docutils literal"><span class="pre">div</span></tt> an <tt class="docutils literal"><span class="pre">id</span></tt>
attribute. If you tab forward after expanding it will let you change
&quot;some_id&quot; to whatever you like. Alternatively, you can just press
<tt class="docutils literal"><span class="pre">C-d</span></tt> (which executes <tt class="docutils literal"><span class="pre">yas/skip-and-clear-or-delete-char</span></tt>) and go
straight to the exit marker.</p>
<p>By the way, <tt class="docutils literal"><span class="pre">C-d</span></tt> will only clear the field if you cursor is at the
beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it
performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p>
</div>
<div class="section" id="indenting">
<h2><a class="toc-backref" href="#id42">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>
</div>
</div>
</div>
</div>
</div>
</body>
</html>

963
doc/define_snippet.rst
View File

@ -1,963 +0,0 @@
=========================
How to define a snippet ?
=========================
:Author: pluskid, joaotavora
:Contact: pluskid@gmail.com
:Date: 2009-07-24
.. contents::
The most convenient way to define snippets for YASnippet is to put
them in a directory arranged by the mode and use
``yas/load-directory`` to load them.
However, this might slow down the Emacs startup speed if you have many
snippets. You can use ``yas/define-snippets`` to define a bunch of
snippets for a perticular mode. But this is hard to maintain! So,
there's a better way: define your snippets in directory and use
``yas/compile-bundle`` to compile it into a bundle file when you
modified your snippets.
The release bundle of YASnippet is produced by
``yas/compile-bundle``. The bundle use ``yas/define-snippets`` to
define snippets. This avoid the IO and parsing overhead when loading
snippets.
Finally, you can use ``yas/define`` to define a single snippet at your
convenience. I ofthen use this to do some testing.
Define snippets in files
========================
Directory hierarchy
-------------------
Here's the directory hierarchy of the ``snippets`` directory comes
with YASnippet:
.. sourcecode:: text
snippets
`-- text-mode/
|-- cc-mode/
| |-- c++-mode/
| | |-- beginend
| | |-- class
| | `-- using
| |-- c-mode/
| | `-- fopen
| |-- do
| |-- for
| |-- if
| |-- inc
| |-- inc.1
| |-- main
| |-- once
| `-- struct
|-- css-mode/
| |-- background
| |-- background.1
| `-- border
|-- email
|-- html-mode/
| |-- div
| |-- doctype
| |-- doctype.xhml1
| |-- doctype.xhtml1_1
| |-- doctype.xhtml1_strict
| `-- doctype.xhtml1_transitional
|-- objc-mode/
| `-- prop
|-- perl-mode/
| |-- cperl-mode/
| |-- eval
| |-- for
| |-- fore
| |-- if
| |-- ife
| |-- ifee
| |-- sub
| |-- unless
| |-- while
| |-- xfore
| |-- xif
| |-- xunless
| `-- xwhile
|-- python-mode/
| |-- __
| |-- class
| |-- def
| |-- for
| |-- ifmain
| `-- while
|-- rst-mode/
| |-- chapter
| |-- section
| `-- title
|-- ruby-mode/
| |-- #
| |-- =b
| |-- Comp
| |-- all
| |-- am
| |-- any
| |-- app
| |-- bm
| |-- case
| |-- cla
| |-- classify
| |-- cls
| |-- collect
| |-- dee
| |-- deli
| |-- det
| |-- ea
| |-- eac
| |-- eai
| |-- eav
| |-- eawi
| |-- forin
| |-- if
| |-- ife
| |-- inject
| |-- mm
| |-- r
| |-- rb
| |-- reject
| |-- req
| |-- rreq
| |-- rw
| |-- select
| |-- w
| |-- y
| `-- zip
`-- time
Snippet definitions are put in plain text files. They are arranged by
subdirectories. For example, snippets for ``c-mode`` are put in the
``c-mode`` directory.
The parent directory acts as the *parent mode*. This is the way of
YASnippet to share snippet definitions among different modes. As you
can see above, ``c-mode`` and ``c++-mode`` share the same parents
``cc-mode``, while all modes are derived from ``text-mode``. This can
be also used to as an *alias* -- ``cperl-mode`` is an empty directory
whose parent is ``perl-mode``.
File names act as the snippet trigger key. Note files starting with a
dot (``.``) are ignored.
File content
------------
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.
Generally speaking, if the file contains a line of ``# --``, 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.
Here's a typical example:
.. sourcecode:: text
#contributor : pluskid <pluskid@gmail.com>
#name : __...__
# --
__${init}__
Meta data are specified in the syntax of
.. sourcecode:: text
#data-name : data value
Any other text above ``# --`` is considered as comment and
ignored. Here's a list of currently supported meta data:
.. image:: images/group.png
:align: right
* ``name``: 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.
* ``contributor``: The contributor of the snippet.
* ``condition``: 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.
* ``key``: The key to expand the snippet. Sometimes the key of a
snippet is non-ASCII or not valid filename (e.g. contains
``/``). One can then define the ``key`` property which will
overwrite the filename as the key to expand the snippet.
* ``group``: 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. ``group``
property only affect menu construction (See `The Menu`_). Refer to
the snippets for ``ruby-mode`` for examples. Group can also be
nested, e.g. ``control structure.loops`` tells that the snippet is
under the ``loops`` group which is under the ``control structure``
group.
Quickly finding/defining snippets
---------------------------------
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
``snippet-mode`` (see ahead)
* ``M-x yas/find-snippets``
Lets you find the snippet file in the directory the snippet was
loaded from (if it exists) like ``find-file-other-window``.
* ``M-x yas/visit-snippet-file``
Prompts you for possible snippet expansions like
``yas/insert-snippet``, but instead of expanding it, takes you
directly to the snippet definition's file, if it exists.
Using the ``snippet-mode`` major mode
-------------------------------------
From version 0.6 upwards there is a major mode ``snippet-mode`` to
edit snippets. You can set the buffer to this mode with ``M-x
snippet-mode``. It provides reasonably useful syntax highlighting.
Two commands are defined in this mode:
* ``M-x yas/load-snippet-buffer``
When editing a snippet, this loads the snippet into the correct
mode and menu. Bound to ``C-c C-c`` by default while in
``snippet-mode``.
* ``M-x yas/tryout-snippet``
When editing a snippet, this opens a new empty buffer, sets it to
the appropriate major mode and inserts the snippet there, so you
can see what it looks like. This is bound to ``C-c C-t`` while in
``snippet-mode``.
There are also snippets for making snippets: ``vars``, ``field`` and
``mirror``.
Define snippets using elisp code
--------------------------------
As I mentioned above, you can define snippets directly by writing
elisp code.
yas/define-snippets
~~~~~~~~~~~~~~~~~~~
The basic syntax of ``yas/define-snippets`` is
.. sourcecode:: common-lisp
(yas/define-snippets MODE SNIPPETS &optional PARENT)
The parameters are self-descriptive. If you specify a ``PARENT``, then
the snippets of the parents may be shared by ``MODE``. Note if you use
this function several times, the later specified ``PARENT`` will
overwrite the original one. However, not specifying a ``PARENT`` won't
erase the original parent.
The ``SNIPPETS`` parameter is a list of snippet definitions. Each
element should have the following form:
.. sourcecode:: common-lisp
(KEY TEMPLATE NAME CONDITION GROUP)
The ``NAME``, ``CONDITION`` and ``GROUP`` can be omitted if you don't
want to provide one. Here's an example:
.. sourcecode:: common-lisp
(yas/define-snippets 'c++-mode
'(
("using" "using namespace ${std};
$0" "using namespace ... " nil)
("class" "class ${1:Name}
{
public:
$1($2);
virtual ~$1();
};" "class ... { ... }" nil)
("beginend" "${1:v}.begin(), $1.end" "v.begin(), v.end()" nil)
)
'cc-mode)
The example above is auto-generated code by ``yas/compile-bundle``.
yas/compile-bundle
~~~~~~~~~~~~~~~~~~
``yas/compile-bundle`` can be used to parse the snippets from a
directory hierarchy and translate them into the elisp form. The
translated code is faster to load. Further more, the generated bundle
is a stand-alone file not depending on ``yasnippet.el``. The released
bundles of YASnippet are all generated this way.
The basic syntax of ``yas/compile-bundle`` is
.. sourcecode:: common-lisp
(yas/compile-bundle &optional yasnippet yasnippet-bundle snippet-roots code dropdown)
As you can see, all the parameters are optional. The default values
for those parameters are convenient for me to produce the default
release bundle:
.. sourcecode:: common-lisp
(yas/compile-bundle "yasnippet.el"
"./yasnippet-bundle.el"
'("snippets")
"(yas/initialize)"
"dropdown-list.el")
The ``snippet-roots`` can be a list of root directories. This is
useful when you have multiple snippet directories (maybe from other
users). The ``code`` parameter can be used to specify your own
customization code instead of the default ``(yas/initialize)``. For
example, you can set ``yas/trigger-key`` to ``(kbd "SPC")`` here if
you like.
From release 0.6 you have to specify the ``dropdown-list.el`` file if
you want it to be a part of the generated bundle.
yas/define
~~~~~~~~~~
The basic syntax for ``yas/define`` is
.. sourcecode:: common-lisp
(yas/define mode key template &optional name condition group)
This is only a syntax sugar for
.. sourcecode:: common-lisp
(yas/define-snippets mode
(list (list key template name condition group)))
The strategy to select a snippet
================================
When user press the ``yas/trigger-key``, YASnippet try to find a
proper snippet to expand. The strategy to find such a snippet is
explained here.
Finding the key
---------------
YASnippet search from current point backward trying to find the
snippet to be expanded. The default searching strategy is quite
powerful. For example, in ``c-mode``, ``"bar"``, ``"foo_bar"``,
``"#foo_bar"`` can all be recognized as a template key. Further more,
the searching is in that order. In other words, if ``"bar"`` is found
to be a key to some *valid* snippet, then ``"foo_bar"`` and
``"#foobar"`` won't be searched.
However, this strategy can also be customized easily from the
``yas/key-syntaxes`` variable. It is a list of syntax rules, the
default value is ``("w" "w_" "w_." "^ ")``. Which means search the
following thing until found one:
* a word.
* a symbol. In lisp, ``-`` and ``?`` can all be part of a symbol.
* a sequence of characters of either word, symbol or punctuation.
* a sequence of characters of non-whitespace characters.
But you'd better keep the default value unless you understand what
Emacs's syntax rule mean.
The condition system
--------------------
I write forked snippet.el to make the smart-snippet.el. I call it
*smart*-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.
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
Consider this scenario: you are an old Emacs hacker. You like the
abbrev-way and set ``yas/trigger-key`` to ``(kbd "SPC")``. However,
you don't want ``if`` to be expanded as a snippet when you are typing
in a comment block or a string (e.g. in ``python-mode``).
It's OK, just specify the condition for ``if`` to be ``(not
(python-in-string/comment))``. But how about ``while``, ``for``,
etc. ? Writing the same condition for all the snippets is just
boring. So YASnippet introduce a buffer local variable
``yas/buffer-local-condition``. You can set this variable to ``(not
(python-in-string/comment))`` in ``python-mode-hook``. There's no way
to do this in smart-snippet.el!
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:
* If ``yas/buffer-local-condition`` evaluate to nil, snippet won't be
expanded.
* If it evaluate to the a cons cell where the ``car`` is the symbol
``require-snippet-condition`` and the ``cdr`` is a symbol (let's
call it ``requirement``):
* If the snippet has no condition, then it won't be expanded.
* If the snippet has a condition but evaluate to nil or error
occured during evaluation, it won't be expanded.
* If the snippet has a condition that evaluate to non-nil (let's
call it ``result``):
* If ``requirement`` is ``t``, the snippet is ready to be
expanded.
* If ``requirement`` is ``eq`` to ``result``, the snippet is ready
to be expanded.
* Otherwise the snippet won't be expanded.
* If it evaluate to other non-nil value:
* If the snippet has no condition, or has a condition that evaluate
to non-nil, it is ready to be expanded.
* Otherwise, it won't be expanded.
So set ``yas/buffer-local-condition`` like this
.. sourcecode:: common-lisp
(add-hook 'python-mode-hook
'(lambda ()
(setq yas/buffer-local-condition
'(if (python-in-string/comment)
'(require-snippet-condition . force-in-comment)
t))))
And specify the condition for a snippet that you're going to expand in
comment to be evaluated to the symbol ``force-in-comment``. Then it
can be expanded as you expected, while other snippets like ``if``
still can't expanded in comment.
Multiple snippet with the same key
----------------------------------
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 *postfix* to the
key.
In general, the *extension* (consider a file name) is *ignored* when
defining a snippet. So ``def``, ``def.1`` and ``def.mine`` will all be
valid candidates when the key is ``def``.
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:
From version 0.6 of YASnippet this has changed significantly. A new
customization variable, called ``yas/prompt-functions`` defines your
preferred method of being prompted for snippets.
You can customize it with ``M-x customize-variable RET
yas/prompt-functions RET``. Alternatively you can put in your
emacs-file:
.. sourcecode:: common-lisp
(setq yas/prompt-functions '(yas/x-prompt yas/dropdown-prompt))
Currently there are some alternatives solution with YASnippet.
.. image:: images/popup-menu.png
:align: right
Use the X window system
~~~~~~~~~~~~~~~~~~~~~~~
The function ``yas/x-prompt`` 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:
* It usually looks beautiful. E.g. when you compile Emacs with gtk
support, this menu will be rendered with your gtk theme.
* Emacs have little control over it. E.g. you can't use ``C-n``,
``C-p`` to navigate.
* This function can't be used when in a terminal.
Use built-in Emacs selection methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use functions ``yas/completing-prompt`` for the classic emacs
completion method or ``yas/ido-prompt`` for a much nicer looking
method. The best way is to try it. This works in a terminal.
.. image:: images/idrop-menu.png
:align: center
Use ``dropdown-menu.el``
~~~~~~~~~~~~~~~~~~~~~~~~
The function ``yas/dropdown-prompt`` can also be placed in the
``yas/prompt-functions`` list.
.. image:: images/dropdown-menu.png
:align: right
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 ``dropdown-menu.el``,
I say wow! It's wonderful!
* It works in both window system and terminal.
* It is customizable, you can use ``C-n``, ``C-p`` to navigate, ``q``
to quite and even press ``6`` as a shortcut to select the 6th
candidate.
So I added ``yas/dropdown-list-popup-for-template`` to support
``dropdown-list.el``. And upload ``dropdown-list.el`` to YASnippet
hompage for an optional download (since Jaeyoun didn't provide a URL).
Then finally, in 0.4.0, I included a copy of the content of
``dropdown-list.el`` [1]_ in ``yasnippet.el`` and made it the default
way for selecting multiple candidates.
However, the original functions are still there, you can still use this
.. sourcecode:: common-lisp
(setq yas/window-system-popup-function
'yas/x-popup-menu-for-template)
if you prefer a *modern* UI. :)
The Trigger Key
---------------
YASnippet is implemented as a minor-mode (``yas/minor-mode``). The
trigger key ``yas/trigger-key`` is defined in ``yas/minor-mode-map``
to call ``yas/expand`` to try to expand a snippet.
The Minor Mode
~~~~~~~~~~~~~~
.. image:: images/minor-mode-indicator.png
:align: left
When ``yas/minor-mode`` is enabled, the trigger key will take
effect. The default key is ``(kbd "TAB")``, however, you can freely
set it to some other key.
In version 0.5, YASnippet add a hook to
``after-change-major-mode-hook`` to enable ``yas/minor-mode`` [2]_ 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
``yas/extra-mode-hooks`` to let YASnippet do it for you:
.. sourcecode:: common-lisp
(require 'yasnippet)
(add-to-list 'yas/extra-mode-hooks
'ruby-mode-hook)
(yas/initialize)
Note that **should** be put after ``(require 'yasnippet)`` and before
``(yas/initialize)``. Further more, you may report it to me, I'll add
that to the default value.
In version 0.6, just use ``yas/global-mode`` to enable YASnippet in
all major modes. Or put ``yas/minor-mode-on`` in that modes hook. See
the `FAQ <faq.html>`_.
The Fallback
~~~~~~~~~~~~
If ``yas/expand`` 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 ``yas/trigger-key``. 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.
However, you can change this behavior by customizing the
``yas/fallback-behavior`` variable. If you set this variable to
``'return-nil``, it will return ``nil`` instead of trying to call the
*original* command when no snippet is found. This is useful when you
would like YASnippet to work with other extensions,
e.g. ``hippie-expand``. I'm also glad to tell you that integration
with ``hippie-expand`` is already included in YASnippet.
Integration with ``hippie-expand``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To integrate with ``hippie-expand``, just put
``yas/hippie-try-expand`` in
``hippie-expand-try-functions-list``. Personally I would like to put
in front of the list, but it can be put anywhere you prefer.
Other way to select a snippet
-----------------------------
When you use the trigger key (so ``yas/expand``) to expand a snippet,
the key for the snippet is deleted before the template for the snippet
is inserted.
However, there're other ways to insert a snippet.
``yas/insert-snippet``
~~~~~~~~~~~~~~~~~~~~~~
The command ``M-x yas/insert-snippet`` lets you insert snippets at
point *for you current major mode*. It prompts you for the snippet
key first, and then for a snippet template if more than one template
exists for the same key.
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
``C-u``.
The prompting methods used are again controlled by
``yas/prompt-functions``.
The Menu
~~~~~~~~
YASnippet will setup a menu just after the *Buffers* Menu in the
menubar. The snippets for all *real* modes are listed there under the
menu. You can select a snippet from the menu to expand it. Since you
select manually from the menu, you can expand any snippet. For
example, you can expand a snippet defined for ``python-mode`` in a
``c-mode`` buffer by selecting it from the menu:
.. image:: images/menubar.png
:align: right
* Condition system is ignored since you select to expand it
explicitly.
* There will be no muliple candidates since they are listed in the
menu as different items.
This can be convenient sometimes. However, if you don't like the
menubar of Emacs and never use it. You can tell YASnippet don't boring
to build a menu by setting ``yas/use-menu`` to nil.
Another thing to note is that only *real* modes are listed under the
menu. As you know, common snippets can be shared by making up a
*virtual* parent mode. It's too bad if the menu is floored by those
*virtual* modes. So YASnippet only show menus for those *real*
modes. But the snippets fo the *virtual* modes can still be accessed
through the ``parent`` submenu of some *real* mode.
YASnippet use a simple way to check whether a mode is *real* or
*virtual*: ``(fboundp mode)``. For example, the symbol ``c-mode`` is
bound to a function while ``cc-mode`` is not. But this is not enough,
some modes aren't part of Emacs, and maybe when initializing
YASnippet, those modes haven't been initialized. So YASnippet also
maintain a list of known modes (``yas/known-modes``). You can add item
to that list if you need.
Expanding From Elisp Code
~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes you might want to expand a snippet directly by calling a
functin from elisp code. You should call ``yas/expand-snippet``
instead of ``yas/expand`` in this case.
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:
.. sourcecode:: common-lisp
(yas/expand-snippet (point) (point) template)
Where ``template`` 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 ``yas/expand`` 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 ``(point)``
is fine. Note only ``(point)`` will be fine because the 1st parameter
also indicate where to insert and expand the ``template``.
The Syntax of the Template
==========================
The syntax of the snippet template is simple but powerful, very
similar to TextMate's.
Plain Text
----------
Arbitrary text can be included as the content of a template. They are
usually interpreted as plain text, except ``$`` and `````. You need to
use ``\`` to escape them: ``\$`` and ``\```. The ``\`` itself may also
needed to be escaped as ``\\`` sometimes.
Embedded elisp code
-------------------
Elisp code can be embedded inside the template. They are written
inside back-quotes (`````):
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
example for ``c-mode`` to calculate the header file guard dynamically:
.. sourcecode:: text
#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
#define $1
$0
#endif /* $1 */
From version 0.6.0, snippets expansions are run with some special
emacs-lisp variables bound. One of this is ``yas/selected-text``. You
can therefore define a snippet like:
.. sourcecode:: text
for ($1;$2;$3) {
`yas/selected-text`$0
}
to "wrap" the selected region inside your recently inserted
snippet. Alternatively, you can also customize the variable
``yas/wrap-around-region`` to ``t`` which will do this automatically.
Tab stop fields
---------------
Tab stops are fields that you can navigate back and forth by ``TAB``
and ``S-TAB`` [3]_. They are written by ``$`` followed with a
number. ``$0`` has the special meaning of the *exit point* of a
snippet. That is the last place to go when you've traveled all the
fields. Here's a typical example:
.. sourcecode:: text
<div$1>
$0
</div>
Placeholder fields
------------------
Tab stops can have default values -- a.k.a placeholders. The syntax is
like this:
.. sourcecode:: text
${N:default value}
They acts as the default value for a tab stop. But when you firstly
type at a tab stop, the default value will be replaced by your
typing. The number can be omitted if you don't want to create
`mirrors`_ or `transformations`_ for this field.
.. _mirrors:
Mirrors
-------
We refer the tab stops with placeholders as a *field*. A field can have
mirrors. Its mirrors will get updated when you change the text of a
field. Here's an example:
.. sourcecode:: text
\begin{${1:enumerate}}
$0
\end{$1}
When you type ``"document"`` at ``${1:enumerate}``, the word
``"document"`` will also be inserted at ``\end{$1}``. The best
explanation is to see the screencast(`YouTube
<http://www.youtube.com/watch?v=vOj7btx3ATg>`_ or `avi video
<http://yasnippet.googlecode.com/files/yasnippet.avi>`_).
The tab stops with the same number to the field act as its mirrors. If
none of the tab stops has an initial value, the first one is selected
as the field and others mirrors.
.. _transformations:
Mirrors with transformations
----------------------------
If the default value of a field starts with ``$``, 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
when the variable text is bind to the inputted text of the
field. Here's an example for Objective-C:
.. sourcecode:: text
- (${1:id})${2:foo}
{
return $2;
}
- (void)set${2:$(capitalize text)}:($1)aValue
{
[$2 autorelease];
$2 = [aValue retain];
}
$0
Look at ``${2:$(capitalize text)}``, it is a transformation instead of
a placeholder. The actual placeholder is at the first line:
``${2:foo}``. When you type text in ``${2:foo}``, 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
the screencast.
Another example is for ``rst-mode``. In reStructuredText, the document
title can be some text surrounded by "===" below and above. The "==="
should be at least as long as the text. So
.. sourcecode:: text
=====
Title
=====
is a valid title but
.. sourcecode:: text
===
Title
===
is not. Here's an snippet for rst title:
.. sourcecode:: text
${1:$(make-string (string-width text) ?\=)}
${1:Title}
${1:$(make-string (string-width text) ?\=)}
$0
.. [1] With some minor change, mainly for fixing some trivial bugs.
.. [2] This is done when you call ``yas/initialize``.
.. [3] Of course, this can be customized.
Fields with transformations
---------------------------
From version 0.6 on, you can also have lisp transformation inside
fields. These work mostly mirror transformations but are evaluated
when you first enter the field, after each change you make to the
field and also just before you exit the field.
The syntax is also a tiny bit different, so that the parser can
distinguish between fields and mirrors. In the following example
.. sourcecode:: text
#define "${1:mydefine$(upcase yas/text)}"
``mydefine`` gets automatically upcased to ``MYDEFINE`` once you enter
the field. As you type text, it gets filtered through the
transformation every time.
Note that this is differentiated from a mirror with a transformation
by the existance of extra text between the ``:`` and the
transformation's ``$``. If you don't want this extra-text, you can use
two ``$``'s instead.
.. sourcecode:: text
#define "${1:$$(upcase yas/text)}"
Please note that as soon as a transformation takes place, it changes
the value of the field and sets it its internal modification state to
``true``. As a consequence, the auto-deletion behaviour of normal
fields does not take place. This is by design.
Choosing fields value from a list
---------------------------------
As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
``yas/field-modified-p`` and ``yas/moving-away-p``. Because of this
feature you can place a transformation in the primary field that lets
you select default values for it.
The ``yas/choose-value`` does this work for you. For example:
.. sourcecode:: text
<div align="${2:$$(yas/choose-value '("right" "center" "left"))}">
$0
</div>
See the definition of ``yas/choose-value`` to see how it was written
using the two variables. Also check out ``yas/verify-value`` for
another neat trick.
Nested placeholder fields
-------------------------
From version 0.6 on, you can also have nested placeholders of the type:
.. sourcecode:: text
<div${1: id="${2:some_id}"}>$0</div>
This allows you to choose if you want to give this ``div`` an ``id``
attribute. If you tab forward after expanding it will let you change
"some_id" to whatever you like. Alternatively, you can just press
``C-d`` (which executes ``yas/skip-and-clear-or-delete-char``) and go
straight to the exit marker.
By the way, ``C-d`` will only clear the field if you cursor is at the
beginning of the field *and* it hasn't been changed yet. Otherwise, it
performs the normal Emacs ``delete-char`` command.
Indenting
---------
Many people miss the indenting feature of smart-snippet: when you
place a ``$>`` in your snippet, an ``(indent-according-to-mode)`` 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.
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 ``indent-according-to-mode`` will break
the overlays created by YASnippet.
However, since many people asked for this feature, I finally added
this to YASnippet. Here's an example of the usage:
.. sourcecode:: text
for (${int i = 0}; ${i < 10}; ${++i})
{$>
$0$>
}$>
In 0.6.0 You should **not** need to use this feature although it's
supported for backward compatibility. Just set ``yas/indent-line`` to
``'auto``.

10
doc/faq.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Frequently Asked Questions</title>
<meta name="author" content="pluskid" />
<meta name="date" content="2008-03-20" />
@ -23,7 +23,13 @@
<a title="" href="index.html">Home</a>
</li>
<li>
<a title="" href="define_snippet.html">Howto</a>
<a title="" href="snippet-organization.html">Organize</a>
</li>
<li>
<a title="" href="snippet-expansion.html">Expand</a>
</li>
<li>
<a title="" href="snippet-development.html">Write</a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>

46
doc/index.html
View File

@ -3,7 +3,7 @@
<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.5: http://docutils.sourceforge.net/" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Yet Another Snippet extension</title>
<meta name="author" content="pluskid" />
<meta name="date" content="2008-03-20" />
@ -23,7 +23,13 @@
<a title="" href="index.html">Home</a>
</li>
<li>
<a title="" href="define_snippet.html">Howto</a>
<a title="" href="snippet-organization.html">Organize</a>
</li>
<li>
<a title="" href="snippet-expansion.html">Expand</a>
</li>
<li>
<a title="" href="snippet-development.html">Write</a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>
@ -49,8 +55,9 @@
<li><a class="reference internal" href="#normal-install" id="id4">Normal Install</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customization-group" id="id5">Customization group</a></li>
<li><a class="reference internal" href="#bugs-contribution-and-support" id="id6">Bugs, Contribution and Support</a></li>
<li><a class="reference internal" href="#how-to-use-yasnippet" id="id5">How to use YASnippet</a></li>
<li><a class="reference internal" href="#customization-group" id="id6">Customization group</a></li>
<li><a class="reference internal" href="#bugs-contribution-and-support" id="id7">Bugs, Contribution and Support</a></li>
</ul>
</div>
<p>Yasnippet is a template system for emacs. It allows you to type a
@ -113,8 +120,35 @@ customization group.</p>
<img align="right" alt="images/customization-group.png" class="align-right" src="images/customization-group.png" />
</div>
</div>
<div class="section" id="how-to-use-yasnippet">
<h1><a class="toc-backref" href="#id5">How to use YASnippet</a></h1>
<p>Since version 0.6, YASnippet contains more functionality. You don't
need to know all of it to use it sucessfully, but you it can improve
your snippeting experience.</p>
<p>Hence this section has been split into separate documents:</p>
<ol class="arabic simple">
<li><a class="reference external" href="snippet-organization.html">Organizing snippets</a></li>
</ol>
<p>Describes ways to organize your snippets in the hard disk, or not
organize them at all and just use plain old elisp.</p>
<p>Also explains how to use the YASnippet menu to explore and learn new
snippets.</p>
<ol class="arabic simple" start="2">
<li><a class="reference external" href="snippet-expansion.html">Controlling snippet expansion</a></li>
</ol>
<p>Maybe, you'll want some snippets to be expanded in a particular mode,
or only under certain conditions. Also you might want snippets to wrap
themselves around a region of selected text, use a direct keybinding,
control indenting, etc...</p>
<ol class="arabic simple" start="3">
<li><a class="reference external" href="snippet-development.html">Defining your own snippets</a></li>
</ol>
<p>Describes the YASnippet definition syntax, which is similar, but not
equivalent to Textmate's. Includes a section about converting Textmate
snippets.</p>
</div>
<div class="section" id="customization-group">
<h1><a class="toc-backref" href="#id5">Customization group</a></h1>
<h1><a class="toc-backref" href="#id6">Customization group</a></h1>
<p>From version 0.6 onwards, there is a customization group that you can
access with:</p>
<p><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">customize-group</span> <span class="pre">RET</span> <span class="pre">yasnippet</span> <span class="pre">RET</span></tt></p>
@ -125,7 +159,7 @@ use, whether to expand snippets inside snippets, etc...</p>
to explain what it does.</p>
</div>
<div class="section" id="bugs-contribution-and-support">
<h1><a class="toc-backref" href="#id6">Bugs, Contribution and Support</a></h1>
<h1><a class="toc-backref" href="#id7">Bugs, Contribution and Support</a></h1>
<ul class="simple">
<li>If you find a bug, please report it at <a class="reference external" href="http://code.google.com/p/yasnippet/issues/list">Issue List</a>.</li>
<li>If you have problem using YASnippet, or have some new ideas, please

31
doc/index.rst
View File

@ -24,7 +24,6 @@ is much cleaner and more powerful than smart-snippet.
.. _smart-snippet: http://code.google.com/p/smart-snippet/
Video Demo
==========
@ -84,6 +83,36 @@ customization group.
.. image:: images/customization-group.png
:align: right
How to use YASnippet
====================
Since version 0.6, YASnippet contains more functionality. You don't
need to know all of it to use it sucessfully, but you it can improve
your snippeting experience.
Hence this section has been split into separate documents:
1. `Organizing snippets <snippet-organization.html>`_
Describes ways to organize your snippets in the hard disk, or not
organize them at all and just use plain old elisp.
Also explains how to use the YASnippet menu to explore and learn new
snippets.
2. `Controlling snippet expansion <snippet-expansion.html>`_
Maybe, you'll want some snippets to be expanded in a particular mode,
or only under certain conditions. Also you might want snippets to wrap
themselves around a region of selected text, use a direct keybinding,
control indenting, etc...
3. `Defining your own snippets <snippet-development.html>`_
Describes the YASnippet definition syntax, which is similar, but not
equivalent to Textmate's. Includes a section about converting Textmate
snippets.
Customization group
===================

313
doc/snippet-development.html Normal file
View File

@ -0,0 +1,313 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Writing snippets</title>
<meta name="author" content="pluskid, joaotavora" />
<meta name="date" content="2009-08-18" />
<link rel="stylesheet" href="styles.css" type="text/css" />
</head>
<body>
<div class="document" id="writing-snippets">
<div id="header-region" class="clear-block"></div>
<div id="wrapper">
<div id="container" class="clear-block">
<div id="header">
<div id="logo-floater">
<h1 class="title">Writing snippets</h1>
</div>
<ul class="primary-links">
<li>
<a title="" href="index.html">Home</a>
</li>
<li>
<a title="" href="snippet-organization.html">Organize</a>
</li>
<li>
<a title="" href="snippet-expansion.html">Expand</a>
</li>
<li>
<a title="" href="snippet-development.html">Write</a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>
</li>
<li>
<a title="" href="changelog.html">ChangeLog</a>
</li>
<li>
<a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
</li>
</ul>
</div>
<div id="center">
<div id="squeeze">
<div class="right-corner">
<div class="left-corner">
<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>
</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>
<ul>
<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>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/visit-snippet-file</span></tt></p>
<p>Prompts you for possible snippet expansions like
<tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt>, but instead of expanding it, takes you
directly to the snippet definition's file, if it exists.</p>
</li>
</ul>
</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>
<p>Two commands are defined in this mode:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p>
<blockquote>
<p>When editing a snippet, this loads the snippet into the correct
mode and menu. Bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-c</span></tt> by default while in
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p>
</blockquote>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/tryout-snippet</span></tt></p>
<blockquote>
<p>When editing a snippet, this opens a new empty buffer, sets it to
the appropriate major mode and inserts the snippet there, so you
can see what it looks like. This is bound to <tt class="docutils literal"><span class="pre">C-c</span> <span class="pre">C-t</span></tt> while in
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt>.</p>
</blockquote>
</li>
</ul>
<p>There are also 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>
<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>
<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
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
example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard dynamically:</p>
<div class="highlight"><pre>#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
#define $1
$0
#endif /* $1 */
</pre></div>
<p>From version 0.6.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
can therefore define a snippet like:</p>
<div class="highlight"><pre>for ($1;$2;$3) {
`yas/selected-text`$0
}
</pre></div>
<p>to &quot;wrap&quot; the selected region inside your recently inserted
snippet. Alternatively, you can also customize the variable
<tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt> which will do this automatically.</p>
</div>
<div class="section" id="tab-stop-fields">
<h1><a class="toc-backref" href="#id11">Tab stop fields</a></h1>
<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
number. <tt class="docutils literal"><span class="pre">$0</span></tt> has the special meaning of the <em>exit point</em> of a
snippet. That is the last place to go when you've traveled all the
fields. Here's a typical example:</p>
<div class="highlight"><pre>&lt;div$1&gt;
$0
&lt;/div&gt;
</pre></div>
</div>
<div class="section" id="placeholder-fields">
<h1><a class="toc-backref" href="#id12">Placeholder fields</a></h1>
<p>Tab stops can have default values -- a.k.a placeholders. The syntax is
like this:</p>
<div class="highlight"><pre>${N:default value}
</pre></div>
<p>They acts as the default value for a tab stop. But when you firstly
type at a tab stop, the default value will be replaced by your
typing. The number can be omitted if you don't want to create
<a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p>
</div>
<div class="section" id="id2">
<span id="mirrors"></span><h1><a class="toc-backref" href="#id13">Mirrors</a></h1>
<p>We refer the tab stops with placeholders as a <em>field</em>. A field can have
mirrors. Its mirrors will get updated when you change the text of a
field. Here's an example:</p>
<div class="highlight"><pre>\begin{${1:enumerate}}
$0
\end{$1}
</pre></div>
<p>When you type <tt class="docutils literal"><span class="pre">&quot;document&quot;</span></tt> at <tt class="docutils literal"><span class="pre">${1:enumerate}</span></tt>, the word
<tt class="docutils literal"><span class="pre">&quot;document&quot;</span></tt> will also be inserted at <tt class="docutils literal"><span class="pre">\end{$1}</span></tt>. The best
explanation is to see the screencast(<a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">YouTube</a> or <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">avi video</a>).</p>
<p>The tab stops with the same number to the field act as its mirrors. If
none of the tab stops has an initial value, the first one is selected
as the field and others mirrors.</p>
</div>
<div class="section" id="mirrors-with-transformations">
<span id="transformations"></span><h1><a class="toc-backref" href="#id14">Mirrors with transformations</a></h1>
<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
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}
{
return $2;
}
- (void)set${2:$(capitalize text)}:($1)aValue
{
[$2 autorelease];
$2 = [aValue retain];
}
$0
</pre></div>
<p>Look at <tt class="docutils literal"><span class="pre">${2:$(capitalize</span> <span class="pre">text)}</span></tt>, it is a transformation instead of
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
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 &quot;===&quot; below and above. The &quot;===&quot;
should be at least as long as the text. So</p>
<div class="highlight"><pre>=====
Title
=====
</pre></div>
<p>is a valid title but</p>
<div class="highlight"><pre>===
Title
===
</pre></div>
<p>is not. Here's an snippet for rst title:</p>
<div class="highlight"><pre>${1:$(make-string (string-width text) ?\=)}
${1:Title}
${1:$(make-string (string-width text) ?\=)}
$0
</pre></div>
<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>
<p>From version 0.6 on, you can also have lisp transformation inside
fields. These work mostly mirror transformations but are evaluated
when you first enter the field, after each change you make to the
field and also just before you exit the field.</p>
<p>The syntax is also a tiny bit different, so that the parser can
distinguish between fields and mirrors. In the following example</p>
<div class="highlight"><pre>#define &quot;${1:mydefine$(upcase yas/text)}&quot;
</pre></div>
<p><tt class="docutils literal"><span class="pre">mydefine</span></tt> gets automatically upcased to <tt class="docutils literal"><span class="pre">MYDEFINE</span></tt> once you enter
the field. As you type text, it gets filtered through the
transformation every time.</p>
<p>Note that 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
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 &quot;${1:$$(upcase yas/text)}&quot;
</pre></div>
<p>Please note that as soon as a transformation takes place, it changes
the value of the field and sets it its internal modification state to
<tt class="docutils literal"><span class="pre">true</span></tt>. As a consequence, the auto-deletion behaviour of normal
fields does not take place. This is by design.</p>
</div>
<div class="section" id="choosing-fields-value-from-a-list">
<h1><a class="toc-backref" href="#id16">Choosing fields value from a list</a></h1>
<p>As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
<tt class="docutils literal"><span class="pre">yas/field-modified-p</span></tt> and <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Because of this
feature you can place a transformation in the primary field that lets
you select default values for it.</p>
<p>The <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> does this work for you. For example:</p>
<div class="highlight"><pre>&lt;div align=&quot;${2:$$(yas/choose-value &#39;(&quot;right&quot; &quot;center&quot; &quot;left&quot;))}&quot;&gt;
$0
&lt;/div&gt;
</pre></div>
<p>See the definition of <tt class="docutils literal"><span class="pre">yas/choose-value</span></tt> to see how it was written
using the two variables. Also check out <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> for
another neat trick.</p>
</div>
<div class="section" id="nested-placeholder-fields">
<h1><a class="toc-backref" href="#id17">Nested placeholder fields</a></h1>
<p>From version 0.6 on, you can also have nested placeholders of the type:</p>
<div class="highlight"><pre>&lt;div${1: id=&quot;${2:some_id}&quot;}&gt;$0&lt;/div&gt;
</pre></div>
<p>This allows you to choose if you want to give this <tt class="docutils literal"><span class="pre">div</span></tt> an <tt class="docutils literal"><span class="pre">id</span></tt>
attribute. If you tab forward after expanding it will let you change
&quot;some_id&quot; to whatever you like. Alternatively, you can just press
<tt class="docutils literal"><span class="pre">C-d</span></tt> (which executes <tt class="docutils literal"><span class="pre">yas/skip-and-clear-or-delete-char</span></tt>) and go
straight to the exit marker.</p>
<p>By the way, <tt class="docutils literal"><span class="pre">C-d</span></tt> will only clear the field if you cursor is at the
beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it
performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>

295
doc/snippet-development.rst Normal file
View File

@ -0,0 +1,295 @@
================
Writing snippets
================
:Author: pluskid, joaotavora
:Contact: pluskid@gmail.com
:Date: 2009-08-18
.. contents::
Quickly finding/defining snippets
---------------------------------
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
``snippet-mode`` (see ahead)
* ``M-x yas/find-snippets``
Lets you find the snippet file in the directory the snippet was
loaded from (if it exists) like ``find-file-other-window``.
* ``M-x yas/visit-snippet-file``
Prompts you for possible snippet expansions like
``yas/insert-snippet``, but instead of expanding it, takes you
directly to the snippet definition's file, if it exists.
Using the ``snippet-mode`` major mode
-------------------------------------
From version 0.6 upwards there is a major mode ``snippet-mode`` to
edit snippets. You can set the buffer to this mode with ``M-x
snippet-mode``. It provides reasonably useful syntax highlighting.
Two commands are defined in this mode:
* ``M-x yas/load-snippet-buffer``
When editing a snippet, this loads the snippet into the correct
mode and menu. Bound to ``C-c C-c`` by default while in
``snippet-mode``.
* ``M-x yas/tryout-snippet``
When editing a snippet, this opens a new empty buffer, sets it to
the appropriate major mode and inserts the snippet there, so you
can see what it looks like. This is bound to ``C-c C-t`` while in
``snippet-mode``.
There are also snippets for making snippets: ``vars``, ``field`` and
``mirror``.
The Syntax of the Template
==========================
The syntax of the snippet template is simple but powerful, very
similar to TextMate's.
Plain Text
----------
Arbitrary text can be included as the content of a template. They are
usually interpreted as plain text, except ``$`` and `````. You need to
use ``\`` to escape them: ``\$`` and ``\```. The ``\`` itself may also
needed to be escaped as ``\\`` sometimes.
Embedded elisp code
-------------------
Elisp code can be embedded inside the template. They are written
inside back-quotes (`````):
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
example for ``c-mode`` to calculate the header file guard dynamically:
.. sourcecode:: text
#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
#define $1
$0
#endif /* $1 */
From version 0.6.0, snippets expansions are run with some special
emacs-lisp variables bound. One of this is ``yas/selected-text``. You
can therefore define a snippet like:
.. sourcecode:: text
for ($1;$2;$3) {
`yas/selected-text`$0
}
to "wrap" the selected region inside your recently inserted
snippet. Alternatively, you can also customize the variable
``yas/wrap-around-region`` to ``t`` which will do this automatically.
Tab stop fields
---------------
Tab stops are fields that you can navigate back and forth by ``TAB``
and ``S-TAB`` [3]_. They are written by ``$`` followed with a
number. ``$0`` has the special meaning of the *exit point* of a
snippet. That is the last place to go when you've traveled all the
fields. Here's a typical example:
.. sourcecode:: text
<div$1>
$0
</div>
Placeholder fields
------------------
Tab stops can have default values -- a.k.a placeholders. The syntax is
like this:
.. sourcecode:: text
${N:default value}
They acts as the default value for a tab stop. But when you firstly
type at a tab stop, the default value will be replaced by your
typing. The number can be omitted if you don't want to create
`mirrors`_ or `transformations`_ for this field.
.. _mirrors:
Mirrors
-------
We refer the tab stops with placeholders as a *field*. A field can have
mirrors. Its mirrors will get updated when you change the text of a
field. Here's an example:
.. sourcecode:: text
\begin{${1:enumerate}}
$0
\end{$1}
When you type ``"document"`` at ``${1:enumerate}``, the word
``"document"`` will also be inserted at ``\end{$1}``. The best
explanation is to see the screencast(`YouTube
<http://www.youtube.com/watch?v=vOj7btx3ATg>`_ or `avi video
<http://yasnippet.googlecode.com/files/yasnippet.avi>`_).
The tab stops with the same number to the field act as its mirrors. If
none of the tab stops has an initial value, the first one is selected
as the field and others mirrors.
.. _transformations:
Mirrors with transformations
----------------------------
If the default value of a field starts with ``$``, 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
when the variable text is bind to the inputted text of the
field. Here's an example for Objective-C:
.. sourcecode:: text
- (${1:id})${2:foo}
{
return $2;
}
- (void)set${2:$(capitalize text)}:($1)aValue
{
[$2 autorelease];
$2 = [aValue retain];
}
$0
Look at ``${2:$(capitalize text)}``, it is a transformation instead of
a placeholder. The actual placeholder is at the first line:
``${2:foo}``. When you type text in ``${2:foo}``, 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
the screencast.
Another example is for ``rst-mode``. In reStructuredText, the document
title can be some text surrounded by "===" below and above. The "==="
should be at least as long as the text. So
.. sourcecode:: text
=====
Title
=====
is a valid title but
.. sourcecode:: text
===
Title
===
is not. Here's an snippet for rst title:
.. sourcecode:: text
${1:$(make-string (string-width text) ?\=)}
${1:Title}
${1:$(make-string (string-width text) ?\=)}
$0
.. [1] With some minor change, mainly for fixing some trivial bugs.
.. [2] This is done when you call ``yas/initialize``.
.. [3] Of course, this can be customized.
Fields with transformations
---------------------------
From version 0.6 on, you can also have lisp transformation inside
fields. These work mostly mirror transformations but are evaluated
when you first enter the field, after each change you make to the
field and also just before you exit the field.
The syntax is also a tiny bit different, so that the parser can
distinguish between fields and mirrors. In the following example
.. sourcecode:: text
#define "${1:mydefine$(upcase yas/text)}"
``mydefine`` gets automatically upcased to ``MYDEFINE`` once you enter
the field. As you type text, it gets filtered through the
transformation every time.
Note that this is differentiated from a mirror with a transformation
by the existance of extra text between the ``:`` and the
transformation's ``$``. If you don't want this extra-text, you can use
two ``$``'s instead.
.. sourcecode:: text
#define "${1:$$(upcase yas/text)}"
Please note that as soon as a transformation takes place, it changes
the value of the field and sets it its internal modification state to
``true``. As a consequence, the auto-deletion behaviour of normal
fields does not take place. This is by design.
Choosing fields value from a list
---------------------------------
As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
``yas/field-modified-p`` and ``yas/moving-away-p``. Because of this
feature you can place a transformation in the primary field that lets
you select default values for it.
The ``yas/choose-value`` does this work for you. For example:
.. sourcecode:: text
<div align="${2:$$(yas/choose-value '("right" "center" "left"))}">
$0
</div>
See the definition of ``yas/choose-value`` to see how it was written
using the two variables. Also check out ``yas/verify-value`` for
another neat trick.
Nested placeholder fields
-------------------------
From version 0.6 on, you can also have nested placeholders of the type:
.. sourcecode:: text
<div${1: id="${2:some_id}"}>$0</div>
This allows you to choose if you want to give this ``div`` an ``id``
attribute. If you tab forward after expanding it will let you change
"some_id" to whatever you like. Alternatively, you can just press
``C-d`` (which executes ``yas/skip-and-clear-or-delete-char``) and go
straight to the exit marker.
By the way, ``C-d`` will only clear the field if you cursor is at the
beginning of the field *and* it hasn't been changed yet. Otherwise, it
performs the normal Emacs ``delete-char`` command.

413
doc/snippet-expansion.html Normal file
View File

@ -0,0 +1,413 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>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>
<div class="document" id="expanding-snippets">
<div id="header-region" class="clear-block"></div>
<div id="wrapper">
<div id="container" class="clear-block">
<div id="header">
<div id="logo-floater">
<h1 class="title">Expanding snippets</h1>
</div>
<ul class="primary-links">
<li>
<a title="" href="index.html">Home</a>
</li>
<li>
<a title="" href="snippet-organization.html">Organize</a>
</li>
<li>
<a title="" href="snippet-expansion.html">Expand</a>
</li>
<li>
<a title="" href="snippet-development.html">Write</a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>
</li>
<li>
<a title="" href="changelog.html">ChangeLog</a>
</li>
<li>
<a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
</li>
</ul>
</div>
<div id="center">
<div id="squeeze">
<div class="right-corner">
<div class="left-corner">
<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>
</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>
</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>
</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>
</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" />
<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>
</ul>
</div>
</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>
<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
following thing until found one:</p>
<ul class="simple">
<li>a word.</li>
<li>a symbol. In lisp, <tt class="docutils literal"><span class="pre">-</span></tt> and <tt class="docutils literal"><span class="pre">?</span></tt> can all be part of a symbol.</li>
<li>a sequence of characters of either word, symbol or punctuation.</li>
<li>a sequence of characters of non-whitespace characters.</li>
</ul>
<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>
</div>
</div>
</div>
</div>
</div>
</body>
</html>

410
doc/snippet-expansion.rst Normal file
View File

@ -0,0 +1,410 @@
==================
Expanding snippets
==================
:Author: pluskid, joaotavora
:Contact: pluskid@gmail.com
:Date: 2009-08-18
.. contents::
Some stuff
==========
File content
------------
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.
Generally speaking, if the file contains a line of ``# --``, 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.
Here's a typical example:
.. sourcecode:: text
#contributor : pluskid <pluskid@gmail.com>
#name : __...__
# --
__${init}__
Meta data are specified in the syntax of
.. sourcecode:: text
#data-name : data value
Any other text above ``# --`` is considered as comment and
ignored. Here's a list of currently supported meta data:
.. image:: images/group.png
:align: right
* ``name``: 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.
* ``contributor``: The contributor of the snippet.
* ``condition``: 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.
* ``key``: The key to expand the snippet. Sometimes the key of a
snippet is non-ASCII or not valid filename (e.g. contains
``/``). One can then define the ``key`` property which will
overwrite the filename as the key to expand the snippet.
* ``group``: 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. ``group``
property only affect menu construction (See `Organizing snippets <snippet-organization.html>`_). Refer to
the snippets for ``ruby-mode`` for examples. Group can also be
nested, e.g. ``control structure.loops`` tells that the snippet is
under the ``loops`` group which is under the ``control structure``
group.
The strategy to select a snippet
================================
When user press the ``yas/trigger-key``, YASnippet try to find a
proper snippet to expand. The strategy to find such a snippet is
explained here.
Finding the key
---------------
YASnippet search from current point backward trying to find the
snippet to be expanded. The default searching strategy is quite
powerful. For example, in ``c-mode``, ``"bar"``, ``"foo_bar"``,
``"#foo_bar"`` can all be recognized as a template key. Further more,
the searching is in that order. In other words, if ``"bar"`` is found
to be a key to some *valid* snippet, then ``"foo_bar"`` and
``"#foobar"`` won't be searched.
However, this strategy can also be customized easily from the
``yas/key-syntaxes`` variable. It is a list of syntax rules, the
default value is ``("w" "w_" "w_." "^ ")``. Which means search the
following thing until found one:
* a word.
* a symbol. In lisp, ``-`` and ``?`` can all be part of a symbol.
* a sequence of characters of either word, symbol or punctuation.
* a sequence of characters of non-whitespace characters.
But you'd better keep the default value unless you understand what
Emacs's syntax rule mean.
The condition system
--------------------
I write forked snippet.el to make the smart-snippet.el. I call it
*smart*-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.
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
Consider this scenario: you are an old Emacs hacker. You like the
abbrev-way and set ``yas/trigger-key`` to ``(kbd "SPC")``. However,
you don't want ``if`` to be expanded as a snippet when you are typing
in a comment block or a string (e.g. in ``python-mode``).
It's OK, just specify the condition for ``if`` to be ``(not
(python-in-string/comment))``. But how about ``while``, ``for``,
etc. ? Writing the same condition for all the snippets is just
boring. So YASnippet introduce a buffer local variable
``yas/buffer-local-condition``. You can set this variable to ``(not
(python-in-string/comment))`` in ``python-mode-hook``. There's no way
to do this in smart-snippet.el!
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:
* If ``yas/buffer-local-condition`` evaluate to nil, snippet won't be
expanded.
* If it evaluate to the a cons cell where the ``car`` is the symbol
``require-snippet-condition`` and the ``cdr`` is a symbol (let's
call it ``requirement``):
* If the snippet has no condition, then it won't be expanded.
* If the snippet has a condition but evaluate to nil or error
occured during evaluation, it won't be expanded.
* If the snippet has a condition that evaluate to non-nil (let's
call it ``result``):
* If ``requirement`` is ``t``, the snippet is ready to be
expanded.
* If ``requirement`` is ``eq`` to ``result``, the snippet is ready
to be expanded.
* Otherwise the snippet won't be expanded.
* If it evaluate to other non-nil value:
* If the snippet has no condition, or has a condition that evaluate
to non-nil, it is ready to be expanded.
* Otherwise, it won't be expanded.
So set ``yas/buffer-local-condition`` like this
.. sourcecode:: common-lisp
(add-hook 'python-mode-hook
'(lambda ()
(setq yas/buffer-local-condition
'(if (python-in-string/comment)
'(require-snippet-condition . force-in-comment)
t))))
And specify the condition for a snippet that you're going to expand in
comment to be evaluated to the symbol ``force-in-comment``. Then it
can be expanded as you expected, while other snippets like ``if``
still can't expanded in comment.
Multiple snippet with the same key
----------------------------------
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 *postfix* to the
key.
In general, the *extension* (consider a file name) is *ignored* when
defining a snippet. So ``def``, ``def.1`` and ``def.mine`` will all be
valid candidates when the key is ``def``.
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:
From version 0.6 of YASnippet this has changed significantly. A new
customization variable, called ``yas/prompt-functions`` defines your
preferred method of being prompted for snippets.
You can customize it with ``M-x customize-variable RET
yas/prompt-functions RET``. Alternatively you can put in your
emacs-file:
.. sourcecode:: common-lisp
(setq yas/prompt-functions '(yas/x-prompt yas/dropdown-prompt))
Currently there are some alternatives solution with YASnippet.
.. image:: images/popup-menu.png
:align: right
Use the X window system
~~~~~~~~~~~~~~~~~~~~~~~
The function ``yas/x-prompt`` 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:
* It usually looks beautiful. E.g. when you compile Emacs with gtk
support, this menu will be rendered with your gtk theme.
* Emacs have little control over it. E.g. you can't use ``C-n``,
``C-p`` to navigate.
* This function can't be used when in a terminal.
Use built-in Emacs selection methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use functions ``yas/completing-prompt`` for the classic emacs
completion method or ``yas/ido-prompt`` for a much nicer looking
method. The best way is to try it. This works in a terminal.
.. image:: images/idrop-menu.png
:align: center
Use ``dropdown-menu.el``
~~~~~~~~~~~~~~~~~~~~~~~~
The function ``yas/dropdown-prompt`` can also be placed in the
``yas/prompt-functions`` list.
.. image:: images/dropdown-menu.png
:align: right
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 ``dropdown-menu.el``,
I say wow! It's wonderful!
* It works in both window system and terminal.
* It is customizable, you can use ``C-n``, ``C-p`` to navigate, ``q``
to quite and even press ``6`` as a shortcut to select the 6th
candidate.
So I added ``yas/dropdown-list-popup-for-template`` to support
``dropdown-list.el``. And upload ``dropdown-list.el`` to YASnippet
hompage for an optional download (since Jaeyoun didn't provide a URL).
Then finally, in 0.4.0, I included a copy of the content of
``dropdown-list.el`` in ``yasnippet.el`` and made it the default
way for selecting multiple candidates.
However, the original functions are still there, you can still use this
.. sourcecode:: common-lisp
(setq yas/window-system-popup-function
'yas/x-popup-menu-for-template)
if you prefer a *modern* UI. :)
The Trigger Key
---------------
YASnippet is implemented as a minor-mode (``yas/minor-mode``). The
trigger key ``yas/trigger-key`` is defined in ``yas/minor-mode-map``
to call ``yas/expand`` to try to expand a snippet.
The Minor Mode
~~~~~~~~~~~~~~
.. image:: images/minor-mode-indicator.png
:align: left
When ``yas/minor-mode`` is enabled, the trigger key will take
effect. The default key is ``(kbd "TAB")``, however, you can freely
set it to some other key.
In version 0.5, YASnippet add a hook to
``after-change-major-mode-hook`` to enable ``yas/minor-mode`` 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
``yas/extra-mode-hooks`` to let YASnippet do it for you:
.. sourcecode:: common-lisp
(require 'yasnippet)
(add-to-list 'yas/extra-mode-hooks
'ruby-mode-hook)
(yas/initialize)
Note that **should** be put after ``(require 'yasnippet)`` and before
``(yas/initialize)``. Further more, you may report it to me, I'll add
that to the default value.
In version 0.6, just use ``yas/global-mode`` to enable YASnippet in
all major modes. Or put ``yas/minor-mode-on`` in that modes hook. See
the `FAQ <faq.html>`_.
The Fallback
~~~~~~~~~~~~
If ``yas/expand`` 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 ``yas/trigger-key``. 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.
However, you can change this behavior by customizing the
``yas/fallback-behavior`` variable. If you set this variable to
``'return-nil``, it will return ``nil`` instead of trying to call the
*original* command when no snippet is found. This is useful when you
would like YASnippet to work with other extensions,
e.g. ``hippie-expand``. I'm also glad to tell you that integration
with ``hippie-expand`` is already included in YASnippet.
Integration with ``hippie-expand``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To integrate with ``hippie-expand``, just put
``yas/hippie-try-expand`` in
``hippie-expand-try-functions-list``. Personally I would like to put
in front of the list, but it can be put anywhere you prefer.
Other way to select a snippet
-----------------------------
When you use the trigger key (so ``yas/expand``) to expand a snippet,
the key for the snippet is deleted before the template for the snippet
is inserted.
However, there're other ways to insert a snippet.
``yas/insert-snippet``
~~~~~~~~~~~~~~~~~~~~~~
The command ``M-x yas/insert-snippet`` lets you insert snippets at
point *for you current major mode*. It prompts you for the snippet
key first, and then for a snippet template if more than one template
exists for the same key.
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
``C-u``.
The prompting methods used are again controlled by
``yas/prompt-functions``.
Expanding From Elisp Code
~~~~~~~~~~~~~~~~~~~~~~~~~
Sometimes you might want to expand a snippet directly by calling a
functin from elisp code. You should call ``yas/expand-snippet``
instead of ``yas/expand`` in this case.
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:
.. sourcecode:: common-lisp
(yas/expand-snippet (point) (point) template)
Where ``template`` 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 ``yas/expand`` 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 ``(point)``
is fine. Note only ``(point)`` will be fine because the 1st parameter
also indicate where to insert and expand the ``template``.
Indenting
---------
Many people miss the indenting feature of smart-snippet: when you
place a ``$>`` in your snippet, an ``(indent-according-to-mode)`` 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.
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 ``indent-according-to-mode`` will break
the overlays created by YASnippet.
However, since many people asked for this feature, I finally added
this to YASnippet. Here's an example of the usage:
.. sourcecode:: text
for (${int i = 0}; ${i < 10}; ${++i})
{$>
$0$>
}$>
In 0.6.0 You should **not** need to use this feature although it's
supported for backward compatibility. Just set ``yas/indent-line`` to
``'auto``.

325
doc/snippet-organization.html Normal file
View File

@ -0,0 +1,325 @@
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>Organizing 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>
<div class="document" id="organizing-snippets">
<div id="header-region" class="clear-block"></div>
<div id="wrapper">
<div id="container" class="clear-block">
<div id="header">
<div id="logo-floater">
<h1 class="title">Organizing snippets</h1>
</div>
<ul class="primary-links">
<li>
<a title="" href="index.html">Home</a>
</li>
<li>
<a title="" href="snippet-organization.html">Organize</a>
</li>
<li>
<a title="" href="snippet-expansion.html">Expand</a>
</li>
<li>
<a title="" href="snippet-development.html">Write</a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>
</li>
<li>
<a title="" href="changelog.html">ChangeLog</a>
</li>
<li>
<a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
</li>
</ul>
</div>
<div id="center">
<div id="squeeze">
<div class="right-corner">
<div class="left-corner">
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#new-style-storage-recommended" id="id1">New-style storage (recommended)</a></li>
<li><a class="reference internal" href="#old-style-storage-pre-0-6" id="id2">Old-style storage (pre 0.6)</a></li>
<li><a class="reference internal" href="#no-storage-bundle" id="id3">No storage (bundle)</a></li>
<li><a class="reference internal" href="#define-snippets-in-files" id="id4">Define snippets in files</a><ul>
<li><a class="reference internal" href="#directory-hierarchy" id="id5">Directory hierarchy</a></li>
<li><a class="reference internal" href="#define-snippets-using-elisp-code" id="id6">Define snippets using elisp code</a><ul>
<li><a class="reference internal" href="#yas-define-snippets" id="id7">yas/define-snippets</a></li>
<li><a class="reference internal" href="#yas-define" id="id8">yas/define</a></li>
<li><a class="reference internal" href="#yas-compile-bundle" id="id9">yas/compile-bundle</a></li>
<li><a class="reference internal" href="#the-menu" id="id10">The Menu</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</div>
<p>There are three ways to keep your snippets:</p>
<div class="section" id="new-style-storage-recommended">
<h1><a class="toc-backref" href="#id1">New-style storage (recommended)</a></h1>
<p>Hehe</p>
</div>
<div class="section" id="old-style-storage-pre-0-6">
<h1><a class="toc-backref" href="#id2">Old-style storage (pre 0.6)</a></h1>
<p>Blabla</p>
</div>
<div class="section" id="no-storage-bundle">
<h1><a class="toc-backref" href="#id3">No storage (bundle)</a></h1>
<p>The most convenient way to define snippets for YASnippet is to put
them in a directory arranged by the mode and use
<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> to load them.</p>
<p>However, this might slow down the Emacs startup speed if you have many
snippets. You can use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to define a bunch of
snippets for a perticular mode. But this is hard to maintain! So,
there's a better way: define your snippets in directory and use
<tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> to compile it into a bundle file when you
modified your snippets.</p>
<p>The release bundle of YASnippet is produced by
<tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>. The bundle use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to
define snippets. This avoid the IO and parsing overhead when loading
snippets.</p>
<p>Finally, you can use <tt class="docutils literal"><span class="pre">yas/define</span></tt> to define a single snippet at your
convenience. I ofthen use this to do some testing.</p>
</div>
<div class="section" id="define-snippets-in-files">
<h1><a class="toc-backref" href="#id4">Define snippets in files</a></h1>
<div class="section" id="directory-hierarchy">
<h2><a class="toc-backref" href="#id5">Directory hierarchy</a></h2>
<p>Here's the directory hierarchy of the <tt class="docutils literal"><span class="pre">snippets</span></tt> directory comes
with YASnippet:</p>
<div class="highlight"><pre>snippets
`-- text-mode/
|-- cc-mode/
| |-- c++-mode/
| | |-- beginend
| | |-- class
| | `-- using
| |-- c-mode/
| | `-- fopen
| |-- do
| |-- for
| |-- if
| |-- inc
| |-- inc.1
| |-- main
| |-- once
| `-- struct
|-- css-mode/
| |-- background
| |-- background.1
| `-- border
|-- email
|-- html-mode/
| |-- div
| |-- doctype
| |-- doctype.xhml1
| |-- doctype.xhtml1_1
| |-- doctype.xhtml1_strict
| `-- doctype.xhtml1_transitional
|-- objc-mode/
| `-- prop
|-- perl-mode/
| |-- cperl-mode/
| |-- eval
| |-- for
| |-- fore
| |-- if
| |-- ife
| |-- ifee
| |-- sub
| |-- unless
| |-- while
| |-- xfore
| |-- xif
| |-- xunless
| `-- xwhile
|-- python-mode/
| |-- __
| |-- class
| |-- def
| |-- for
| |-- ifmain
| `-- while
|-- rst-mode/
| |-- chapter
| |-- section
| `-- title
|-- ruby-mode/
| |-- #
| |-- =b
| |-- Comp
| |-- all
| |-- am
| |-- any
| |-- app
| |-- bm
| |-- case
| |-- cla
| |-- classify
| |-- cls
| |-- collect
| |-- dee
| |-- deli
| |-- det
| |-- ea
| |-- eac
| |-- eai
| |-- eav
| |-- eawi
| |-- forin
| |-- if
| |-- ife
| |-- inject
| |-- mm
| |-- r
| |-- rb
| |-- reject
| |-- req
| |-- rreq
| |-- rw
| |-- select
| |-- w
| |-- y
| `-- zip
`-- time
</pre></div>
<p>Snippet definitions are put in plain text files. They are arranged by
subdirectories. For example, snippets for <tt class="docutils literal"><span class="pre">c-mode</span></tt> are put in the
<tt class="docutils literal"><span class="pre">c-mode</span></tt> directory.</p>
<p>The parent directory acts as the <em>parent mode</em>. This is the way of
YASnippet to share snippet definitions among different modes. As you
can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and <tt class="docutils literal"><span class="pre">c++-mode</span></tt> share the same parents
<tt class="docutils literal"><span class="pre">cc-mode</span></tt>, while all modes are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>. This can
be also used to as an <em>alias</em> -- <tt class="docutils literal"><span class="pre">cperl-mode</span></tt> is an empty directory
whose parent is <tt class="docutils literal"><span class="pre">perl-mode</span></tt>.</p>
<p>File names act as the snippet trigger key. Note files starting with a
dot (<tt class="docutils literal"><span class="pre">.</span></tt>) are ignored.</p>
</div>
<div class="section" id="define-snippets-using-elisp-code">
<h2><a class="toc-backref" href="#id6">Define snippets using elisp code</a></h2>
<p>As I mentioned above, you can define snippets directly by writing
elisp code.</p>
<div class="section" id="yas-define-snippets">
<h3><a class="toc-backref" href="#id7">yas/define-snippets</a></h3>
<p>The basic syntax of <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> is</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">MODE</span> <span style="color: #19177C">SNIPPETS</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">PARENT</span>)
</pre></div>
<p>The parameters are self-descriptive. If you specify a <tt class="docutils literal"><span class="pre">PARENT</span></tt>, then
the snippets of the parents may be shared by <tt class="docutils literal"><span class="pre">MODE</span></tt>. Note if you use
this function several times, the later specified <tt class="docutils literal"><span class="pre">PARENT</span></tt> will
overwrite the original one. However, not specifying a <tt class="docutils literal"><span class="pre">PARENT</span></tt> won't
erase the original parent.</p>
<p>The <tt class="docutils literal"><span class="pre">SNIPPETS</span></tt> parameter is a list of snippet definitions. Each
element should have the following form:</p>
<div class="highlight"><pre>(<span style="color: #19177C">KEY</span> <span style="color: #19177C">TEMPLATE</span> <span style="color: #19177C">NAME</span> <span style="color: #19177C">CONDITION</span> <span style="color: #19177C">GROUP</span>)
</pre></div>
<p>The <tt class="docutils literal"><span class="pre">NAME</span></tt>, <tt class="docutils literal"><span class="pre">CONDITION</span></tt> and <tt class="docutils literal"><span class="pre">GROUP</span></tt> can be omitted if you don't
want to provide one. Here's an example:</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">&#39;c++-mode</span>
<span style="color: #666666">&#39;</span>(
(<span style="color: #BA2121">&quot;using&quot;</span> <span style="color: #BA2121">&quot;using namespace ${std};</span>
<span style="color: #BA2121">$0&quot;</span> <span style="color: #BA2121">&quot;using namespace ... &quot;</span> <span style="color: #880000">nil</span>)
(<span style="color: #BA2121">&quot;class&quot;</span> <span style="color: #BA2121">&quot;class ${1:Name}</span>
<span style="color: #BA2121">{</span>
<span style="color: #BA2121">public:</span>
<span style="color: #BA2121"> $1($2);</span>
<span style="color: #BA2121"> virtual ~$1();</span>
<span style="color: #BA2121">};&quot;</span> <span style="color: #BA2121">&quot;class ... { ... }&quot;</span> <span style="color: #880000">nil</span>)
(<span style="color: #BA2121">&quot;beginend&quot;</span> <span style="color: #BA2121">&quot;${1:v}.begin(), $1.end&quot;</span> <span style="color: #BA2121">&quot;v.begin(), v.end()&quot;</span> <span style="color: #880000">nil</span>)
)
<span style="color: #19177C">&#39;cc-mode</span>)
</pre></div>
<p>The example above is auto-generated code by <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>.</p>
</div>
<div class="section" id="yas-define">
<h3><a class="toc-backref" href="#id8">yas/define</a></h3>
<p>The basic syntax for <tt class="docutils literal"><span class="pre">yas/define</span></tt> is</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/define</span> <span style="color: #19177C">mode</span> <span style="color: #19177C">key</span> <span style="color: #19177C">template</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">name</span> <span style="color: #B00040">condition</span> <span style="color: #19177C">group</span>)
</pre></div>
<p>This is only a syntax sugar for</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/define-snippets</span> <span style="color: #19177C">mode</span>
(<span style="color: #008000">list</span> (<span style="color: #008000">list</span> <span style="color: #19177C">key</span> <span style="color: #19177C">template</span> <span style="color: #19177C">name</span> <span style="color: #B00040">condition</span> <span style="color: #19177C">group</span>)))
</pre></div>
</div>
<div class="section" id="yas-compile-bundle">
<h3><a class="toc-backref" href="#id9">yas/compile-bundle</a></h3>
<p><tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> can be used to parse the snippets from a
directory hierarchy and translate them into the elisp form. The
translated code is faster to load. Further more, the generated bundle
is a stand-alone file not depending on <tt class="docutils literal"><span class="pre">yasnippet.el</span></tt>. The released
bundles of YASnippet are all generated this way.</p>
</div>
<div class="section" id="the-menu">
<h3><a class="toc-backref" href="#id10">The Menu</a></h3>
<p>YASnippet will setup a menu just after the <em>Buffers</em> Menu in the
menubar. The snippets for all <em>real</em> modes are listed there under the
menu. You can select a snippet from the menu to expand it. Since you
select manually from the menu, you can expand any snippet. For
example, you can expand a snippet defined for <tt class="docutils literal"><span class="pre">python-mode</span></tt> in a
<tt class="docutils literal"><span class="pre">c-mode</span></tt> buffer by selecting it from the menu:</p>
<img align="right" alt="images/menubar.png" class="align-right" src="images/menubar.png" />
<ul class="simple">
<li>Condition system is ignored since you select to expand it
explicitly.</li>
<li>There will be no muliple candidates since they are listed in the
menu as different items.</li>
</ul>
<p>This can be convenient sometimes. However, if you don't like the
menubar of Emacs and never use it. You can tell YASnippet don't boring
to build a menu by setting <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to nil.</p>
<p>Another thing to note is that only <em>real</em> modes are listed under the
menu. As you know, common snippets can be shared by making up a
<em>virtual</em> parent mode. It's too bad if the menu is floored by those
<em>virtual</em> modes. So YASnippet only show menus for those <em>real</em>
modes. But the snippets fo the <em>virtual</em> modes can still be accessed
through the <tt class="docutils literal"><span class="pre">parent</span></tt> submenu of some <em>real</em> mode.</p>
<p>YASnippet use a simple way to check whether a mode is <em>real</em> or
<em>virtual</em>: <tt class="docutils literal"><span class="pre">(fboundp</span> <span class="pre">mode)</span></tt>. For example, the symbol <tt class="docutils literal"><span class="pre">c-mode</span></tt> is
bound to a function while <tt class="docutils literal"><span class="pre">cc-mode</span></tt> is not. But this is not enough,
some modes aren't part of Emacs, and maybe when initializing
YASnippet, those modes haven't been initialized. So YASnippet also
maintain a list of known modes (<tt class="docutils literal"><span class="pre">yas/known-modes</span></tt>). You can add item
to that list if you need.</p>
<p>The basic syntax of <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt> is</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/compile-bundle</span> <span style="color: #008000; font-weight: bold">&amp;optional</span> <span style="color: #19177C">yasnippet</span> <span style="color: #19177C">yasnippet-bundle</span> <span style="color: #19177C">snippet-roots</span> <span style="color: #19177C">code</span> <span style="color: #19177C">dropdown</span>)
</pre></div>
<p>As you can see, all the parameters are optional. The default values
for those parameters are convenient for me to produce the default
release bundle:</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/compile-bundle</span> <span style="color: #BA2121">&quot;yasnippet.el&quot;</span>
<span style="color: #BA2121">&quot;./yasnippet-bundle.el&quot;</span>
<span style="color: #666666">&#39;</span>(<span style="color: #BA2121">&quot;snippets&quot;</span>)
<span style="color: #BA2121">&quot;(yas/initialize)&quot;</span>
<span style="color: #BA2121">&quot;dropdown-list.el&quot;</span>)
</pre></div>
<p>The <tt class="docutils literal"><span class="pre">snippet-roots</span></tt> can be a list of root directories. This is
useful when you have multiple snippet directories (maybe from other
users). The <tt class="docutils literal"><span class="pre">code</span></tt> parameter can be used to specify your own
customization code instead of the default <tt class="docutils literal"><span class="pre">(yas/initialize)</span></tt>. For
example, you can 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> here if
you like.</p>
<p>From release 0.6 you have to specify the <tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> file if
you want it to be a part of the generated bundle.</p>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</div>
</body>
</html>

307
doc/snippet-organization.rst Normal file
View File

@ -0,0 +1,307 @@
===================
Organizing snippets
===================
:Author: pluskid, joaotavora
:Contact: pluskid@gmail.com
:Date: 2009-08-18
.. contents::
There are three ways to keep your snippets:
New-style storage (recommended)
===============================
Hehe
Old-style storage (pre 0.6)
===========================
Blabla
No storage (bundle)
===================
The most convenient way to define snippets for YASnippet is to put
them in a directory arranged by the mode and use
``yas/load-directory`` to load them.
However, this might slow down the Emacs startup speed if you have many
snippets. You can use ``yas/define-snippets`` to define a bunch of
snippets for a perticular mode. But this is hard to maintain! So,
there's a better way: define your snippets in directory and use
``yas/compile-bundle`` to compile it into a bundle file when you
modified your snippets.
The release bundle of YASnippet is produced by
``yas/compile-bundle``. The bundle use ``yas/define-snippets`` to
define snippets. This avoid the IO and parsing overhead when loading
snippets.
Finally, you can use ``yas/define`` to define a single snippet at your
convenience. I ofthen use this to do some testing.
Define snippets in files
========================
Directory hierarchy
-------------------
Here's the directory hierarchy of the ``snippets`` directory comes
with YASnippet:
.. sourcecode:: text
snippets
`-- text-mode/
|-- cc-mode/
| |-- c++-mode/
| | |-- beginend
| | |-- class
| | `-- using
| |-- c-mode/
| | `-- fopen
| |-- do
| |-- for
| |-- if
| |-- inc
| |-- inc.1
| |-- main
| |-- once
| `-- struct
|-- css-mode/
| |-- background
| |-- background.1
| `-- border
|-- email
|-- html-mode/
| |-- div
| |-- doctype
| |-- doctype.xhml1
| |-- doctype.xhtml1_1
| |-- doctype.xhtml1_strict
| `-- doctype.xhtml1_transitional
|-- objc-mode/
| `-- prop
|-- perl-mode/
| |-- cperl-mode/
| |-- eval
| |-- for
| |-- fore
| |-- if
| |-- ife
| |-- ifee
| |-- sub
| |-- unless
| |-- while
| |-- xfore
| |-- xif
| |-- xunless
| `-- xwhile
|-- python-mode/
| |-- __
| |-- class
| |-- def
| |-- for
| |-- ifmain
| `-- while
|-- rst-mode/
| |-- chapter
| |-- section
| `-- title
|-- ruby-mode/
| |-- #
| |-- =b
| |-- Comp
| |-- all
| |-- am
| |-- any
| |-- app
| |-- bm
| |-- case
| |-- cla
| |-- classify
| |-- cls
| |-- collect
| |-- dee
| |-- deli
| |-- det
| |-- ea
| |-- eac
| |-- eai
| |-- eav
| |-- eawi
| |-- forin
| |-- if
| |-- ife
| |-- inject
| |-- mm
| |-- r
| |-- rb
| |-- reject
| |-- req
| |-- rreq
| |-- rw
| |-- select
| |-- w
| |-- y
| `-- zip
`-- time
Snippet definitions are put in plain text files. They are arranged by
subdirectories. For example, snippets for ``c-mode`` are put in the
``c-mode`` directory.
The parent directory acts as the *parent mode*. This is the way of
YASnippet to share snippet definitions among different modes. As you
can see above, ``c-mode`` and ``c++-mode`` share the same parents
``cc-mode``, while all modes are derived from ``text-mode``. This can
be also used to as an *alias* -- ``cperl-mode`` is an empty directory
whose parent is ``perl-mode``.
File names act as the snippet trigger key. Note files starting with a
dot (``.``) are ignored.
Define snippets using elisp code
--------------------------------
As I mentioned above, you can define snippets directly by writing
elisp code.
yas/define-snippets
~~~~~~~~~~~~~~~~~~~
The basic syntax of ``yas/define-snippets`` is
.. sourcecode:: common-lisp
(yas/define-snippets MODE SNIPPETS &optional PARENT)
The parameters are self-descriptive. If you specify a ``PARENT``, then
the snippets of the parents may be shared by ``MODE``. Note if you use
this function several times, the later specified ``PARENT`` will
overwrite the original one. However, not specifying a ``PARENT`` won't
erase the original parent.
The ``SNIPPETS`` parameter is a list of snippet definitions. Each
element should have the following form:
.. sourcecode:: common-lisp
(KEY TEMPLATE NAME CONDITION GROUP)
The ``NAME``, ``CONDITION`` and ``GROUP`` can be omitted if you don't
want to provide one. Here's an example:
.. sourcecode:: common-lisp
(yas/define-snippets 'c++-mode
'(
("using" "using namespace ${std};
$0" "using namespace ... " nil)
("class" "class ${1:Name}
{
public:
$1($2);
virtual ~$1();
};" "class ... { ... }" nil)
("beginend" "${1:v}.begin(), $1.end" "v.begin(), v.end()" nil)
)
'cc-mode)
The example above is auto-generated code by ``yas/compile-bundle``.
yas/define
~~~~~~~~~~
The basic syntax for ``yas/define`` is
.. sourcecode:: common-lisp
(yas/define mode key template &optional name condition group)
This is only a syntax sugar for
.. sourcecode:: common-lisp
(yas/define-snippets mode
(list (list key template name condition group)))
yas/compile-bundle
~~~~~~~~~~~~~~~~~~
``yas/compile-bundle`` can be used to parse the snippets from a
directory hierarchy and translate them into the elisp form. The
translated code is faster to load. Further more, the generated bundle
is a stand-alone file not depending on ``yasnippet.el``. The released
bundles of YASnippet are all generated this way.
The Menu
~~~~~~~~
YASnippet will setup a menu just after the *Buffers* Menu in the
menubar. The snippets for all *real* modes are listed there under the
menu. You can select a snippet from the menu to expand it. Since you
select manually from the menu, you can expand any snippet. For
example, you can expand a snippet defined for ``python-mode`` in a
``c-mode`` buffer by selecting it from the menu:
.. image:: images/menubar.png
:align: right
* Condition system is ignored since you select to expand it
explicitly.
* There will be no muliple candidates since they are listed in the
menu as different items.
This can be convenient sometimes. However, if you don't like the
menubar of Emacs and never use it. You can tell YASnippet don't boring
to build a menu by setting ``yas/use-menu`` to nil.
Another thing to note is that only *real* modes are listed under the
menu. As you know, common snippets can be shared by making up a
*virtual* parent mode. It's too bad if the menu is floored by those
*virtual* modes. So YASnippet only show menus for those *real*
modes. But the snippets fo the *virtual* modes can still be accessed
through the ``parent`` submenu of some *real* mode.
YASnippet use a simple way to check whether a mode is *real* or
*virtual*: ``(fboundp mode)``. For example, the symbol ``c-mode`` is
bound to a function while ``cc-mode`` is not. But this is not enough,
some modes aren't part of Emacs, and maybe when initializing
YASnippet, those modes haven't been initialized. So YASnippet also
maintain a list of known modes (``yas/known-modes``). You can add item
to that list if you need.
The basic syntax of ``yas/compile-bundle`` is
.. sourcecode:: common-lisp
(yas/compile-bundle &optional yasnippet yasnippet-bundle snippet-roots code dropdown)
As you can see, all the parameters are optional. The default values
for those parameters are convenient for me to produce the default
release bundle:
.. sourcecode:: common-lisp
(yas/compile-bundle "yasnippet.el"
"./yasnippet-bundle.el"
'("snippets")
"(yas/initialize)"
"dropdown-list.el")
The ``snippet-roots`` can be a list of root directories. This is
useful when you have multiple snippet directories (maybe from other
users). The ``code`` parameter can be used to specify your own
customization code instead of the default ``(yas/initialize)``. For
example, you can set ``yas/trigger-key`` to ``(kbd "SPC")`` here if
you like.
From release 0.6 you have to specify the ``dropdown-list.el`` file if
you want it to be a part of the generated bundle.

8
doc/template.txt
View File

@ -14,7 +14,13 @@
<a title="" href="index.html">Home</a>
</li>
<li>
<a title="" href="define_snippet.html">Howto</a>
<a title="" href="snippet-organization.html">Organize</a>
</li>
<li>
<a title="" href="snippet-expansion.html">Expand</a>
</li>
<li>
<a title="" href="snippet-development.html">Write</a>
</li>
<li>
<a title="" href="faq.html">FAQ</a>

167
snippet_copier.rb Executable file
View File

@ -0,0 +1,167 @@
#!/usr/bin/env ruby
# This is a quick script to generate YASnippets from TextMate Snippets.
#
# I based the script off of a python script of a similar nature by
# Jeff Wheeler: http://nokrev.com
# http://code.nokrev.com/?p=snippet-copier.git;a=blob_plain;f=snippet_copier.py
#
# Usage
#
# Make sure you have the plist and the choice gem installed
# $ sudo gem install plist
# $ sudo gem install choice
#
# Usage: snippet_copier.rb [-dofp]
#
# Standard Options:
# -d, --snippet-dir=PATH Tells the program the directory to find the TextMate Snippets
# -o, --output-dir=PATH What directory to write the new YASnippets to
# -f, --file=SNIPPET FILE NAME A specific snippet that you want to copy or a glob for various files
# -p, --pretty-print Pretty prints multiple snippets when printing to standard out
#
# Common options:
# --help Show this message
require 'rubygems'
require 'plist'
require 'choice'
Choice.options do
header ''
header 'Standard Options:'
option :snippet_dir do
short '-d'
long '--snippet-dir=PATH'
desc 'Tells the program the directory to find the TextMate Snippets'
default '.'
end
option :output_dir do
short '-o'
long '--output-dir=PATH'
desc 'What directory to write the new YASnippets to'
end
option :snippet do
short '-f'
long '--file=SNIPPET FILE NAME'
desc 'A specific snippet that you want to copy or a glob for various files'
default '*.{tmSnippet,plist}'
end
option :pretty_print do
short '-p'
long '--pretty-print'
desc 'Pretty prints multiple snippets when printing to standard out'
end
separator ''
separator 'Common options: '
option :help do
long '--help'
desc 'Show this message'
end
end
class TmSnippet
@@known_substitutions = {
"${TM_RAILS_TEMPLATE_START_RUBY_EXPR}" => "<%= ",
"${TM_RAILS_TEMPLATE_END_RUBY_EXPR}" => " %>",
"${TM_RAILS_TEMPLATE_START_RUBY_INLINE}" => "<% ",
"${TM_RAILS_TEMPLATE_END_RUBY_INLINE}" => " -%>",
"${TM_RAILS_TEMPLATE_END_RUBY_BLOCK}" => "end" ,
/$\{TM_SELECTED_TEXT.*\}/ => "`yas/selected-text`" }
def initialize(file)
@snippet = Plist::parse_xml(file)
end
def name
@snippet["name"]
end
def tab_trigger
@snippet["tabTrigger"]
end
def key_equivalent
@snippet["keyEquivalent"]
end
def content
@snippet["content"]
end
def to_yasnippet
doc = "# -*- mode: snippet -*-\n"
doc << "#key: #{self.tab_trigger}\n" if self.tab_trigger
doc << "#contributor : Translated from TextMate Snippet\n"
doc << "#name : #{self.name}\n"
doc << "#binding : \"#{self.key_equivalent}\"\n" if self.key_equivalent
doc << "# --\n"
@@known_substitutions.each_pair { |k, v| self.content.gsub!(k,v) }
doc << "#{self.content}"
end
end
# def yasnippet_file_name(dir, snippet, ext=nil)
# begin
# file = ""
# shortname = (snippet.tab_trigger or
# snippet.name.gsub(/[^a-z0-9_-].*/,""))
# if ext
# file = File.join(dir, shortname + "." + ext.to_s)
# else
# file = File.join(dir, shortname)
# end
# if File.exist?(file)
# if ext
# file = yasnippet_file_name(dir,snippet, ext+1)
# else
# file = yasnippet_file_name(dir,snippet, 1)
# end
# end
# # puts "returning #{file} since shortname is #{shortname}\n"
# file
# rescue TypeError
# raise "Cannot convert " + snippet.name + " (probably no tab-trigger)"
# end
# end
def yasnippet_dir_and_name(dir, file)
dir = File.join(dir,File.dirname(file))
file = File.join(File.basename(file, File.extname(file))) << ".yasnippet"
[dir, file]
end
snippet_files_glob = File.join(Choice.choices.snippet_dir, "**", Choice.choices.snippet)
snippet_files = Dir.glob(snippet_files_glob)
puts "Will try to convert #{snippet_files.length} snippets...\n"
snippet_files.each do |file|
puts "Processing #{file}\n"
snippet = TmSnippet.new(file)
if Choice.choices.output_dir
begin
( dir_to_create, file_to_create ) = yasnippet_dir_and_name(Choice.choices.output_dir, file)
FileUtils.mkdir_p(dir_to_create)
File.open(File.join(dir_to_create,file_to_create), 'w') do |f|
f.write(snippet.to_yasnippet)
end
rescue RuntimeError => error
$stderr.print error.message + "\n"
end
else
if Choice.choices.pretty_print
puts "--------------------------------------------"
end
puts snippet.to_yasnippet
if Choice.choices.pretty_print
puts "--------------------------------------------"
end
puts "\n\n"
end
end