mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 13:13:03 +00:00
Update doc for grouping
This commit is contained in:
Zhang Chiyuan
parent
64e5027d10
commit
34f2be0b88
286
doc/changelog.html
Normal file
286
doc/changelog.html
Normal file
@ -0,0 +1,286 @@
|
||||
<?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>ChangeLog</title>
|
||||
<meta name="author" content="pluskid" />
|
||||
<meta name="date" content="2008-03-22" />
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
<div class="document" id="changelog">
|
||||
<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="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="section" id="id1">
|
||||
<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" id="id2">
|
||||
<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 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 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 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 external" href="http://code.google.com/p/yasnippet/issues/detail?id=27">Issue 27</a>).</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="id3">
|
||||
<h1>0.5.7 / 2008-12-03</h1>
|
||||
<ul class="simple">
|
||||
<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 "Field-level undo functionality" to correct
|
||||
<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 external" href="http://code.google.com/p/yasnippet/issues/detail?id=16">Issue 16</a> by adding
|
||||
<tt class="docutils literal"><span class="pre">$></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 $> indenting</a>.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="id4">
|
||||
<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 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>
|
||||
<li>Use filename or full key extension for snippet name if no <tt class="docutils literal"><span class="pre">name</span></tt>
|
||||
property is defined.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="id5">
|
||||
<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>
|
||||
<li>Add an entry in FAQ about why <tt class="docutils literal"><span class="pre">TAB</span></tt> key doesn't work in some
|
||||
modes.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="id6">
|
||||
<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" id="id7">
|
||||
<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 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" id="id8">
|
||||
<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" id="id9">
|
||||
<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" id="id10">
|
||||
<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>
|
||||
<li>If you set <tt class="docutils literal"><span class="pre">yas/fall-back-behavior</span></tt> to <tt class="docutils literal"><span class="pre">'return-nil</span></tt>, YASnippet
|
||||
will return nil when it can't find a snippet to expand.</li>
|
||||
<li>Defect fix: the condition of a snippet was evaluated twice in
|
||||
earlier version.</li>
|
||||
<li>Deleting snippet (using <tt class="docutils literal"><span class="pre">C-w</span></tt> or <tt class="docutils literal"><span class="pre">C-k</span></tt>) won't cause serious
|
||||
problem now.</li>
|
||||
<li>Several complex snippet for python-mode from Yasser included in the
|
||||
distribution.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="id11">
|
||||
<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 external" href="mailto:sunwaybupt@newsmth">sunwaybupt@newsmth</a> for reporting this bug.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="id12">
|
||||
<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" id="id13">
|
||||
<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" id="id14">
|
||||
<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" id="id15">
|
||||
<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" id="id16">
|
||||
<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 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" id="id17">
|
||||
<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 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" id="id18">
|
||||
<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 external" href="http://code.google.com/p/yasnippet/issues/detail?id=10">issue 10</a>.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="id19">
|
||||
<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"><tab></span></tt>. Thanks to Trey Jackson. See
|
||||
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>
|
||||
<li>Support <tt class="docutils literal"><span class="pre">dropdown-list.el</span></tt> to be a better way to select multiple
|
||||
candidate when in text mode.</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="id20">
|
||||
<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 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" id="id21">
|
||||
<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" id="id22">
|
||||
<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" id="id23">
|
||||
<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 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" id="id24">
|
||||
<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" id="id25">
|
||||
<h1>0.1.0 / 2008-03-07</h1>
|
||||
<ul class="simple">
|
||||
<li>Embedded elisp support.</li>
|
||||
<li>Fields navigation support.</li>
|
||||
<li>Mirror of fields support.</li>
|
||||
<li>Menu-bar support.</li>
|
||||
<li>Multiple snippets with same name support.</li>
|
||||
<li>Popup menu for multiple snippet with same name support.</li>
|
||||
<li>Transformation of fields support.</li>
|
||||
<li>Load directory support.</li>
|
||||
<li>Compile bundle support.</li>
|
||||
</ul>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
760
doc/define_snippet.html
Normal file
760
doc/define_snippet.html
Normal file
@ -0,0 +1,760 @@
|
||||
<?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" />
|
||||
<meta name="date" content="2008-03-20" />
|
||||
<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="id9">Define snippets in files</a><ul>
|
||||
<li><a class="reference internal" href="#directory-hierarchy" id="id10">Directory hierarchy</a></li>
|
||||
<li><a class="reference internal" href="#file-content" id="id11">File content</a></li>
|
||||
<li><a class="reference internal" href="#define-snippets-using-elisp-code" id="id12">Define snippets using elisp code</a><ul>
|
||||
<li><a class="reference internal" href="#yas-define-snippets" id="id13">yas/define-snippets</a></li>
|
||||
<li><a class="reference internal" href="#yas-compile-bundle" id="id14">yas/compile-bundle</a></li>
|
||||
<li><a class="reference internal" href="#yas-define" id="id15">yas/define</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#the-strategy-to-select-a-snippet" id="id16">The strategy to select a snippet</a><ul>
|
||||
<li><a class="reference internal" href="#finding-the-key" id="id17">Finding the key</a></li>
|
||||
<li><a class="reference internal" href="#the-condition-system" id="id18">The condition system</a></li>
|
||||
<li><a class="reference internal" href="#multiple-snippet-with-the-same-key" id="id19">Multiple snippet with the same key</a><ul>
|
||||
<li><a class="reference internal" href="#popup-menu" id="id20">Popup Menu</a></li>
|
||||
<li><a class="reference internal" href="#just-select-the-first-one" id="id21">Just select the first one</a></li>
|
||||
<li><a class="reference internal" href="#use-a-dropdown-menu-el" id="id22">Use a dropdown-menu.el</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#the-trigger-key" id="id23">The Trigger Key</a><ul>
|
||||
<li><a class="reference internal" href="#the-minor-mode" id="id24">The Minor Mode</a></li>
|
||||
<li><a class="reference internal" href="#the-fallback" id="id25">The Fallback</a></li>
|
||||
<li><a class="reference internal" href="#integration-with-hippie-expand" id="id26">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="id27">Other way to select a snippet</a><ul>
|
||||
<li><a class="reference internal" href="#the-menu" id="id28">The Menu</a></li>
|
||||
<li><a class="reference internal" href="#expanding-from-elisp-code" id="id29">Expanding From Elisp Code</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#the-syntax-of-the-template" id="id30">The Syntax of the Template</a><ul>
|
||||
<li><a class="reference internal" href="#plain-text" id="id31">Plain Text</a></li>
|
||||
<li><a class="reference internal" href="#embedded-elisp-code" id="id32">Embedded elisp code</a></li>
|
||||
<li><a class="reference internal" href="#tab-stops" id="id33">Tab Stops</a></li>
|
||||
<li><a class="reference internal" href="#placeholders" id="id34">Placeholders</a></li>
|
||||
<li><a class="reference internal" href="#id4" id="id35">Mirrors</a></li>
|
||||
<li><a class="reference internal" href="#id5" id="id36">Transformations</a></li>
|
||||
<li><a class="reference internal" href="#indenting" id="id37">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="#id9">Define snippets in files</a></h1>
|
||||
<div class="section" id="directory-hierarchy">
|
||||
<h2><a class="toc-backref" href="#id10">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="#id11">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 <pluskid@gmail.com>
|
||||
#name : __...__
|
||||
# --
|
||||
__${init}__
|
||||
</pre></div>
|
||||
<p>Meta data are specified in the syntax of</p>
|
||||
<div class="highlight"><pre>#data-name : data value
|
||||
</pre></div>
|
||||
<p>Any other text above <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is considered as comment and
|
||||
ignored. Here's a list of currently supported 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="define-snippets-using-elisp-code">
|
||||
<h2><a class="toc-backref" href="#id12">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="#id13">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">&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">'c++-mode</span>
|
||||
<span style="color: #666666">'</span>(
|
||||
(<span style="color: #BA2121">"using"</span> <span style="color: #BA2121">"using namespace ${std};</span>
|
||||
<span style="color: #BA2121">$0"</span> <span style="color: #BA2121">"using namespace ... "</span> <span style="color: #880000">nil</span>)
|
||||
(<span style="color: #BA2121">"class"</span> <span style="color: #BA2121">"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">};"</span> <span style="color: #BA2121">"class ... { ... }"</span> <span style="color: #880000">nil</span>)
|
||||
(<span style="color: #BA2121">"beginend"</span> <span style="color: #BA2121">"${1:v}.begin(), $1.end"</span> <span style="color: #BA2121">"v.begin(), v.end()"</span> <span style="color: #880000">nil</span>)
|
||||
)
|
||||
<span style="color: #19177C">'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="#id14">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">&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>)
|
||||
</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">"yasnippet.el"</span>
|
||||
<span style="color: #BA2121">"./yasnippet-bundle.el"</span>
|
||||
<span style="color: #666666">'</span>(<span style="color: #BA2121">"snippets"</span>)
|
||||
<span style="color: #BA2121">"(yas/initialize)"</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">"SPC")</span></tt> here if
|
||||
you like.</p>
|
||||
</div>
|
||||
<div class="section" id="yas-define">
|
||||
<h3><a class="toc-backref" href="#id15">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">&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="#id16">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="#id17">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">"bar"</span></tt>, <tt class="docutils literal"><span class="pre">"foo_bar"</span></tt>,
|
||||
<tt class="docutils literal"><span class="pre">"#foo_bar"</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">"bar"</span></tt> is found
|
||||
to be a key to some <em>valid</em> snippet, then <tt class="docutils literal"><span class="pre">"foo_bar"</span></tt> and
|
||||
<tt class="docutils literal"><span class="pre">"#foobar"</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">("w"</span> <span class="pre">"w_"</span> <span class="pre">"w_."</span> <span class="pre">"^</span> <span class="pre">")</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="#id18">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">"SPC")</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">'python-mode-hook</span>
|
||||
<span style="color: #666666">'</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">'</span>(<span style="color: #008000; font-weight: bold">if</span> (<span style="color: #19177C">python-in-string/comment</span>)
|
||||
<span style="color: #666666">'</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="#id19">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>
|
||||
<ul class="simple">
|
||||
<li><tt class="docutils literal"><span class="pre">yas/window-system-popup-function</span></tt>: the function used when you
|
||||
have a window system.</li>
|
||||
<li><tt class="docutils literal"><span class="pre">yas/text-popup-function</span></tt>: the function used when you don't have a
|
||||
window system, i.e. when you are working in a terminal.</li>
|
||||
</ul>
|
||||
<blockquote>
|
||||
Currently there're three solution come with YASnippet.</blockquote>
|
||||
<img align="right" alt="images/popup-menu.png" class="align-right" src="images/popup-menu.png" />
|
||||
<div class="section" id="popup-menu">
|
||||
<h3><a class="toc-backref" href="#id20">Popup Menu</a></h3>
|
||||
<p>The function <tt class="docutils literal"><span class="pre">yas/x-popup-menu-for-template</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="just-select-the-first-one">
|
||||
<h3><a class="toc-backref" href="#id21">Just select the first one</a></h3>
|
||||
<p>This one is originally used in terminal mode. It doesn't let you to
|
||||
choose anything, it just select the first one on behalf of you. So I
|
||||
bet you never want to use this. :p</p>
|
||||
</div>
|
||||
<div class="section" id="use-a-dropdown-menu-el">
|
||||
<h3><a class="toc-backref" href="#id22">Use a dropdown-menu.el</a></h3>
|
||||
<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="#id6" 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">'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="#id23">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="#id24">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">"TAB")</span></tt>, however, you can freely
|
||||
set it to some other key. By default, 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="#id7" 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">'yasnippet</span>)
|
||||
(<span style="color: #19177C">add-to-list</span> <span style="color: #19177C">'yas/extra-mode-hooks</span>
|
||||
<span style="color: #19177C">'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>
|
||||
</div>
|
||||
<div class="section" id="the-fallback">
|
||||
<h3><a class="toc-backref" href="#id25">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="#id26">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="#id27">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="the-menu">
|
||||
<h3><a class="toc-backref" href="#id28">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="#id29">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="#id30">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="#id31">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="#id32">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>
|
||||
</div>
|
||||
<div class="section" id="tab-stops">
|
||||
<h2><a class="toc-backref" href="#id33">Tab Stops</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="#id8" 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><div$1>
|
||||
$0
|
||||
</div>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="placeholders">
|
||||
<h2><a class="toc-backref" href="#id34">Placeholders</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="#id35">Mirrors</a></h2>
|
||||
<p>We refer the tab stops with placeholders as a <em>field</em>. A field can have
|
||||
mirrors. Its mirrors will get updated when you change the text of a
|
||||
field. Here's an example:</p>
|
||||
<div class="highlight"><pre>\begin{${1:enumerate}}
|
||||
$0
|
||||
\end{$1}
|
||||
</pre></div>
|
||||
<p>When you type <tt class="docutils literal"><span class="pre">"document"</span></tt> at <tt class="docutils literal"><span class="pre">${1:enumerate}</span></tt>, the word
|
||||
<tt class="docutils literal"><span class="pre">"document"</span></tt> will also be inserted at <tt class="docutils literal"><span class="pre">\end{$1}</span></tt>. The best
|
||||
explanation is to see the screencast(<a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">YouTube</a> or <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">avi video</a>).</p>
|
||||
<p>The tab stops with the same number to the field act as its mirrors. If
|
||||
none of the tab stops has an initial value, the first one is selected
|
||||
as the field and others mirrors.</p>
|
||||
</div>
|
||||
<div class="section" id="id5">
|
||||
<span id="transformations"></span><h2><a class="toc-backref" href="#id36">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 "===" below and above. The "==="
|
||||
should be at least as long as the text. So</p>
|
||||
<div class="highlight"><pre>=====
|
||||
Title
|
||||
=====
|
||||
</pre></div>
|
||||
<p>is a valid title but</p>
|
||||
<div class="highlight"><pre>===
|
||||
Title
|
||||
===
|
||||
</pre></div>
|
||||
<p>is not. Here's an snippet for rst title:</p>
|
||||
<div class="highlight"><pre>${1:$(make-string (string-width text) ?\=)}
|
||||
${1:Title}
|
||||
${1:$(make-string (string-width text) ?\=)}
|
||||
|
||||
$0
|
||||
</pre></div>
|
||||
<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="#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="id7" 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="id8" 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="indenting">
|
||||
<h2><a class="toc-backref" href="#id37">Indenting</a></h2>
|
||||
<p>Many people miss the indenting feature of smart-snippet: when you
|
||||
place a <tt class="docutils literal"><span class="pre">$></span></tt> in your snippet, an <tt class="docutils literal"><span class="pre">(indent-according-to-mode)</span></tt> will
|
||||
be executed there to indent the line. 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 < 10}; ${++i})
|
||||
{$>
|
||||
$0$>
|
||||
}$>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@ -178,6 +178,9 @@ Meta data are specified in the syntax of
|
||||
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
|
||||
@ -186,6 +189,18 @@ ignored. Here's a list of currently supported meta data:
|
||||
* ``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.
|
||||
|
||||
|
||||
|
||||
@ -215,10 +230,10 @@ element should have the following form:
|
||||
|
||||
.. sourcecode:: common-lisp
|
||||
|
||||
(KEY TEMPLATE NAME CONDITION)
|
||||
(KEY TEMPLATE NAME CONDITION GROUP)
|
||||
|
||||
The ``NAME`` and ``CONDITION`` can be omitted if you don't want to
|
||||
provide one. Here's an example:
|
||||
The ``NAME``, ``CONDITION`` and ``GROUP`` can be omitted if you don't
|
||||
want to provide one. Here's an example:
|
||||
|
||||
.. sourcecode:: common-lisp
|
||||
|
||||
@ -278,14 +293,14 @@ The basic syntax for ``yas/define`` is
|
||||
|
||||
.. sourcecode:: common-lisp
|
||||
|
||||
(yas/define mode key template &optional name condition)
|
||||
(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)))
|
||||
(list (list key template name condition group)))
|
||||
|
||||
The strategy to select a snippet
|
||||
================================
|
||||
|
||||
107
doc/faq.html
Normal file
107
doc/faq.html
Normal file
@ -0,0 +1,107 @@
|
||||
<?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" />
|
||||
<meta name="date" content="2008-03-20" />
|
||||
<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="section" id="why-there-s-an-extra-newline">
|
||||
<h1>Why there's an extra newline?</h1>
|
||||
<p>If you have a newline at the end of the snippet definition file, then
|
||||
YASnippet will add a newline when you expanding a snippet. Please
|
||||
don't add a newline at the end if you don't want it when you saving
|
||||
the snippet file.</p>
|
||||
<p>Note some editors will automatically add a newline for you. In Emacs,
|
||||
if you set <tt class="docutils literal"><span class="pre">require-final-newline</span></tt> to <tt class="docutils literal"><span class="pre">t</span></tt>, it will add the final
|
||||
newline for you automatically.</p>
|
||||
</div>
|
||||
<div class="section" id="why-tab-key-doesn-t-expand-a-snippet">
|
||||
<h1>Why TAB key doesn't expand a snippet?</h1>
|
||||
<p>First check the mode line to see if there's <tt class="docutils literal"><span class="pre">yas</span></tt>. If no, then try
|
||||
<tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/minor-mode-on</span></tt> to manually turn on <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> and
|
||||
try to expand the snippet again. If it works, then, you can add the
|
||||
following code to your <tt class="docutils literal"><span class="pre">.emacs</span></tt> <em>before</em> loading YASnippet:</p>
|
||||
<div class="highlight"><pre>(setq yas/extra-mode-hooks '(the-major-mode))
|
||||
</pre></div>
|
||||
<p>where <tt class="docutils literal"><span class="pre">the-major-mode</span></tt> is the major mode in which <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt>
|
||||
isn't enabled by default.</p>
|
||||
<p>If <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is on but the snippet still not expanded. Then
|
||||
try to see what command is bound to the <tt class="docutils literal"><span class="pre">TAB</span></tt> key: press <tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">k</span></tt>
|
||||
and then press <tt class="docutils literal"><span class="pre">TAB</span></tt>. Emacs will show you the result.</p>
|
||||
<p>You'll see a buffer prompted by Emacs saying that <tt class="docutils literal"><span class="pre">TAB</span> <span class="pre">runs</span> <span class="pre">the</span>
|
||||
<span class="pre">command</span> <span class="pre">...</span></tt>. Alternatively, you might see <tt class="docutils literal"><span class="pre"><tab></span> <span class="pre">runs</span> <span class="pre">the</span> <span class="pre">command</span>
|
||||
<span class="pre">...</span></tt>, note the difference between <tt class="docutils literal"><span class="pre">TAB</span></tt> and <tt class="docutils literal"><span class="pre"><tab></span></tt> where the
|
||||
latter has priority. If you see <tt class="docutils literal"><span class="pre"><tab></span></tt> bound to a command other
|
||||
than <tt class="docutils literal"><span class="pre">yas/expand</span></tt>, (e.g. in <tt class="docutils literal"><span class="pre">org-mode</span></tt>) you can try the following
|
||||
code to work around:</p>
|
||||
<div class="highlight"><pre>(add-hook 'org-mode-hook
|
||||
'(lambda ()
|
||||
(make-variable-buffer-local 'yas/trigger-key)
|
||||
(setq yas/trigger-key [tab])))
|
||||
</pre></div>
|
||||
<p>replace <tt class="docutils literal"><span class="pre">org-mode-hook</span></tt> with the major mode hook you are dealing
|
||||
with (<tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">m</span></tt> to see what major mode you are in).</p>
|
||||
<p>If it says <tt class="docutils literal"><span class="pre">TAB</span></tt> but YASnippet still doesn't work, check your
|
||||
configuration and you may also ask for help on the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a>. Don't forget to
|
||||
attach the information on what command is bound to TAB as well as the
|
||||
mode information (Can be obtained by <tt class="docutils literal"><span class="pre">C-h</span> <span class="pre">m</span></tt>).</p>
|
||||
</div>
|
||||
<div class="section" id="how-to-define-snippets-with-named-by-characters-not-supported-by-the-filesystem">
|
||||
<h1>How to define snippets with named by characters not supported by the filesystem?</h1>
|
||||
<p>For example, you want to define a snippet by the key <tt class="docutils literal"><span class="pre"><</span></tt> which is not a
|
||||
valid character for filename on Windows. In this case, you may use
|
||||
<tt class="docutils literal"><span class="pre">yas/define</span></tt> to define the snippet. If you want to enjoy defining
|
||||
snippets in a file, you can use the <tt class="docutils literal"><span class="pre">key</span></tt> property to specify the key of
|
||||
the defined snippet explicitly.</p>
|
||||
<p>Just name your snippet with an arbitrary valid filename, <tt class="docutils literal"><span class="pre">lt</span></tt> for
|
||||
example. and specify <tt class="docutils literal"><span class="pre"><</span></tt> for the <tt class="docutils literal"><span class="pre">key</span></tt> property:</p>
|
||||
<div class="highlight"><pre>#key: <
|
||||
#name: <...></...>
|
||||
# --
|
||||
<${1:div}>$0</$1>
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
BIN
doc/images/group.png
Normal file
BIN
doc/images/group.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 79 KiB |
191
doc/index.html
Normal file
191
doc/index.html
Normal file
@ -0,0 +1,191 @@
|
||||
<?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>Yet Another Snippet extension</title>
|
||||
<meta name="author" content="pluskid" />
|
||||
<meta name="date" content="2008-03-20" />
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
<div class="document" id="yet-another-snippet-extension">
|
||||
<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">Yet Another Snippet extension</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="#getting-started" id="id5">Getting Started</a><ul>
|
||||
<li><a class="reference internal" href="#for-the-busy-or-impatient-people" id="id6">For the busy or impatient people</a></li>
|
||||
<li><a class="reference internal" href="#for-lazy-poeple-or-beginners" id="id7">For lazy poeple or beginners</a></li>
|
||||
<li><a class="reference internal" href="#for-you" id="id8">For you</a></li>
|
||||
<li><a class="reference internal" href="#for-geeks" id="id9">For geeks</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#how-to-contribute" id="id10">How to contribute ?</a><ul>
|
||||
<li><a class="reference internal" href="#issues" id="id11">Issues</a></li>
|
||||
<li><a class="reference internal" href="#suggestion-feature-request" id="id12">Suggestion, Feature Request</a></li>
|
||||
<li><a class="reference internal" href="#snippets" id="id13">Snippets</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#detailed-documentation" id="id14">Detailed Documentation</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<p>YASnippet is a re-design and re-write of my original extension
|
||||
<a class="reference external" href="http://code.google.com/p/smart-snippet/">smart-snippet</a>. It is much cleaner and more powerful than
|
||||
smart-snippet.</p>
|
||||
<div class="section" id="getting-started">
|
||||
<h1><a class="toc-backref" href="#id5">Getting Started</a></h1>
|
||||
<div class="section" id="for-the-busy-or-impatient-people">
|
||||
<h2><a class="toc-backref" href="#id6">For the busy or impatient people</a></h2>
|
||||
<p>Watch the <a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">screencast at YouTube</a> or download <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">the one
|
||||
with a higher resolution</a>.</p>
|
||||
</div>
|
||||
<div class="section" id="for-lazy-poeple-or-beginners">
|
||||
<h2><a class="toc-backref" href="#id7">For lazy poeple or beginners</a></h2>
|
||||
<ol class="arabic">
|
||||
<li><p class="first">Download the latest bundle release <a class="footnote-reference" href="#id3" id="id1">[1]</a> from the <a class="reference external" href="http://code.google.com/p/yasnippet/downloads/list">downloads page</a>.</p>
|
||||
</li>
|
||||
<li><p class="first">Create a directory <tt class="docutils literal"><span class="pre">~/emacs/plugins</span></tt>.</p>
|
||||
</li>
|
||||
<li><p class="first">Unpack the downloaded bundle to that directory.</p>
|
||||
</li>
|
||||
<li><p class="first">Add the following code to your <tt class="docutils literal"><span class="pre">~/.emacs</span></tt> file:</p>
|
||||
<div class="highlight"><pre>(<span style="color: #19177C">add-to-list</span> <span style="color: #19177C">'load-path</span>
|
||||
<span style="color: #BA2121">"~/emacs/plugins"</span>)
|
||||
(<span style="color: #008000">require</span> <span style="color: #19177C">'yasnippet-bundle</span>)
|
||||
</pre></div>
|
||||
</li>
|
||||
</ol>
|
||||
</div>
|
||||
<div class="section" id="for-you">
|
||||
<h2><a class="toc-backref" href="#id8">For you</a></h2>
|
||||
<ol class="arabic">
|
||||
<li><p class="first">Download the latest YASnippet release package <a class="footnote-reference" href="#id4" id="id2">[2]</a> from the
|
||||
<a class="reference external" href="http://code.google.com/p/yasnippet/downloads/list">downloads page</a>.</p>
|
||||
</li>
|
||||
<li><p class="first">Unpack it to a directory and add that directory to your
|
||||
<tt class="docutils literal"><span class="pre">load-path</span></tt>.</p>
|
||||
</li>
|
||||
<li><p class="first">Add the following code to your <tt class="docutils literal"><span class="pre">~/.emacs</span></tt> file:</p>
|
||||
<div class="highlight"><pre>(<span style="color: #008000">require</span> <span style="color: #19177C">'yasnippet</span>) <span style="color: #408080; font-style: italic">;; not yasnippet-bundle</span>
|
||||
(<span style="color: #19177C">yas/initialize</span>)
|
||||
(<span style="color: #19177C">yas/load-directory</span> <span style="color: #BA2121">"/path/to/the/snippets/directory/"</span>)
|
||||
</pre></div>
|
||||
</li>
|
||||
<li><p class="first">You can inspect into the <tt class="docutils literal"><span class="pre">snippets</span></tt> directory for adding your own
|
||||
snippets.</p>
|
||||
</li>
|
||||
<li><p class="first">Detailed document can be found at the <tt class="docutils literal"><span class="pre">doc</span></tt> directory.</p>
|
||||
</li>
|
||||
</ol>
|
||||
</div>
|
||||
<div class="section" id="for-geeks">
|
||||
<h2><a class="toc-backref" href="#id9">For geeks</a></h2>
|
||||
<p>If you want to always follow the latest code. You can check out it
|
||||
from the svn repository:</p>
|
||||
<div class="highlight"><pre>svn checkout http://yasnippet.googlecode.com/svn/trunk/ yasnippet
|
||||
</pre></div>
|
||||
<p>However, I try to release a new version as soon as I made some changes
|
||||
that will affect the normal use or added some new features. So there's
|
||||
usually no need to follow the svn repository. Except that you might
|
||||
find <tt class="docutils literal"><span class="pre">svn</span> <span class="pre">up</span></tt> is more convenient than downloading and unpacking the
|
||||
release package. :D</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="how-to-contribute">
|
||||
<h1><a class="toc-backref" href="#id10">How to contribute ?</a></h1>
|
||||
<p>If you like YASnippet, you can recommendate it to your friends.</p>
|
||||
<div class="section" id="issues">
|
||||
<h2><a class="toc-backref" href="#id11">Issues</a></h2>
|
||||
<p>If you find a bug you can create a new issue at the <a class="reference external" href="http://code.google.com/p/yasnippet/issues/list">issue list</a>. Please describe
|
||||
the problem as clear as possible.</p>
|
||||
</div>
|
||||
<div class="section" id="suggestion-feature-request">
|
||||
<h2><a class="toc-backref" href="#id12">Suggestion, Feature Request</a></h2>
|
||||
<p>There's a <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a> for both smart-snippet and yasnippet. If
|
||||
you have any suggesion, you can post to there and discuss with other
|
||||
members.</p>
|
||||
<p>Especially, there's a <a class="reference external" href="http://code.google.com/p/yasnippet/wiki/WishList">wish list</a> wiki page. I'll collect ideas from
|
||||
the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a> to the <a class="reference external" href="http://code.google.com/p/yasnippet/wiki/WishList">wish list</a>. So you might want to look
|
||||
at the <a class="reference external" href="http://code.google.com/p/yasnippet/wiki/WishList">wish list</a> before you post something.</p>
|
||||
</div>
|
||||
<div class="section" id="snippets">
|
||||
<h2><a class="toc-backref" href="#id13">Snippets</a></h2>
|
||||
<p>YASnippet comes with some default snippet definitions. However, they
|
||||
are far from complete. So I'm calling users to share their
|
||||
snippets. If you have some good snippet definitions, you can post them
|
||||
to the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a>. You can specify the <tt class="docutils literal"><span class="pre">contributor</span></tt>
|
||||
property of the snippet like:</p>
|
||||
<div class="highlight"><pre>#contributor : pluskid <pluskid@gmail.com>
|
||||
#name : __...__
|
||||
# --
|
||||
__${init}__
|
||||
</pre></div>
|
||||
<p>I'll incorporate (some of) them in the release if suitable. However,
|
||||
if you have <em>many</em> snippets (especially when they need to be
|
||||
maintained and updated constantly), it is not suitable to put them in
|
||||
the YASnippet release package. A better way is to make your snippets
|
||||
publicly available and tell me the URL. I'll try to keep a list of
|
||||
them on the wiki page.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="detailed-documentation">
|
||||
<h1><a class="toc-backref" href="#id14">Detailed Documentation</a></h1>
|
||||
<ul class="simple">
|
||||
<li>See <a class="reference external" href="define_snippet.html">this page</a> on how to define a snippet by
|
||||
yourself.</li>
|
||||
<li>Here's the <a class="reference external" href="faq.html">FAQ</a> page.</li>
|
||||
<li>Here's the <a class="reference external" href="changelog.html">ChangeLog</a>.</li>
|
||||
</ul>
|
||||
<table class="docutils footnote" frame="void" id="id3" 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>They usually named like <tt class="docutils literal"><span class="pre">yasnippet-bundle-x.y.z.el.tgz</span></tt> where
|
||||
<tt class="docutils literal"><span class="pre">x.y.z</span></tt> is the version number.</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"><a class="fn-backref" href="#id2">[2]</a></td><td>They usually named like <tt class="docutils literal"><span class="pre">yasnippet.x.y.z.tar.bz2</span></tt>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Loading…
x
Reference in New Issue
Block a user