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

doc almost complete. Drawing closer to 0.6.1b

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

23
doc/changelog.html
View File

@ -3,10 +3,8 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>ChangeLog</title> <title>ChangeLog</title>
<meta name="author" content="pluskid" />
<meta name="date" content="2008-03-22" />
<link rel="stylesheet" href="styles.css" type="text/css" /> <link rel="stylesheet" href="styles.css" type="text/css" />
</head> </head>
<body> <body>
@ -49,7 +47,24 @@
<div id="squeeze"> <div id="squeeze">
<div class="right-corner"> <div class="right-corner">
<div class="left-corner"> <div class="left-corner">
<div class="section" id="c-2009-07-27"> <div class="section" id="b-2009-08-23">
<h1>0.6.1b / 2009-08-23</h1>
<ul class="simple">
<li>Much more powerful menu. See <a class="reference external" href="snippet-menu.html">The YASnippet menu</a>.</li>
<li>New ways to organize snippets. See <a class="reference external" href="snippet-organization.html">Organizing snippets</a>.</li>
<li>Added <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt> customization variable.</li>
<li>Renamed directive <tt class="docutils literal"><span class="pre">#</span> <span class="pre">env:</span></tt> to <tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt></li>
<li>Rewrote much of the documentation.</li>
<li>Added <tt class="docutils literal"><span class="pre">textmate-import.rb</span></tt> to svn repository.</li>
<li>Many random bugs fixed.</li>
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=72">Issue 72</a> (thanks
rmartin.k...&#64;gmail.com)</li>
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=74">Issue 74</a></li>
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=70">Issue 70</a></li>
<li>Fixed <a class="reference external" href="http://code.google.com/p/yasnippet/issues/detail?id=69">Issue 69</a></li>
</ul>
</div>
<div class="section" id="c-2009-07-27">
<h1>0.6.0c / 2009-07-27</h1> <h1>0.6.0c / 2009-07-27</h1>
<ul class="simple"> <ul class="simple">
<li>Now byte compiles correctly with no warnings.</li> <li>Now byte compiles correctly with no warnings.</li>

28
doc/changelog.rst
View File

@ -2,9 +2,31 @@
ChangeLog ChangeLog
========= =========
:Author: pluskid .. _Organizing Snippets: snippet-organization.html
:Contact: pluskid@gmail.com .. _Expanding Snippets: snippet-expansion.html
:Date: 2008-03-22 .. _Writing Snippets: snippet-development.html
.. _The YASnippet Menu: snippet-menu.html
0.6.1b / 2009-08-23
===================
* Much more powerful menu. See `The YASnippet menu`_.
* New ways to organize snippets. See `Organizing snippets`_.
* Added ``yas/also-auto-indent-first-line`` customization variable.
* Renamed directive ``# env:`` to ``# expand-env:``
* Rewrote much of the documentation.
* Added ``textmate-import.rb`` to svn repository.
* Many random bugs fixed.
* Fixed `Issue 72
<http://code.google.com/p/yasnippet/issues/detail?id=72>`_ (thanks
rmartin.k...@gmail.com)
* Fixed `Issue 74
<http://code.google.com/p/yasnippet/issues/detail?id=74>`_
* Fixed `Issue 70
<http://code.google.com/p/yasnippet/issues/detail?id=70>`_
* Fixed `Issue 69
<http://code.google.com/p/yasnippet/issues/detail?id=69>`_
0.6.0c / 2009-07-27 0.6.0c / 2009-07-27
=================== ===================

50
doc/compile-doc.py
View File

@ -43,6 +43,56 @@ pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS])
directives.register_directive('sourcecode', pygments_directive) directives.register_directive('sourcecode', pygments_directive)
# =================
# Youtube embedding
# =================
from docutils import nodes
from docutils.parsers.rst import directives
CODE = """\
<object type="application/x-shockwave-flash"
width="%(width)s"
height="%(height)s"
align="%(align)s"
class="youtube-embed"
data="http://www.youtube.com/v/%(yid)s">
<param name="movie" value="http://www.youtube.com/v/%(yid)s"></param>
<param name="wmode" value="transparent"></param>%(extra)s
</object>
"""
PARAM = """\n <param name="%s" value="%s"></param>"""
def youtube(name, args, options, content, lineno,
contentOffset, blockText, state, stateMachine):
""" Restructured text extension for inserting youtube embedded videos """
if len(content) == 0:
return
string_vars = {
'yid': content[0],
'width': 425,
'height': 344,
'align': "right",
'extra': ''
}
extra_args = content[1:] # Because content[0] is ID
extra_args = [ea.strip().split("=") for ea in extra_args] # key=value
extra_args = [ea for ea in extra_args if len(ea) == 2] # drop bad lines
extra_args = dict(extra_args)
if 'width' in extra_args:
string_vars['width'] = extra_args.pop('width')
if 'align' in extra_args:
string_vars['align'] = extra_args.pop('align')
if 'height' in extra_args:
string_vars['height'] = extra_args.pop('height')
if extra_args:
params = [PARAM % (key, extra_args[key]) for key in extra_args]
string_vars['extra'] = "".join(params)
return [nodes.raw('', CODE % (string_vars), format='html')]
youtube.content = True
directives.register_directive('youtube', youtube)
# ======================================== # ========================================
# Command line processing # Command line processing

BIN
doc/images/customization-group.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 54 KiB

After

Width:  |  Height:  |  Size: 59 KiB

BIN
doc/images/dropdown-menu.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 40 KiB

After

Width:  |  Height:  |  Size: 31 KiB

BIN
doc/images/group.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 79 KiB

BIN
doc/images/ido-menu.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 57 KiB

BIN
doc/images/idrop-menu.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

BIN
doc/images/menu-1.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 67 KiB

BIN
doc/images/menu-2.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 59 KiB

BIN
doc/images/menu-groups.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 82 KiB

BIN
doc/images/menu-parent.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 72 KiB

BIN
doc/images/menubar.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 15 KiB

BIN
doc/images/popup-menu.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 25 KiB

BIN
doc/images/x-menu.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 34 KiB

102
doc/index.html
View File

@ -3,10 +3,8 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Yet Another Snippet extension</title> <title>Yet Another Snippet extension</title>
<meta name="author" content="pluskid" />
<meta name="date" content="2008-03-20" />
<link rel="stylesheet" href="styles.css" type="text/css" /> <link rel="stylesheet" href="styles.css" type="text/css" />
</head> </head>
<body> <body>
@ -53,36 +51,44 @@
<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="#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="#brief-install-instruction" id="id2">Brief Install Instruction</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="#bundle-install" id="id3">Bundle Install</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>
<li><a class="reference internal" href="#how-to-use-yasnippet" id="id5">How to use YASnippet</a></li> <li><a class="reference internal" href="#how-to-use-yasnippet" id="id5">How to use YASnippet</a></li>
<li><a class="reference internal" href="#customization-group" id="id6">Customization group</a></li> <li><a class="reference internal" href="#bugs-contribution-and-support" id="id6">Bugs, Contribution and Support</a></li>
<li><a class="reference internal" href="#bugs-contribution-and-support" id="id7">Bugs, Contribution and Support</a></li>
</ul> </ul>
</div> </div>
<p>Yasnippet is a template system for emacs. It allows you to type a <p>YASnippet is a template system for Emacs. It allows you to type a
abbrevation and automatically expand the abbreviation into function abbreviation and automatically expand the abbreviation into function
templates.</p> templates.</p>
<p>Bundled language templates includes: C, C++, C#, Perl, Python, Ruby, <p>Bundled language templates includes: C, C++, C#, Perl, Python, Ruby,
SQL, LaTeX, HTML, CSS and more.</p> SQL, LaTeX, HTML, CSS and more.</p>
<p>Yasnippet system is inspired from TextMate's template system. You can <p>YASnippet system is inspired from TextMate's template system. You can
use <a class="reference external" href="https://groups.google.com/group/smart-snippet/browse_thread/thread/691fbdd33412d86e?pli=1">a tool</a> use <a class="reference external" href="https://groups.google.com/group/smart-snippet/browse_thread/thread/691fbdd33412d86e?pli=1">a tool</a>
to import any TextMate template you have to Yasnippet. It is a to import any TextMate template you have to YASnippet.</p>
re-design and re-write of my original extension <a class="reference external" href="http://code.google.com/p/smart-snippet/">smart-snippet</a>. It <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
is much cleaner and more powerful than smart-snippet.</p> 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"
width="425"
height="344"
align="right"
class="youtube-embed"
data="http://www.youtube.com/v/vOj7btx3ATg">
<param name="movie" value="http://www.youtube.com/v/vOj7btx3ATg"></param>
<param name="wmode" value="transparent"></param>
</object>
<p>Watch the <a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">demo at YouTube</a> (download a higher <p>Watch the <a class="reference external" href="http://www.youtube.com/watch?v=vOj7btx3ATg">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="brief-install-instruction"> <div class="section" id="installation">
<h1><a class="toc-backref" href="#id2">Brief Install Instruction</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 of YASnippet. One is a single file compiled
“bundle”, and the other is normal. If all you need is to use the “bundle”, and the other is normal. If all you need is to use the
builtin templates, download the bundle one. If you want to add your built-in templates, download the bundle one. If you want to add your
own templates, download the normal one.</p> own templates, download the normal one.</p>
<div class="section" id="bundle-install"> <div class="section" id="bundle-install">
<h2><a class="toc-backref" href="#id3">Bundle Install</a></h2> <h2><a class="toc-backref" href="#id3">Bundle Install</a></h2>
@ -95,7 +101,7 @@ own templates, download the normal one.</p>
<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 pre-defined abbrev and 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>
<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>
@ -120,62 +126,52 @@ following in your <tt class="docutils literal"><span class="pre">.emacs</span></
</blockquote> </blockquote>
<p>Please refer to the documentation for full customization, or use the <p>Please refer to the documentation for full customization, or use the
customization group.</p> customization group.</p>
<img align="right" alt="images/customization-group.png" class="align-right" src="images/customization-group.png" />
</div> </div>
</div> </div>
<div class="section" id="how-to-use-yasnippet"> <div class="section" id="how-to-use-yasnippet">
<h1><a class="toc-backref" href="#id5">How to use YASnippet</a></h1> <h1><a class="toc-backref" href="#id5">How to use YASnippet</a></h1>
<p>Since version 0.6, YASnippet contains more functionality. You don't <p>Since version 0.6, YASnippet contains more functionality. You don't
need to know all of it to use it sucessfully, but you it can improve need to know all of it to use it successfully, but you it can improve
your snippeting experience.</p> your snippeting experience.</p>
<p>Hence this section has been split into separate documents:</p> <p>Hence this section has been split into separate documents:</p>
<ol class="arabic simple"> <ol class="arabic simple">
<li><a class="reference external" href="snippet-organization.html">Organizing snippets</a></li> <li><a class="reference external" href="snippet-organization.html">Organizing Snippets</a></li>
</ol> </ol>
<p>Describes ways to organize your snippets in the hard disk, or not <blockquote>
organize them at all and just use plain old elisp.</p> Describes ways to organize your snippets in the hard disk (or not
<p>Also explains how to use the YASnippet menu to explore and learn new organize them at all and just use <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt>.</blockquote>
snippets.</p>
<ol class="arabic simple" start="2"> <ol class="arabic simple" start="2">
<li><a class="reference external" href="snippet-expansion.html">Controlling snippet expansion</a></li> <li><a class="reference external" href="snippet-expansion.html">Expanding Snippets</a></li>
</ol> </ol>
<p>Maybe, you'll want some snippets to be expanded in a particular mode, <blockquote>
or only under certain conditions. Also you might want snippets to wrap <p>Describes how YASnippet chooses snippets for expansion at point.</p>
themselves around a region of selected text, use a direct keybinding, <p>Maybe, you'll want some snippets to be expanded in a particular
control indenting, etc...</p> mode, or only under certain conditions, or be prompted using
<tt class="docutils literal"><span class="pre">ido</span></tt>, etc...</p>
</blockquote>
<ol class="arabic simple" start="3"> <ol class="arabic simple" start="3">
<li><a class="reference external" href="snippet-development.html">Defining your own snippets</a></li> <li><a class="reference external" href="snippet-development.html">Writing Snippets</a></li>
</ol> </ol>
<p>Describes the YASnippet definition syntax, which is similar, but not <blockquote>
equivalent to Textmate's. Includes a section about converting Textmate Describes the YASnippet definition syntax, which is very close (but
snippets.</p> not equivalent) to Textmate's. Includes a section about converting
</div> TextMate snippets.</blockquote>
<div class="section" id="customization-group"> <ol class="arabic simple" start="4">
<h1><a class="toc-backref" href="#id6">Customization group</a></h1> <li><a class="reference external" href="snippet-menu.html">The YASnippet menu</a></li>
<p>From version 0.6 onwards, there is a customization group that you can </ol>
access with:</p> <blockquote>
<p><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">customize-group</span> <span class="pre">RET</span> <span class="pre">yasnippet</span> <span class="pre">RET</span></tt></p> Explains how to use the YASnippet menu to explore and learn new
<p>Each customization variable affects how some part of YASnippet works, snippets.</blockquote>
for example automatic snippet indentation, what prompting method to
use, whether to expand snippets inside snippets, etc...</p>
<p>Inside the customization group, each variable is reasonably documented
to explain what it does.</p>
</div> </div>
<div class="section" id="bugs-contribution-and-support"> <div class="section" id="bugs-contribution-and-support">
<h1><a class="toc-backref" href="#id7">Bugs, Contribution and Support</a></h1> <h1><a class="toc-backref" href="#id6">Bugs, Contribution and Support</a></h1>
<ul class="simple"> <ul class="simple">
<li>If you find a bug, please report it at <a class="reference external" href="http://code.google.com/p/yasnippet/issues/list">Issue List</a>.</li> <li>If you find a bug, please report it at <a class="reference external" href="http://code.google.com/p/yasnippet/issues/list">Issue List</a>.</li>
<li>If you have problem using YASnippet, or have some new ideas, please <li>If you have problem using YASnippet, or have some new ideas,
post to the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a>. Especially, there's a <a class="reference external" href="http://code.google.com/p/yasnippet/wiki/WishList">wish list</a> including snippets, please post to the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a>.</li>
wiki page. I'll collect ideas from the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a> to the
<a class="reference external" href="http://code.google.com/p/yasnippet/wiki/WishList">wish list</a>. So you might want to look at the <a class="reference external" href="http://code.google.com/p/yasnippet/wiki/WishList">wish list</a> before
you post something.</li>
<li>If you want to contribute some snippets, you can also post them to
the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a>. Some common snippets may be added to
YASnippet, while others will be collected at the
<a class="reference external" href="http://code.google.com/p/yasnippet/wiki/UserContributedSnippets">UserContributedSnippets wiki page</a>.</li>
</ul> </ul>
<p>Thank you very much for using YASnippet!</p> <p>Thank you very much for using YASnippet!</p>
<!-- LocalWords: YASnippet SQL LaTeX CSS yasnippet el eval html ido RET wiki -->
</div> </div>
</div> </div>
</div> </div>

