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

* proof-reading the documentation

Browse Source 
* added link to the new screencast
This commit is contained in:
capitaomorte 2009-09-24 15:59:45 +00:00
parent 5d0b9657e3
commit 037f8fd3ee
12 changed files with 361 additions and 333 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
doc/changelog.html
View File

@ -54,8 +54,8 @@
for other versions can be found <a title=""
href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
</p>
<div class="section" id="upcoming-0-6-1c">
<h1>Upcoming 0.6.1c</h1>
<div class="section" id="c-2009-08-13">
<h1>0.6.1c / 2009-08-13</h1>
<ul class="simple">
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues">issues</a> 99, 98, 93,
90, 91, 88, 87. Thanks everybody.</li>

4
doc/changelog.rst
View File

@ -7,8 +7,8 @@ ChangeLog
.. _Writing Snippets: snippet-development.html
.. _The YASnippet Menu: snippet-menu.html
Upcoming 0.6.1c
===============
0.6.1c / 2009-08-13
===================
* Fixed `issues <http://code.google.com/p/yasnippet/issues>`_ 99, 98, 93,
90, 91, 88, 87. Thanks everybody.

52
doc/index.html
View File

@ -59,7 +59,7 @@
<ul class="simple">
<li><a class="reference internal" href="#video-demo" id="id1">Video Demo</a></li>
<li><a class="reference internal" href="#installation" id="id2">Installation</a><ul>
<li><a class="reference internal" href="#bundle-install" id="id3">Bundle Install</a></li>
<li><a class="reference internal" href="#install-with-yasnippet-bundle-el" id="id3">Install with <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt></a></li>
<li><a class="reference internal" href="#normal-install" id="id4">Normal Install</a></li>
</ul>
</li>
@ -67,16 +67,14 @@
<li><a class="reference internal" href="#bugs-contribution-and-support" id="id6">Bugs, Contribution and Support</a></li>
</ul>
</div>
<p><strong>YASnippet</strong> is a template system for Emacs. It allows you to type a
abbreviation and automatically expand the abbreviation into function
templates.</p>
<p>Bundled language templates includes: C, C++, C#, Perl, Python, Ruby,
SQL, LaTeX, HTML, CSS and more.</p>
<p>The snippet syntax is inspired from TextMate's syntax, you can
even <a class="reference external" href="snippet-development.html#importing-textmate-snippets">import</a>
import most TextMate templates to YASnippet.</p>
<p>YASnippet is a re-write of the extension <a class="reference external" href="http://code.google.com/p/smart-snippet/">smart-snippet</a>. Both are
original creations of <a class="reference external" href="http://pluskid.lifegoo.org">pluskid</a>.</p>
<p><strong>YASnippet</strong> is a template system for Emacs. It allows you to type an
abbreviation and automatically expand it into function
templates. Bundled language templates includes: C, C++, C#, Perl,
Python, Ruby, SQL, LaTeX, HTML, CSS and more.</p>
<p>The snippet syntax is inspired from TextMate's syntax, you can even
<a class="reference external" href="snippet-development.html#importing-textmate-snippets">import</a>
import most TextMate templates. YASnippet is a re-write of the
extension <a class="reference external" href="http://code.google.com/p/smart-snippet/">smart-snippet</a>. Both are original creations of <a class="reference external" href="http://pluskid.lifegoo.org">pluskid</a>.</p>
<div class="section" id="video-demo">
<h1><a class="toc-backref" href="#id1">Video Demo</a></h1>
<object type="application/x-shockwave-flash"
@ -84,21 +82,21 @@ original creations of <a class="reference external" href="http://pluskid.lifegoo
height="344"
align="right"
class="youtube-embed"
data="http://www.youtube.com/v/vOj7btx3ATg">
<param name="movie" value="http://www.youtube.com/v/vOj7btx3ATg"></param>
data="http://www.youtube.com/v/76Ygeg9miao">
<param name="movie" value="http://www.youtube.com/v/76Ygeg9miao"></param>
<param name="wmode" value="transparent"></param>
</object>
<p>Watch the <a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">demo at YouTube</a> (download a higher
<p>Watch the <a class="reference external" href="http://www.youtube.com/watch?v=76Ygeg9miao">demo at YouTube</a> (download a higher
resolution version: <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">yasnippet.avi</a>).</p>
</div>
<div class="section" id="installation">
<h1><a class="toc-backref" href="#id2">Installation</a></h1>
<p>There are two archives of YASnippet. One is a single file compiled
“bundle”, and the other is normal. If all you need is to use the
built-in templates, download the bundle one. If you want to add your
own templates, download the normal one.</p>
<div class="section" id="bundle-install">
<h2><a class="toc-backref" href="#id3">Bundle Install</a></h2>
<p>There are two archives you can download. To quickly tryout YASnippet,
download the simpler &quot;bundle&quot; version. If you plan to modify the
bundled templates and/or build your own, download the &quot;normal&quot;
package.</p>
<div class="section" id="install-with-yasnippet-bundle-el">
<h2><a class="toc-backref" href="#id3">Install with <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt></a></h2>
<ol class="arabic simple">
<li>Download the latest <tt class="docutils literal"><span class="pre">yasnippet-bundle-x.y.z.el.tgz</span></tt> and unpack it.</li>
<li>You'll get a file named <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt>, put it under
@ -107,7 +105,7 @@ own templates, download the normal one.</p>
</ol>
<p>That's it. Now open any one of your language file, you'll see a menu
YASnippet. you can pull the menu to insert a template. Or, you can
type the pre-defined abbrev and press <tt class="docutils literal"><span class="pre">TAB</span></tt> to expand it.</p>
type the a <em>trigger key</em> then press <tt class="docutils literal"><span class="pre">TAB</span></tt> to expand it.</p>
<p>To have Emacs load YASnippet automatically when it starts, put the
following in your <tt class="docutils literal"><span class="pre">~/.emacs</span></tt> file:</p>
<blockquote>
@ -116,13 +114,15 @@ following in your <tt class="docutils literal"><span class="pre">~/.emacs</span>
(<span style="color: #008000">require</span> <span style="color: #19177C">&#39;yasnippet-bundle</span>)
</pre></div>
</blockquote>
<p>The <a class="reference external" href="http://www.youtube.com/watch?v=76Ygeg9miao">youtube video</a>
demonstrates this quick installation.</p>
</div>
<div class="section" id="normal-install">
<h2><a class="toc-backref" href="#id4">Normal Install</a></h2>
<p>For full install of the normal archive, just download and unpack the
latest <tt class="docutils literal"><span class="pre">yasnippet-x.y.z.tar.bz2</span></tt>. You'll get a directory named
<tt class="docutils literal"><span class="pre">yasnippet-x.y.z</span></tt>, put it in your <tt class="docutils literal"><span class="pre">~/.emacs.d/plugins</span></tt> and add the
following in your <tt class="docutils literal"><span class="pre">.emacs</span></tt> file:</p>
<p>To install YASnippet as a normal emacs package, download and unpack
the latest <tt class="docutils literal"><span class="pre">yasnippet-x.y.z.tar.bz2</span></tt>. You'll get a directory named
<tt class="docutils literal"><span class="pre">yasnippet-x.y.z</span></tt>, which you can put it in your
<tt class="docutils literal"><span class="pre">~/.emacs.d/plugins</span></tt> and add the following in your <tt class="docutils literal"><span class="pre">.emacs</span></tt> file:</p>
<blockquote>
<div class="highlight"><pre>(<span style="color: #19177C">add-to-list</span> <span style="color: #19177C">&#39;load-path</span>
<span style="color: #BA2121">&quot;~/.emacs.d/plugins/yasnippet-x.y.z&quot;</span>)
@ -167,7 +167,7 @@ TextMate snippets.</blockquote>
<li><a class="reference external" href="snippet-menu.html">The YASnippet menu</a></li>
</ol>
<blockquote>
Explains how to use the YASnippet menu to explore and learn new
Explains how to use the YASnippet menu to explore, learn and modify
snippets.</blockquote>
</div>
<div class="section" id="bugs-contribution-and-support">

52
doc/index.rst
View File

@ -9,43 +9,40 @@ Yet Another Snippet extension
.. contents::
**YASnippet** is a template system for Emacs. It allows you to type a
abbreviation and automatically expand the abbreviation into function
templates.
**YASnippet** is a template system for Emacs. It allows you to type an
abbreviation and automatically expand it into function
templates. Bundled language templates includes: C, C++, C#, Perl,
Python, Ruby, SQL, LaTeX, HTML, CSS and more.
Bundled language templates includes: C, C++, C#, Perl, Python, Ruby,
SQL, LaTeX, HTML, CSS and more.
The snippet syntax is inspired from TextMate's syntax, you can
even `import <snippet-development.html#importing-textmate-snippets>`_
import most TextMate templates to YASnippet.
YASnippet is a re-write of the extension `smart-snippet`_. Both are
original creations of `pluskid <http://pluskid.lifegoo.org>`_.
The snippet syntax is inspired from TextMate's syntax, you can even
`import <snippet-development.html#importing-textmate-snippets>`_
import most TextMate templates. YASnippet is a re-write of the
extension `smart-snippet`_. Both are original creations of `pluskid
<http://pluskid.lifegoo.org>`_.
.. _smart-snippet: http://code.google.com/p/smart-snippet/
Video Demo
==========
.. youtube:: vOj7btx3ATg
.. youtube:: 76Ygeg9miao
:align: right
Watch the `demo at YouTube
<http://www.youtube.com/watch?v=vOj7btx3ATg>`_ (download a higher
<http://www.youtube.com/watch?v=76Ygeg9miao>`_ (download a higher
resolution version: `yasnippet.avi
<http://yasnippet.googlecode.com/files/yasnippet.avi>`_).
Installation
============
There are two archives of YASnippet. One is a single file compiled
“bundle”, and the other is normal. If all you need is to use the
built-in templates, download the bundle one. If you want to add your
own templates, download the normal one.
There are two archives you can download. To quickly tryout YASnippet,
download the simpler "bundle" version. If you plan to modify the
bundled templates and/or build your own, download the "normal"
package.
Bundle Install
--------------
Install with ``yasnippet-bundle.el``
------------------------------------
1. Download the latest ``yasnippet-bundle-x.y.z.el.tgz`` and unpack it.
2. You'll get a file named ``yasnippet-bundle.el``, put it under
@ -54,7 +51,7 @@ Bundle Install
That's it. Now open any one of your language file, you'll see a menu
YASnippet. you can pull the menu to insert a template. Or, you can
type the pre-defined abbrev and press ``TAB`` to expand it.
type the a *trigger key* then press ``TAB`` to expand it.
To have Emacs load YASnippet automatically when it starts, put the
following in your ``~/.emacs`` file:
@ -65,13 +62,16 @@ following in your ``~/.emacs`` file:
"~/.emacs.d/plugins")
(require 'yasnippet-bundle)
The `youtube video <http://www.youtube.com/watch?v=76Ygeg9miao>`_
demonstrates this quick installation.
Normal Install
--------------
For full install of the normal archive, just download and unpack the
latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named
``yasnippet-x.y.z``, put it in your ``~/.emacs.d/plugins`` and add the
following in your ``.emacs`` file:
To install YASnippet as a normal emacs package, download and unpack
the latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named
``yasnippet-x.y.z``, which you can put it in your
``~/.emacs.d/plugins`` and add the following in your ``.emacs`` file:
.. sourcecode:: common-lisp
@ -114,7 +114,7 @@ Hence this section has been split into separate documents:
4. `The YASnippet menu`_
Explains how to use the YASnippet menu to explore and learn new
Explains how to use the YASnippet menu to explore, learn and modify
snippets.
Bugs, Contribution and Support

189
doc/snippet-development.html
View File

@ -66,46 +66,45 @@
<li><a class="reference internal" href="#key-snippet-abbrev" id="id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></li>
<li><a class="reference internal" href="#name-snippet-name" id="id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></li>
<li><a class="reference internal" href="#condition-snippet-condition" id="id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></li>
<li><a class="reference internal" href="#expand-env-expand-environment" id="id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></li>
<li><a class="reference internal" href="#binding-direct-keybinding" id="id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></li>
<li><a class="reference internal" href="#contributor-snippet-author" id="id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></li>
<li><a class="reference internal" href="#group-snippet-menu-grouping" id="id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> snippet menu grouping</a></li>
<li><a class="reference internal" href="#expand-env-expand-environment" id="id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></li>
<li><a class="reference internal" href="#binding-direct-keybinding" id="id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></li>
<li><a class="reference internal" href="#contributor-snippet-author" id="id13"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></li>
</ul>
</li>
<li><a class="reference internal" href="#template-syntax" id="id13">Template syntax</a><ul>
<li><a class="reference internal" href="#plain-text" id="id14">Plain Text</a></li>
<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id15">Embedded Emacs-lisp code</a></li>
<li><a class="reference internal" href="#tab-stop-fields" id="id16">Tab stop fields</a></li>
<li><a class="reference internal" href="#placeholder-fields" id="id17">Placeholder fields</a></li>
<li><a class="reference internal" href="#id2" id="id18">Mirrors</a></li>
<li><a class="reference internal" href="#mirrors-with-transformations" id="id19">Mirrors with transformations</a></li>
<li><a class="reference internal" href="#fields-with-transformations" id="id20">Fields with transformations</a></li>
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id21">Choosing fields value from a list</a></li>
<li><a class="reference internal" href="#nested-placeholder-fields" id="id22">Nested placeholder fields</a></li>
<li><a class="reference internal" href="#template-syntax" id="id14">Template syntax</a><ul>
<li><a class="reference internal" href="#plain-text" id="id15">Plain Text</a></li>
<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id16">Embedded Emacs-lisp code</a></li>
<li><a class="reference internal" href="#tab-stop-fields" id="id17">Tab stop fields</a></li>
<li><a class="reference internal" href="#placeholder-fields" id="id18">Placeholder fields</a></li>
<li><a class="reference internal" href="#id2" id="id19">Mirrors</a></li>
<li><a class="reference internal" href="#mirrors-with-transformations" id="id20">Mirrors with transformations</a></li>
<li><a class="reference internal" href="#fields-with-transformations" id="id21">Fields with transformations</a></li>
<li><a class="reference internal" href="#choosing-fields-value-from-a-list-and-other-tricks" id="id22">Choosing fields value from a list and other tricks</a></li>
<li><a class="reference internal" href="#nested-placeholder-fields" id="id23">Nested placeholder fields</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizable-variables" id="id23">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-trigger-key" id="id24"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-next-field-key" id="id25"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-prev-field-key" id="id26"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-skip-and-clear-key" id="id27"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-good-grace" id="id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li>
<li><a class="reference internal" href="#yas-indent-line" id="id29"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></li>
<li><a class="reference internal" href="#yas-wrap-around-region" id="id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></li>
<li><a class="reference internal" href="#yas-triggers-in-field" id="id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></li>
<li><a class="reference internal" href="#yas-snippet-revival" id="id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></li>
<li><a class="reference internal" href="#yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook" id="id33"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></li>
<li><a class="reference internal" href="#customizable-variables" id="id24">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-trigger-key" id="id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-next-field-key" id="id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-prev-field-key" id="id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-skip-and-clear-key" id="id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-good-grace" id="id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li>
<li><a class="reference internal" href="#yas-indent-line" id="id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></li>
<li><a class="reference internal" href="#yas-wrap-around-region" id="id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></li>
<li><a class="reference internal" href="#yas-triggers-in-field" id="id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></li>
<li><a class="reference internal" href="#yas-snippet-revival" id="id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></li>
<li><a class="reference internal" href="#yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook" id="id34"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></li>
</ul>
</li>
<li><a class="reference internal" href="#importing-textmate-snippets" id="id34">Importing TextMate snippets</a></li>
<li><a class="reference internal" href="#importing-textmate-snippets" id="id35">Importing TextMate snippets</a></li>
</ul>
</div>
<div class="section" id="snippet-development">
<h1><a class="toc-backref" href="#id3">Snippet development</a></h1>
<div class="section" id="quickly-finding-snippets">
<h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2>
<p>There are some ways you can quickly find a snippet file. Once you find
this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead) and you can
start editing your snippet.</p>
<p>There are some ways you can quickly find a snippet file:</p>
<ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt></p>
<p>Prompts you for a snippet name, then tries to guess a suitable
@ -115,7 +114,8 @@ so you can write your snippet.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/find-snippets</span></tt></p>
<p>Lets you find the snippet file in the directory the snippet was
loaded from (if it exists) like <tt class="docutils literal"><span class="pre">find-file-other-window</span></tt>.</p>
loaded from (if it exists) like <tt class="docutils literal"><span class="pre">find-file-other-window</span></tt>. The
directory searching logic is similar to <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt>.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/visit-snippet-file</span></tt></p>
<p>Prompts you for possible snippet expansions like
@ -123,6 +123,8 @@ loaded from (if it exists) like <tt class="docutils literal"><span class="pre">f
directly to the snippet definition's file, if it exists.</p>
</li>
</ul>
<p>Once you find this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead)
and you can start editing your snippet.</p>
</div>
<div class="section" id="using-the-snippet-mode-major-mode">
<h2><a class="toc-backref" href="#id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h2>
@ -147,31 +149,26 @@ can see what it looks like. This is bound to <tt class="docutils literal"><span
</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>
<p>There are also <em>snippets for writing snippets</em>: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">$f</span></tt> and
<tt class="docutils literal"><span class="pre">$m</span></tt> :-).</p>
</div>
</div>
<div class="section" id="file-content">
<h1><a class="toc-backref" href="#id6">File content</a></h1>
<p>A file defining a snippet may just contain the template for the
snippet. Optionally it can also contains some meta data for the
snippet as well as comments.</p>
<p>Generally speaking, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, then all
contents above that line are considered directives (meta data) and
comments; below that line lies the snippet template.</p>
<p>If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found, the whole file content is considered as the
template.</p>
<p>A file defining a snippet generally contains the template to be
expanded.</p>
<p>Optionally, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, the lines above
it count as comments, some of which can be <em>directives</em> (or meta
data). Snippet directives look like <tt class="docutils literal"><span class="pre">#</span> <span class="pre">property:</span> <span class="pre">value</span></tt> and tweak
certain snippets properties described below. If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found,
the whole file is considered the snippet template.</p>
<p>Here's a typical example:</p>
<div class="highlight"><pre>#contributor : pluskid &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 directives:</p>
<p>Here's a list of currently supported directives:</p>
<div class="section" id="key-snippet-abbrev">
<h2><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></h2>
<p>This is the probably the most important directive, it's the
@ -200,7 +197,9 @@ loaded from.</p>
will only be expanded when the condition code evaluate to some non-nil
value.</p>
<p>See also <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> in <a class="reference external" href="snippet-expansion.html">Expanding snippets</a></p>
<p><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group</span></tt> snippet menu grouping</p>
</div>
<div class="section" id="group-snippet-menu-grouping">
<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> snippet menu grouping</a></h2>
<p>When expanding/visiting snippets from the menu-bar menu, snippets for a
given mode can be grouped into sub-menus . This is useful if one has
too many snippets for a mode which will make the menu too
@ -215,10 +214,11 @@ special file (for this see <a class="reference external" href="snippet-organizat
which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt> group.</p>
</div>
<div class="section" id="expand-env-expand-environment">
<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></h2>
<p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt> <em>varlist</em>
form, i.e. a list of lists assigning values to variables. It can be
used to override variable values while the snippet is being expanded.</p>
<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></h2>
<p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt>
<em>varlist form</em>, i.e. a list of lists assigning values to variables. It
can be used to override variable values while the snippet is being
expanded.</p>
<p>Interesting variables to override are <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> and
<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> (see <a class="reference external" href="snippet-expansion.html">Expanding Snippets</a>).</p>
<p>As an example, you might normally have <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> set to
@ -241,7 +241,7 @@ your hard work. You can then use:</p>
</pre></div>
</div>
<div class="section" id="binding-direct-keybinding">
<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></h2>
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt> direct keybinding</a></h2>
<p>You can use this directive to expand a snippet directly from a normal
Emacs keybinding. The keybinding will be registered in the Emacs
keymap named after the major mode the snippet is active
@ -267,38 +267,39 @@ you want to record the keybinding.</p>
# --
&lt;p&gt;`(when yas/prefix &quot;\n&quot;)`$0`(when yas/prefix &quot;\n&quot;)`&lt;/p&gt;
</pre></div>
<p><em>Note</em> that this feature is still <strong>experimental</strong>, it might go away,
be changed in future release, and should be used with caution: It is
easy to override important keybindings for many basic modes and it is
hard to undefine them. For the moment, the variable
<tt class="docutils literal"><span class="pre">yas/active-keybinding</span></tt> can tell you what snippet keybindings are
active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt to
undefine all the keybindings.</p>
<p><strong>Note</strong>: this feature is still <strong>experimental</strong>, it might go away, be
changed in future release, and should be used with caution: It is easy
to override important keybindings for many basic modes and it is hard
to undefine them. For the moment, the variable
<tt class="docutils literal"><span class="pre">yas/active-keybindings</span></tt> can tell you what snippet keybindings are
active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt
to undefine all the keybindings.</p>
</div>
<div class="section" id="contributor-snippet-author">
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></h2>
<h2><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt> snippet author</a></h2>
<p>This is optional and has no effect whatsoever on snippet
functionality, but it looks nice.</p>
</div>
</div>
<div class="section" id="template-syntax">
<h1><a class="toc-backref" href="#id13">Template syntax</a></h1>
<h1><a class="toc-backref" href="#id14">Template syntax</a></h1>
<p>The syntax of the snippet template is simple but powerful, very
similar to TextMate's.</p>
<div class="section" id="plain-text">
<h2><a class="toc-backref" href="#id14">Plain Text</a></h2>
<h2><a class="toc-backref" href="#id15">Plain Text</a></h2>
<p>Arbitrary text can be included as the content of a template. They are
usually interpreted as plain text, except <tt class="docutils literal"><span class="pre">$</span></tt> and <tt class="docutils literal"><span class="pre">`</span></tt>. You need to
use <tt class="docutils literal"><span class="pre">\</span></tt> to escape them: <tt class="docutils literal"><span class="pre">\$</span></tt> and <tt class="docutils literal"><span class="pre">\`</span></tt>. The <tt class="docutils literal"><span class="pre">\</span></tt> itself may also
needed to be escaped as <tt class="docutils literal"><span class="pre">\\</span></tt> sometimes.</p>
</div>
<div class="section" id="embedded-emacs-lisp-code">
<h2><a class="toc-backref" href="#id15">Embedded Emacs-lisp code</a></h2>
<p>Emacs-Lisp code can be embedded inside the template. They are written
inside back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>):</p>
<p>They are evaluated when the snippet is being expanded. The evaluation
is done in the same buffer as the snippet being expanded. Here's an
example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard dynamically:</p>
<h2><a class="toc-backref" href="#id16">Embedded Emacs-lisp code</a></h2>
<p>Emacs-Lisp code can be embedded inside the template, written inside
back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>). The lisp forms are evaluated when the snippet is
being expanded. The evaluation is done in the same buffer as the
snippet being expanded.</p>
<p>Here's an example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard
dynamically:</p>
<div class="highlight"><pre>#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
#define $1
@ -306,7 +307,7 @@ $0
#endif /* $1 */
</pre></div>
<p>From version 0.6.0, snippets expansions are run with some special
<p>From version 0.6, snippets expansions are run with some special
Emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You
can therefore define a snippet like:</p>
<div class="highlight"><pre>for ($1;$2;$3) {
@ -318,7 +319,7 @@ 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="#id16">Tab stop fields</a></h2>
<h2><a class="toc-backref" href="#id17">Tab stop fields</a></h2>
<p>Tab stops are fields that you can navigate back and forth by <tt class="docutils literal"><span class="pre">TAB</span></tt>
and <tt class="docutils literal"><span class="pre">S-TAB</span></tt>. They are written by <tt class="docutils literal"><span class="pre">$</span></tt> followed with a
number. <tt class="docutils literal"><span class="pre">$0</span></tt> has the special meaning of the <em>exit point</em> of a
@ -330,7 +331,7 @@ fields. Here's a typical example:</p>
</pre></div>
</div>
<div class="section" id="placeholder-fields">
<h2><a class="toc-backref" href="#id17">Placeholder fields</a></h2>
<h2><a class="toc-backref" href="#id18">Placeholder fields</a></h2>
<p>Tab stops can have default values -- a.k.a placeholders. The syntax is
like this:</p>
<div class="highlight"><pre>${N:default value}
@ -341,7 +342,7 @@ typing. The number can be omitted if you don't want to create
<a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p>
</div>
<div class="section" id="id2">
<span id="mirrors"></span><h2><a class="toc-backref" href="#id18">Mirrors</a></h2>
<span id="mirrors"></span><h2><a class="toc-backref" href="#id19">Mirrors</a></h2>
<p>We refer the tab stops with placeholders as a <em>field</em>. A field can have
mirrors. Its mirrors will get updated when you change the text of a
field. Here's an example:</p>
@ -357,7 +358,7 @@ 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="#id19">Mirrors with transformations</a></h2>
<span id="transformations"></span><h2><a class="toc-backref" href="#id20">Mirrors with transformations</a></h2>
<p>If the value of an <tt class="docutils literal"><span class="pre">${n:</span></tt>-construct starts with and contains <tt class="docutils literal"><span class="pre">$(</span></tt>,
then it is interpreted as a mirror for field <tt class="docutils literal"><span class="pre">n</span></tt> with a
transformation. The mirror's text content is calculated according to
@ -405,7 +406,7 @@ $0
</pre></div>
</div>
<div class="section" id="fields-with-transformations">
<h2><a class="toc-backref" href="#id20">Fields with transformations</a></h2>
<h2><a class="toc-backref" href="#id21">Fields with transformations</a></h2>
<p>From version 0.6 on, you can also have lisp transformation inside
fields. These work mostly mirror transformations but are evaluated
when you first enter the field, after each change you make to the
@ -428,8 +429,8 @@ 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="#id21">Choosing fields value from a list</a></h2>
<div class="section" id="choosing-fields-value-from-a-list-and-other-tricks">
<h2><a class="toc-backref" href="#id22">Choosing fields value from a list and other tricks</a></h2>
<p>As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
<tt class="docutils literal"><span class="pre">yas/field-modified-p</span></tt> and <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Because of this
@ -441,11 +442,21 @@ you select default values for it.</p>
&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>
using the two variables.</p>
<p>Here's another use, for LaTeX-mode, which calls reftex-label just as
you enter snippet field 2. This one makes use of <tt class="docutils literal"><span class="pre">yas/modified-p</span></tt>
directly.</p>
<div class="highlight"><pre>\section{${1:&quot;Titel der Tour&quot;}}%
\index{$1}%
\label{{2:&quot;waiting for reftex-label call...&quot;$(unless yas/modified-p (reftex-label nil &#39;dont-
insert))}}%
</pre></div>
<p>The function <tt class="docutils literal"><span class="pre">yas/verify-value</span></tt> has another neat trick, and makes
use of <tt class="docutils literal"><span class="pre">yas/moving-away-p</span></tt>. Try it and see! Also, check out this
<a class="reference external" href="http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662">thread</a></p>
</div>
<div class="section" id="nested-placeholder-fields">
<h2><a class="toc-backref" href="#id22">Nested placeholder fields</a></h2>
<h2><a class="toc-backref" href="#id23">Nested placeholder fields</a></h2>
<p>From version 0.6 on, you can also have nested placeholders of the type:</p>
<div class="highlight"><pre>&lt;div${1: id=&quot;${2:some_id}&quot;}&gt;$0&lt;/div&gt;
</pre></div>
@ -460,9 +471,9 @@ performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-
</div>
</div>
<div class="section" id="customizable-variables">
<h1><a class="toc-backref" href="#id23">Customizable variables</a></h1>
<h1><a class="toc-backref" href="#id24">Customizable variables</a></h1>
<div class="section" id="yas-trigger-key">
<h2><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2>
<h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2>
<p>The key bound to <tt class="docutils literal"><span class="pre">yas/expand</span></tt> when function <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is
active.</p>
<p>Value is a string that is converted to the internal Emacs key
@ -470,7 +481,7 @@ representation using <tt class="docutils literal"><span class="pre">read-kbd-mac
<p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
</div>
<div class="section" id="yas-next-field-key">
<h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2>
<h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2>
<p>The key to navigate to next field when a snippet is active.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
@ -478,7 +489,7 @@ representation using <tt class="docutils literal"><span class="pre">read-kbd-mac
<p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
</div>
<div class="section" id="yas-prev-field-key">
<h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2>
<h2><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2>
<p>The key to navigate to previous field when a snippet is active.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
@ -486,7 +497,7 @@ representation using <tt class="docutils literal"><span class="pre">read-kbd-mac
<p>Default value is <tt class="docutils literal"><span class="pre">(&quot;&lt;backtab&gt;&quot;</span> <span class="pre">&quot;&lt;S-tab&gt;)&quot;</span></tt>.</p>
</div>
<div class="section" id="yas-skip-and-clear-key">
<h2><a class="toc-backref" href="#id27"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></h2>
<h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></h2>
<p>The key to clear the currently active field.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
@ -494,12 +505,12 @@ representation using <tt class="docutils literal"><span class="pre">read-kbd-mac
<p>Default value is <tt class="docutils literal"><span class="pre">&quot;C-d&quot;</span></tt>.</p>
</div>
<div class="section" id="yas-good-grace">
<h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2>
<h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2>
<p>If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
snippet definitions. An error string &quot;[yas] error&quot; is returned instead.</p>
</div>
<div class="section" id="yas-indent-line">
<h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2>
<h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2>
<p>The variable <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> controls the indenting. It is bound
to <tt class="docutils literal"><span class="pre">'auto</span></tt> by default, which causes your snippet to be indented
according to the mode of the buffer it was inserted in.</p>
@ -520,7 +531,7 @@ $0$&gt;
</pre></div>
</div>
<div class="section" id="yas-wrap-around-region">
<h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2>
<h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2>
<p>If non-nil, YASnippet will try to expand the snippet's exit marker
around the currently selected region. When this variable is set to t,
this has the same effect has using the <tt class="docutils literal"><span class="pre">`yas/selected-text`</span></tt> inline
@ -534,18 +545,18 @@ the region), then press <tt class="docutils literal"><span class="pre">yas/trigg
spring back to life inside your new snippet.</p>
</div>
<div class="section" id="yas-triggers-in-field">
<h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2>
<h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2>
<p>If non-nil, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> can trigger stacked expansions,
that is a snippet expansion inside another snippet
expansion. Otherwise, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> just tries to move on to
the next field.</p>
</div>
<div class="section" id="yas-snippet-revival">
<h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2>
<h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2>
<p>Non-nil means re-activate snippet fields after undo/redo.</p>
</div>
<div class="section" id="yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook">
<h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></h2>
<h2><a class="toc-backref" href="#id34"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></h2>
<p>These hooks are called, respectively, before the insertion of a
snippet and after exiting the snippet. If you find any strange but
functional use for them, that's probably a design flaw in YASnippet,
@ -553,7 +564,7 @@ so let us know.</p>
</div>
</div>
<div class="section" id="importing-textmate-snippets">
<h1><a class="toc-backref" href="#id34">Importing TextMate snippets</a></h1>
<h1><a class="toc-backref" href="#id35">Importing TextMate snippets</a></h1>
<p>There are a couple of tools that take TextMate's &quot;.tmSnippet&quot; xml
files and create YASnippet definitions:</p>
<blockquote>

102
doc/snippet-development.rst
View File

@ -15,9 +15,7 @@ Snippet development
Quickly finding snippets
------------------------
There are some ways you can quickly find a snippet file. Once you find
this file it will be set to ``snippet-mode`` (see ahead) and you can
start editing your snippet.
There are some ways you can quickly find a snippet file:
* ``M-x yas/new-snippet``
@ -29,7 +27,8 @@ start editing your snippet.
* ``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``.
loaded from (if it exists) like ``find-file-other-window``. The
directory searching logic is similar to ``M-x yas/new-snippet``.
* ``M-x yas/visit-snippet-file``
@ -37,6 +36,9 @@ start editing your snippet.
``yas/insert-snippet``, but instead of expanding it, takes you
directly to the snippet definition's file, if it exists.
Once you find this file it will be set to ``snippet-mode`` (see ahead)
and you can start editing your snippet.
Using the ``snippet-mode`` major mode
-------------------------------------
@ -60,22 +62,20 @@ Two commands are defined in this mode:
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``.
There are also *snippets for writing snippets*: ``vars``, ``$f`` and
``$m`` :-).
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.
A file defining a snippet generally contains the template to be
expanded.
Generally speaking, if the file contains a line of ``# --``, then all
contents above that line are considered directives (meta data) and
comments; below that line lies the snippet template.
If no ``# --`` is found, the whole file content is considered as the
template.
Optionally, if the file contains a line of ``# --``, the lines above
it count as comments, some of which can be *directives* (or meta
data). Snippet directives look like ``# property: value`` and tweak
certain snippets properties described below. If no ``# --`` is found,
the whole file is considered the snippet template.
Here's a typical example:
@ -86,14 +86,7 @@ Here's a typical example:
# --
__${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 directives:
Here's a list of currently supported directives:
``# key:`` snippet abbrev
--------------------------
@ -122,7 +115,6 @@ snippet -- especially distinguishable among similar snippets.
If you omit this name it will default to the file name the snippet was
loaded from.
``# condition:`` snippet condition
----------------------------------
This is a piece of Emacs-lisp code. If a snippet has a condition, then it
@ -132,8 +124,8 @@ value.
See also ``yas/buffer-local-condition`` in `Expanding snippets`_
``# group`` snippet menu grouping
``# group:`` snippet menu grouping
----------------------------------
When expanding/visiting snippets from the menu-bar menu, snippets for a
given mode can be grouped into sub-menus . This is useful if one has
@ -154,14 +146,14 @@ which is under the ``control structure`` group.
``# expand-env:`` expand environment
------------------------------------
This is another piece of Emacs-lisp code in the form of a ``let`` *varlist*
form, i.e. a list of lists assigning values to variables. It can be
used to override variable values while the snippet is being expanded.
This is another piece of Emacs-lisp code in the form of a ``let``
*varlist form*, i.e. a list of lists assigning values to variables. It
can be used to override variable values while the snippet is being
expanded.
Interesting variables to override are ``yas/wrap-around-region`` and
``yas/indent-line`` (see `Expanding Snippets`_).
As an example, you might normally have ``yas/indent-line`` set to
``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this
particularly brilliant piece of ASCII art these values would mess up
@ -219,13 +211,13 @@ you want to record the keybinding.
# --
<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
*Note* that this feature is still **experimental**, it might go away,
be changed in future release, and should be used with caution: It is
easy to override important keybindings for many basic modes and it is
hard to undefine them. For the moment, the variable
``yas/active-keybinding`` can tell you what snippet keybindings are
active and the function ``yas/kill-snippet-keybindings`` will attempt to
undefine all the keybindings.
**Note**: this feature is still **experimental**, it might go away, be
changed in future release, and should be used with caution: It is easy
to override important keybindings for many basic modes and it is hard
to undefine them. For the moment, the variable
``yas/active-keybindings`` can tell you what snippet keybindings are
active and the function ``yas/kill-snippet-keybindings`` will attempt
to undefine all the keybindings.
``# contributor:`` snippet author
---------------------------------------------------
@ -251,12 +243,13 @@ needed to be escaped as ``\\`` sometimes.
Embedded Emacs-lisp code
------------------------
Emacs-Lisp code can be embedded inside the template. They are written
inside back-quotes (`````):
Emacs-Lisp code can be embedded inside the template, written inside
back-quotes (`````). The lisp forms are evaluated when the snippet is
being expanded. The evaluation is done in the same buffer as the
snippet being expanded.
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:
Here's an example for ``c-mode`` to calculate the header file guard
dynamically:
.. sourcecode:: text
@ -267,7 +260,7 @@ example for ``c-mode`` to calculate the header file guard dynamically:
#endif /* $1 */
From version 0.6.0, snippets expansions are run with some special
From version 0.6, 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:
@ -432,8 +425,8 @@ 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
---------------------------------
Choosing fields value from a list and other tricks
--------------------------------------------------
As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably
@ -450,8 +443,23 @@ The ``yas/choose-value`` does this work for you. For example:
</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.
using the two variables.
Here's another use, for LaTeX-mode, which calls reftex-label just as
you enter snippet field 2. This one makes use of ``yas/modified-p``
directly.
.. sourcecode:: text
\section{${1:"Titel der Tour"}}%
\index{$1}%
\label{{2:"waiting for reftex-label call..."$(unless yas/modified-p (reftex-label nil 'dont-
insert))}}%
The function ``yas/verify-value`` has another neat trick, and makes
use of ``yas/moving-away-p``. Try it and see! Also, check out this
`thread
<http://groups.google.com/group/smart-snippet/browse_thread/thread/282a90a118e1b662>`_
Nested placeholder fields
-------------------------

70
doc/snippet-expansion.html
View File

@ -74,7 +74,7 @@
<li><a class="reference internal" href="#the-condition-system" id="id12">The condition system</a></li>
<li><a class="reference internal" href="#multiples-snippet-with-the-same-key" id="id13">Multiples snippet with the same key</a><ul>
<li><a class="reference internal" href="#use-the-x-window-system" id="id14">Use the X window system</a></li>
<li><a class="reference internal" href="#use-built-in-emacs-selection-methods" id="id15">Use built-in Emacs selection methods</a></li>
<li><a class="reference internal" href="#minibuffer-prompting" id="id15">Minibuffer prompting</a></li>
<li><a class="reference internal" href="#use-dropdown-menu-el" id="id16">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></li>
<li><a class="reference internal" href="#roll-your-own" id="id17">Roll your own</a></li>
</ul>
@ -95,9 +95,10 @@
<h1><a class="toc-backref" href="#id2">Triggering expansion</a></h1>
<p>You can use YASnippet to expand snippets in different ways:</p>
<ul class="simple">
<li>By typing a snippet abbrev and then pressing the key defined in
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to &quot;TAB&quot;). This works in a
buffer where the minor mode <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active;</li>
<li>By typing an abbrev, the snippet <em>trigger key</em>, and then pressing
the key defined in <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to
&quot;TAB&quot;). This works in buffers where the minor mode
<tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active;</li>
<li>By invoking the command <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> (either by typing
<tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/insert-snippet</span></tt> or its keybinding). This does <em>not</em>
require <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active.</li>
@ -171,12 +172,12 @@ prefer.</p>
</div>
<div class="section" id="expanding-from-emacs-lisp-code">
<h2><a class="toc-backref" href="#id9">Expanding from emacs-lisp code</a></h2>
<p>Sometimes you might want to expand a snippet directly by calling a
functin from elisp code. You should call <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt>
instead of <tt class="docutils literal"><span class="pre">yas/expand</span></tt> in this case.</p>
<p>As with expanding from the menubar, condition system and multiple
candidates won't exists here. In fact, expanding from menubar has the
same effect of evaluating the follow code:</p>
<p>Sometimes you might want to expand a snippet directly from you own
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, the condition system and multiple
candidates doesn't affect expansion. In fact, expanding from the
YASnippet menu has the same effect of evaluating the follow code:</p>
<div class="highlight"><pre>(<span style="color: #19177C">yas/expand-snippet</span> <span style="color: #19177C">template</span>)
</pre></div>
<p>See the internal documentation on <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> for more
@ -188,7 +189,7 @@ information.</p>
<div class="section" id="eligible-snippets">
<h2><a class="toc-backref" href="#id11">Eligible snippets</a></h2>
<p>YASnippet does quite a bit of filtering to find out which snippets are
eligible for expanding at point.</p>
eligible for expanding at the current cursor position.</p>
<p>In particular, the following things matter:</p>
<ul>
<li><p class="first">Currently loaded snippets tables</p>
@ -197,21 +198,22 @@ eligible for expanding at point.</p>
<tt class="docutils literal"><span class="pre">html-mode</span></tt>, <tt class="docutils literal"><span class="pre">ruby-mode</span></tt>, etc...</p>
</li>
<li><p class="first">Major mode of the current buffer</p>
<p>If it matches one of the loaded snippet tables, then all that
table's snippets are considered for expansion. Use <tt class="docutils literal"><span class="pre">M-x</span>
<span class="pre">describe-variable</span> <span class="pre">RET</span> <span class="pre">major-mode</span> <span class="pre">RET</span></tt> to find out which mode you
are in currently.</p>
<p>If the currrent major mode matches one of the loaded snippet tables,
then all that table's snippets are considered for expansion. Use
<tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-variable</span> <span class="pre">RET</span> <span class="pre">major-mode</span> <span class="pre">RET</span></tt> to find out which major
mode you are in currently.</p>
</li>
<li><p class="first">Parent tables</p>
<p>Snippet tables defined as parent of some other table considered in
the previous step are also considered.</p>
<p>Snippet tables defined as the parent of some other eligible table
are also considered. This works recursively, i.e. parents of parents
of eligible tables are also considered.</p>
</li>
<li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/mode-symbol</span></tt> variable</p>
<p>This can be used to consider snippet tables whose name does not
correspond to a major mode. If you set this variable to a name ,
like <tt class="docutils literal"><span class="pre">rinari-minor-mode</span></tt>, you can have some snippets expand only
in that minor mode. Naturally, you want to set this conditionally,
i.e. only when entering that minor mode, using a hook is a good
i.e. only when entering that minor mode, so using a hook is a good
idea.</p>
</li>
</ul>
@ -223,10 +225,10 @@ idea.</p>
</pre></div>
<ul>
<li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> variable</p>
<p>This variable provides more fine grained control over what snippets
can be expanded in the current buffer. The default value, won't let
you expand snippets inside comments or string literals for
example. See <a class="reference internal" href="#the-condition-system">The condition system</a> for more info.</p>
<p>This variable provides finer grained control over what snippets can
be expanded in the current buffer. The default value won't let you
expand snippets inside comments or string literals for example. See
<a class="reference internal" href="#the-condition-system">The condition system</a> for more info.</p>
</li>
</ul>
</div>
@ -294,9 +296,9 @@ other snippets like <tt class="docutils literal"><span class="pre">if</span></tt
<p>The rules outlined <a class="reference external" href="Eligiblesnippets">above</a> can return more than
one snippet to be expanded at point.</p>
<p>When there are multiple candidates, YASnippet will let you select
one. The UI for selecting multiple candidate can be customized. A
customization variable, called <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> defines your
preferred method of being prompted for snippets.</p>
one. The UI for selecting multiple candidate can be customized through
<tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> , which defines your preferred methods 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>
@ -318,8 +320,8 @@ support, this menu will be rendered with your gtk theme.</li>
</ul>
<img align="right" alt="images/ido-menu.png" class="align-right" src="images/ido-menu.png" />
</div>
<div class="section" id="use-built-in-emacs-selection-methods">
<h3><a class="toc-backref" href="#id15">Use built-in Emacs selection methods</a></h3>
<div class="section" id="minibuffer-prompting">
<h3><a class="toc-backref" href="#id15">Minibuffer prompting</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>
@ -390,11 +392,11 @@ eligible tables.</p>
<div class="section" id="yas-key-syntaxes">
<h2><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt></a></h2>
<p>The default searching strategy is quite powerful. For example, in
<tt class="docutils literal"><span class="pre">c-mode</span></tt>, <tt class="docutils literal"><span class="pre">&quot;bar&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;foo_bar&quot;</span></tt>, <tt class="docutils literal"><span class="pre">&quot;#foo_bar&quot;</span></tt> can all be
recognized as a snippet key. Furthermore, the searching is in that
order. In other words, if <tt class="docutils literal"><span class="pre">&quot;bar&quot;</span></tt> is found to be a key to some
<em>valid</em> snippet, then <tt class="docutils literal"><span class="pre">&quot;foo_bar&quot;</span></tt> and <tt class="docutils literal"><span class="pre">&quot;#foobar&quot;</span></tt> won't be
searched.</p>
<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">&quot;#foo_bar&quot;</span></tt> can all be recognized
as a snippet key. Furthermore, the searching is in that order. In
other words, if <tt class="docutils literal"><span class="pre">bar</span></tt> is found to be a key to some <em>valid</em> snippet,
then that snippet is expanded and replaces the <tt class="docutils literal"><span class="pre">bar</span></tt>. Snippets
pointed to by <tt class="docutils literal"><span class="pre">foo_bar</span></tt> and <tt class="docutils literal"><span class="pre">&quot;#foobar</span></tt> won't be considered.</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
@ -405,8 +407,8 @@ following thing until found one:</p>
<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>
<p>But you'd better keep the default value unless you want to understand
how Emacs's syntax rules work...</p>
</div>
</div>
</div>

