ld/yasnippet
1
0
Fork 0
mirror of https://github.com/joaotavora/yasnippet.git synced 2025-10-13 21:13:04 +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="" for other versions can be found <a title=""
href="http://code.google.com/p/yasnippet/downloads/list">here</a>. href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
</p> </p>
<div class="section" id="upcoming-0-6-1c"> <div class="section" id="c-2009-08-13">
<h1>Upcoming 0.6.1c</h1> <h1>0.6.1c / 2009-08-13</h1>
<ul class="simple"> <ul class="simple">
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues">issues</a> 99, 98, 93, <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> 90, 91, 88, 87. Thanks everybody.</li>

4
doc/changelog.rst
View File

@ -7,8 +7,8 @@ ChangeLog
.. _Writing Snippets: snippet-development.html .. _Writing Snippets: snippet-development.html
.. _The YASnippet Menu: snippet-menu.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, * Fixed `issues <http://code.google.com/p/yasnippet/issues>`_ 99, 98, 93,
90, 91, 88, 87. Thanks everybody. 90, 91, 88, 87. Thanks everybody.

52
doc/index.html
View File

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

52
doc/index.rst
View File

@ -9,43 +9,40 @@ Yet Another Snippet extension
.. contents:: .. contents::
**YASnippet** is a template system for Emacs. It allows you to type a **YASnippet** is a template system for Emacs. It allows you to type an
abbreviation and automatically expand the abbreviation into function abbreviation and automatically expand it into function
templates. 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, The snippet syntax is inspired from TextMate's syntax, you can even
SQL, LaTeX, HTML, CSS and more. `import <snippet-development.html#importing-textmate-snippets>`_
import most TextMate templates. YASnippet is a re-write of the
The snippet syntax is inspired from TextMate's syntax, you can extension `smart-snippet`_. Both are original creations of `pluskid
even `import <snippet-development.html#importing-textmate-snippets>`_ <http://pluskid.lifegoo.org>`_.
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>`_.
.. _smart-snippet: http://code.google.com/p/smart-snippet/ .. _smart-snippet: http://code.google.com/p/smart-snippet/
Video Demo Video Demo
========== ==========
.. youtube:: vOj7btx3ATg .. youtube:: 76Ygeg9miao
:align: right :align: right
Watch the `demo at YouTube 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 resolution version: `yasnippet.avi
<http://yasnippet.googlecode.com/files/yasnippet.avi>`_). <http://yasnippet.googlecode.com/files/yasnippet.avi>`_).
Installation Installation
============ ============
There are two archives of YASnippet. One is a single file compiled There are two archives you can download. To quickly tryout YASnippet,
“bundle”, and the other is normal. If all you need is to use the download the simpler "bundle" version. If you plan to modify the
built-in templates, download the bundle one. If you want to add your bundled templates and/or build your own, download the "normal"
own templates, download the normal one. package.
Bundle Install Install with ``yasnippet-bundle.el``
-------------- ------------------------------------
1. Download the latest ``yasnippet-bundle-x.y.z.el.tgz`` and unpack it. 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 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 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 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 To have Emacs load YASnippet automatically when it starts, put the
following in your ``~/.emacs`` file: following in your ``~/.emacs`` file:
@ -65,13 +62,16 @@ following in your ``~/.emacs`` file:
"~/.emacs.d/plugins") "~/.emacs.d/plugins")
(require 'yasnippet-bundle) (require 'yasnippet-bundle)
The `youtube video <http://www.youtube.com/watch?v=76Ygeg9miao>`_
demonstrates this quick installation.
Normal Install Normal Install
-------------- --------------
For full install of the normal archive, just download and unpack the To install YASnippet as a normal emacs package, download and unpack
latest ``yasnippet-x.y.z.tar.bz2``. You'll get a directory named 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 ``yasnippet-x.y.z``, which you can put it in your
following in your ``.emacs`` file: ``~/.emacs.d/plugins`` and add the following in your ``.emacs`` file:
.. sourcecode:: common-lisp .. sourcecode:: common-lisp
@ -114,7 +114,7 @@ Hence this section has been split into separate documents:
4. `The YASnippet menu`_ 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. snippets.
Bugs, Contribution and Support 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="#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="#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="#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="#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="#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="#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="#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="#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> </ul>
</li> </li>
<li><a class="reference internal" href="#template-syntax" id="id13">Template syntax</a><ul> <li><a class="reference internal" href="#template-syntax" id="id14">Template syntax</a><ul>
<li><a class="reference internal" href="#plain-text" id="id14">Plain Text</a></li> <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="id15">Embedded Emacs-lisp code</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="id16">Tab stop fields</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="id17">Placeholder 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="id18">Mirrors</a></li> <li><a class="reference internal" href="#id2" id="id19">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="#mirrors-with-transformations" id="id20">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="#fields-with-transformations" id="id21">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="#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="id22">Nested placeholder fields</a></li> <li><a class="reference internal" href="#nested-placeholder-fields" id="id23">Nested placeholder fields</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#customizable-variables" id="id23">Customizable variables</a><ul> <li><a class="reference internal" href="#customizable-variables" id="id24">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-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="id25"><tt class="docutils literal"><span class="pre">yas/next-field-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="id26"><tt class="docutils literal"><span class="pre">yas/prev-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="id27"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-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="id28"><tt class="docutils literal"><span class="pre">yas/good-grace</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="id29"><tt class="docutils literal"><span class="pre">yas/indent-line</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="id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</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="id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</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="id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</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="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="#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> </ul>
</li> </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> </ul>
</div> </div>
<div class="section" id="snippet-development"> <div class="section" id="snippet-development">
<h1><a class="toc-backref" href="#id3">Snippet development</a></h1> <h1><a class="toc-backref" href="#id3">Snippet development</a></h1>
<div class="section" id="quickly-finding-snippets"> <div class="section" id="quickly-finding-snippets">
<h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2> <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 <p>There are some ways you can quickly find a snippet file:</p>
this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead) and you can
start editing your snippet.</p>
<ul> <ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/new-snippet</span></tt></p> <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 <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>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/find-snippets</span></tt></p> <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 <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>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/visit-snippet-file</span></tt></p> <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 <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> directly to the snippet definition's file, if it exists.</p>
</li> </li>
</ul> </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>
<div class="section" id="using-the-snippet-mode-major-mode"> <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> <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> </blockquote>
</li> </li>
</ul> </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 <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">mirror</span></tt>.</p> <tt class="docutils literal"><span class="pre">$m</span></tt> :-).</p>
</div> </div>
</div> </div>
<div class="section" id="file-content"> <div class="section" id="file-content">
<h1><a class="toc-backref" href="#id6">File content</a></h1> <h1><a class="toc-backref" href="#id6">File content</a></h1>
<p>A file defining a snippet may just contain the template for the <p>A file defining a snippet generally contains the template to be
snippet. Optionally it can also contains some meta data for the expanded.</p>
snippet as well as comments.</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
<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 it count as comments, some of which can be <em>directives</em> (or meta
contents above that line are considered directives (meta data) and 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
comments; below that line lies the snippet template.</p> certain snippets properties described below. If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found,
<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 the whole file is considered the snippet template.</p>
template.</p>
<p>Here's a typical example:</p> <p>Here's a typical example:</p>
<div class="highlight"><pre>#contributor : pluskid &lt;pluskid@gmail.com&gt; <div class="highlight"><pre>#contributor : pluskid &lt;pluskid@gmail.com&gt;
#name : __...__ #name : __...__
# -- # --
__${init}__ __${init}__
</pre></div> </pre></div>
<p>Meta data are specified in the syntax of</p> <p>Here's a list of currently supported directives:</p>
<div class="highlight"><pre>#data-name : data value
</pre></div>
<p>Any other text above <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is considered as comment and
ignored. Here's a list of currently supported directives:</p>
<div class="section" id="key-snippet-abbrev"> <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> <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 <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 will only be expanded when the condition code evaluate to some non-nil
value.</p> 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>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 <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 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 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> which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt> group.</p>
</div> </div>
<div class="section" id="expand-env-expand-environment"> <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> <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</em> <p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt>
form, i.e. a list of lists assigning values to variables. It can be <em>varlist form</em>, i.e. a list of lists assigning values to variables. It
used to override variable values while the snippet is being expanded.</p> 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 <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> <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 <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> </pre></div>
</div> </div>
<div class="section" id="binding-direct-keybinding"> <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 <p>You can use this directive to expand a snippet directly from a normal
Emacs keybinding. The keybinding will be registered in the Emacs Emacs keybinding. The keybinding will be registered in the Emacs
keymap named after the major mode the snippet is active 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; &lt;p&gt;`(when yas/prefix &quot;\n&quot;)`$0`(when yas/prefix &quot;\n&quot;)`&lt;/p&gt;
</pre></div> </pre></div>
<p><em>Note</em> that this feature is still <strong>experimental</strong>, it might go away, <p><strong>Note</strong>: this feature is still <strong>experimental</strong>, it might go away, be
be changed in future release, and should be used with caution: It is changed in future release, and should be used with caution: It is easy
easy to override important keybindings for many basic modes and it is to override important keybindings for many basic modes and it is hard
hard to undefine them. For the moment, the variable 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 <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 active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will attempt
undefine all the keybindings.</p> to undefine all the keybindings.</p>
</div> </div>
<div class="section" id="contributor-snippet-author"> <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 <p>This is optional and has no effect whatsoever on snippet
functionality, but it looks nice.</p> functionality, but it looks nice.</p>
</div> </div>
</div> </div>
<div class="section" id="template-syntax"> <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 <p>The syntax of the snippet template is simple but powerful, very
similar to TextMate's.</p> similar to TextMate's.</p>
<div class="section" id="plain-text"> <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 <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 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 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> needed to be escaped as <tt class="docutils literal"><span class="pre">\\</span></tt> sometimes.</p>
</div> </div>
<div class="section" id="embedded-emacs-lisp-code"> <div class="section" id="embedded-emacs-lisp-code">
<h2><a class="toc-backref" href="#id15">Embedded Emacs-lisp code</a></h2> <h2><a class="toc-backref" href="#id16">Embedded Emacs-lisp code</a></h2>
<p>Emacs-Lisp code can be embedded inside the template. They are written <p>Emacs-Lisp code can be embedded inside the template, written inside
inside back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>):</p> back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>). The lisp forms are evaluated when the snippet is
<p>They are evaluated when the snippet is being expanded. The evaluation being expanded. The evaluation is done in the same buffer as the
is done in the same buffer as the snippet being expanded. Here's an snippet being expanded.</p>
example for <tt class="docutils literal"><span class="pre">c-mode</span></tt> to calculate the header file guard dynamically:</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_} <div class="highlight"><pre>#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
#define $1 #define $1
@ -306,7 +307,7 @@ $0
#endif /* $1 */ #endif /* $1 */
</pre></div> </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 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> can therefore define a snippet like:</p>
<div class="highlight"><pre>for ($1;$2;$3) { <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> <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>
<div class="section" id="tab-stop-fields"> <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> <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 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 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> </pre></div>
</div> </div>
<div class="section" id="placeholder-fields"> <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 <p>Tab stops can have default values -- a.k.a placeholders. The syntax is
like this:</p> like this:</p>
<div class="highlight"><pre>${N:default value} <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> <a class="reference internal" href="#mirrors">mirrors</a> or <a class="reference internal" href="#transformations">transformations</a> for this field.</p>
</div> </div>
<div class="section" id="id2"> <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 <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 mirrors. Its mirrors will get updated when you change the text of a
field. Here's an example:</p> 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> as the field and others mirrors.</p>
</div> </div>
<div class="section" id="mirrors-with-transformations"> <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>, <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 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 transformation. The mirror's text content is calculated according to
@ -405,7 +406,7 @@ $0
</pre></div> </pre></div>
</div> </div>
<div class="section" id="fields-with-transformations"> <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 <p>From version 0.6 on, you can also have lisp transformation inside
fields. These work mostly mirror transformations but are evaluated fields. These work mostly mirror transformations but are evaluated
when you first enter the field, after each change you make to the 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 <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> fields does not take place. This is by design.</p>
</div> </div>
<div class="section" id="choosing-fields-value-from-a-list"> <div class="section" id="choosing-fields-value-from-a-list-and-other-tricks">
<h2><a class="toc-backref" href="#id21">Choosing fields value from a list</a></h2> <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 <p>As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably 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 <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; &lt;/div&gt;
</pre></div> </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 <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 using the two variables.</p>
another neat trick.</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>
<div class="section" id="nested-placeholder-fields"> <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> <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; <div class="highlight"><pre>&lt;div${1: id=&quot;${2:some_id}&quot;}&gt;$0&lt;/div&gt;
</pre></div> </pre></div>
@ -460,9 +471,9 @@ performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-
</div> </div>
</div> </div>
<div class="section" id="customizable-variables"> <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"> <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 <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> active.</p>
<p>Value is a string that is converted to the internal Emacs key <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> <p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
</div> </div>
<div class="section" id="yas-next-field-key"> <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>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 <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> 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> <p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
</div> </div>
<div class="section" id="yas-prev-field-key"> <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>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 <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> 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> <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>
<div class="section" id="yas-skip-and-clear-key"> <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>The key to clear the currently active field.</p>
<p>Value is a string that is converted to the internal Emacs key <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> 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> <p>Default value is <tt class="docutils literal"><span class="pre">&quot;C-d&quot;</span></tt>.</p>
</div> </div>
<div class="section" id="yas-good-grace"> <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 <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> snippet definitions. An error string &quot;[yas] error&quot; is returned instead.</p>
</div> </div>
<div class="section" id="yas-indent-line"> <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 <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 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> according to the mode of the buffer it was inserted in.</p>
@ -520,7 +531,7 @@ $0$&gt;
</pre></div> </pre></div>
</div> </div>
<div class="section" id="yas-wrap-around-region"> <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 <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, 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 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> spring back to life inside your new snippet.</p>
</div> </div>
<div class="section" id="yas-triggers-in-field"> <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, <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 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 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> the next field.</p>
</div> </div>
<div class="section" id="yas-snippet-revival"> <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> <p>Non-nil means re-activate snippet fields after undo/redo.</p>
</div> </div>
<div class="section" id="yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook"> <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 <p>These hooks are called, respectively, before the insertion of a
snippet and after exiting the snippet. If you find any strange but snippet and after exiting the snippet. If you find any strange but
functional use for them, that's probably a design flaw in YASnippet, functional use for them, that's probably a design flaw in YASnippet,
@ -553,7 +564,7 @@ so let us know.</p>
</div> </div>
</div> </div>
<div class="section" id="importing-textmate-snippets"> <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 <p>There are a couple of tools that take TextMate's &quot;.tmSnippet&quot; xml
files and create YASnippet definitions:</p> files and create YASnippet definitions:</p>
<blockquote> <blockquote>

102
doc/snippet-development.rst
View File

@ -15,9 +15,7 @@ Snippet development
Quickly finding snippets Quickly finding snippets
------------------------ ------------------------
There are some ways you can quickly find a snippet file. Once you find There are some ways you can quickly find a snippet file:
this file it will be set to ``snippet-mode`` (see ahead) and you can
start editing your snippet.
* ``M-x yas/new-snippet`` * ``M-x yas/new-snippet``
@ -29,7 +27,8 @@ start editing your snippet.
* ``M-x yas/find-snippets`` * ``M-x yas/find-snippets``
Lets you find the snippet file in the directory the snippet was 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`` * ``M-x yas/visit-snippet-file``
@ -37,6 +36,9 @@ start editing your snippet.
``yas/insert-snippet``, but instead of expanding it, takes you ``yas/insert-snippet``, but instead of expanding it, takes you
directly to the snippet definition's file, if it exists. 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 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 can see what it looks like. This is bound to ``C-c C-t`` while in
``snippet-mode``. ``snippet-mode``.
There are also snippets for making snippets: ``vars``, ``field`` and There are also *snippets for writing snippets*: ``vars``, ``$f`` and
``mirror``. ``$m`` :-).
File content File content
============ ============
A file defining a snippet may just contain the template for the A file defining a snippet generally contains the template to be
snippet. Optionally it can also contains some meta data for the expanded.
snippet as well as comments.
Generally speaking, if the file contains a line of ``# --``, then all Optionally, if the file contains a line of ``# --``, the lines above
contents above that line are considered directives (meta data) and it count as comments, some of which can be *directives* (or meta
comments; below that line lies the snippet template. data). Snippet directives look like ``# property: value`` and tweak
certain snippets properties described below. If no ``# --`` is found,
If no ``# --`` is found, the whole file content is considered as the the whole file is considered the snippet template.
template.
Here's a typical example: Here's a typical example:
@ -86,14 +86,7 @@ Here's a typical example:
# -- # --
__${init}__ __${init}__
Meta data are specified in the syntax of Here's a list of currently supported directives:
.. sourcecode:: text
#data-name : data value
Any other text above ``# --`` is considered as comment and
ignored. Here's a list of currently supported directives:
``# key:`` snippet abbrev ``# 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 If you omit this name it will default to the file name the snippet was
loaded from. loaded from.
``# condition:`` snippet condition ``# condition:`` snippet condition
---------------------------------- ----------------------------------
This is a piece of Emacs-lisp code. If a snippet has a condition, then it 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`_ 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 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 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 ``# expand-env:`` expand environment
------------------------------------ ------------------------------------
This is another piece of Emacs-lisp code in the form of a ``let`` *varlist* This is another piece of Emacs-lisp code in the form of a ``let``
form, i.e. a list of lists assigning values to variables. It can be *varlist form*, i.e. a list of lists assigning values to variables. It
used to override variable values while the snippet is being expanded. can be used to override variable values while the snippet is being
expanded.
Interesting variables to override are ``yas/wrap-around-region`` and Interesting variables to override are ``yas/wrap-around-region`` and
``yas/indent-line`` (see `Expanding Snippets`_). ``yas/indent-line`` (see `Expanding Snippets`_).
As an example, you might normally have ``yas/indent-line`` set to As an example, you might normally have ``yas/indent-line`` set to
``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this ``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this
particularly brilliant piece of ASCII art these values would mess up 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> <p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
*Note* that this feature is still **experimental**, it might go away, **Note**: this feature is still **experimental**, it might go away, be
be changed in future release, and should be used with caution: It is changed in future release, and should be used with caution: It is easy
easy to override important keybindings for many basic modes and it is to override important keybindings for many basic modes and it is hard
hard to undefine them. For the moment, the variable to undefine them. For the moment, the variable
``yas/active-keybinding`` can tell you what snippet keybindings are ``yas/active-keybindings`` can tell you what snippet keybindings are
active and the function ``yas/kill-snippet-keybindings`` will attempt to active and the function ``yas/kill-snippet-keybindings`` will attempt
undefine all the keybindings. to undefine all the keybindings.
``# contributor:`` snippet author ``# contributor:`` snippet author
--------------------------------------------------- ---------------------------------------------------
@ -251,12 +243,13 @@ needed to be escaped as ``\\`` sometimes.
Embedded Emacs-lisp code Embedded Emacs-lisp code
------------------------ ------------------------
Emacs-Lisp code can be embedded inside the template. They are written Emacs-Lisp code can be embedded inside the template, written inside
inside back-quotes (`````): 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 Here's an example for ``c-mode`` to calculate the header file guard
is done in the same buffer as the snippet being expanded. Here's an dynamically:
example for ``c-mode`` to calculate the header file guard dynamically:
.. sourcecode:: text .. sourcecode:: text
@ -267,7 +260,7 @@ example for ``c-mode`` to calculate the header file guard dynamically:
#endif /* $1 */ #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 Emacs-lisp variables bound. One of this is ``yas/selected-text``. You
can therefore define a snippet like: 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 ``true``. As a consequence, the auto-deletion behaviour of normal
fields does not take place. This is by design. 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 As mentioned, the field transformation is invoked just after you enter
the field, and with some useful variables bound, notably 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> </div>
See the definition of ``yas/choose-value`` to see how it was written See the definition of ``yas/choose-value`` to see how it was written
using the two variables. Also check out ``yas/verify-value`` for using the two variables.
another neat trick.
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 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="#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="#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-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="#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> <li><a class="reference internal" href="#roll-your-own" id="id17">Roll your own</a></li>
</ul> </ul>
@ -95,9 +95,10 @@
<h1><a class="toc-backref" href="#id2">Triggering expansion</a></h1> <h1><a class="toc-backref" href="#id2">Triggering expansion</a></h1>
<p>You can use YASnippet to expand snippets in different ways:</p> <p>You can use YASnippet to expand snippets in different ways:</p>
<ul class="simple"> <ul class="simple">
<li>By typing a snippet abbrev and then pressing the key defined in <li>By typing an abbrev, the snippet <em>trigger key</em>, and then pressing
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to &quot;TAB&quot;). This works in a the key defined in <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to
buffer where the minor mode <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active;</li> &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 <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> <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> 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>
<div class="section" id="expanding-from-emacs-lisp-code"> <div class="section" id="expanding-from-emacs-lisp-code">
<h2><a class="toc-backref" href="#id9">Expanding from emacs-lisp code</a></h2> <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 <p>Sometimes you might want to expand a snippet directly from you own
functin from elisp code. You should call <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> elisp code. You should call <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> instead of
instead of <tt class="docutils literal"><span class="pre">yas/expand</span></tt> in this case.</p> <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 <p>As with expanding from the menubar, the condition system and multiple
candidates won't exists here. In fact, expanding from menubar has the candidates doesn't affect expansion. In fact, expanding from the
same effect of evaluating the follow code:</p> 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>) <div class="highlight"><pre>(<span style="color: #19177C">yas/expand-snippet</span> <span style="color: #19177C">template</span>)
</pre></div> </pre></div>
<p>See the internal documentation on <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> for more <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"> <div class="section" id="eligible-snippets">
<h2><a class="toc-backref" href="#id11">Eligible snippets</a></h2> <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 <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> <p>In particular, the following things matter:</p>
<ul> <ul>
<li><p class="first">Currently loaded snippets tables</p> <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> <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>
<li><p class="first">Major mode of the current buffer</p> <li><p class="first">Major mode of the current buffer</p>
<p>If it matches one of the loaded snippet tables, then all that <p>If the currrent major mode matches one of the loaded snippet tables,
table's snippets are considered for expansion. Use <tt class="docutils literal"><span class="pre">M-x</span> then all that table's snippets are considered for expansion. Use
<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 <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
are in currently.</p> mode you are in currently.</p>
</li> </li>
<li><p class="first">Parent tables</p> <li><p class="first">Parent tables</p>
<p>Snippet tables defined as parent of some other table considered in <p>Snippet tables defined as the parent of some other eligible table
the previous step are also considered.</p> are also considered. This works recursively, i.e. parents of parents
of eligible tables are also considered.</p>
</li> </li>
<li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/mode-symbol</span></tt> variable</p> <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 <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 , 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 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, 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> idea.</p>
</li> </li>
</ul> </ul>
@ -223,10 +225,10 @@ idea.</p>
</pre></div> </pre></div>
<ul> <ul>
<li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> variable</p> <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 <p>This variable provides finer grained control over what snippets can
can be expanded in the current buffer. The default value, won't let be expanded in the current buffer. The default value won't let you
you expand snippets inside comments or string literals for expand snippets inside comments or string literals for example. See
example. See <a class="reference internal" href="#the-condition-system">The condition system</a> for more info.</p> <a class="reference internal" href="#the-condition-system">The condition system</a> for more info.</p>
</li> </li>
</ul> </ul>
</div> </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 <p>The rules outlined <a class="reference external" href="Eligiblesnippets">above</a> can return more than
one snippet to be expanded at point.</p> one snippet to be expanded at point.</p>
<p>When there are multiple candidates, YASnippet will let you select <p>When there are multiple candidates, YASnippet will let you select
one. The UI for selecting multiple candidate can be customized. A one. The UI for selecting multiple candidate can be customized through
customization variable, called <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> defines your <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> , which defines your preferred methods of
preferred method of being prompted for snippets.</p> 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> <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 <span class="pre">yas/prompt-functions</span> <span class="pre">RET</span></tt>. Alternatively you can put in your
emacs-file:</p> emacs-file:</p>
@ -318,8 +320,8 @@ support, this menu will be rendered with your gtk theme.</li>
</ul> </ul>
<img align="right" alt="images/ido-menu.png" class="align-right" src="images/ido-menu.png" /> <img align="right" alt="images/ido-menu.png" class="align-right" src="images/ido-menu.png" />
</div> </div>
<div class="section" id="use-built-in-emacs-selection-methods"> <div class="section" id="minibuffer-prompting">
<h3><a class="toc-backref" href="#id15">Use built-in Emacs selection methods</a></h3> <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 <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 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> 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"> <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> <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 <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 <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
recognized as a snippet key. Furthermore, the searching is in that as a snippet key. Furthermore, the searching is in that order. In
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 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,
<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 then that snippet is expanded and replaces the <tt class="docutils literal"><span class="pre">bar</span></tt>. Snippets
searched.</p> 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 <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 <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 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 either word, symbol or punctuation.</li>
<li>a sequence of characters of non-whitespace characters.</li> <li>a sequence of characters of non-whitespace characters.</li>
</ul> </ul>
<p>But you'd better keep the default value unless you understand what <p>But you'd better keep the default value unless you want to understand
Emacs's syntax rule mean.</p> how Emacs's syntax rules work...</p>
</div> </div>
</div> </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: You can use YASnippet to expand snippets in different ways:
* By typing a snippet abbrev and then pressing the key defined in * By typing an abbrev, the snippet *trigger key*, and then pressing
``yas/trigger-key`` (which defaults to "TAB"). This works in a the key defined in ``yas/trigger-key`` (which defaults to
buffer where the minor mode ``yas/minor-mode`` is active; "TAB"). This works in buffers where the minor mode
``yas/minor-mode`` is active;
* By invoking the command ``yas/insert-snippet`` (either by typing * By invoking the command ``yas/insert-snippet`` (either by typing
``M-x yas/insert-snippet`` or its keybinding). This does *not* ``M-x yas/insert-snippet`` or its keybinding). This does *not*
@ -115,13 +116,13 @@ prefer.
Expanding from emacs-lisp code Expanding from emacs-lisp code
------------------------------ ------------------------------
Sometimes you might want to expand a snippet directly by calling a Sometimes you might want to expand a snippet directly from you own
functin from elisp code. You should call ``yas/expand-snippet`` elisp code. You should call ``yas/expand-snippet`` instead of
instead of ``yas/expand`` in this case. ``yas/expand`` in this case.
As with expanding from the menubar, condition system and multiple As with expanding from the menubar, the condition system and multiple
candidates won't exists here. In fact, expanding from menubar has the candidates doesn't affect expansion. In fact, expanding from the
same effect of evaluating the follow code: YASnippet menu has the same effect of evaluating the follow code:
.. sourcecode:: common-lisp .. sourcecode:: common-lisp
@ -137,7 +138,7 @@ Eligible snippets
----------------- -----------------
YASnippet does quite a bit of filtering to find out which snippets are 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: In particular, the following things matter:
@ -149,15 +150,16 @@ In particular, the following things matter:
* Major mode of the current buffer * Major mode of the current buffer
If it matches one of the loaded snippet tables, then all that If the currrent major mode matches one of the loaded snippet tables,
table's snippets are considered for expansion. Use ``M-x then all that table's snippets are considered for expansion. Use
describe-variable RET major-mode RET`` to find out which mode you ``M-x describe-variable RET major-mode RET`` to find out which major
are in currently. mode you are in currently.
* Parent tables * Parent tables
Snippet tables defined as parent of some other table considered in Snippet tables defined as the parent of some other eligible table
the previous step are also considered. are also considered. This works recursively, i.e. parents of parents
of eligible tables are also considered.
* Buffer-local ``yas/mode-symbol`` variable * 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 , correspond to a major mode. If you set this variable to a name ,
like ``rinari-minor-mode``, you can have some snippets expand only like ``rinari-minor-mode``, you can have some snippets expand only
in that minor mode. Naturally, you want to set this conditionally, 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. idea.
.. sourcecode:: common-lisp .. sourcecode:: common-lisp
@ -178,10 +180,10 @@ In particular, the following things matter:
* Buffer-local ``yas/buffer-local-condition`` variable * Buffer-local ``yas/buffer-local-condition`` variable
This variable provides more fine grained control over what snippets This variable provides finer grained control over what snippets can
can be expanded in the current buffer. The default value, won't let be expanded in the current buffer. The default value won't let you
you expand snippets inside comments or string literals for expand snippets inside comments or string literals for example. See
example. See `The condition system`_ for more info. `The condition system`_ for more info.
The condition system The condition system
-------------------- --------------------
@ -260,9 +262,9 @@ The rules outlined `above <Eligible snippets>`_ can return more than
one snippet to be expanded at point. one snippet to be expanded at point.
When there are multiple candidates, YASnippet will let you select When there are multiple candidates, YASnippet will let you select
one. The UI for selecting multiple candidate can be customized. A one. The UI for selecting multiple candidate can be customized through
customization variable, called ``yas/prompt-functions`` defines your ``yas/prompt-functions`` , which defines your preferred methods of
preferred method of being prompted for snippets. being prompted for snippets.
You can customize it with ``M-x customize-variable RET You can customize it with ``M-x customize-variable RET
yas/prompt-functions RET``. Alternatively you can put in your yas/prompt-functions RET``. Alternatively you can put in your
@ -293,8 +295,8 @@ which means:
.. image:: images/ido-menu.png .. image:: images/ido-menu.png
:align: right :align: right
Use built-in Emacs selection methods Minibuffer prompting
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~
You can use functions ``yas/completing-prompt`` for the classic emacs You can use functions ``yas/completing-prompt`` for the classic emacs
completion method or ``yas/ido-prompt`` for a much nicer looking completion method or ``yas/ido-prompt`` for a much nicer looking
@ -324,7 +326,6 @@ Customizable Variables
``yas/prompt-functions`` ``yas/prompt-functions``
------------------------ ------------------------
You can write a function and add it to the ``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: 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 The default searching strategy is quite powerful. For example, in
``c-mode``, ``"bar"``, ``"foo_bar"``, ``"#foo_bar"`` can all be ``c-mode``, ``bar``, ``foo_bar``, ``"#foo_bar"`` can all be recognized
recognized as a snippet key. Furthermore, the searching is in that as a snippet key. Furthermore, the searching is in that order. In
order. In other words, if ``"bar"`` is found to be a key to some other words, if ``bar`` is found to be a key to some *valid* snippet,
*valid* snippet, then ``"foo_bar"`` and ``"#foobar"`` won't be then that snippet is expanded and replaces the ``bar``. Snippets
searched. pointed to by ``foo_bar`` and ``"#foobar`` won't be considered.
However, this strategy can also be customized easily from the However, this strategy can also be customized easily from the
``yas/key-syntaxes`` variable. It is a list of syntax rules, 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 either word, symbol or punctuation.
* a sequence of characters of non-whitespace characters. * a sequence of characters of non-whitespace characters.
But you'd better keep the default value unless you understand what But you'd better keep the default value unless you want to understand
Emacs's syntax rule mean. how Emacs's syntax rules work...