94
doc/index.rst
View File

@ -2,42 +2,47 @@
Yet Another Snippet extension Yet Another Snippet extension
============================= =============================
:Author: pluskid .. _Organizing Snippets: snippet-organization.html
:Contact: pluskid@gmail.com .. _Expanding Snippets: snippet-expansion.html
:Date: 2008-03-20 .. _Writing Snippets: snippet-development.html
.. _The YASnippet Menu: snippet-menu.html
.. 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 a
abbrevation and automatically expand the abbreviation into function abbreviation and automatically expand the abbreviation into function
templates. templates.
Bundled language templates includes: C, C++, C#, Perl, Python, Ruby, Bundled language templates includes: C, C++, C#, Perl, Python, Ruby,
SQL, LaTeX, HTML, CSS and more. SQL, LaTeX, HTML, CSS and more.
Yasnippet system is inspired from TextMate's template system. You can YASnippet system is inspired from TextMate's template system. You can
use `a tool use `a tool
<https://groups.google.com/group/smart-snippet/browse_thread/thread/691fbdd33412d86e?pli=1>`_ <http://yasnippet.googlecode.com/svn/trunk/textmate-import.rb> to
to import any TextMate template you have to Yasnippet. It is a import most TextMate templates to YASnippet.
re-design and re-write of my original extension `smart-snippet`_. It
is much cleaner and more powerful than smart-snippet. 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
: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=vOj7btx3ATg>`_ (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>`_).
Brief Install Instruction Installation
========================= ============
There are two archives of YASnippet. One is a single file compiled There are two archives of YASnippet. One is a single file compiled
“bundle”, and the other is normal. If all you need is to use the “bundle”, and the other is normal. If all you need is to use the
builtin templates, download the bundle one. If you want to add your built-in templates, download the bundle one. If you want to add your
own templates, download the normal one. own templates, download the normal one.
Bundle Install Bundle Install
@ -52,7 +57,7 @@ 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 pre-defined abbrev and 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:
.. sourcecode:: common-lisp .. sourcecode:: common-lisp
@ -80,71 +85,50 @@ following in your ``.emacs`` file:
Please refer to the documentation for full customization, or use the Please refer to the documentation for full customization, or use the
customization group. customization group.
.. image:: images/customization-group.png
:align: right
How to use YASnippet How to use YASnippet
==================== ====================
Since version 0.6, YASnippet contains more functionality. You don't Since version 0.6, YASnippet contains more functionality. You don't
need to know all of it to use it sucessfully, but you it can improve need to know all of it to use it successfully, but you it can improve
your snippeting experience. your snippeting experience.
Hence this section has been split into separate documents: Hence this section has been split into separate documents:
1. `Organizing snippets <snippet-organization.html>`_ 1. `Organizing Snippets`_
Describes ways to organize your snippets in the hard disk, or not Describes ways to organize your snippets in the hard disk (or not
organize them at all and just use plain old elisp. organize them at all and just use ``yasnippet-bundle.el``.
Also explains how to use the YASnippet menu to explore and learn new 2. `Expanding Snippets`_
snippets.
2. `Controlling snippet expansion <snippet-expansion.html>`_ Describes how YASnippet chooses snippets for expansion at point.
Maybe, you'll want some snippets to be expanded in a particular mode, Maybe, you'll want some snippets to be expanded in a particular
or only under certain conditions. Also you might want snippets to wrap mode, or only under certain conditions, or be prompted using
themselves around a region of selected text, use a direct keybinding, ``ido``, etc...
control indenting, etc...
3. `Defining your own snippets <snippet-development.html>`_ 3. `Writing Snippets`_
Describes the YASnippet definition syntax, which is similar, but not Describes the YASnippet definition syntax, which is very close (but
equivalent to Textmate's. Includes a section about converting Textmate not equivalent) to Textmate's. Includes a section about converting
snippets. TextMate snippets.
Customization group 4. `The YASnippet menu`_
===================
From version 0.6 onwards, there is a customization group that you can Explains how to use the YASnippet menu to explore and learn new
access with: snippets.
``M-x customize-group RET yasnippet RET``
Each customization variable affects how some part of YASnippet works,
for example automatic snippet indentation, what prompting method to
use, whether to expand snippets inside snippets, etc...
Inside the customization group, each variable is reasonably documented
to explain what it does.
Bugs, Contribution and Support Bugs, Contribution and Support
============================== ==============================
* If you find a bug, please report it at `Issue List * If you find a bug, please report it at `Issue List
<http://code.google.com/p/yasnippet/issues/list>`_. <http://code.google.com/p/yasnippet/issues/list>`_.
* If you have problem using YASnippet, or have some new ideas, please * If you have problem using YASnippet, or have some new ideas,
post to the `discussion group`_. Especially, there's a `wish list`_ including snippets, please post to the `discussion group`_.
wiki page. I'll collect ideas from the `discussion group`_ to the
`wish list`_. So you might want to look at the `wish list`_ before
you post something.
* If you want to contribute some snippets, you can also post them to
the `discussion group`_. Some common snippets may be added to
YASnippet, while others will be collected at the
`UserContributedSnippets wiki page
<http://code.google.com/p/yasnippet/wiki/UserContributedSnippets>`_.
.. _discussion group: http://groups.google.com/group/smart-snippet .. _discussion group: http://groups.google.com/group/smart-snippet
.. _wish list: http://code.google.com/p/yasnippet/wiki/WishList .. _wish list: http://code.google.com/p/yasnippet/wiki/WishList
Thank you very much for using YASnippet! Thank you very much for using YASnippet!
.. LocalWords: YASnippet SQL LaTeX CSS yasnippet el eval html ido RET wiki

364
doc/snippet-development.html
View File

@ -3,10 +3,8 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Writing snippets</title> <title>Writing snippets</title>
<meta name="author" content="pluskid, joaotavora" />
<meta name="date" content="2009-08-18" />
<link rel="stylesheet" href="styles.css" type="text/css" /> <link rel="stylesheet" href="styles.css" type="text/css" />
</head> </head>
<body> <body>
@ -52,28 +50,61 @@
<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="#quickly-finding-defining-snippets" id="id6">Quickly finding/defining snippets</a></li> <li><a class="reference internal" href="#snippet-development" id="id3">Snippet development</a><ul>
<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id7">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a><ul> <li><a class="reference internal" href="#quickly-finding-snippets" id="id4">Quickly finding snippets</a></li>
<li><a class="reference internal" href="#the-syntax-of-the-template" id="id8">The Syntax of the Template</a></li> <li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></li>
</ul>
</li>
<li><a class="reference internal" href="#file-content" id="id6">File content</a><ul>
<li><a class="reference internal" href="#key-snippet-abbrev" id="id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></li>
<li><a class="reference internal" href="#name-snippet-name" id="id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></li>
<li><a class="reference internal" href="#condition-snippet-condition" id="id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></li>
<li><a class="reference internal" href="#expand-env-expand-environment" id="id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></li>
<li><a class="reference internal" href="#binding-direct-keybinding" id="id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt>: direct keybinding</a></li>
<li><a class="reference internal" href="#contributor-snippet-author" id="id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt>: snippet author</a></li>
</ul>
</li>
<li><a class="reference internal" href="#template-syntax" id="id13">Template syntax</a><ul>
<li><a class="reference internal" href="#plain-text" id="id14">Plain Text</a></li>
<li><a class="reference internal" href="#embedded-emacs-lisp-code" id="id15">Embedded Emacs-lisp code</a></li>
<li><a class="reference internal" href="#tab-stop-fields" id="id16">Tab stop fields</a></li>
<li><a class="reference internal" href="#placeholder-fields" id="id17">Placeholder fields</a></li>
<li><a class="reference internal" href="#id2" id="id18">Mirrors</a></li>
<li><a class="reference internal" href="#mirrors-with-transformations" id="id19">Mirrors with transformations</a></li>
<li><a class="reference internal" href="#fields-with-transformations" id="id20">Fields with transformations</a></li>
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id21">Choosing fields value from a list</a></li>
<li><a class="reference internal" href="#nested-placeholder-fields" id="id22">Nested placeholder fields</a></li>
</ul>
</li>
<li><a class="reference internal" href="#customizable-variables" id="id23">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-trigger-key" id="id24"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-next-field-key" id="id25"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-prev-field-key" id="id26"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-skip-and-clear-key" id="id27"><tt class="docutils literal"><span class="pre">yas/skip-and-clear-key</span></tt></a></li>
<li><a class="reference internal" href="#yas-good-grace" id="id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></li>
<li><a class="reference internal" href="#yas-indent-line" id="id29"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></li>
<li><a class="reference internal" href="#yas-wrap-around-region" id="id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></li>
<li><a class="reference internal" href="#yas-triggers-in-field" id="id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></li>
<li><a class="reference internal" href="#yas-snippet-revival" id="id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></li>
<li><a class="reference internal" href="#yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook" id="id33"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#plain-text" id="id9">Plain Text</a></li>
<li><a class="reference internal" href="#embedded-elisp-code" id="id10">Embedded elisp code</a></li>
<li><a class="reference internal" href="#tab-stop-fields" id="id11">Tab stop fields</a></li>
<li><a class="reference internal" href="#placeholder-fields" id="id12">Placeholder fields</a></li>
<li><a class="reference internal" href="#id2" id="id13">Mirrors</a></li>
<li><a class="reference internal" href="#mirrors-with-transformations" id="id14">Mirrors with transformations</a></li>
<li><a class="reference internal" href="#fields-with-transformations" id="id15">Fields with transformations</a></li>
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id16">Choosing fields value from a list</a></li>
<li><a class="reference internal" href="#nested-placeholder-fields" id="id17">Nested placeholder fields</a></li>
</ul> </ul>
</div> </div>
<div class="section" id="quickly-finding-defining-snippets"> <div class="section" id="snippet-development">
<h1><a class="toc-backref" href="#id6">Quickly finding/defining snippets</a></h1> <h1><a class="toc-backref" href="#id3">Snippet development</a></h1>
<p>From version 0.6 upwards there are two ways you can quickly find a <div class="section" id="quickly-finding-snippets">
snippet file. Once you find this file it will be set to <h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2>
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead)</p> <p>There are some ways you can quickly find a snippet file. Once you find
this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead) and you can
start editing your snippet.</p>
<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>
<p>Prompts you for a snippet name, then tries to guess a suitable
directory to store it, prompting you for creation if it does not
exist. Finally, places you in a new buffer set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt>
so you can write your snippet.</p>
</li>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/find-snippets</span></tt></p> <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>.</p>
@ -86,10 +117,10 @@ directly to the snippet definition's file, if it exists.</p>
</ul> </ul>
</div> </div>
<div class="section" id="using-the-snippet-mode-major-mode"> <div class="section" id="using-the-snippet-mode-major-mode">
<h1><a class="toc-backref" href="#id7">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h1> <h2><a class="toc-backref" href="#id5">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h2>
<p>From version 0.6 upwards there is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to <p>There is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to edit snippets. You can set
edit snippets. You can set the buffer to this mode with <tt class="docutils literal"><span class="pre">M-x</span> the buffer to this mode with <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">snippet-mode</span></tt>. It provides
<span class="pre">snippet-mode</span></tt>. It provides reasonably useful syntax highlighting.</p> reasonably useful syntax highlighting.</p>
<p>Two commands are defined in this mode:</p> <p>Two commands are defined in this mode:</p>
<ul> <ul>
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p> <li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p>
@ -110,22 +141,148 @@ can see what it looks like. This is bound to <tt class="docutils literal"><span
</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 snippets for making snippets: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">field</span></tt> and
<tt class="docutils literal"><span class="pre">mirror</span></tt>.</p> <tt class="docutils literal"><span class="pre">mirror</span></tt>.</p>
<div class="section" id="the-syntax-of-the-template"> </div>
<h2><a class="toc-backref" href="#id8">The Syntax of the Template</a></h2> </div>
<div class="section" id="file-content">
<h1><a class="toc-backref" href="#id6">File content</a></h1>
<p>A file defining a snippet may just contain the template for the
snippet. Optionally it can also contains some meta data for the
snippet as well as comments.</p>
<p>Generally speaking, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, then all
contents above that line are considered directives (meta data) and
comments; below that line lies the snippet template.</p>
<p>If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found, the whole file content is considered as the
template.</p>
<p>Here's a typical example:</p>
<div class="highlight"><pre>#contributor : pluskid &lt;pluskid@gmail.com&gt;
#name : __...__
# --
__${init}__
</pre></div>
<p>Meta data are specified in the syntax of</p>
<div class="highlight"><pre>#data-name : data value
</pre></div>
<p>Any other text above <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is considered as comment and
ignored. Here's a list of currently supported directives:</p>
<div class="section" id="key-snippet-abbrev">
<h2><a class="toc-backref" href="#id7"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> snippet abbrev</a></h2>
<p>This is the probably the most important directive, it's the
abbreviation you type to expand a snippet just before hitting
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p>
<p>If you don't specify this it will default to the name of the file the
snippet is being loaded from, unless YASnippet is ignoring file names
as triggers (see <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> in <a class="reference external" href="snippet-organization.html">Organizing
snippets</a>), in which case this snippet
will not be expandable through the key mechanism.</p>
<p>Sometimes the key of a snippet is non-ASCII or not valid filename
(e.g. contains <tt class="docutils literal"><span class="pre">/</span></tt>). One can then define the <tt class="docutils literal"><span class="pre">key</span></tt> property which
will overwrite the filename as the key to expand the snippet.</p>
</div>
<div class="section" id="name-snippet-name">
<h2><a class="toc-backref" href="#id8"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">name:</span></tt> snippet name</a></h2>
<p>This is a one-line description of the snippet. It will be displayed in
the menu. It's a good idea to select a descriptive name for a
snippet -- especially distinguishable among similar snippets.</p>
<p>If you omit this name it will default to the file name the snippet was
loaded from.</p>
</div>
<div class="section" id="condition-snippet-condition">
<h2><a class="toc-backref" href="#id9"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> snippet condition</a></h2>
<p>This is a piece of Emacs-lisp code. If a snippet has a condition, then it
will only be expanded when the condition code evaluate to some non-nil
value.</p>
<p>See also <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> in <a class="reference external" href="snippet-expansion.html">Expanding snippets</a></p>
<p><tt class="docutils literal"><span class="pre">#</span> <span class="pre">group</span></tt> snippet menu grouping</p>
<p>When expanding/visiting snippets from the menu-bar menu, snippets for a
given mode can be grouped into sub-menus . This is useful if one has
too many snippets for a mode which will make the menu too
long.</p>
<p>The <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> property only affect menu construction (See <a class="reference external" href="snippet-menu.html">the
YASnippet menu</a>) and the same effect can be achieved by grouping
snippets into sub-directories and using the <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt>
special file (for this see <a class="reference external" href="snippet-organization.html">Organizing Snippets</a></p>
<p>Refer to the bundled snippets for <tt class="docutils literal"><span class="pre">ruby-mode</span></tt> for examples on the
<tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> directive. Group can also be nested, e.g. <tt class="docutils literal"><span class="pre">control</span>
<span class="pre">structure.loops</span></tt> tells that the snippet is under the <tt class="docutils literal"><span class="pre">loops</span></tt> group
which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt> group.</p>
</div>
<div class="section" id="expand-env-expand-environment">
<h2><a class="toc-backref" href="#id10"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> expand environment</a></h2>
<p>This is another piece of Emacs-lisp code in the form of a <tt class="docutils literal"><span class="pre">let</span></tt> <em>varlist</em>
form, i.e. a list of lists assigning values to variables. It can be
used to override variable values while the snippet is being expanded.</p>
<p>Interesting variables to override are <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> and
<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> (see <a class="reference external" href="snippet-expansion.html">Expanding Snippets</a>).</p>
<p>As an example, you might normally have <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> set to
<tt class="docutils literal"><span class="pre">'auto</span></tt> and <tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt> set to <tt class="docutils literal"><span class="pre">t</span></tt>, but for this
particularly brilliant piece of ASCII art these values would mess up
your hard work. You can then use:</p>
<div class="highlight"><pre># name : ASCII home
# expand-env: ((yas/indent-line &#39;fixed) (yas/wrap-around-region &#39;nil))
# --
welcome to my
X humble
/ \ home,
/ \ $0
/ \
/-------\
| |
| +-+ |
| | | |
+--+-+--+
</pre></div>
</div>
<div class="section" id="binding-direct-keybinding">
<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">binding:</span></tt>: direct keybinding</a></h2>
<p>You can use this directive to expand a snippet directly from a normal
Emacs keybinding. The keybinding will be registered in the Emacs
keymap named after the major mode the snippet is active
for.</p>
<p>Additionally a variable <tt class="docutils literal"><span class="pre">yas/prefix</span></tt> is set to to the prefix
argument you normally use for a command. This allows for small
variations on the same snippet, for example in this &quot;html-mode&quot;
snippet.</p>
<div class="highlight"><pre>#name : &lt;p&gt;...&lt;/p&gt;
#binding: &quot;C-c C-c C-m&quot;
# --
&lt;p&gt;`(when yas/prefix &quot;\n&quot;)`$0`(when yas/prefix &quot;\n&quot;)`&lt;/p&gt;
</pre></div>
<p>This binding will be recorded in the keymap <tt class="docutils literal"><span class="pre">html-mode-map</span></tt>. To
expand a paragraph tag newlines, just press &quot;C-u C-c C-c
C-m&quot;. Omitting the &quot;C-u&quot; will expand the paragraph tag without
newlines.</p>
<p>To override the keymap choice based on the major mode name. Use a cons
cell where the first element specifies the name of the keymap where
you want to record the keybinding.</p>
<div class="highlight"><pre>
</pre></div>
<p>Note that this feature is still experimental and should be used with
caution: It is easy to override important keybindings for many basic
modes and it is hard to undefine them. In particular, the variable
<tt class="docutils literal"><span class="pre">yas/active-keybinding</span></tt> can tell you what snippet keybindings are
active and the function <tt class="docutils literal"><span class="pre">yas/kill-snippet-keybindings</span></tt> will try to
undefine all the keybindings.</p>
</div>
<div class="section" id="contributor-snippet-author">
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">#</span> <span class="pre">contributor:</span></tt>: snippet author</a></h2>
<p>This is optional and has no effect whatsoever on snippet
functionality, but it looks nice.</p>
</div>
</div>
<div class="section" id="template-syntax">
<h1><a class="toc-backref" href="#id13">Template syntax</a></h1>
<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>
</div>
<div class="section" id="plain-text"> <div class="section" id="plain-text">
<h1><a class="toc-backref" href="#id9">Plain Text</a></h1> <h2><a class="toc-backref" href="#id14">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-elisp-code"> <div class="section" id="embedded-emacs-lisp-code">
<h1><a class="toc-backref" href="#id10">Embedded elisp code</a></h1> <h2><a class="toc-backref" href="#id15">Embedded Emacs-lisp code</a></h2>
<p>Elisp code can be embedded inside the template. They are written <p>Emacs-Lisp code can be embedded inside the template. They are written
inside back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>):</p> inside back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>):</p>
<p>They are evaluated when the snippet is being expanded. The evaluation <p>They are evaluated when the snippet is being expanded. The evaluation
is done in the same buffer as the snippet being expanded. Here's an is done in the same buffer as the snippet being expanded. Here's an
@ -138,7 +295,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.0, snippets expansions are run with some special
emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You 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) {
`yas/selected-text`$0 `yas/selected-text`$0
@ -149,9 +306,9 @@ 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">
<h1><a class="toc-backref" href="#id11">Tab stop fields</a></h1> <h2><a class="toc-backref" href="#id16">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> <a class="footnote-reference" href="#id5" id="id1">[3]</a>. They are written by <tt class="docutils literal"><span class="pre">$</span></tt> followed with a 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
snippet. That is the last place to go when you've traveled all the snippet. That is the last place to go when you've traveled all the
fields. Here's a typical example:</p> fields. Here's a typical example:</p>
@ -161,7 +318,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">
<h1><a class="toc-backref" href="#id12">Placeholder fields</a></h1> <h2><a class="toc-backref" href="#id17">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}
@ -172,7 +329,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><h1><a class="toc-backref" href="#id13">Mirrors</a></h1> <span id="mirrors"></span><h2><a class="toc-backref" href="#id18">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>
@ -188,10 +345,10 @@ 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><h1><a class="toc-backref" href="#id14">Mirrors with transformations</a></h1> <span id="transformations"></span><h2><a class="toc-backref" href="#id19">Mirrors with transformations</a></h2>
<p>If the default value of a field starts with <tt class="docutils literal"><span class="pre">$</span></tt>, then it is interpreted <p>If the default value of a field starts with <tt class="docutils literal"><span class="pre">$</span></tt>, then it is interpreted
as the transformation code instead of default value. A transformation as the transformation code instead of default value. A transformation
is some arbitrary elisp code that will get evaluated in an environment is some arbitrary Emacs-lisp code that will get evaluated in an environment
when the variable text is bind to the inputted text of the when the variable text is bind to the inputted text of the
field. Here's an example for Objective-C:</p> field. Here's an example for Objective-C:</p>
<div class="highlight"><pre>- (${1:id})${2:foo} <div class="highlight"><pre>- (${1:id})${2:foo}
@ -210,8 +367,8 @@ $0
a placeholder. The actual placeholder is at the first line: a placeholder. The actual placeholder is at the first line:
<tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the transformation <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the transformation
will be evaluated and the result will be placed there as the will be evaluated and the result will be placed there as the
transformated text. So in this example, if you type baz in the field, transformed text. So in this example, if you type &quot;baz&quot; in the field,
the transformed text will be Baz. This example is also available in the transformed text will be &quot;Baz&quot;. This example is also available in
the screencast.</p> the screencast.</p>
<p>Another example is for <tt class="docutils literal"><span class="pre">rst-mode</span></tt>. In reStructuredText, the document <p>Another example is for <tt class="docutils literal"><span class="pre">rst-mode</span></tt>. In reStructuredText, the document
title can be some text surrounded by &quot;===&quot; below and above. The &quot;===&quot; title can be some text surrounded by &quot;===&quot; below and above. The &quot;===&quot;
@ -232,27 +389,9 @@ ${1:$(make-string (string-width text) ?\=)}
$0 $0
</pre></div> </pre></div>
<table class="docutils footnote" frame="void" id="id3" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td>With some minor change, mainly for fixing some trivial bugs.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id4" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td>This is done when you call <tt class="docutils literal"><span class="pre">yas/initialize</span></tt>.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id5" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[3]</a></td><td>Of course, this can be customized.</td></tr>
</tbody>
</table>
</div> </div>
<div class="section" id="fields-with-transformations"> <div class="section" id="fields-with-transformations">
<h1><a class="toc-backref" href="#id15">Fields with transformations</a></h1> <h2><a class="toc-backref" href="#id20">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
@ -264,8 +403,8 @@ distinguish between fields and mirrors. In the following example</p>
<p><tt class="docutils literal"><span class="pre">mydefine</span></tt> gets automatically upcased to <tt class="docutils literal"><span class="pre">MYDEFINE</span></tt> once you enter <p><tt class="docutils literal"><span class="pre">mydefine</span></tt> gets automatically upcased to <tt class="docutils literal"><span class="pre">MYDEFINE</span></tt> once you enter
the field. As you type text, it gets filtered through the the field. As you type text, it gets filtered through the
transformation every time.</p> transformation every time.</p>
<p>Note that this is differentiated from a mirror with a transformation <p>Note that to tell this kind of expression from a mirror with a
by the existance of extra text between the <tt class="docutils literal"><span class="pre">:</span></tt> and the transformation, YASnippet needs extra text between the <tt class="docutils literal"><span class="pre">:</span></tt> and the
transformation's <tt class="docutils literal"><span class="pre">$</span></tt>. If you don't want this extra-text, you can use transformation's <tt class="docutils literal"><span class="pre">$</span></tt>. If you don't want this extra-text, you can use
two <tt class="docutils literal"><span class="pre">$</span></tt>'s instead.</p> two <tt class="docutils literal"><span class="pre">$</span></tt>'s instead.</p>
<div class="highlight"><pre>#define &quot;${1:$$(upcase yas/text)}&quot; <div class="highlight"><pre>#define &quot;${1:$$(upcase yas/text)}&quot;
@ -276,7 +415,7 @@ the value of the field and sets it its internal modification state to
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">
<h1><a class="toc-backref" href="#id16">Choosing fields value from a list</a></h1> <h2><a class="toc-backref" href="#id21">Choosing fields value from a list</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
@ -292,7 +431,7 @@ using the two variables. Also check out <tt class="docutils literal"><span class
another neat trick.</p> another neat trick.</p>
</div> </div>
<div class="section" id="nested-placeholder-fields"> <div class="section" id="nested-placeholder-fields">
<h1><a class="toc-backref" href="#id17">Nested placeholder fields</a></h1> <h2><a class="toc-backref" href="#id22">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>
@ -304,6 +443,103 @@ straight to the exit marker.</p>
<p>By the way, <tt class="docutils literal"><span class="pre">C-d</span></tt> will only clear the field if you cursor is at the <p>By the way, <tt class="docutils literal"><span class="pre">C-d</span></tt> will only clear the field if you cursor is at the
beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it
performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p> performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p>
</div>
</div>
<div class="section" id="customizable-variables">
<h1><a class="toc-backref" href="#id23">Customizable variables</a></h1>
<div class="section" id="yas-trigger-key">
<h2><a class="toc-backref" href="#id24"><tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt></a></h2>
<p>The key bound to <tt class="docutils literal"><span class="pre">yas/expand</span></tt> when function <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is
active.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
<p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
</div>
<div class="section" id="yas-next-field-key">
<h2><a class="toc-backref" href="#id25"><tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt></a></h2>
<p>The key to navigate to next field when a snippet is active.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
<p>Can also be a list of keys.</p>
<p>Default value is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>.</p>
</div>
<div class="section" id="yas-prev-field-key">
<h2><a class="toc-backref" href="#id26"><tt class="docutils literal"><span class="pre">yas/prev-field-key</span></tt></a></h2>
<p>The key to navigate to previous field when a snippet is active.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
<p>Can also be a list of keys.</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 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>
<p>The key to clear the currently active field.</p>
<p>Value is a string that is converted to the internal Emacs key
representation using <tt class="docutils literal"><span class="pre">read-kbd-macro</span></tt>.</p>
<p>Can also be a list of keys.</p>
<p>Default value is <tt class="docutils literal"><span class="pre">&quot;C-d&quot;</span></tt>.</p>
</div>
<div class="section" id="yas-good-grace">
<h2><a class="toc-backref" href="#id28"><tt class="docutils literal"><span class="pre">yas/good-grace</span></tt></a></h2>
<p>If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
snippet definitions. An error string &quot;[yas] error&quot; is returned instead.</p>
</div>
<div class="section" id="yas-indent-line">
<h2><a class="toc-backref" href="#id29"><tt class="docutils literal"><span class="pre">yas/indent-line</span></tt></a></h2>
<p>The variable <tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> controls the indenting. It is bound
to <tt class="docutils literal"><span class="pre">'auto</span></tt> by default, which causes your snippet to be indented
according to the mode of the buffer it was inserted in.</p>
<p>Another variable <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt>, when non-nil
does exactly that :-).</p>
<p>To use the hard-coded indentation in your snippet template, set this
variable to <tt class="docutils literal"><span class="pre">fixed</span></tt>.</p>
<p>To control indentation on a per-snippet basis, see also the directive
<tt class="docutils literal"><span class="pre">#</span> <span class="pre">expand-env:</span></tt> in <a class="reference external" href="snippet-development.html">Writing Snippets</a>.</p>
<p>For backward compatibility with earlier versions of YASnippet, you can
also place a <tt class="docutils literal"><span class="pre">$&gt;</span></tt> in your snippet, an <tt class="docutils literal"><span class="pre">(indent-according-to-mode)</span></tt>
will be executed there to indent the line. This only takes effect when
<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> is set to something other than <tt class="docutils literal"><span class="pre">'auto</span></tt>.</p>
<div class="highlight"><pre>for (${int i = 0}; ${i &lt; 10}; ${++i})
{$&gt;
$0$&gt;
}$&gt;
</pre></div>
</div>
<div class="section" id="yas-wrap-around-region">
<h2><a class="toc-backref" href="#id30"><tt class="docutils literal"><span class="pre">yas/wrap-around-region</span></tt></a></h2>
<p>If non-nil, YASnippet will try to expand the snippet's exit marker
around the currently selected region. When this variable is set to t,
this has the same effect has using the <tt class="docutils literal"><span class="pre">`yas/selected-text`</span></tt> inline
evaluation.</p>
<p>Because on most systems starting to type deletes the currently region,
this works mostly with the <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> command.</p>
<p>However, when the value is of this variable is <tt class="docutils literal"><span class="pre">cua</span></tt> YASnippet will
additionally look-up any recently selected that you deleted by starting
typing. This allows you select a region, type a snippet key (deleting
the region), then press <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to see the deleted region
spring back to life inside your new snippet.</p>
</div>
<div class="section" id="yas-triggers-in-field">
<h2><a class="toc-backref" href="#id31"><tt class="docutils literal"><span class="pre">yas/triggers-in-field</span></tt></a></h2>
<p>If non-nil, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> can trigger stacked expansions,
that is a snippet expansion inside another snippet
expansion. Otherwise, <tt class="docutils literal"><span class="pre">yas/next-field-key</span></tt> just tries to move on to
the next field.</p>
</div>
<div class="section" id="yas-snippet-revival">
<h2><a class="toc-backref" href="#id32"><tt class="docutils literal"><span class="pre">yas/snippet-revival</span></tt></a></h2>
<p>Non-nil means re-activate snippet fields after undo/redo.</p>
</div>
<div class="section" id="yas-after-exit-snippet-hook-and-yas-before-expand-snippet-hook">
<h2><a class="toc-backref" href="#id33"><tt class="docutils literal"><span class="pre">yas/after-exit-snippet-hook</span></tt> and <tt class="docutils literal"><span class="pre">yas/before-expand-snippet-hook</span></tt></a></h2>
<p>These hooks are called, respectively, before the insertion of a
snippet and after exiting the snippet. If you find any strange but
functional use for them, that's probably a design flaw in YASnippet,
so let us know.</p>
<!-- LocalWords: html YASnippet yas sourcecode pluskid init filenames filename -->
<!-- LocalWords: env varlist keybinding keymap rinari ifndef upcase endif -->
<!-- LocalWords: nondirectory autorelease aValue inline -->
</div>
</div> </div>
</div> </div>
</div> </div>