69
doc/snippet-expansion.rst
View File

@ -15,9 +15,10 @@ Triggering expansion
You can use YASnippet to expand snippets in different ways:
* By typing a snippet abbrev and then pressing the key defined in
``yas/trigger-key`` (which defaults to "TAB"). This works in a
buffer where the minor mode ``yas/minor-mode`` is active;
* By typing an abbrev, the snippet *trigger key*, and then pressing
the key defined in ``yas/trigger-key`` (which defaults to
"TAB"). This works in buffers where the minor mode
``yas/minor-mode`` is active;
* By invoking the command ``yas/insert-snippet`` (either by typing
``M-x yas/insert-snippet`` or its keybinding). This does *not*
@ -115,13 +116,13 @@ prefer.
Expanding from emacs-lisp 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.
Sometimes you might want to expand a snippet directly from you own
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:
As with expanding from the menubar, the condition system and multiple
candidates doesn't affect expansion. In fact, expanding from the
YASnippet menu has the same effect of evaluating the follow code:
.. sourcecode:: common-lisp
@ -137,7 +138,7 @@ Eligible snippets
-----------------
YASnippet does quite a bit of filtering to find out which snippets are
eligible for expanding at point.
eligible for expanding at the current cursor position.
In particular, the following things matter:
@ -149,15 +150,16 @@ In particular, the following things matter:
* Major mode of the current buffer
If it matches one of the loaded snippet tables, then all that
table's snippets are considered for expansion. Use ``M-x
describe-variable RET major-mode RET`` to find out which mode you
are in currently.
If the currrent major mode matches one of the loaded snippet tables,
then all that table's snippets are considered for expansion. Use
``M-x describe-variable RET major-mode RET`` to find out which major
mode you are in currently.
* Parent tables
Snippet tables defined as parent of some other table considered in
the previous step are also considered.
Snippet tables defined as the parent of some other eligible table
are also considered. This works recursively, i.e. parents of parents
of eligible tables are also considered.
* Buffer-local ``yas/mode-symbol`` variable
@ -165,7 +167,7 @@ In particular, the following things matter:
correspond to a major mode. If you set this variable to a name ,
like ``rinari-minor-mode``, you can have some snippets expand only
in that minor mode. Naturally, you want to set this conditionally,
i.e. only when entering that minor mode, using a hook is a good
i.e. only when entering that minor mode, so using a hook is a good
idea.
.. sourcecode:: common-lisp
@ -178,10 +180,10 @@ In particular, the following things matter:
* Buffer-local ``yas/buffer-local-condition`` variable
This variable provides more fine grained control over what snippets
can be expanded in the current buffer. The default value, won't let
you expand snippets inside comments or string literals for
example. See `The condition system`_ for more info.
This variable provides finer grained control over what snippets can
be expanded in the current buffer. The default value won't let you
expand snippets inside comments or string literals for example. See
`The condition system`_ for more info.
The condition system
--------------------
@ -260,9 +262,9 @@ The rules outlined `above <Eligible snippets>`_ can return more than
one snippet to be expanded at point.
When there are multiple candidates, YASnippet will let you select
one. The UI for selecting multiple candidate can be customized. A
customization variable, called ``yas/prompt-functions`` defines your
preferred method of being prompted for snippets.
one. The UI for selecting multiple candidate can be customized through
``yas/prompt-functions`` , which defines your preferred methods 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
@ -293,8 +295,8 @@ which means:
.. image:: images/ido-menu.png
:align: right
Use built-in Emacs selection methods
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Minibuffer prompting
~~~~~~~~~~~~~~~~~~~~
You can use functions ``yas/completing-prompt`` for the classic emacs
completion method or ``yas/ido-prompt`` for a much nicer looking
@ -324,7 +326,6 @@ Customizable Variables
``yas/prompt-functions``
------------------------
You can write a function and add it to the ``yas/prompt-functions``
list. These functions are called with the following arguments:
@ -383,11 +384,11 @@ This affects ``yas/insert-snippet``, ``yas/visit-snippet-file``
--------------------
The default searching strategy is quite powerful. For example, in
``c-mode``, ``"bar"``, ``"foo_bar"``, ``"#foo_bar"`` can all be
recognized as a snippet key. Furthermore, 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.
``c-mode``, ``bar``, ``foo_bar``, ``"#foo_bar"`` can all be recognized
as a snippet key. Furthermore, the searching is in that order. In
other words, if ``bar`` is found to be a key to some *valid* snippet,
then that snippet is expanded and replaces the ``bar``. Snippets
pointed to by ``foo_bar`` and ``"#foobar`` won't be considered.
However, this strategy can also be customized easily from the
``yas/key-syntaxes`` variable. It is a list of syntax rules, the
@ -399,7 +400,7 @@ following thing until found one:
* 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.
But you'd better keep the default value unless you want to understand
how Emacs's syntax rules work...