2
doc/snippet-menu.html
View File

@ -65,7 +65,7 @@
</ul> </ul>
</div> </div>
<p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active, YASnippet will setup a menu just <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> <p>In this menu, you can find</p>
<ul class="simple"> <ul class="simple">
<li>The currently loaded snippet definitions, organized by major mode, <li>The currently loaded snippet definitions, organized by major mode,

2
doc/snippet-menu.rst
View File

@ -5,7 +5,7 @@ YASnippet menu
.. contents:: .. contents::
When ``yas/minor-mode`` is active, YASnippet will setup a menu just 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 In this menu, you can find

92
doc/snippet-organization.html
View File

@ -57,34 +57,35 @@
<div class="contents topic" id="contents"> <div class="contents topic" id="contents">
<p class="topic-title first">Contents</p> <p class="topic-title first">Contents</p>
<ul class="simple"> <ul class="simple">
<li><a class="reference internal" href="#loading-snippets" id="id4">Loading snippets</a></li> <li><a class="reference internal" href="#loading-snippets" id="id3">Loading snippets</a></li>
<li><a class="reference internal" href="#id2" id="id5">Organizing snippets</a><ul> <li><a class="reference internal" href="#id2" id="id4">Organizing snippets</a><ul>
<li><a class="reference internal" href="#nested-organization" id="id6">Nested organization</a></li> <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="id7">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</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="id8">The <tt class="docutils literal"><span class="pre">.yas-make-groups</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="id9">Using plain file names</a></li> <li><a class="reference internal" href="#using-plain-file-names" id="id8">Using plain file names</a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#id3" id="id10">YASnippet bundle</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="id11">Customizable variables</a><ul> <li><a class="reference internal" href="#customizable-variables" id="id10">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-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="id13"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</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> </ul>
</li> </li>
</ul> </ul>
</div> </div>
<div class="section" id="loading-snippets"> <div class="section" id="loading-snippets">
<h1><a class="toc-backref" href="#id4">Loading snippets</a></h1> <h1><a class="toc-backref" href="#id3">Loading snippets</a></h1>
<p>Snippet definitions are stored in files in the filesystem and you have <p>Snippet definitions are stored in files in the filesystem. Unless you
to arrange for YASnippet to load them (unless you use a <a class="reference external" href="mailto:index.html&#64;bundle-install">YASnippet use the simpler <a class="reference external" href="mailto:index.html&#64;installation">bundle version</a>), these
bundle</a>) into <em>snippet tables</em>.</p> are arranged so that YASnippet can load them into <em>snippet
<p>The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will look up tables</em>. The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will
these snippet tables and (hopefully) expand your intended snippet.</p> 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 <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 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 <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> <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>) (<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: #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>) (<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> </pre></div>
<p>Here the directories after the first are loaded, their snippets <p>In this last example, the all the directories are loaded and their
considered for expansion, but development still happens in snippets considered for expansion. However development still happens
&quot;~/emacs.d/mysnippets&quot;</p> in the first element, &quot;~/emacs.d/mysnippets&quot;.</p>
</div> </div>
<div class="section" id="id2"> <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 <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> inside sub-directories of these directories.</p>
<p>Snippet definitions are put in plain text files. They are arranged by <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 <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 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 <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"> <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 <p>Here is an excerpt of a directory hierarchy containing snippets
for some modes:</p> for some modes:</p>
<div class="highlight"><pre>$ tree <div class="highlight"><pre>$ tree
@ -140,20 +141,23 @@ for some modes:</p>
`-- time `-- time
</pre></div> </pre></div>
<p>A parent directory acts as a <em>parent table</em> of any of its <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 sub-directories. This is one of the ways different Emacs major modes
definitions among different modes. As you can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> can share snippet definitions. As you can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and
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 <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>
are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>.</p> 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 <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> 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" /> <img align="right" alt="images/menu-parent.png" class="align-right" src="images/menu-parent.png" />
</div> </div>
<div class="section" id="the-yas-parents-file"> <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> <h2><a class="toc-backref" href="#id6">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 <p>An alternate (and preferred) way of setting up parent tables consists
sub-directories you can bypass nesting and still have parent modes. In of placing a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the
this file you just write white-space-separated names of modes. This sub-directories. By doing this, you avoid complex directory
allows more flexibility and readability of your snippet hierarchy.</p> 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 <div class="highlight"><pre>$ tree
. .
|-- c-mode |-- c-mode
@ -171,7 +175,7 @@ allows more flexibility and readability of your snippet hierarchy.</p>
</pre></div> </pre></div>
</div> </div>
<div class="section" id="the-yas-make-groups-file"> <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" /> <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 <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 of the mode directories, the names of these sub-directories are
@ -195,7 +199,7 @@ ruby-mode/
</pre></div> </pre></div>
</div> </div>
<div class="section" id="using-plain-file-names"> <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 <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 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> Snippets</a>).</p>
@ -222,8 +226,8 @@ rails-mode/
</pre></div> </pre></div>
</div> </div>
</div> </div>
<div class="section" id="id3"> <div class="section" id="yasnippet-bundle">
<h1><a class="toc-backref" href="#id10">YASnippet bundle</a></h1> <h1><a class="toc-backref" href="#id9">YASnippet bundle</a></h1>
<p>The most convenient way to define snippets for YASnippet is to put <p>The most convenient way to define snippets for YASnippet is to put
them in a directory arranged by the mode and use 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> <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> </ul>
</div> </div>
<div class="section" id="customizable-variables"> <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"> <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>Root directory that stores the snippets for each major mode.</p>
<p>Can also be a list of strings, for multiple root directories. If <p>If you set this from your .emacs, can also be a list of strings,
you make this a list, the first element is always the for multiple root directories. If you make this a list, the first
user-created snippets directory.</p> element is always the user-created snippets directory. Other
<p>Other directories are used for bulk reloading of all snippets using directories are used for bulk reloading of all snippets using
<tt class="docutils literal"><span class="pre">yas/reload-all</span></tt></p> <tt class="docutils literal"><span class="pre">yas/reload-all</span></tt></p>
</div> </div>
<div class="section" id="yas-ignore-filenames-as-triggers"> <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>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 <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> trigger.</p>

50
doc/snippet-organization.rst
View File

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