354
doc/snippet-development.rst
View File

@ -2,18 +2,29 @@
Writing snippets Writing snippets
================ ================
:Author: pluskid, joaotavora .. _Organizing Snippets: snippet-organization.html
:Contact: pluskid@gmail.com .. _Expanding Snippets: snippet-expansion.html
:Date: 2009-08-18 .. _Writing Snippets: snippet-development.html
.. _The YASnippet Menu: snippet-menu.html
.. contents:: .. contents::
Quickly finding/defining snippets Snippet development
--------------------------------- ===================
From version 0.6 upwards there are two ways you can quickly find a Quickly finding snippets
snippet file. Once you find this file it will be set to ------------------------
``snippet-mode`` (see ahead)
There are some ways you can quickly find a snippet file. Once you find
this file it will be set to ``snippet-mode`` (see ahead) and you can
start editing your snippet.
* ``M-x yas/new-snippet``
Prompts you for a snippet name, then tries to guess a suitable
directory to store it, prompting you for creation if it does not
exist. Finally, places you in a new buffer set to ``snippet-mode``
so you can write your snippet.
* ``M-x yas/find-snippets`` * ``M-x yas/find-snippets``
@ -30,9 +41,9 @@ snippet file. Once you find this file it will be set to
Using the ``snippet-mode`` major mode Using the ``snippet-mode`` major mode
------------------------------------- -------------------------------------
From version 0.6 upwards there is a major mode ``snippet-mode`` to There is a major mode ``snippet-mode`` to edit snippets. You can set
edit snippets. You can set the buffer to this mode with ``M-x the buffer to this mode with ``M-x snippet-mode``. It provides
snippet-mode``. It provides reasonably useful syntax highlighting. reasonably useful syntax highlighting.
Two commands are defined in this mode: Two commands are defined in this mode:
@ -52,10 +63,177 @@ Two commands are defined in this mode:
There are also snippets for making snippets: ``vars``, ``field`` and There are also snippets for making snippets: ``vars``, ``field`` and
``mirror``. ``mirror``.
File content
============
A file defining a snippet may just contain the template for the
snippet. Optionally it can also contains some meta data for the
snippet as well as comments.
Generally speaking, if the file contains a line of ``# --``, then all
contents above that line are considered directives (meta data) and
comments; below that line lies the snippet template.
If no ``# --`` is found, the whole file content is considered as the
template.
Here's a typical example:
.. sourcecode:: text
#contributor : pluskid <pluskid@gmail.com>
#name : __...__
# --
__${init}__
Meta data are specified in the syntax of
.. sourcecode:: text
#data-name : data value
Any other text above ``# --`` is considered as comment and
ignored. Here's a list of currently supported directives:
``# key:`` snippet abbrev
--------------------------
This is the probably the most important directive, it's the
abbreviation you type to expand a snippet just before hitting
``yas/trigger-key``.
If you don't specify this it will default to the name of the file the
snippet is being loaded from, unless YASnippet is ignoring file names
as triggers (see ``yas/ignore-filenames-as-triggers`` in `Organizing
snippets`_), in which case this snippet
will not be expandable through the key mechanism.
Sometimes the key of a snippet is non-ASCII or not valid filename
(e.g. contains ``/``). One can then define the ``key`` property which
will overwrite the filename as the key to expand the snippet.
``# name:`` snippet name
------------------------
This is a one-line description of the snippet. It will be displayed in
the menu. It's a good idea to select a descriptive name for a
snippet -- especially distinguishable among similar snippets.
If you omit this name it will default to the file name the snippet was
loaded from.
The Syntax of the Template ``# condition:`` snippet condition
========================== ----------------------------------
This is a piece of Emacs-lisp code. If a snippet has a condition, then it
will only be expanded when the condition code evaluate to some non-nil
value.
See also ``yas/buffer-local-condition`` in `Expanding snippets`_
``# group`` snippet menu grouping
When expanding/visiting snippets from the menu-bar menu, snippets for a
given mode can be grouped into sub-menus . This is useful if one has
too many snippets for a mode which will make the menu too
long.
The ``# group:`` property only affect menu construction (See `the
YASnippet menu`_) and the same effect can be achieved by grouping
snippets into sub-directories and using the ``.yas-make-groups``
special file (for this see `Organizing Snippets`_
Refer to the bundled snippets for ``ruby-mode`` for examples on the
``# group:`` directive. Group can also be nested, e.g. ``control
structure.loops`` tells that the snippet is under the ``loops`` group
which is under the ``control structure`` group.
``# expand-env:`` expand environment
------------------------------------
This is another piece of Emacs-lisp code in the form of a ``let`` *varlist*
form, i.e. a list of lists assigning values to variables. It can be
used to override variable values while the snippet is being expanded.
Interesting variables to override are ``yas/wrap-around-region`` and
``yas/indent-line`` (see `Expanding Snippets`_).
As an example, you might normally have ``yas/indent-line`` set to
``'auto`` and ``yas/wrap-around-region`` set to ``t``, but for this
particularly brilliant piece of ASCII art these values would mess up
your hard work. You can then use:
.. sourcecode:: text
# name : ASCII home
# expand-env: ((yas/indent-line 'fixed) (yas/wrap-around-region 'nil))
# --
welcome to my
X humble
/ \ home,
/ \ $0
/ \
/-------\
| |
| +-+ |
| | | |
+--+-+--+
``# binding:``: direct keybinding
---------------------------------
You can use this directive to expand a snippet directly from a normal
Emacs keybinding. The keybinding will be registered in the Emacs
keymap named after the major mode the snippet is active
for.
Additionally a variable ``yas/prefix`` is set to to the prefix
argument you normally use for a command. This allows for small
variations on the same snippet, for example in this "html-mode"
snippet.
.. sourcecode:: text
#name : <p>...</p>
#binding: "C-c C-c C-m"
# --
<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
This binding will be recorded in the keymap ``html-mode-map``. To
expand a paragraph tag newlines, just press "C-u C-c C-c
C-m". Omitting the "C-u" will expand the paragraph tag without
newlines.
To override the keymap choice based on the major mode name. Use a cons
cell where the first element specifies the name of the keymap where
you want to record the keybinding.
.. sourcecode:: text
#name : <p>...</p>
#binding: (rinari-minor-mode-map . "C-c C-c C-m")
# --
<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
Note that this feature is still experimental and should be used with
caution: It is easy to override important keybindings for many basic
modes and it is hard to undefine them. In particular, the variable
``yas/active-keybinding`` can tell you what snippet keybindings are
active and the function ``yas/kill-snippet-keybindings`` will try to
undefine all the keybindings.
``# contributor:``: snippet author
---------------------------------------------------
This is optional and has no effect whatsoever on snippet
functionality, but it looks nice.
Template syntax
===============
The syntax of the snippet template is simple but powerful, very The syntax of the snippet template is simple but powerful, very
similar to TextMate's. similar to TextMate's.
@ -68,10 +246,10 @@ usually interpreted as plain text, except ``$`` and `````. You need to
use ``\`` to escape them: ``\$`` and ``\```. The ``\`` itself may also use ``\`` to escape them: ``\$`` and ``\```. The ``\`` itself may also
needed to be escaped as ``\\`` sometimes. needed to be escaped as ``\\`` sometimes.
Embedded elisp code Embedded Emacs-lisp code
------------------- ------------------------
Elisp code can be embedded inside the template. They are written Emacs-Lisp code can be embedded inside the template. They are written
inside back-quotes (`````): inside back-quotes (`````):
They are evaluated when the snippet is being expanded. The evaluation They are evaluated when the snippet is being expanded. The evaluation
@ -88,7 +266,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.0, 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:
.. sourcecode:: text .. sourcecode:: text
@ -105,7 +283,7 @@ Tab stop fields
--------------- ---------------
Tab stops are fields that you can navigate back and forth by ``TAB`` Tab stops are fields that you can navigate back and forth by ``TAB``
and ``S-TAB`` [3]_. They are written by ``$`` followed with a and ``S-TAB``. They are written by ``$`` followed with a
number. ``$0`` has the special meaning of the *exit point* of a number. ``$0`` has the special meaning of the *exit point* of a
snippet. That is the last place to go when you've traveled all the snippet. That is the last place to go when you've traveled all the
fields. Here's a typical example: fields. Here's a typical example:
@ -163,7 +341,7 @@ Mirrors with transformations
If the default value of a field starts with ``$``, then it is interpreted If the default value of a field starts with ``$``, then it is interpreted
as the transformation code instead of default value. A transformation as the transformation code instead of default value. A transformation
is some arbitrary elisp code that will get evaluated in an environment is some arbitrary Emacs-lisp code that will get evaluated in an environment
when the variable text is bind to the inputted text of the when the variable text is bind to the inputted text of the
field. Here's an example for Objective-C: field. Here's an example for Objective-C:
@ -185,8 +363,8 @@ Look at ``${2:$(capitalize text)}``, it is a transformation instead of
a placeholder. The actual placeholder is at the first line: a placeholder. The actual placeholder is at the first line:
``${2:foo}``. When you type text in ``${2:foo}``, the transformation ``${2:foo}``. When you type text in ``${2:foo}``, the transformation
will be evaluated and the result will be placed there as the will be evaluated and the result will be placed there as the
transformated text. So in this example, if you type baz in the field, transformed text. So in this example, if you type "baz" in the field,
the transformed text will be Baz. This example is also available in the transformed text will be "Baz". This example is also available in
the screencast. the screencast.
Another example is for ``rst-mode``. In reStructuredText, the document Another example is for ``rst-mode``. In reStructuredText, the document
@ -217,10 +395,6 @@ is not. Here's an snippet for rst title:
$0 $0
.. [1] With some minor change, mainly for fixing some trivial bugs.
.. [2] This is done when you call ``yas/initialize``.
.. [3] Of course, this can be customized.
Fields with transformations Fields with transformations
--------------------------- ---------------------------
@ -240,8 +414,8 @@ distinguish between fields and mirrors. In the following example
the field. As you type text, it gets filtered through the the field. As you type text, it gets filtered through the
transformation every time. transformation every time.
Note that this is differentiated from a mirror with a transformation Note that to tell this kind of expression from a mirror with a
by the existance of extra text between the ``:`` and the transformation, YASnippet needs extra text between the ``:`` and the
transformation's ``$``. If you don't want this extra-text, you can use transformation's ``$``. If you don't want this extra-text, you can use
two ``$``'s instead. two ``$``'s instead.
@ -293,3 +467,129 @@ straight to the exit marker.
By the way, ``C-d`` will only clear the field if you cursor is at the By the way, ``C-d`` will only clear the field if you cursor is at the
beginning of the field *and* it hasn't been changed yet. Otherwise, it beginning of the field *and* it hasn't been changed yet. Otherwise, it
performs the normal Emacs ``delete-char`` command. performs the normal Emacs ``delete-char`` command.
Customizable variables
======================
``yas/trigger-key``
-------------------
The key bound to ``yas/expand`` when function ``yas/minor-mode`` is
active.
Value is a string that is converted to the internal Emacs key
representation using ``read-kbd-macro``.
Default value is ``"TAB"``.
``yas/next-field-key``
----------------------
The key to navigate to next field when a snippet is active.
Value is a string that is converted to the internal Emacs key
representation using ``read-kbd-macro``.
Can also be a list of keys.
Default value is ``"TAB"``.
``yas/prev-field-key``
----------------------
The key to navigate to previous field when a snippet is active.
Value is a string that is converted to the internal Emacs key
representation using ``read-kbd-macro``.
Can also be a list of keys.
Default value is ``("<backtab>" "<S-tab>)"``.
``yas/skip-and-clear-key``
--------------------------
The key to clear the currently active field.
Value is a string that is converted to the internal Emacs key
representation using ``read-kbd-macro``.
Can also be a list of keys.
Default value is ``"C-d"``.
``yas/good-grace``
------------------
If non-nil, don't raise errors in inline Emacs-lisp evaluation inside
snippet definitions. An error string "[yas] error" is returned instead.
``yas/indent-line``
-------------------
The variable ``yas/indent-line`` controls the indenting. It is bound
to ``'auto`` by default, which causes your snippet to be indented
according to the mode of the buffer it was inserted in.
Another variable ``yas/also-auto-indent-first-line``, when non-nil
does exactly that :-).
To use the hard-coded indentation in your snippet template, set this
variable to ``fixed``.
To control indentation on a per-snippet basis, see also the directive
``# expand-env:`` in `Writing Snippets`_.
For backward compatibility with earlier versions of YASnippet, you can
also place a ``$>`` in your snippet, an ``(indent-according-to-mode)``
will be executed there to indent the line. This only takes effect when
``yas/indent-line`` is set to something other than ``'auto``.
.. sourcecode:: text
for (${int i = 0}; ${i < 10}; ${++i})
{$>
$0$>
}$>
``yas/wrap-around-region``
--------------------------
If non-nil, YASnippet will try to expand the snippet's exit marker
around the currently selected region. When this variable is set to t,
this has the same effect has using the ```yas/selected-text``` inline
evaluation.
Because on most systems starting to type deletes the currently region,
this works mostly with the ``yas/insert-snippet`` command.
However, when the value is of this variable is ``cua`` YASnippet will
additionally look-up any recently selected that you deleted by starting
typing. This allows you select a region, type a snippet key (deleting
the region), then press ``yas/trigger-key`` to see the deleted region
spring back to life inside your new snippet.
``yas/triggers-in-field``
--------------------------
If non-nil, ``yas/next-field-key`` can trigger stacked expansions,
that is a snippet expansion inside another snippet
expansion. Otherwise, ``yas/next-field-key`` just tries to move on to
the next field.
``yas/snippet-revival``
-----------------------
Non-nil means re-activate snippet fields after undo/redo.
``yas/after-exit-snippet-hook`` and ``yas/before-expand-snippet-hook``
----------------------------------------------------------------------
These hooks are called, respectively, before the insertion of a
snippet and after exiting the snippet. If you find any strange but
functional use for them, that's probably a design flaw in YASnippet,
so let us know.
.. LocalWords: html YASnippet yas sourcecode pluskid init filenames filename
.. LocalWords: env varlist keybinding keymap rinari ifndef upcase endif
.. LocalWords: nondirectory autorelease aValue inline