2
doc/snippet-menu.html
View File

@ -65,7 +65,7 @@
</ul>
</div>
<p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active, YASnippet will setup a menu just
after the Buffers Menu in the menubar.</p>
after the &quot;Buffers&quot; menu in the menubar.</p>
<p>In this menu, you can find</p>
<ul class="simple">
<li>The currently loaded snippet definitions, organized by major mode,

2
doc/snippet-menu.rst
View File

@ -5,7 +5,7 @@ YASnippet menu
.. contents::
When ``yas/minor-mode`` is active, YASnippet will setup a menu just
after the Buffers Menu in the menubar.
after the "Buffers" menu in the menubar.
In this menu, you can find

92
doc/snippet-organization.html
View File

@ -57,34 +57,35 @@
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#loading-snippets" id="id4">Loading snippets</a></li>
<li><a class="reference internal" href="#id2" id="id5">Organizing snippets</a><ul>
<li><a class="reference internal" href="#nested-organization" id="id6">Nested organization</a></li>
<li><a class="reference internal" href="#the-yas-parents-file" id="id7">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></li>
<li><a class="reference internal" href="#the-yas-make-groups-file" id="id8">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></li>
<li><a class="reference internal" href="#using-plain-file-names" id="id9">Using plain file names</a></li>
<li><a class="reference internal" href="#loading-snippets" id="id3">Loading snippets</a></li>
<li><a class="reference internal" href="#id2" id="id4">Organizing snippets</a><ul>
<li><a class="reference internal" href="#nested-organization" id="id5">Nested organization</a></li>
<li><a class="reference internal" href="#the-yas-parents-file" id="id6">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></li>
<li><a class="reference internal" href="#the-yas-make-groups-file" id="id7">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></li>
<li><a class="reference internal" href="#using-plain-file-names" id="id8">Using plain file names</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id3" id="id10">YASnippet bundle</a></li>
<li><a class="reference internal" href="#customizable-variables" id="id11">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-root-directory" id="id12"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></li>
<li><a class="reference internal" href="#yas-ignore-filenames-as-triggers" id="id13"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></li>
<li><a class="reference internal" href="#yasnippet-bundle" id="id9">YASnippet bundle</a></li>
<li><a class="reference internal" href="#customizable-variables" id="id10">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-root-directory" id="id11"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></li>
<li><a class="reference internal" href="#yas-ignore-filenames-as-triggers" id="id12"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></li>
</ul>
</li>
</ul>
</div>
<div class="section" id="loading-snippets">
<h1><a class="toc-backref" href="#id4">Loading snippets</a></h1>
<p>Snippet definitions are stored in files in the filesystem and you have
to arrange for YASnippet to load them (unless you use a <a class="reference external" href="mailto:index.html&#64;bundle-install">YASnippet
bundle</a>) into <em>snippet tables</em>.</p>
<p>The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will look up
these snippet tables and (hopefully) expand your intended snippet.</p>
<h1><a class="toc-backref" href="#id3">Loading snippets</a></h1>
<p>Snippet definitions are stored in files in the filesystem. Unless you
use the simpler <a class="reference external" href="mailto:index.html&#64;installation">bundle version</a>), these
are arranged so that YASnippet can load them into <em>snippet
tables</em>. The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will
look up these snippet tables and (hopefully) expand the snippet you
intended.</p>
<p>The non-bundle version of YASnippet, once unpacked, comes with a full
directory of snippets, which you can copy somewhere and use. You can
also create or download, one or more directories.</p>
also create or download more directories.</p>
<p>Once these directories are in place reference them in the variable
<tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> and then load them with <tt class="docutils literal"><span class="pre">yas/load-directory</span></tt>:</p>
<tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> and load them with <tt class="docutils literal"><span class="pre">yas/load-directory</span></tt>:</p>
<div class="highlight"><pre><span style="color: #408080; font-style: italic">;; Develop and keep personal snippets under ~/emacs.d/mysnippets</span>
(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/root-directory</span> <span style="color: #BA2121">&quot;~/emacs.d/mysnippets&quot;</span>)
@ -105,12 +106,12 @@ Snippets</a>.</p>
<span style="color: #408080; font-style: italic">;; Map `yas/load-directory&#39; to every element</span>
(<span style="color: #008000">mapc</span> <span style="color: #19177C">&#39;yas/load-directory</span> <span style="color: #19177C">yas/root-directory</span>)
</pre></div>
<p>Here the directories after the first are loaded, their snippets
considered for expansion, but development still happens in
&quot;~/emacs.d/mysnippets&quot;</p>
<p>In this last example, the all the directories are loaded and their
snippets considered for expansion. However development still happens
in the first element, &quot;~/emacs.d/mysnippets&quot;.</p>
</div>
<div class="section" id="id2">
<h1><a class="toc-backref" href="#id5">Organizing snippets</a></h1>
<h1><a class="toc-backref" href="#id4">Organizing snippets</a></h1>
<p>Once you've setup <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> , you can store snippets
inside sub-directories of these directories.</p>
<p>Snippet definitions are put in plain text files. They are arranged by
@ -118,9 +119,9 @@ sub-directories, and the snippet tables are named after these directories.</p>
<p>The name corresponds to the Emacs mode where you want expansion to
take place. 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> sub-directory. You can also skip snippet storage altogether
and use the bundle (see <a class="reference external" href="mailto:index.html&#64;bundle-install">YASnippet bundle</a>).</p>
and use the bundle (see <a class="reference internal" href="#yasnippet-bundle">YASnippet bundle</a>).</p>
<div class="section" id="nested-organization">
<h2><a class="toc-backref" href="#id6">Nested organization</a></h2>
<h2><a class="toc-backref" href="#id5">Nested organization</a></h2>
<p>Here is an excerpt of a directory hierarchy containing snippets
for some modes:</p>
<div class="highlight"><pre>$ tree
@ -140,20 +141,23 @@ for some modes:</p>
`-- time
</pre></div>
<p>A parent directory acts as a <em>parent table</em> of any of its
sub-directories. This is one of the ways YASnippet can 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">java-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>.</p>
sub-directories. This is one of the ways different Emacs major modes
can share snippet definitions. As you can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and
<tt class="docutils literal"><span class="pre">java-mode</span></tt> share the same parent <tt class="docutils literal"><span class="pre">cc-mode</span></tt> and its <tt class="docutils literal"><span class="pre">while</span></tt>
snipepts, while all modes are share the <tt class="docutils literal"><span class="pre">time</span></tt> snippet from
<tt class="docutils literal"><span class="pre">text-mode</span></tt>.</p>
<p>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>
<img align="right" alt="images/menu-parent.png" class="align-right" src="images/menu-parent.png" />
</div>
<div class="section" id="the-yas-parents-file">
<h2><a class="toc-backref" href="#id7">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2>
<p>If you place a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the
sub-directories you can bypass nesting and still have parent modes. In
this file you just write white-space-separated names of modes. This
allows more flexibility and readability of your snippet hierarchy.</p>
<h2><a class="toc-backref" href="#id6">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2>
<p>An alternate (and preferred) way of setting up parent tables consists
of placing a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the
sub-directories. By doing this, you avoid complex directory
nesting. In the <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file you just write
whitespace-separated names of modes. This allows more flexibility and
readability of your snippet hierarchy.</p>
<div class="highlight"><pre>$ tree
.
|-- c-mode
@ -171,7 +175,7 @@ allows more flexibility and readability of your snippet hierarchy.</p>
</pre></div>
</div>
<div class="section" id="the-yas-make-groups-file">
<h2><a class="toc-backref" href="#id8">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2>
<h2><a class="toc-backref" href="#id7">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2>
<img align="right" alt="images/menu-groups.png" class="align-right" src="images/menu-groups.png" />
<p>If you place an empty plain text file <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> inside one
of the mode directories, the names of these sub-directories are
@ -195,7 +199,7 @@ ruby-mode/
</pre></div>
</div>
<div class="section" id="using-plain-file-names">
<h2><a class="toc-backref" href="#id9">Using plain file names</a></h2>
<h2><a class="toc-backref" href="#id8">Using plain file names</a></h2>
<p>Normally, file names act as the snippet expansion <em>abbreviation</em> (also
known as the <em>snippet key</em> or <em>snippet trigger</em>, see <a class="reference external" href="snippet-expansion.html">Expanding
Snippets</a>).</p>
@ -222,8 +226,8 @@ rails-mode/
</pre></div>
</div>
</div>
<div class="section" id="id3">
<h1><a class="toc-backref" href="#id10">YASnippet bundle</a></h1>
<div class="section" id="yasnippet-bundle">
<h1><a class="toc-backref" href="#id9">YASnippet 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>
@ -247,18 +251,18 @@ generated this way.</p>
</ul>
</div>
<div class="section" id="customizable-variables">
<h1><a class="toc-backref" href="#id11">Customizable variables</a></h1>
<h1><a class="toc-backref" href="#id10">Customizable variables</a></h1>
<div class="section" id="yas-root-directory">
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></h2>
<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></h2>
<p>Root directory that stores the snippets for each major mode.</p>
<p>Can also be a list of strings, for multiple root directories. If
you make this a list, the first element is always the
user-created snippets directory.</p>
<p>Other directories are used for bulk reloading of all snippets using
<p>If you set this from your .emacs, can also be a list of strings,
for multiple root directories. If you make this a list, the first
element is always the user-created snippets directory. Other
directories are used for bulk reloading of all snippets using
<tt class="docutils literal"><span class="pre">yas/reload-all</span></tt></p>
</div>
<div class="section" id="yas-ignore-filenames-as-triggers">
<h2><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></h2>
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></h2>
<p>If non-nil, don't derive tab triggers from filenames.</p>
<p>This means a snippet without a <tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> directive wont have a tab
trigger.</p>