649
doc/snippet-expansion.html
View File

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

571
doc/snippet-expansion.rst
View File

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

101
doc/snippet-menu.html
View File

@ -3,20 +3,18 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>The menu</title> <title>YASnippet menu</title>
<meta name="author" content="pluskid, joaotavora" />
<meta name="date" content="2009-08-18" />
<link rel="stylesheet" href="styles.css" type="text/css" /> <link rel="stylesheet" href="styles.css" type="text/css" />
</head> </head>
<body> <body>
<div class="document" id="the-menu"> <div class="document" id="yasnippet-menu">
<div id="header-region" class="clear-block"></div> <div id="header-region" class="clear-block"></div>
<div id="wrapper"> <div id="wrapper">
<div id="container" class="clear-block"> <div id="container" class="clear-block">
<div id="header"> <div id="header">
<div id="logo-floater"> <div id="logo-floater">
<h1 class="title">The menu</h1> <h1 class="title">YASnippet menu</h1>
</div> </div>
<ul class="primary-links"> <ul class="primary-links">
<li> <li>
@ -49,35 +47,72 @@
<div id="squeeze"> <div id="squeeze">
<div class="right-corner"> <div class="right-corner">
<div class="left-corner"> <div class="left-corner">
<p>YASnippet will setup a menu just after the <em>Buffers</em> Menu in the <div class="contents topic" id="contents">
menubar. The snippets for all <em>real</em> modes are listed there under the <p class="topic-title first">Contents</p>
menu. You can select a snippet from the menu to expand it. Since you
select manually from the menu, you can expand any snippet. For
example, you can expand a snippet defined for <tt class="docutils literal"><span class="pre">python-mode</span></tt> in a
<tt class="docutils literal"><span class="pre">c-mode</span></tt> buffer by selecting it from the menu:</p>
<img align="right" alt="images/menubar.png" class="align-right" src="images/menubar.png" />
<ul class="simple"> <ul class="simple">
<li>Condition system is ignored since you select to expand it <li><a class="reference internal" href="#loading-snippets-from-menu" id="id1">Loading snippets from menu</a></li>
explicitly.</li> <li><a class="reference internal" href="#snippet-menu-behavior" id="id2">Snippet menu behavior</a></li>
<li>There will be no muliple candidates since they are listed in the <li><a class="reference internal" href="#controlling-indenting" id="id3">Controlling indenting</a></li>
menu as different items.</li> <li><a class="reference internal" href="#prompting-method" id="id4">Prompting method</a></li>
<li><a class="reference internal" href="#misc" id="id5">Misc</a></li>
</ul> </ul>
<p>This can be convenient sometimes. However, if you don't like the </div>
menubar of Emacs and never use it. You can tell YASnippet don't boring <p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active, YASnippet will setup a menu just
to build a menu by setting <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to nil.</p> after the Buffers Menu in the menubar.</p>
<p>Another thing to note is that only <em>real</em> modes are listed under the <p>In this menu, you can find</p>
menu. As you know, common snippets can be shared by making up a <ul class="simple">
<em>virtual</em> parent mode. It's too bad if the menu is floored by those <li>The currently loaded snippet definitions, organized by major mode,
<em>virtual</em> modes. So YASnippet only show menus for those <em>real</em> and optional grouping.</li>
modes. But the snippets fo the <em>virtual</em> modes can still be accessed <li>A rundown of the most common commands, (followed by their
through the <tt class="docutils literal"><span class="pre">parent</span></tt> submenu of some <em>real</em> mode.</p> keybindings) including commands to load directories and reload all
<p>YASnippet use a simple way to check whether a mode is <em>real</em> or snippet definitions.</li>
<em>virtual</em>: <tt class="docutils literal"><span class="pre">(fboundp</span> <span class="pre">mode)</span></tt>. For example, the symbol <tt class="docutils literal"><span class="pre">c-mode</span></tt> is <li>A series of submenus for customizing and exploring YASnippet
bound to a function while <tt class="docutils literal"><span class="pre">cc-mode</span></tt> is not. But this is not enough, behavior.</li>
some modes aren't part of Emacs, and maybe when initializing </ul>
YASnippet, those modes haven't been initialized. So YASnippet also <img align="right" alt="images/menu-1.png" class="align-right" src="images/menu-1.png" />
maintain a list of known modes (<tt class="docutils literal"><span class="pre">yas/known-modes</span></tt>). You can add item <div class="section" id="loading-snippets-from-menu">
to that list if you need.</p> <h1><a class="toc-backref" href="#id1">Loading snippets from menu</a></h1>
<p>Invoking &quot;Load snippets...&quot; from the menu invokes
<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> and prompts you for a snippet directory
hierarchy to load.</p>
<p>Also useful is the &quot;Reload all&quot; options which uncondionally reloads
all the snippets directories defined in <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> and
rebuilds the menus.</p>
</div>
<div class="section" id="snippet-menu-behavior">
<h1><a class="toc-backref" href="#id2">Snippet menu behavior</a></h1>
<p>YASnippet will list in this section all the loaded snippet definitions
organized by snippet table name.</p>
<p>You can use this section to explore currently loaded snippets. If you
click on one of them, the default behavior is to expand it,
unconditionally, inside the current buffer.</p>
<p>You can however, customize variable <tt class="docutils literal"><span class="pre">yas/visit-from-menu</span></tt> to be
<tt class="docutils literal"><span class="pre">t</span></tt> which will take you to the snippet definition file when you
select it from the menu.</p>
<p>If you want the menu show only snippet tables whose name corresponds
to a &quot;real&quot; major mode. You do this by setting <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to
<tt class="docutils literal"><span class="pre">'real-modes</span></tt>.</p>
<p>Finally, to have the menu show only the tables for the currently
active mode, set <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to <tt class="docutils literal"><span class="pre">abbreviate</span></tt>.</p>
<p>These customizations can also be found in the menu itself, under the
&quot;Snippet menu behavior&quot; submenu.</p>
</div>
<div class="section" id="controlling-indenting">
<h1><a class="toc-backref" href="#id3">Controlling indenting</a></h1>
<p>The &quot;Indenting&quot; submenu contains options to control the values of
<tt class="docutils literal"><span class="pre">yas/indent-line</span></tt> and <tt class="docutils literal"><span class="pre">yas/also-auto-indent-first-line</span></tt>. See
<a class="reference external" href="snippet-development.html">Writing snippets</a> .</p>
</div>
<div class="section" id="prompting-method">
<h1><a class="toc-backref" href="#id4">Prompting method</a></h1>
<p>The &quot;Prompting method&quot; submenu contains options to control the value
of <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt>. See <a class="reference external" href="snippet-expansion.html">Expanding snippets</a> .</p>
</div>
<div class="section" id="misc">
<h1><a class="toc-backref" href="#id5">Misc</a></h1>
<p>The &quot;Misc&quot; submenu contains options to control the values of more
variables.</p>
</div>
</div> </div>
</div> </div>
</div> </div>

85
doc/snippet-menu.rst Normal file
View File

@ -0,0 +1,85 @@
==============
YASnippet menu
==============
.. contents::
When ``yas/minor-mode`` is active, YASnippet will setup a menu just
after the Buffers Menu in the menubar.
In this menu, you can find
* The currently loaded snippet definitions, organized by major mode,
and optional grouping.
* A rundown of the most common commands, (followed by their
keybindings) including commands to load directories and reload all
snippet definitions.
* A series of submenus for customizing and exploring YASnippet
behavior.
.. image:: images/menu-1.png
:align: right
Loading snippets from menu
--------------------------
Invoking "Load snippets..." from the menu invokes
``yas/load-directory`` and prompts you for a snippet directory
hierarchy to load.
Also useful is the "Reload all" options which uncondionally reloads
all the snippets directories defined in ``yas/root-directory`` and
rebuilds the menus.
Snippet menu behavior
---------------------
YASnippet will list in this section all the loaded snippet definitions
organized by snippet table name.
You can use this section to explore currently loaded snippets. If you
click on one of them, the default behavior is to expand it,
unconditionally, inside the current buffer.
You can however, customize variable ``yas/visit-from-menu`` to be
``t`` which will take you to the snippet definition file when you
select it from the menu.
If you want the menu show only snippet tables whose name corresponds
to a "real" major mode. You do this by setting ``yas/use-menu`` to
``'real-modes``.
Finally, to have the menu show only the tables for the currently
active mode, set ``yas/use-menu`` to ``abbreviate``.
These customizations can also be found in the menu itself, under the
"Snippet menu behavior" submenu.
Controlling indenting
---------------------
The "Indenting" submenu contains options to control the values of
``yas/indent-line`` and ``yas/also-auto-indent-first-line``. See
`Writing snippets <snippet-development.html>`_ .
Prompting method
----------------
The "Prompting method" submenu contains options to control the value
of ``yas/prompt-functions``. See `Expanding snippets <snippet-expansion.html>`_ .
Misc
----
The "Misc" submenu contains options to control the values of more
variables.