50
doc/snippet-organization.rst
View File

@ -12,19 +12,19 @@ Organizing snippets
Loading snippets
================
Snippet definitions are stored in files in the filesystem and you have
to arrange for YASnippet to load them (unless you use a `YASnippet
bundle <index.html@bundle-install>`_) into *snippet tables*.
The triggering mechanisms (see `Expanding snippets`_) will look up
these snippet tables and (hopefully) expand your intended snippet.
Snippet definitions are stored in files in the filesystem. Unless you
use the simpler `bundle version <index.html@installation>`_), these
are arranged so that YASnippet can load them into *snippet
tables*. The triggering mechanisms (see `Expanding snippets`_) will
look up these snippet tables and (hopefully) expand the snippet you
intended.
The non-bundle version of YASnippet, once unpacked, comes with a full
directory of snippets, which you can copy somewhere and use. You can
also create or download, one or more directories.
also create or download more directories.
Once these directories are in place reference them in the variable
``yas/root-directory`` and then load them with ``yas/load-directory``:
``yas/root-directory`` and load them with ``yas/load-directory``:
.. sourcecode:: common-lisp
@ -52,9 +52,9 @@ You can make this variable a list and store more items into it:
;; Map `yas/load-directory' to every element
(mapc 'yas/load-directory yas/root-directory)
Here the directories after the first are loaded, their snippets
considered for expansion, but development still happens in
"~/emacs.d/mysnippets"
In this last example, the all the directories are loaded and their
snippets considered for expansion. However development still happens
in the first element, "~/emacs.d/mysnippets".
Organizing snippets
===================
@ -95,10 +95,11 @@ for some modes:
`-- time
A parent directory acts as a *parent table* of any of its
sub-directories. This is one of the ways YASnippet can share snippet
definitions among different modes. As you can see above, ``c-mode``
and ``java-mode`` share the same parents ``cc-mode``, while all modes
are derived from ``text-mode``.
sub-directories. This is one of the ways different Emacs major modes
can share snippet definitions. As you can see above, ``c-mode`` and
``java-mode`` share the same parent ``cc-mode`` and its ``while``
snipepts, while all modes are share the ``time`` snippet from
``text-mode``.
This can be also used to as an *alias* -- ``cperl-mode`` is an empty
directory whose parent is ``perl-mode``.
@ -109,10 +110,12 @@ directory whose parent is ``perl-mode``.
The ``.yas-parents`` file
------------------------------
If you place a plain text file ``.yas-parents`` inside one of the
sub-directories you can bypass nesting and still have parent modes. In
this file you just write white-space-separated names of modes. This
allows more flexibility and readability of your snippet hierarchy.
An alternate (and preferred) way of setting up parent tables consists
of placing a plain text file ``.yas-parents`` inside one of the
sub-directories. By doing this, you avoid complex directory
nesting. In the ``.yas-parents`` file you just write
whitespace-separated names of modes. This allows more flexibility and
readability of your snippet hierarchy.
.. sourcecode:: text
@ -231,11 +234,10 @@ Customizable variables
Root directory that stores the snippets for each major mode.
Can also be a list of strings, for multiple root directories. If
you make this a list, the first element is always the
user-created snippets directory.
Other directories are used for bulk reloading of all snippets using
If you set this from your .emacs, can also be a list of strings,
for multiple root directories. If you make this a list, the first
element is always the user-created snippets directory. Other
directories are used for bulk reloading of all snippets using
``yas/reload-all``
``yas/ignore-filenames-as-triggers``