152
doc/snippet-organization.html
View File

@ -3,10 +3,8 @@
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head> <head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" /> <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>Organizing snippets</title> <title>Organizing snippets</title>
<meta name="author" content="pluskid, joaotavora" />
<meta name="date" content="2009-08-18" />
<link rel="stylesheet" href="styles.css" type="text/css" /> <link rel="stylesheet" href="styles.css" type="text/css" />
</head> </head>
<body> <body>
@ -52,26 +50,33 @@
<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="id2">Loading snippets</a></li> <li><a class="reference internal" href="#loading-snippets" id="id4">Loading snippets</a></li>
<li><a class="reference internal" href="#id1" id="id3">Organizing snippets</a><ul> <li><a class="reference internal" href="#id2" id="id5">Organizing snippets</a><ul>
<li><a class="reference internal" href="#nested-organization" id="id4">Nested organization</a></li> <li><a class="reference internal" href="#nested-organization" id="id6">Nested organization</a></li>
<li><a class="reference internal" href="#the-yas-parents-file" id="id5">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="id7">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></li>
<li><a class="reference internal" href="#the-yas-make-groups-file" id="id6">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="id8">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></li>
<li><a class="reference internal" href="#using-plain-file-names" id="id7">Using plain file names</a></li> <li><a class="reference internal" href="#using-plain-file-names" id="id9">Using plain file names</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id3" id="id10">YASnippet bundle</a></li>
<li><a class="reference internal" href="#customizable-variables" id="id11">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-root-directory" id="id12"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></li>
<li><a class="reference internal" href="#yas-ignore-filenames-as-triggers" id="id13"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></li>
</ul> </ul>
</li> </li>
<li><a class="reference internal" href="#no-storage-bundle" id="id8">No storage (bundle)</a></li>
</ul> </ul>
</div> </div>
<div class="section" id="loading-snippets"> <div class="section" id="loading-snippets">
<h1><a class="toc-backref" href="#id2">Loading snippets</a></h1> <h1><a class="toc-backref" href="#id4">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 and you have
to arrange for YASnippet to load them (unless you use a <a class="reference external" href="mailto:index.html&#64;bundle-install">YASnippet to arrange for YASnippet to load them (unless you use a <a class="reference external" href="mailto:index.html&#64;bundle-install">YASnippet
bundle</a> (see <a class="reference internal" href="#no-storage-bundle">No storage (bundle)</a>),</p> bundle</a>) into <em>snippet tables</em>.</p>
<p>The non-bundle version of YASsnippet, once unpacked, comes with a full <p>The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will look up
these snippet tables and (hopefully) expand your intended snippet.</p>
<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, one or more directories.</p>
<p>Once these 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 then 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>)
@ -82,32 +87,33 @@ also create or download, one or more directories.</p>
<p>The point in using <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> (as opposed to calling <p>The point in using <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> (as opposed to calling
<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> directly) is considering &quot;~/emacs.d/mysnippets&quot; <tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> directly) is considering &quot;~/emacs.d/mysnippets&quot;
for snippet development, so you can use commands like for snippet development, so you can use commands like
<tt class="docutils literal"><span class="pre">yas/new-snippet</span></tt> and others described <a class="reference external" href="snippet-development.html">here</a>)</p> <tt class="docutils literal"><span class="pre">yas/new-snippet</span></tt> and others described in section <a class="reference external" href="snippet-development.html">Writing
<p>If you make this variable a list and store more items into it...</p> Snippets</a>.</p>
<div class="highlight"><pre>;; Develop in ~/emacs.d/mysnippets, but also <p>You can make this variable a list and store more items into it:</p>
;; try out snippets in ~/Downloads/interesting-snippets <div class="highlight"><pre><span style="color: #408080; font-style: italic">;; Develop in ~/emacs.d/mysnippets, but also</span>
(setq yas/root-directory &#39;(&quot;~/emacs.d/mysnippets&quot; <span style="color: #408080; font-style: italic">;; try out snippets in ~/Downloads/interesting-snippets</span>
&quot;~/Downloads/interesting-snippets&quot;)) (<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/root-directory</span> <span style="color: #666666">&#39;</span>(<span style="color: #BA2121">&quot;~/emacs.d/mysnippets&quot;</span>
<span style="color: #BA2121">&quot;~/Downloads/interesting-snippets&quot;</span>))
;; Map `yas/load-directory&#39; to every element <span style="color: #408080; font-style: italic">;; Map `yas/load-directory&#39; to every element</span>
(mapc &#39;yas/load-directory yas/root-directory) (<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>, the directories after the first are loaded, their snippets <p>Here the directories after the first are loaded, their snippets
considered for expansion, but development still happens in considered for expansion, but development still happens in
&quot;~/emacs.d/mysnippets&quot;</p> &quot;~/emacs.d/mysnippets&quot;</p>
</div> </div>
<div class="section" id="id1"> <div class="section" id="id2">
<h1><a class="toc-backref" href="#id3">Organizing snippets</a></h1> <h1><a class="toc-backref" href="#id5">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 subdirectories of these directories.</p> inside sub-directories of these directories.</p>
<p>Common to <em>both</em> cases, snippet definitions are put in plain text <p>Snippet definitions are put in plain text files. They are arranged by
files. They are arranged by subdirectories, and the name of these sub-directories, and the snippet tables are named after these directories.</p>
directories correspond 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> subdirectory. 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 internal" href="#no-storage-bundle">No storage (bundle)</a>).</p> and use the bundle (see <a class="reference external" href="mailto:index.html&#64;bundle-install">YASnippet bundle</a>).</p>
<div class="section" id="nested-organization"> <div class="section" id="nested-organization">
<h2><a class="toc-backref" href="#id4">Nested organization</a></h2> <h2><a class="toc-backref" href="#id6">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
@ -126,18 +132,20 @@ for some modes:</p>
| `-- for | `-- for
`-- time `-- time
</pre></div> </pre></div>
<p>The parent directory acts as the <em>parent mode</em>. This is the way of <p>A parent directory acts as a <em>parent table</em> of any of its
YASnippet to share snippet definitions among different modes. As you sub-directories. This is one of the ways YASnippet can share snippet
can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and <tt class="docutils literal"><span class="pre">java-mode</span></tt> share the same parents definitions among different modes. As you can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt>
<tt class="docutils literal"><span class="pre">cc-mode</span></tt>, while all modes are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>. This can 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
be also used to as an <em>alias</em> -- <tt class="docutils literal"><span class="pre">cperl-mode</span></tt> is an empty directory are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>.</p>
whose parent is <tt class="docutils literal"><span class="pre">perl-mode</span></tt>.</p> <p>This can be also used to as an <em>alias</em> -- <tt class="docutils literal"><span class="pre">cperl-mode</span></tt> is an empty
directory whose parent is <tt class="docutils literal"><span class="pre">perl-mode</span></tt>.</p>
<img align="right" alt="images/menu-parent.png" class="align-right" src="images/menu-parent.png" />
</div> </div>
<div class="section" id="the-yas-parents-file"> <div class="section" id="the-yas-parents-file">
<h2><a class="toc-backref" href="#id5">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2> <h2><a class="toc-backref" href="#id7">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2>
<p>If you place a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the <p>If you place a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the
subdirectories you can bypass nesting and still have parent modes. In sub-directories you can bypass nesting and still have parent modes. In
this file you just write whitespace-separated names of modes. This this file you just write white-space-separated names of modes. This
allows more flexibility and readability of your snippet hierarchy.</p> allows more flexibility and readability of your snippet hierarchy.</p>
<div class="highlight"><pre>$ tree <div class="highlight"><pre>$ tree
. .
@ -156,14 +164,14 @@ 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="#id6">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2> <h2><a class="toc-backref" href="#id8">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2>
<img align="right" alt="images/group.png" class="align-right" src="images/group.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 subdirectories are of the mode directories, the names of these sub-directories are
considered groups of snippets and the <cite>YASsnippet menu</cite> is organized considered groups of snippets and <a class="reference external" href="snippet-menu.html">The YASnippet Menu</a> is organized
much more cleanly, as you can see in the image.</p> much more cleanly, as you can see in the image.</p>
<p>Another alternative way to achieve this is to place a <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> <p>Another alternative way to achieve this is to place a <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt>
directive inside the snippet definition. See <a class="reference external" href="snippet-development.html">Writing snippets</a></p> directive inside the snippet definition. See <a class="reference external" href="snippet-development.html">Writing Snippets</a>.</p>
<div class="highlight"><pre>$ tree ruby-mode/ <div class="highlight"><pre>$ tree ruby-mode/
ruby-mode/ ruby-mode/
|-- .yas-make-groups |-- .yas-make-groups
@ -180,13 +188,15 @@ 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="#id7">Using plain file names</a></h2> <h2><a class="toc-backref" href="#id9">Using plain file names</a></h2>
<p>Normally, file names act as the snippet trigger <em>key</em>, see <a class="reference external" href="snippet-expansion.html">Expanding <p>Normally, file names act as the snippet expansion <em>abbreviation</em> (also
snippets</a>. However, if you customize the known as the <em>snippet key</em> or <em>snippet trigger</em>, see <a class="reference external" href="snippet-expansion.html">Expanding
variable <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> to be true <em>or</em> place an Snippets</a>).</p>
empty file <tt class="docutils literal"><span class="pre">.yas-ignore-filename-triggers</span></tt> you can use much more <p>However, if you customize the variable
descriptive file names. This is useful (but not mandatory) if many <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> to be true <em>or</em> place an empty
snippets within a mode share the same trigger key.</p> file <tt class="docutils literal"><span class="pre">.yas-ignore-filename-triggers</span></tt> you can use much more
descriptive file names. This is useful if many snippets within a mode
share the same trigger key.</p>
<div class="highlight"><pre>$ tree rails-mode/ <div class="highlight"><pre>$ tree rails-mode/
rails-mode/ rails-mode/
|-- .yas-make-groups |-- .yas-make-groups
@ -205,14 +215,14 @@ rails-mode/
</pre></div> </pre></div>
</div> </div>
</div> </div>
<div class="section" id="no-storage-bundle"> <div class="section" id="id3">
<h1><a class="toc-backref" href="#id8">No storage (bundle)</a></h1> <h1><a class="toc-backref" href="#id10">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>
<p>However, this might slow down the Emacs startup speed if you have many <p>However, this might slow down the Emacs start-up speed if you have many
snippets. You can use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to define a bunch of snippets. You can use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to define a bunch of
snippets for a particular mode in an emacs-lisp file.</p> snippets for a particular mode in an Emacs-lisp file.</p>
<p>Since this is hard to maintain, there's a better way: define your <p>Since this is hard to maintain, there's a better way: define your
snippets in directory and then call <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/compile-bundle</span></tt> to snippets in directory and then call <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/compile-bundle</span></tt> to
compile it into a bundle file when you modified your snippets.</p> compile it into a bundle file when you modified your snippets.</p>
@ -223,8 +233,32 @@ snippets.</p>
<p>Further more, the generated bundle is a stand-alone file not depending <p>Further more, the generated bundle is a stand-alone file not depending
on <tt class="docutils literal"><span class="pre">yasnippet.el</span></tt>. The released bundles of YASnippet are all on <tt class="docutils literal"><span class="pre">yasnippet.el</span></tt>. The released bundles of YASnippet are all
generated this way.</p> generated this way.</p>
<p>See the internal documentation for the functions <p>See the internal documentation for these functions</p>
<tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> and <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>.</p> <ul class="simple">
<li><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-function</span> <span class="pre">RET</span> <span class="pre">yas/define-snippets</span> <span class="pre">RET</span></tt></li>
<li><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-function</span> <span class="pre">RET</span> <span class="pre">yas/compile-bundle</span> <span class="pre">RET</span></tt>.</li>
</ul>
</div>
<div class="section" id="customizable-variables">
<h1><a class="toc-backref" href="#id11">Customizable variables</a></h1>
<div class="section" id="yas-root-directory">
<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></h2>
<p>Root directory that stores the snippets for each major mode.</p>
<p>Can also be a list of strings, for multiple root directories. If
you make this a list, the first element is always the
user-created snippets directory.</p>
<p>Other directories are used for bulk reloading of all snippets using
<tt class="docutils literal"><span class="pre">yas/reload-all</span></tt></p>
</div>
<div class="section" id="yas-ignore-filenames-as-triggers">
<h2><a class="toc-backref" href="#id13"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></h2>
<p>If non-nil, don't derive tab triggers from filenames.</p>
<p>This means a snippet without a <tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> directive wont have a tab
trigger.</p>
<!-- LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl -->
<!-- LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el -->
<!-- LocalWords: rjs RET -->
</div>
</div> </div>
</div> </div>
</div> </div>

125
doc/snippet-organization.rst
View File

@ -2,9 +2,10 @@
Organizing snippets Organizing snippets
=================== ===================
:Author: pluskid, joaotavora .. _Organizing Snippets: snippet-organization.html
:Contact: pluskid@gmail.com .. _Expanding Snippets: snippet-expansion.html
:Date: 2009-08-18 .. _Writing Snippets: snippet-development.html
.. _The YASnippet Menu: snippet-menu.html
.. contents:: .. contents::
@ -13,13 +14,16 @@ Loading snippets
Snippet definitions are stored in files in the filesystem and you have Snippet definitions are stored in files in the filesystem and you have
to arrange for YASnippet to load them (unless you use a `YASnippet to arrange for YASnippet to load them (unless you use a `YASnippet
bundle <index.html@bundle-install>`_ (see `No storage (bundle)`_), bundle <index.html@bundle-install>`_) into *snippet tables*.
The non-bundle version of YASsnippet, once unpacked, comes with a full The triggering mechanisms (see `Expanding snippets`_) will look up
these snippet tables and (hopefully) expand your intended snippet.
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, one or more directories.
Once these 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 then load them with ``yas/load-directory``:
.. sourcecode:: common-lisp .. sourcecode:: common-lisp
@ -33,13 +37,12 @@ Once these are in place reference them in the variable
The point in using ``yas/root-directory`` (as opposed to calling The point in using ``yas/root-directory`` (as opposed to calling
``yas/load-directory`` directly) is considering "~/emacs.d/mysnippets" ``yas/load-directory`` directly) is considering "~/emacs.d/mysnippets"
for snippet development, so you can use commands like for snippet development, so you can use commands like
``yas/new-snippet`` and others described `here ``yas/new-snippet`` and others described in section `Writing
<snippet-development.html>`_) Snippets`_.
If you make this variable a list and store more items into it... You can make this variable a list and store more items into it:
.. sourcecode:: common-lisp .. sourcecode:: common-lisp
:align: right
;; Develop in ~/emacs.d/mysnippets, but also ;; Develop in ~/emacs.d/mysnippets, but also
;; try out snippets in ~/Downloads/interesting-snippets ;; try out snippets in ~/Downloads/interesting-snippets
@ -49,7 +52,7 @@ If you 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)
, the directories after the first are loaded, their snippets Here the directories after the first are loaded, their snippets
considered for expansion, but development still happens in considered for expansion, but development still happens in
"~/emacs.d/mysnippets" "~/emacs.d/mysnippets"
@ -57,14 +60,15 @@ Organizing snippets
=================== ===================
Once you've setup ``yas/root-directory`` , you can store snippets Once you've setup ``yas/root-directory`` , you can store snippets
inside subdirectories of these directories. inside sub-directories of these directories.
Common to *both* cases, snippet definitions are put in plain text Snippet definitions are put in plain text files. They are arranged by
files. They are arranged by subdirectories, and the name of these sub-directories, and the snippet tables are named after these directories.
directories correspond to the Emacs mode where you want expansion to
The name corresponds to the Emacs mode where you want expansion to
take place. For example, snippets for ``c-mode`` are put in the take place. For example, snippets for ``c-mode`` are put in the
``c-mode`` subdirectory. You can also skip snippet storage altogether ``c-mode`` sub-directory. You can also skip snippet storage altogether
and use the bundle (see `No storage (bundle)`_). and use the bundle (see `YASnippet bundle`_).
Nested organization Nested organization
------------------- -------------------
@ -90,19 +94,24 @@ for some modes:
| `-- for | `-- for
`-- time `-- time
The parent directory acts as the *parent mode*. This is the way of A parent directory acts as a *parent table* of any of its
YASnippet to share snippet definitions among different modes. As you sub-directories. This is one of the ways YASnippet can share snippet
can see above, ``c-mode`` and ``java-mode`` share the same parents definitions among different modes. As you can see above, ``c-mode``
``cc-mode``, while all modes are derived from ``text-mode``. This can and ``java-mode`` share the same parents ``cc-mode``, while all modes
be also used to as an *alias* -- ``cperl-mode`` is an empty directory are derived from ``text-mode``.
whose parent is ``perl-mode``.
This can be also used to as an *alias* -- ``cperl-mode`` is an empty
directory whose parent is ``perl-mode``.
.. image:: images/menu-parent.png
:align: right
The ``.yas-parents`` file The ``.yas-parents`` file
------------------------------ ------------------------------
If you place a plain text file ``.yas-parents`` inside one of the If you place a plain text file ``.yas-parents`` inside one of the
subdirectories you can bypass nesting and still have parent modes. In sub-directories you can bypass nesting and still have parent modes. In
this file you just write whitespace-separated names of modes. This this file you just write white-space-separated names of modes. This
allows more flexibility and readability of your snippet hierarchy. allows more flexibility and readability of your snippet hierarchy.
.. sourcecode:: text .. sourcecode:: text
@ -125,17 +134,16 @@ allows more flexibility and readability of your snippet hierarchy.
The ``.yas-make-groups`` file The ``.yas-make-groups`` file
----------------------------- -----------------------------
.. image:: images/group.png .. image:: images/menu-groups.png
:align: right :align: right
If you place an empty plain text file ``.yas-make-groups`` inside one If you place an empty plain text file ``.yas-make-groups`` inside one
of the mode directories, the names of these subdirectories are of the mode directories, the names of these sub-directories are
considered groups of snippets and the `YASsnippet menu` is organized considered groups of snippets and `The YASnippet Menu`_ is organized
much more cleanly, as you can see in the image. much more cleanly, as you can see in the image.
Another alternative way to achieve this is to place a ``# group:`` Another alternative way to achieve this is to place a ``# group:``
directive inside the snippet definition. See `Writing snippets directive inside the snippet definition. See `Writing Snippets`_.
<snippet-development.html>`_
.. sourcecode:: text .. sourcecode:: text
@ -157,12 +165,15 @@ directive inside the snippet definition. See `Writing snippets
Using plain file names Using plain file names
---------------------- ----------------------
Normally, file names act as the snippet trigger *key*, see `Expanding Normally, file names act as the snippet expansion *abbreviation* (also
snippets <snippet-expansion.html>`_. However, if you customize the known as the *snippet key* or *snippet trigger*, see `Expanding
variable ``yas/ignore-filenames-as-triggers`` to be true *or* place an Snippets`_).
empty file ``.yas-ignore-filename-triggers`` you can use much more
descriptive file names. This is useful (but not mandatory) if many However, if you customize the variable
snippets within a mode share the same trigger key. ``yas/ignore-filenames-as-triggers`` to be true *or* place an empty
file ``.yas-ignore-filename-triggers`` you can use much more
descriptive file names. This is useful if many snippets within a mode
share the same trigger key.
.. sourcecode:: text .. sourcecode:: text
@ -183,17 +194,16 @@ snippets within a mode share the same trigger key.
| `-- assert_select.yasnippet | `-- assert_select.yasnippet
YASnippet bundle
No storage (bundle) ================
===================
The most convenient way to define snippets for YASnippet is to put 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
``yas/load-directory`` to load them. ``yas/load-directory`` to load them.
However, this might slow down the Emacs startup speed if you have many However, this might slow down the Emacs start-up speed if you have many
snippets. You can use ``yas/define-snippets`` to define a bunch of snippets. You can use ``yas/define-snippets`` to define a bunch of
snippets for a particular mode in an emacs-lisp file. snippets for a particular mode in an Emacs-lisp file.
Since this is hard to maintain, there's a better way: define your Since this is hard to maintain, there's a better way: define your
snippets in directory and then call ``M-x yas/compile-bundle`` to snippets in directory and then call ``M-x yas/compile-bundle`` to
@ -208,5 +218,34 @@ Further more, the generated bundle is a stand-alone file not depending
on ``yasnippet.el``. The released bundles of YASnippet are all on ``yasnippet.el``. The released bundles of YASnippet are all
generated this way. generated this way.
See the internal documentation for the functions See the internal documentation for these functions
``yas/define-snippets`` and ``yas/compile-bundle``.
* ``M-x describe-function RET yas/define-snippets RET``
* ``M-x describe-function RET yas/compile-bundle RET``.
Customizable variables
======================
``yas/root-directory``
----------------------
Root directory that stores the snippets for each major mode.
Can also be a list of strings, for multiple root directories. If
you make this a list, the first element is always the
user-created snippets directory.
Other directories are used for bulk reloading of all snippets using
``yas/reload-all``
``yas/ignore-filenames-as-triggers``
------------------------------------
If non-nil, don't derive tab triggers from filenames.
This means a snippet without a ``# key:`` directive wont have a tab
trigger.
.. LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl
.. LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el
.. LocalWords: rjs RET

0
snippet_copier.rb → textmate_import.rb
View File

64
yasnippet.el
View File

@ -160,7 +160,29 @@ bulk reloading of all snippets using `yas/reload-all'"
yas/completing-prompt yas/completing-prompt
yas/ido-prompt yas/ido-prompt
yas/no-prompt) yas/no-prompt)
"Functions to prompt for keys, templates, etc interactively." "Functions to prompt for keys, templates, etc interactively.
These functions are called with the following arguments:
* PROMPT: A string to prompt the user
* CHOICES: a list of strings or objects.
* optional DISPLAY-FN : A function that, when applied to each of
the objects in CHOICES will return a string.
The return value of any function you put here should be one of
the objects in CHOICES, properly formatted with DISPLAY-FN (if
that is passed).
* To signal that your particular style of prompting is
unavailable at the moment, you can also have the function return
nil.
* To signal that the user quit the prompting process, you can
signal `quit' with
(signal 'quit \"user quit!\")."
:type 'list :type 'list
:group 'yasnippet) :group 'yasnippet)
@ -238,9 +260,6 @@ field"
(defcustom yas/fallback-behavior 'call-other-command (defcustom yas/fallback-behavior 'call-other-command
"How to act when `yas/trigger-key' does *not* expand a snippet. "How to act when `yas/trigger-key' does *not* expand a snippet.
The fall back behavior of YASnippet when it can't find a snippet
to expand.
`call-other-command' means try to temporarily disable YASnippet `call-other-command' means try to temporarily disable YASnippet
and call the next command bound to `yas/trigger-key'. and call the next command bound to `yas/trigger-key'.
@ -528,7 +547,7 @@ Here's an example:
:active t :style radio :selected (eq yas/use-menu 'real-modes)] :active t :style radio :selected (eq yas/use-menu 'real-modes)]
["Show all modes" (setq yas/use-menu 't) ["Show all modes" (setq yas/use-menu 't)
:help "Show one snippet submenu for each loaded table" :help "Show one snippet submenu for each loaded table"
:active t :style radio :selected (eq yas/use-menu 'y)] :active t :style radio :selected (eq yas/use-menu 't)]
["Abbreviate according to current mode" (setq yas/use-menu 'abbreviate) ["Abbreviate according to current mode" (setq yas/use-menu 'abbreviate)
:help "Show only snippet submenus for the current active modes" :help "Show only snippet submenus for the current active modes"
:active t :style radio :selected (eq yas/use-menu 'abbreviate)]) :active t :style radio :selected (eq yas/use-menu 'abbreviate)])
@ -1271,6 +1290,8 @@ TEMPLATES is a list of `yas/template'."
(yas/compute-major-mode-and-parents (concat directory "/dummy") (yas/compute-major-mode-and-parents (concat directory "/dummy")
nil nil
no-hierarchy-parents))) no-hierarchy-parents)))
(yas/ignore-filenames-as-triggers (or yas/ignore-filenames-as-triggers
(file-exists-p (concat directory "/" ".yas-ignore-filenames-as-triggers"))))
(mode-sym (and major-mode-and-parents (mode-sym (and major-mode-and-parents
(car major-mode-and-parents))) (car major-mode-and-parents)))
(parents (if making-groups-sym (parents (if making-groups-sym
@ -1397,18 +1418,21 @@ YASNIPPET-BUNDLE is the output file of the compile result.
SNIPPET-ROOTS is a list of root directories that contains the SNIPPET-ROOTS is a list of root directories that contains the
snippets definition. snippets definition.
CODE is the code you would like to used to initialize yasnippet. CODE is the code to be placed at the end of the generated file
and that can initialize the YASnippet bundle.
Last optional argument DROPDOWN is the filename of the Last optional argument DROPDOWN is the filename of the
dropdown-list.el library. dropdown-list.el library.
Here's the default value for all the parameters: Here's the default value for all the parameters:
(yas/compile-bundle \"yasnippet.el\" (yas/compile-bundle \"yasnippet.el\"
\"./yasnippet-bundle.el\" \"yasnippet-bundle.el\"
'(\"snippets\") \"snippets\")
\"(yas/initialize-bundle)\" \"(yas/initialize-bundle)
\"dropdown-list.el\") ### autoload
(require 'yasnippet-bundle)`\"
\"dropdown-list.el\")
" "
(interactive "ffind the yasnippet.el file: \nFTarget bundle file: \nDSnippet directory to bundle: \nMExtra code? \nfdropdown-library: ") (interactive "ffind the yasnippet.el file: \nFTarget bundle file: \nDSnippet directory to bundle: \nMExtra code? \nfdropdown-library: ")
@ -1503,16 +1527,22 @@ Here's the default value for all the parameters:
SNIPPETS is a list of snippet definitions, each taking the SNIPPETS is a list of snippet definitions, each taking the
following form: following form:
(KEY TEMPLATE NAME CONDITION GROUP VARS FILE KEYBINDING) (KEY TEMPLATE NAME CONDITION GROUP EXPAND-ENV FILE KEYBINDING)
Within these, only TEMPLATE is actually mandatory. Within these, only TEMPLATE is actually mandatory.
Optional PARENT-MODE can be used to specify the parent modes of All the elelements are strings, including CONDITION, EXPAND-ENV
MODE. It can be a mode symbol of a list of mode symbols. It does and KEYBINDING which will be `read' and eventually `eval'-ed.
not need to be a real mode.
That is, when looking a snippet in MODE failed, it can refer to FILE is probably of very little use if you're programatically
its parent modes." defining snippets.
You can use `yas/parse-template' to return such lists based on
the current buffers contents.
Optional PARENT-MODE can be used to specify the parent tables of
MODE. It can be a mode symbol of a list of mode symbols. It does
not need to be a real mode."
(let ((snippet-table (yas/snippet-table-get-create mode)) (let ((snippet-table (yas/snippet-table-get-create mode))
(parent-tables (mapcar #'yas/snippet-table-get-create (parent-tables (mapcar #'yas/snippet-table-get-create
(if (listp parent-mode) (if (listp parent-mode)