mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 05:03:04 +00:00
doc almost complete. Drawing closer to 0.6.1b
This commit is contained in:
capitaomorte
parent
5b8671f8c3
commit
6c88b24bf8
@ -3,10 +3,8 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<title>ChangeLog</title>
|
||||
<meta name="author" content="pluskid" />
|
||||
<meta name="date" content="2008-03-22" />
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
@ -49,7 +47,24 @@
|
||||
<div id="squeeze">
|
||||
<div class="right-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...@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>
|
||||
<ul class="simple">
|
||||
<li>Now byte compiles correctly with no warnings.</li>
|
||||
|
||||
@ -2,9 +2,31 @@
|
||||
ChangeLog
|
||||
=========
|
||||
|
||||
:Author: pluskid
|
||||
:Contact: pluskid@gmail.com
|
||||
:Date: 2008-03-22
|
||||
.. _Organizing Snippets: snippet-organization.html
|
||||
.. _Expanding Snippets: snippet-expansion.html
|
||||
.. _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
|
||||
===================
|
||||
|
||||
@ -43,6 +43,56 @@ pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS])
|
||||
|
||||
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
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 54 KiB After Width: | Height: | Size: 59 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 40 KiB After Width: | Height: | Size: 31 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 79 KiB |
BIN
doc/images/ido-menu.png
Normal file
BIN
doc/images/ido-menu.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 57 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 10 KiB |
BIN
doc/images/menu-1.png
Normal file
BIN
doc/images/menu-1.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
BIN
doc/images/menu-2.png
Normal file
BIN
doc/images/menu-2.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 59 KiB |
BIN
doc/images/menu-groups.png
Normal file
BIN
doc/images/menu-groups.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 82 KiB |
BIN
doc/images/menu-parent.png
Normal file
BIN
doc/images/menu-parent.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 72 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 25 KiB |
BIN
doc/images/x-menu.png
Normal file
BIN
doc/images/x-menu.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 34 KiB |
102
doc/index.html
102
doc/index.html
@ -3,10 +3,8 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<title>Yet Another Snippet extension</title>
|
||||
<meta name="author" content="pluskid" />
|
||||
<meta name="date" content="2008-03-20" />
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
@ -53,36 +51,44 @@
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<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="#normal-install" id="id4">Normal Install</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#how-to-use-yasnippet" id="id5">How to use YASnippet</a></li>
|
||||
<li><a class="reference internal" href="#customization-group" id="id6">Customization group</a></li>
|
||||
<li><a class="reference internal" href="#bugs-contribution-and-support" id="id7">Bugs, Contribution and Support</a></li>
|
||||
<li><a class="reference internal" href="#bugs-contribution-and-support" id="id6">Bugs, Contribution and Support</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<p>Yasnippet is a template system for emacs. It allows you to type a
|
||||
abbrevation and automatically expand the abbreviation into function
|
||||
<p>YASnippet is a template system for Emacs. It allows you to type a
|
||||
abbreviation and automatically expand the abbreviation into function
|
||||
templates.</p>
|
||||
<p>Bundled language templates includes: C, C++, C#, Perl, Python, Ruby,
|
||||
SQL, LaTeX, HTML, CSS and more.</p>
|
||||
<p>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>
|
||||
to import any TextMate template you have to Yasnippet. It is a
|
||||
re-design and re-write of my original extension <a class="reference external" href="http://code.google.com/p/smart-snippet/">smart-snippet</a>. It
|
||||
is much cleaner and more powerful than smart-snippet.</p>
|
||||
to import any TextMate template you have to YASnippet.</p>
|
||||
<p>YASnippet is a re-write of the extension <a class="reference external" href="http://code.google.com/p/smart-snippet/">smart-snippet</a>. Both are
|
||||
original creations of <a class="reference external" href="http://pluskid.lifegoo.org">pluskid</a>.</p>
|
||||
<div class="section" id="video-demo">
|
||||
<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
|
||||
resolution version: <a class="reference external" href="http://yasnippet.googlecode.com/files/yasnippet.avi">yasnippet.avi</a>).</p>
|
||||
</div>
|
||||
<div class="section" id="brief-install-instruction">
|
||||
<h1><a class="toc-backref" href="#id2">Brief Install Instruction</a></h1>
|
||||
<div class="section" id="installation">
|
||||
<h1><a class="toc-backref" href="#id2">Installation</a></h1>
|
||||
<p>There are two archives of YASnippet. One is a single file compiled
|
||||
“bundle”, and the other is normal. If all you need is to use the
|
||||
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>
|
||||
<div class="section" id="bundle-install">
|
||||
<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
|
||||
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>
|
||||
<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>
|
||||
<blockquote>
|
||||
<div class="highlight"><pre>(<span style="color: #19177C">add-to-list</span> <span style="color: #19177C">'load-path</span>
|
||||
@ -120,62 +126,52 @@ following in your <tt class="docutils literal"><span class="pre">.emacs</span></
|
||||
</blockquote>
|
||||
<p>Please refer to the documentation for full customization, or use the
|
||||
customization group.</p>
|
||||
<img align="right" alt="images/customization-group.png" class="align-right" src="images/customization-group.png" />
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="how-to-use-yasnippet">
|
||||
<h1><a class="toc-backref" href="#id5">How to use YASnippet</a></h1>
|
||||
<p>Since version 0.6, YASnippet contains more functionality. You don't
|
||||
need to know all of it to use it sucessfully, but you it can improve
|
||||
need to know all of it to use it successfully, but you it can improve
|
||||
your snippeting experience.</p>
|
||||
<p>Hence this section has been split into separate documents:</p>
|
||||
<ol class="arabic simple">
|
||||
<li><a class="reference external" href="snippet-organization.html">Organizing snippets</a></li>
|
||||
<li><a class="reference external" href="snippet-organization.html">Organizing Snippets</a></li>
|
||||
</ol>
|
||||
<p>Describes ways to organize your snippets in the hard disk, or not
|
||||
organize them at all and just use plain old elisp.</p>
|
||||
<p>Also explains how to use the YASnippet menu to explore and learn new
|
||||
snippets.</p>
|
||||
<blockquote>
|
||||
Describes ways to organize your snippets in the hard disk (or not
|
||||
organize them at all and just use <tt class="docutils literal"><span class="pre">yasnippet-bundle.el</span></tt>.</blockquote>
|
||||
<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>
|
||||
<p>Maybe, you'll want some snippets to be expanded in a particular mode,
|
||||
or only under certain conditions. Also you might want snippets to wrap
|
||||
themselves around a region of selected text, use a direct keybinding,
|
||||
control indenting, etc...</p>
|
||||
<blockquote>
|
||||
<p>Describes how YASnippet chooses snippets for expansion at point.</p>
|
||||
<p>Maybe, you'll want some snippets to be expanded in a particular
|
||||
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">
|
||||
<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>
|
||||
<p>Describes the YASnippet definition syntax, which is similar, but not
|
||||
equivalent to Textmate's. Includes a section about converting Textmate
|
||||
snippets.</p>
|
||||
</div>
|
||||
<div class="section" id="customization-group">
|
||||
<h1><a class="toc-backref" href="#id6">Customization group</a></h1>
|
||||
<p>From version 0.6 onwards, there is a customization group that you can
|
||||
access with:</p>
|
||||
<p><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">customize-group</span> <span class="pre">RET</span> <span class="pre">yasnippet</span> <span class="pre">RET</span></tt></p>
|
||||
<p>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...</p>
|
||||
<p>Inside the customization group, each variable is reasonably documented
|
||||
to explain what it does.</p>
|
||||
<blockquote>
|
||||
Describes the YASnippet definition syntax, which is very close (but
|
||||
not equivalent) to Textmate's. Includes a section about converting
|
||||
TextMate snippets.</blockquote>
|
||||
<ol class="arabic simple" start="4">
|
||||
<li><a class="reference external" href="snippet-menu.html">The YASnippet menu</a></li>
|
||||
</ol>
|
||||
<blockquote>
|
||||
Explains how to use the YASnippet menu to explore and learn new
|
||||
snippets.</blockquote>
|
||||
</div>
|
||||
<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">
|
||||
<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
|
||||
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>
|
||||
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>
|
||||
<li>If you have problem using YASnippet, or have some new ideas,
|
||||
including snippets, please post to the <a class="reference external" href="http://groups.google.com/group/smart-snippet">discussion group</a>.</li>
|
||||
</ul>
|
||||
<p>Thank you very much for using YASnippet!</p>
|
||||
<!-- LocalWords: YASnippet SQL LaTeX CSS yasnippet el eval html ido RET wiki -->
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
@ -2,42 +2,47 @@
|
||||
Yet Another Snippet extension
|
||||
=============================
|
||||
|
||||
:Author: pluskid
|
||||
:Contact: pluskid@gmail.com
|
||||
:Date: 2008-03-20
|
||||
.. _Organizing Snippets: snippet-organization.html
|
||||
.. _Expanding Snippets: snippet-expansion.html
|
||||
.. _Writing Snippets: snippet-development.html
|
||||
.. _The YASnippet Menu: snippet-menu.html
|
||||
|
||||
.. contents::
|
||||
|
||||
Yasnippet is a template system for emacs. It allows you to type a
|
||||
abbrevation and automatically expand the abbreviation into function
|
||||
YASnippet is a template system for Emacs. It allows you to type a
|
||||
abbreviation and automatically expand the abbreviation into function
|
||||
templates.
|
||||
|
||||
Bundled language templates includes: C, C++, C#, Perl, Python, Ruby,
|
||||
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
|
||||
<https://groups.google.com/group/smart-snippet/browse_thread/thread/691fbdd33412d86e?pli=1>`_
|
||||
to import any TextMate template you have to Yasnippet. It is a
|
||||
re-design and re-write of my original extension `smart-snippet`_. It
|
||||
is much cleaner and more powerful than smart-snippet.
|
||||
<http://yasnippet.googlecode.com/svn/trunk/textmate-import.rb> to
|
||||
import most TextMate templates to YASnippet.
|
||||
|
||||
YASnippet is a re-write of the extension `smart-snippet`_. Both are
|
||||
original creations of `pluskid <http://pluskid.lifegoo.org>`_.
|
||||
|
||||
.. _smart-snippet: http://code.google.com/p/smart-snippet/
|
||||
|
||||
Video Demo
|
||||
==========
|
||||
|
||||
.. youtube:: vOj7btx3ATg
|
||||
:align: right
|
||||
|
||||
Watch the `demo at YouTube
|
||||
<http://www.youtube.com/watch?v=vOj7btx3ATg>`_ (download a higher
|
||||
resolution version: `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
|
||||
“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.
|
||||
|
||||
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
|
||||
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:
|
||||
|
||||
.. sourcecode:: common-lisp
|
||||
@ -80,71 +85,50 @@ following in your ``.emacs`` file:
|
||||
Please refer to the documentation for full customization, or use the
|
||||
customization group.
|
||||
|
||||
.. image:: images/customization-group.png
|
||||
:align: right
|
||||
|
||||
How to use YASnippet
|
||||
====================
|
||||
|
||||
Since version 0.6, YASnippet contains more functionality. You don't
|
||||
need to know all of it to use it sucessfully, but you it can improve
|
||||
need to know all of it to use it successfully, but you it can improve
|
||||
your snippeting experience.
|
||||
|
||||
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
|
||||
organize them at all and just use plain old elisp.
|
||||
Describes ways to organize your snippets in the hard disk (or not
|
||||
organize them at all and just use ``yasnippet-bundle.el``.
|
||||
|
||||
Also explains how to use the YASnippet menu to explore and learn new
|
||||
snippets.
|
||||
2. `Expanding 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,
|
||||
or only under certain conditions. Also you might want snippets to wrap
|
||||
themselves around a region of selected text, use a direct keybinding,
|
||||
control indenting, etc...
|
||||
Maybe, you'll want some snippets to be expanded in a particular
|
||||
mode, or only under certain conditions, or be prompted using
|
||||
``ido``, etc...
|
||||
|
||||
3. `Defining your own snippets <snippet-development.html>`_
|
||||
3. `Writing Snippets`_
|
||||
|
||||
Describes the YASnippet definition syntax, which is similar, but not
|
||||
equivalent to Textmate's. Includes a section about converting Textmate
|
||||
snippets.
|
||||
Describes the YASnippet definition syntax, which is very close (but
|
||||
not equivalent) to Textmate's. Includes a section about converting
|
||||
TextMate snippets.
|
||||
|
||||
Customization group
|
||||
===================
|
||||
4. `The YASnippet menu`_
|
||||
|
||||
From version 0.6 onwards, there is a customization group that you can
|
||||
access with:
|
||||
|
||||
``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.
|
||||
Explains how to use the YASnippet menu to explore and learn new
|
||||
snippets.
|
||||
|
||||
Bugs, Contribution and Support
|
||||
==============================
|
||||
|
||||
* If you find a bug, please report it at `Issue List
|
||||
<http://code.google.com/p/yasnippet/issues/list>`_.
|
||||
* If you have problem using YASnippet, or have some new ideas, please
|
||||
post to the `discussion group`_. Especially, there's a `wish list`_
|
||||
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>`_.
|
||||
* If you have problem using YASnippet, or have some new ideas,
|
||||
including snippets, please post to the `discussion group`_.
|
||||
|
||||
.. _discussion group: http://groups.google.com/group/smart-snippet
|
||||
.. _wish list: http://code.google.com/p/yasnippet/wiki/WishList
|
||||
|
||||
Thank you very much for using YASnippet!
|
||||
|
||||
.. LocalWords: YASnippet SQL LaTeX CSS yasnippet el eval html ido RET wiki
|
||||
|
||||
@ -3,10 +3,8 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<title>Writing snippets</title>
|
||||
<meta name="author" content="pluskid, joaotavora" />
|
||||
<meta name="date" content="2009-08-18" />
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
@ -52,28 +50,61 @@
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#quickly-finding-defining-snippets" id="id6">Quickly finding/defining snippets</a></li>
|
||||
<li><a class="reference internal" href="#using-the-snippet-mode-major-mode" id="id7">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a><ul>
|
||||
<li><a class="reference internal" href="#the-syntax-of-the-template" id="id8">The Syntax of the Template</a></li>
|
||||
<li><a class="reference internal" href="#snippet-development" id="id3">Snippet development</a><ul>
|
||||
<li><a class="reference internal" href="#quickly-finding-snippets" id="id4">Quickly finding snippets</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>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#plain-text" id="id9">Plain Text</a></li>
|
||||
<li><a class="reference internal" href="#embedded-elisp-code" id="id10">Embedded elisp code</a></li>
|
||||
<li><a class="reference internal" href="#tab-stop-fields" id="id11">Tab stop fields</a></li>
|
||||
<li><a class="reference internal" href="#placeholder-fields" id="id12">Placeholder fields</a></li>
|
||||
<li><a class="reference internal" href="#id2" id="id13">Mirrors</a></li>
|
||||
<li><a class="reference internal" href="#mirrors-with-transformations" id="id14">Mirrors with transformations</a></li>
|
||||
<li><a class="reference internal" href="#fields-with-transformations" id="id15">Fields with transformations</a></li>
|
||||
<li><a class="reference internal" href="#choosing-fields-value-from-a-list" id="id16">Choosing fields value from a list</a></li>
|
||||
<li><a class="reference internal" href="#nested-placeholder-fields" id="id17">Nested placeholder fields</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="quickly-finding-defining-snippets">
|
||||
<h1><a class="toc-backref" href="#id6">Quickly finding/defining snippets</a></h1>
|
||||
<p>From version 0.6 upwards there are two ways you can quickly find a
|
||||
snippet file. Once you find this file it will be set to
|
||||
<tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead)</p>
|
||||
<div class="section" id="snippet-development">
|
||||
<h1><a class="toc-backref" href="#id3">Snippet development</a></h1>
|
||||
<div class="section" id="quickly-finding-snippets">
|
||||
<h2><a class="toc-backref" href="#id4">Quickly finding snippets</a></h2>
|
||||
<p>There are some ways you can quickly find a snippet file. Once you find
|
||||
this file it will be set to <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> (see ahead) and you can
|
||||
start editing your snippet.</p>
|
||||
<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>
|
||||
<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>
|
||||
@ -86,10 +117,10 @@ directly to the snippet definition's file, if it exists.</p>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="using-the-snippet-mode-major-mode">
|
||||
<h1><a class="toc-backref" href="#id7">Using the <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> major mode</a></h1>
|
||||
<p>From version 0.6 upwards there is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to
|
||||
edit snippets. You can set the buffer to this mode with <tt class="docutils literal"><span class="pre">M-x</span>
|
||||
<span class="pre">snippet-mode</span></tt>. It provides reasonably useful syntax highlighting.</p>
|
||||
<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>There is a major mode <tt class="docutils literal"><span class="pre">snippet-mode</span></tt> to edit snippets. You can set
|
||||
the buffer to this mode with <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">snippet-mode</span></tt>. It provides
|
||||
reasonably useful syntax highlighting.</p>
|
||||
<p>Two commands are defined in this mode:</p>
|
||||
<ul>
|
||||
<li><p class="first"><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/load-snippet-buffer</span></tt></p>
|
||||
@ -110,22 +141,148 @@ can see what it looks like. This is bound to <tt class="docutils literal"><span
|
||||
</ul>
|
||||
<p>There are also snippets for making snippets: <tt class="docutils literal"><span class="pre">vars</span></tt>, <tt class="docutils literal"><span class="pre">field</span></tt> and
|
||||
<tt class="docutils literal"><span class="pre">mirror</span></tt>.</p>
|
||||
<div class="section" id="the-syntax-of-the-template">
|
||||
<h2><a class="toc-backref" href="#id8">The Syntax of the Template</a></h2>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="file-content">
|
||||
<h1><a class="toc-backref" href="#id6">File content</a></h1>
|
||||
<p>A file defining a snippet may just contain the template for the
|
||||
snippet. Optionally it can also contains some meta data for the
|
||||
snippet as well as comments.</p>
|
||||
<p>Generally speaking, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, then all
|
||||
contents above that line are considered directives (meta data) and
|
||||
comments; below that line lies the snippet template.</p>
|
||||
<p>If no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is found, the whole file content is considered as the
|
||||
template.</p>
|
||||
<p>Here's a typical example:</p>
|
||||
<div class="highlight"><pre>#contributor : pluskid <pluskid@gmail.com>
|
||||
#name : __...__
|
||||
# --
|
||||
__${init}__
|
||||
</pre></div>
|
||||
<p>Meta data are specified in the syntax of</p>
|
||||
<div class="highlight"><pre>#data-name : data value
|
||||
</pre></div>
|
||||
<p>Any other text above <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is considered as comment and
|
||||
ignored. Here's a list of currently supported 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 'fixed) (yas/wrap-around-region '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 "html-mode"
|
||||
snippet.</p>
|
||||
<div class="highlight"><pre>#name : <p>...</p>
|
||||
#binding: "C-c C-c C-m"
|
||||
# --
|
||||
<p>`(when yas/prefix "\n")`$0`(when yas/prefix "\n")`</p>
|
||||
</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 "C-u C-c C-c
|
||||
C-m". Omitting the "C-u" 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
|
||||
similar to TextMate's.</p>
|
||||
</div>
|
||||
</div>
|
||||
<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
|
||||
usually interpreted as plain text, except <tt class="docutils literal"><span class="pre">$</span></tt> and <tt class="docutils literal"><span class="pre">`</span></tt>. You need to
|
||||
use <tt class="docutils literal"><span class="pre">\</span></tt> to escape them: <tt class="docutils literal"><span class="pre">\$</span></tt> and <tt class="docutils literal"><span class="pre">\`</span></tt>. The <tt class="docutils literal"><span class="pre">\</span></tt> itself may also
|
||||
needed to be escaped as <tt class="docutils literal"><span class="pre">\\</span></tt> sometimes.</p>
|
||||
</div>
|
||||
<div class="section" id="embedded-elisp-code">
|
||||
<h1><a class="toc-backref" href="#id10">Embedded elisp code</a></h1>
|
||||
<p>Elisp code can be embedded inside the template. They are written
|
||||
<div class="section" id="embedded-emacs-lisp-code">
|
||||
<h2><a class="toc-backref" href="#id15">Embedded Emacs-lisp code</a></h2>
|
||||
<p>Emacs-Lisp code can be embedded inside the template. They are written
|
||||
inside back-quotes (<tt class="docutils literal"><span class="pre">`</span></tt>):</p>
|
||||
<p>They are evaluated when the snippet is being expanded. The evaluation
|
||||
is done in the same buffer as the snippet being expanded. Here's an
|
||||
@ -138,7 +295,7 @@ $0
|
||||
#endif /* $1 */
|
||||
</pre></div>
|
||||
<p>From version 0.6.0, snippets expansions are run with some special
|
||||
emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You
|
||||
Emacs-lisp variables bound. One of this is <tt class="docutils literal"><span class="pre">yas/selected-text</span></tt>. You
|
||||
can therefore define a snippet like:</p>
|
||||
<div class="highlight"><pre>for ($1;$2;$3) {
|
||||
`yas/selected-text`$0
|
||||
@ -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>
|
||||
</div>
|
||||
<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>
|
||||
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
|
||||
snippet. That is the last place to go when you've traveled all the
|
||||
fields. Here's a typical example:</p>
|
||||
@ -161,7 +318,7 @@ fields. Here's a typical example:</p>
|
||||
</pre></div>
|
||||
</div>
|
||||
<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
|
||||
like this:</p>
|
||||
<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>
|
||||
</div>
|
||||
<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
|
||||
mirrors. Its mirrors will get updated when you change the text of a
|
||||
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>
|
||||
</div>
|
||||
<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
|
||||
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
|
||||
field. Here's an example for Objective-C:</p>
|
||||
<div class="highlight"><pre>- (${1:id})${2:foo}
|
||||
@ -210,8 +367,8 @@ $0
|
||||
a placeholder. The actual placeholder is at the first line:
|
||||
<tt class="docutils literal"><span class="pre">${2:foo}</span></tt>. When you type text in <tt class="docutils literal"><span class="pre">${2:foo}</span></tt>, the transformation
|
||||
will be evaluated and the result will be placed there as the
|
||||
transformated text. So in this example, if you type baz in the field,
|
||||
the transformed text will be Baz. This example is also available in
|
||||
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 screencast.</p>
|
||||
<p>Another example is for <tt class="docutils literal"><span class="pre">rst-mode</span></tt>. In reStructuredText, the document
|
||||
title can be some text surrounded by "===" below and above. The "==="
|
||||
@ -232,27 +389,9 @@ ${1:$(make-string (string-width text) ?\=)}
|
||||
|
||||
$0
|
||||
</pre></div>
|
||||
<table class="docutils footnote" frame="void" id="id3" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label">[1]</td><td>With some minor change, mainly for fixing some trivial bugs.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table class="docutils footnote" frame="void" id="id4" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label">[2]</td><td>This is done when you call <tt class="docutils literal"><span class="pre">yas/initialize</span></tt>.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
<table class="docutils footnote" frame="void" id="id5" rules="none">
|
||||
<colgroup><col class="label" /><col /></colgroup>
|
||||
<tbody valign="top">
|
||||
<tr><td class="label"><a class="fn-backref" href="#id1">[3]</a></td><td>Of course, this can be customized.</td></tr>
|
||||
</tbody>
|
||||
</table>
|
||||
</div>
|
||||
<div class="section" id="fields-with-transformations">
|
||||
<h1><a class="toc-backref" href="#id15">Fields with transformations</a></h1>
|
||||
<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
|
||||
fields. These work mostly mirror transformations but are evaluated
|
||||
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
|
||||
the field. As you type text, it gets filtered through the
|
||||
transformation every time.</p>
|
||||
<p>Note that this is differentiated from a mirror with a transformation
|
||||
by the existance of extra text between the <tt class="docutils literal"><span class="pre">:</span></tt> and the
|
||||
<p>Note that to tell this kind of expression from a mirror with a
|
||||
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
|
||||
two <tt class="docutils literal"><span class="pre">$</span></tt>'s instead.</p>
|
||||
<div class="highlight"><pre>#define "${1:$$(upcase yas/text)}"
|
||||
@ -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>
|
||||
</div>
|
||||
<div class="section" id="choosing-fields-value-from-a-list">
|
||||
<h1><a class="toc-backref" href="#id16">Choosing fields value from a list</a></h1>
|
||||
<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
|
||||
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
|
||||
@ -292,7 +431,7 @@ using the two variables. Also check out <tt class="docutils literal"><span class
|
||||
another neat trick.</p>
|
||||
</div>
|
||||
<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>
|
||||
<div class="highlight"><pre><div${1: id="${2:some_id}"}>$0</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
|
||||
beginning of the field <em>and</em> it hasn't been changed yet. Otherwise, it
|
||||
performs the normal Emacs <tt class="docutils literal"><span class="pre">delete-char</span></tt> command.</p>
|
||||
</div>
|
||||
</div>
|
||||
<div 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">"TAB"</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">"TAB"</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">("<backtab>"</span> <span class="pre">"<S-tab>)"</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">"C-d"</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 "[yas] error" 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">$></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 < 10}; ${++i})
|
||||
{$>
|
||||
$0$>
|
||||
}$>
|
||||
</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>
|
||||
|
||||
@ -2,23 +2,34 @@
|
||||
Writing snippets
|
||||
================
|
||||
|
||||
:Author: pluskid, joaotavora
|
||||
:Contact: pluskid@gmail.com
|
||||
:Date: 2009-08-18
|
||||
.. _Organizing Snippets: snippet-organization.html
|
||||
.. _Expanding Snippets: snippet-expansion.html
|
||||
.. _Writing Snippets: snippet-development.html
|
||||
.. _The YASnippet Menu: snippet-menu.html
|
||||
|
||||
.. contents::
|
||||
|
||||
Quickly finding/defining snippets
|
||||
---------------------------------
|
||||
Snippet development
|
||||
===================
|
||||
|
||||
From version 0.6 upwards there are two ways you can quickly find a
|
||||
snippet file. Once you find this file it will be set to
|
||||
``snippet-mode`` (see ahead)
|
||||
Quickly finding snippets
|
||||
------------------------
|
||||
|
||||
There are some ways you can quickly find a snippet file. Once you find
|
||||
this file it will be set to ``snippet-mode`` (see ahead) and you can
|
||||
start editing your snippet.
|
||||
|
||||
* ``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``
|
||||
|
||||
Lets you find the snippet file in the directory the snippet was
|
||||
loaded from (if it exists) like ``find-file-other-window``.
|
||||
loaded from (if it exists) like ``find-file-other-window``.
|
||||
|
||||
* ``M-x yas/visit-snippet-file``
|
||||
|
||||
@ -30,32 +41,199 @@ snippet file. Once you find this file it will be set to
|
||||
Using the ``snippet-mode`` major mode
|
||||
-------------------------------------
|
||||
|
||||
From version 0.6 upwards there is a major mode ``snippet-mode`` to
|
||||
edit snippets. You can set the buffer to this mode with ``M-x
|
||||
snippet-mode``. It provides reasonably useful syntax highlighting.
|
||||
There is a major mode ``snippet-mode`` to edit snippets. You can set
|
||||
the buffer to this mode with ``M-x snippet-mode``. It provides
|
||||
reasonably useful syntax highlighting.
|
||||
|
||||
Two commands are defined in this mode:
|
||||
|
||||
* ``M-x yas/load-snippet-buffer``
|
||||
|
||||
* ``M-x yas/load-snippet-buffer``
|
||||
|
||||
When editing a snippet, this loads the snippet into the correct
|
||||
mode and menu. Bound to ``C-c C-c`` by default while in
|
||||
``snippet-mode``.
|
||||
|
||||
* ``M-x yas/tryout-snippet``
|
||||
|
||||
|
||||
* ``M-x yas/tryout-snippet``
|
||||
|
||||
When editing a snippet, this opens a new empty buffer, sets it to
|
||||
the appropriate major mode and inserts the snippet there, so you
|
||||
can see what it looks like. This is bound to ``C-c C-t`` while in
|
||||
``snippet-mode``.
|
||||
|
||||
|
||||
There are also snippets for making snippets: ``vars``, ``field`` and
|
||||
``mirror``.
|
||||
|
||||
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
|
||||
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
|
||||
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 (`````):
|
||||
|
||||
They are evaluated when the snippet is being expanded. The evaluation
|
||||
@ -82,13 +260,13 @@ example for ``c-mode`` to calculate the header file guard dynamically:
|
||||
|
||||
#ifndef ${1:_`(upcase (file-name-nondirectory (file-name-sans-extension (buffer-file-name))))`_H_}
|
||||
#define $1
|
||||
|
||||
|
||||
$0
|
||||
|
||||
|
||||
#endif /* $1 */
|
||||
|
||||
From version 0.6.0, snippets expansions are run with some special
|
||||
emacs-lisp variables bound. One of this is ``yas/selected-text``. You
|
||||
Emacs-lisp variables bound. One of this is ``yas/selected-text``. You
|
||||
can therefore define a snippet like:
|
||||
|
||||
.. sourcecode:: text
|
||||
@ -105,7 +283,7 @@ Tab stop fields
|
||||
---------------
|
||||
|
||||
Tab stops are fields that you can navigate back and forth by ``TAB``
|
||||
and ``S-TAB`` [3]_. They are written by ``$`` followed with a
|
||||
and ``S-TAB``. They are written by ``$`` followed with a
|
||||
number. ``$0`` has the special meaning of the *exit point* of a
|
||||
snippet. That is the last place to go when you've traveled all the
|
||||
fields. Here's a typical example:
|
||||
@ -163,7 +341,7 @@ Mirrors with transformations
|
||||
|
||||
If the default value of a field starts with ``$``, then it is interpreted
|
||||
as the transformation code instead of default value. A transformation
|
||||
is some arbitrary elisp code that will get evaluated in an environment
|
||||
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
|
||||
field. Here's an example for Objective-C:
|
||||
|
||||
@ -173,7 +351,7 @@ field. Here's an example for Objective-C:
|
||||
{
|
||||
return $2;
|
||||
}
|
||||
|
||||
|
||||
- (void)set${2:$(capitalize text)}:($1)aValue
|
||||
{
|
||||
[$2 autorelease];
|
||||
@ -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:
|
||||
``${2:foo}``. When you type text in ``${2:foo}``, the transformation
|
||||
will be evaluated and the result will be placed there as the
|
||||
transformated text. So in this example, if you type baz in the field,
|
||||
the transformed text will be Baz. This example is also available in
|
||||
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 screencast.
|
||||
|
||||
Another example is for ``rst-mode``. In reStructuredText, the document
|
||||
@ -207,19 +385,15 @@ is a valid title but
|
||||
Title
|
||||
===
|
||||
|
||||
is not. Here's an snippet for rst title:
|
||||
is not. Here's an snippet for rst title:
|
||||
|
||||
.. sourcecode:: text
|
||||
|
||||
${1:$(make-string (string-width text) ?\=)}
|
||||
${1:Title}
|
||||
${1:$(make-string (string-width text) ?\=)}
|
||||
|
||||
$0
|
||||
|
||||
.. [1] With some minor change, mainly for fixing some trivial bugs.
|
||||
.. [2] This is done when you call ``yas/initialize``.
|
||||
.. [3] Of course, this can be customized.
|
||||
$0
|
||||
|
||||
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
|
||||
transformation every time.
|
||||
|
||||
Note that this is differentiated from a mirror with a transformation
|
||||
by the existance of extra text between the ``:`` and the
|
||||
Note that to tell this kind of expression from a mirror with a
|
||||
transformation, YASnippet needs extra text between the ``:`` and the
|
||||
transformation's ``$``. If you don't want this extra-text, you can use
|
||||
two ``$``'s instead.
|
||||
|
||||
@ -261,16 +435,16 @@ As mentioned, the field transformation is invoked just after you enter
|
||||
the field, and with some useful variables bound, notably
|
||||
``yas/field-modified-p`` and ``yas/moving-away-p``. Because of this
|
||||
feature you can place a transformation in the primary field that lets
|
||||
you select default values for it.
|
||||
you select default values for it.
|
||||
|
||||
The ``yas/choose-value`` does this work for you. For example:
|
||||
|
||||
|
||||
.. sourcecode:: text
|
||||
|
||||
<div align="${2:$$(yas/choose-value '("right" "center" "left"))}">
|
||||
$0
|
||||
</div>
|
||||
|
||||
|
||||
See the definition of ``yas/choose-value`` to see how it was written
|
||||
using the two variables. Also check out ``yas/verify-value`` for
|
||||
another neat trick.
|
||||
@ -288,8 +462,134 @@ This allows you to choose if you want to give this ``div`` an ``id``
|
||||
attribute. If you tab forward after expanding it will let you change
|
||||
"some_id" to whatever you like. Alternatively, you can just press
|
||||
``C-d`` (which executes ``yas/skip-and-clear-or-delete-char``) and go
|
||||
straight to the exit marker.
|
||||
straight to the exit marker.
|
||||
|
||||
By the way, ``C-d`` will only clear the field if you cursor is at the
|
||||
beginning of the field *and* it hasn't been changed yet. Otherwise, it
|
||||
performs the normal Emacs ``delete-char`` command.
|
||||
|
||||
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
|
||||
|
||||
@ -3,10 +3,8 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<title>Expanding snippets</title>
|
||||
<meta name="author" content="pluskid, joaotavora" />
|
||||
<meta name="date" content="2009-08-18" />
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
@ -52,96 +50,344 @@
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#some-stuff" id="id1">Some stuff</a><ul>
|
||||
<li><a class="reference internal" href="#file-content" id="id2">File content</a></li>
|
||||
<li><a class="reference internal" href="#triggering-expansion" id="id2">Triggering expansion</a><ul>
|
||||
<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>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#the-strategy-to-select-a-snippet" id="id3">The strategy to select a snippet</a><ul>
|
||||
<li><a class="reference internal" href="#finding-the-key" id="id4">Finding the key</a></li>
|
||||
<li><a class="reference internal" href="#the-condition-system" id="id5">The condition system</a></li>
|
||||
<li><a class="reference internal" href="#multiple-snippet-with-the-same-key" id="id6">Multiple snippet with the same key</a><ul>
|
||||
<li><a class="reference internal" href="#use-the-x-window-system" id="id7">Use the X window system</a></li>
|
||||
<li><a class="reference internal" href="#use-built-in-emacs-selection-methods" id="id8">Use built-in Emacs selection methods</a></li>
|
||||
<li><a class="reference internal" href="#use-dropdown-menu-el" id="id9">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#insert-at-point" id="id5">Insert at point</a></li>
|
||||
<li><a class="reference internal" href="#snippet-keybinding" id="id6">Snippet keybinding</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="#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="#expanding-from-emacs-lisp-code" id="id9">Expanding from emacs-lisp code</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#the-trigger-key" id="id10">The Trigger Key</a><ul>
|
||||
<li><a class="reference internal" href="#the-minor-mode" id="id11">The Minor Mode</a></li>
|
||||
<li><a class="reference internal" href="#the-fallback" id="id12">The Fallback</a></li>
|
||||
<li><a class="reference internal" href="#integration-with-hippie-expand" id="id13">Integration with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#controlling-expansion" id="id10">Controlling expansion</a><ul>
|
||||
<li><a class="reference internal" href="#eligible-snippets" id="id11">Eligible snippets</a></li>
|
||||
<li><a class="reference internal" href="#the-condition-system" id="id12">The condition system</a></li>
|
||||
<li><a class="reference internal" href="#multiples-snippet-with-the-same-key" id="id13">Multiples snippet with the same key</a><ul>
|
||||
<li><a class="reference internal" href="#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>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#other-way-to-select-a-snippet" id="id14">Other way to select a snippet</a><ul>
|
||||
<li><a class="reference internal" href="#yas-insert-snippet" id="id15"><tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt></a></li>
|
||||
<li><a class="reference internal" href="#expanding-from-elisp-code" id="id16">Expanding From Elisp Code</a></li>
|
||||
</ul>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#indenting" id="id17">Indenting</a></li>
|
||||
<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>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<div class="section" id="some-stuff">
|
||||
<h1><a class="toc-backref" href="#id1">Some stuff</a></h1>
|
||||
<div class="section" id="file-content">
|
||||
<h2><a class="toc-backref" href="#id2">File content</a></h2>
|
||||
<p>A file defining a snippet may just contain the template for the
|
||||
snippet. Optionally it can also contains some meta data for the
|
||||
snippet as well as comments.</p>
|
||||
<p>Generally speaking, if the file contains a line of <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt>, then all
|
||||
contents above that line are considered as meta data and comments;
|
||||
below are template. Or else the whole file content is considered as
|
||||
the template.</p>
|
||||
<p>Here's a typical example:</p>
|
||||
<div class="highlight"><pre>#contributor : pluskid <pluskid@gmail.com>
|
||||
#name : __...__
|
||||
# --
|
||||
__${init}__
|
||||
</pre></div>
|
||||
<p>Meta data are specified in the syntax of</p>
|
||||
<div class="highlight"><pre>#data-name : data value
|
||||
</pre></div>
|
||||
<p>Any other text above <tt class="docutils literal"><span class="pre">#</span> <span class="pre">--</span></tt> is considered as comment and
|
||||
ignored. Here's a list of currently supported meta data:</p>
|
||||
<img align="right" alt="images/group.png" class="align-right" src="images/group.png" />
|
||||
<div class="section" id="triggering-expansion">
|
||||
<h1><a class="toc-backref" href="#id2">Triggering expansion</a></h1>
|
||||
<p>You can use YASnippet to expand snippets in different ways:</p>
|
||||
<ul class="simple">
|
||||
<li><tt class="docutils literal"><span class="pre">name</span></tt>: The name of the snippet. This is a one-line description of
|
||||
the snippet. It will be displayed in the menu. So it's a good idea
|
||||
to select a descriptive name fo a snippet -- especially
|
||||
distinguishable among similar snippets.</li>
|
||||
<li><tt class="docutils literal"><span class="pre">contributor</span></tt>: The contributor of the snippet.</li>
|
||||
<li><tt class="docutils literal"><span class="pre">condition</span></tt>: The condition of the snippet. This is a piece of
|
||||
elisp code. If a snippet has a condition, then it will only be
|
||||
expanded when the condition code evaluate to some non-nil value.</li>
|
||||
<li><tt class="docutils literal"><span class="pre">key</span></tt>: The key to expand the snippet. Sometimes the key of a
|
||||
snippet is non-ASCII or not valid filename (e.g. contains
|
||||
<tt class="docutils literal"><span class="pre">/</span></tt>). One can then define the <tt class="docutils literal"><span class="pre">key</span></tt> property which will
|
||||
overwrite the filename as the key to expand the snippet.</li>
|
||||
<li><tt class="docutils literal"><span class="pre">group</span></tt>: The snippets for a mode can be grouped. Grouped snippets
|
||||
will be grouped in sub-menu. This is useful if one has too many
|
||||
snippets for a mode which will make the menu too long. <tt class="docutils literal"><span class="pre">group</span></tt>
|
||||
property only affect menu construction (See <a class="reference external" href="snippet-organization.html">Organizing snippets</a>). Refer to
|
||||
the snippets for <tt class="docutils literal"><span class="pre">ruby-mode</span></tt> for examples. Group can also be
|
||||
nested, e.g. <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure.loops</span></tt> tells that the snippet is
|
||||
under the <tt class="docutils literal"><span class="pre">loops</span></tt> group which is under the <tt class="docutils literal"><span class="pre">control</span> <span class="pre">structure</span></tt>
|
||||
group.</li>
|
||||
<li>By typing a snippet abbrev and then pressing the key defined in
|
||||
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to "TAB"). This works in a
|
||||
buffer where the minor mode <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active;</li>
|
||||
<li>By invoking the command <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> (either by typing
|
||||
<tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/insert-snippet</span></tt> or its keybinding). This does <em>not</em>
|
||||
require <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active.</li>
|
||||
<li>By using the keybinding associated with an active snippet. This also
|
||||
requires <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active;</li>
|
||||
<li>By expanding directly from the "YASnippet" menu in the menu-bar</li>
|
||||
<li>By using hippie-expand</li>
|
||||
<li>Expanding from emacs-lisp code</li>
|
||||
</ul>
|
||||
<div class="section" id="trigger-key">
|
||||
<h2><a class="toc-backref" href="#id3">Trigger key</a></h2>
|
||||
<p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is enabled, the keybinding taken from
|
||||
<tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> will take effect.</p>
|
||||
<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
|
||||
<em>snippet abbrev</em> (also known as <em>snippet key</em>) before point.</p>
|
||||
<p>The default key is <tt class="docutils literal"><span class="pre">"TAB"</span></tt>, however, you can freely set it to some
|
||||
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 "rails-mode"</span>
|
||||
(<span style="color: #19177C">add-hook</span> <span style="color: #19177C">'rinari-minor-mode-hook</span>
|
||||
<span style="color: #0000FF">#'</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">'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>
|
||||
</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">"SPC"</span></tt>. However,
|
||||
you don't want <tt class="docutils literal"><span class="pre">if</span></tt> to be expanded as a snippet when you are typing
|
||||
in a comment block or a string (e.g. in <tt class="docutils literal"><span class="pre">python-mode</span></tt>).</p>
|
||||
<p>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">'python-mode-hook</span>
|
||||
<span style="color: #666666">'</span>(<span style="color: #008000; font-weight: bold">lambda</span> ()
|
||||
(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/buffer-local-condition</span>
|
||||
<span style="color: #666666">'</span>(<span style="color: #008000; font-weight: bold">if</span> (<span style="color: #19177C">python-in-string/comment</span>)
|
||||
<span style="color: #666666">'</span>(<span style="color: #19177C">require-snippet-condition</span> <span style="color: #666666">.</span> <span style="color: #19177C">force-in-comment</span>)
|
||||
<span style="color: #880000">t</span>))))
|
||||
</pre></div>
|
||||
<p>... and specify the condition for a snippet that you're going to
|
||||
expand in comment to be evaluated to the symbol
|
||||
<tt class="docutils literal"><span class="pre">force-in-comment</span></tt>. Then it can be expanded as you expected, while
|
||||
other snippets like <tt class="docutils literal"><span class="pre">if</span></tt> still can't expanded in comment.</p>
|
||||
</div>
|
||||
<div class="section" id="the-strategy-to-select-a-snippet">
|
||||
<h1><a class="toc-backref" href="#id3">The strategy to select a snippet</a></h1>
|
||||
<p>When user press the <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>, YASnippet try to find a
|
||||
proper snippet to expand. The strategy to find such a snippet is
|
||||
explained here.</p>
|
||||
<div class="section" id="finding-the-key">
|
||||
<h2><a class="toc-backref" href="#id4">Finding the key</a></h2>
|
||||
<p>YASnippet search from current point backward trying to find the
|
||||
snippet to be expanded. The default searching strategy is quite
|
||||
powerful. For example, in <tt class="docutils literal"><span class="pre">c-mode</span></tt>, <tt class="docutils literal"><span class="pre">"bar"</span></tt>, <tt class="docutils literal"><span class="pre">"foo_bar"</span></tt>,
|
||||
<tt class="docutils literal"><span class="pre">"#foo_bar"</span></tt> can all be recognized as a template key. Further more,
|
||||
the searching is in that order. In other words, if <tt class="docutils literal"><span class="pre">"bar"</span></tt> is found
|
||||
to be a key to some <em>valid</em> snippet, then <tt class="docutils literal"><span class="pre">"foo_bar"</span></tt> and
|
||||
<tt class="docutils literal"><span class="pre">"#foobar"</span></tt> won't be searched.</p>
|
||||
<div class="section" id="multiples-snippet-with-the-same-key">
|
||||
<h2><a class="toc-backref" href="#id13">Multiples snippet with the same key</a></h2>
|
||||
<p>The rules outlined <a class="reference external" href="Eligiblesnippets">above</a> can return more than
|
||||
one snippet to be expanded at point.</p>
|
||||
<p>When there are multiple candidates, YASnippet will let you select
|
||||
one. The UI for selecting multiple candidate can be customized. A
|
||||
customization variable, called <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> defines your
|
||||
preferred method of being prompted for snippets.</p>
|
||||
<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">'</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/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">"user</span> <span class="pre">quit!")</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">"bar"</span></tt>, <tt class="docutils literal"><span class="pre">"foo_bar"</span></tt>, <tt class="docutils literal"><span class="pre">"#foo_bar"</span></tt> can all be
|
||||
recognized as a snippet key. Furthermore, the searching is in that
|
||||
order. In other words, if <tt class="docutils literal"><span class="pre">"bar"</span></tt> is found to be a key to some
|
||||
<em>valid</em> snippet, then <tt class="docutils literal"><span class="pre">"foo_bar"</span></tt> and <tt class="docutils literal"><span class="pre">"#foobar"</span></tt> won't be
|
||||
searched.</p>
|
||||
<p>However, this strategy can also be customized easily from the
|
||||
<tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt> variable. It is a list of syntax rules, the
|
||||
default value is <tt class="docutils literal"><span class="pre">("w"</span> <span class="pre">"w_"</span> <span class="pre">"w_."</span> <span class="pre">"^</span> <span class="pre">")</span></tt>. Which means search the
|
||||
@ -155,255 +401,6 @@ following thing until found one:</p>
|
||||
<p>But you'd better keep the default value unless you understand what
|
||||
Emacs's syntax rule mean.</p>
|
||||
</div>
|
||||
<div class="section" id="the-condition-system">
|
||||
<h2><a class="toc-backref" href="#id5">The condition system</a></h2>
|
||||
<p>I write forked snippet.el to make the smart-snippet.el. I call it
|
||||
<em>smart</em>-snippet because a condition can be attached to a snippet. This
|
||||
is really a good idea. However, writing condition for a snippet
|
||||
usually needs good elisp and Emacs knowledge, so it is strange to many
|
||||
user.</p>
|
||||
<p>Later I write YASnippet and persuade people to use it instead of
|
||||
smart-snippet.el. However, some user still love smart-snippet because
|
||||
it is smart. So I make YASnippet smart. Even smarter than
|
||||
smart-snippet.el. :p</p>
|
||||
<p>Consider this scenario: you are an old Emacs hacker. You like the
|
||||
abbrev-way and set <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to <tt class="docutils literal"><span class="pre">(kbd</span> <span class="pre">"SPC")</span></tt>. However,
|
||||
you don't want <tt class="docutils literal"><span class="pre">if</span></tt> to be expanded as a snippet when you are typing
|
||||
in a comment block or a string (e.g. in <tt class="docutils literal"><span class="pre">python-mode</span></tt>).</p>
|
||||
<p>It's OK, just specify the condition for <tt class="docutils literal"><span class="pre">if</span></tt> to be <tt class="docutils literal"><span class="pre">(not</span>
|
||||
<span class="pre">(python-in-string/comment))</span></tt>. But how about <tt class="docutils literal"><span class="pre">while</span></tt>, <tt class="docutils literal"><span class="pre">for</span></tt>,
|
||||
etc. ? Writing the same condition for all the snippets is just
|
||||
boring. So YASnippet introduce a buffer local variable
|
||||
<tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt>. You can set this variable to <tt class="docutils literal"><span class="pre">(not</span>
|
||||
<span class="pre">(python-in-string/comment))</span></tt> in <tt class="docutils literal"><span class="pre">python-mode-hook</span></tt>. There's no way
|
||||
to do this in smart-snippet.el!</p>
|
||||
<p>Then, what if you really want some snippet even in comment? This is
|
||||
also possible! But let's stop telling the story and look at the rules:</p>
|
||||
<ul class="simple">
|
||||
<li>If <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> evaluate to nil, snippet won't be
|
||||
expanded.</li>
|
||||
<li>If it evaluate to the a cons cell where the <tt class="docutils literal"><span class="pre">car</span></tt> is the symbol
|
||||
<tt class="docutils literal"><span class="pre">require-snippet-condition</span></tt> and the <tt class="docutils literal"><span class="pre">cdr</span></tt> is a symbol (let's
|
||||
call it <tt class="docutils literal"><span class="pre">requirement</span></tt>):<ul>
|
||||
<li>If the snippet has no condition, then it won't be expanded.</li>
|
||||
<li>If the snippet has a condition but evaluate to nil or error
|
||||
occured during evaluation, it won't be expanded.</li>
|
||||
<li>If the snippet has a condition that evaluate to non-nil (let's
|
||||
call it <tt class="docutils literal"><span class="pre">result</span></tt>):<ul>
|
||||
<li>If <tt class="docutils literal"><span class="pre">requirement</span></tt> is <tt class="docutils literal"><span class="pre">t</span></tt>, the snippet is ready to be
|
||||
expanded.</li>
|
||||
<li>If <tt class="docutils literal"><span class="pre">requirement</span></tt> is <tt class="docutils literal"><span class="pre">eq</span></tt> to <tt class="docutils literal"><span class="pre">result</span></tt>, the snippet is ready
|
||||
to be expanded.</li>
|
||||
<li>Otherwise the snippet won't be expanded.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
<li>If it evaluate to other non-nil value:<ul>
|
||||
<li>If the snippet has no condition, or has a condition that evaluate
|
||||
to non-nil, it is ready to be expanded.</li>
|
||||
<li>Otherwise, it won't be expanded.</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
<p>So set <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> like this</p>
|
||||
<div class="highlight"><pre>(<span style="color: #19177C">add-hook</span> <span style="color: #19177C">'python-mode-hook</span>
|
||||
<span style="color: #666666">'</span>(<span style="color: #008000; font-weight: bold">lambda</span> ()
|
||||
(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/buffer-local-condition</span>
|
||||
<span style="color: #666666">'</span>(<span style="color: #008000; font-weight: bold">if</span> (<span style="color: #19177C">python-in-string/comment</span>)
|
||||
<span style="color: #666666">'</span>(<span style="color: #19177C">require-snippet-condition</span> <span style="color: #666666">.</span> <span style="color: #19177C">force-in-comment</span>)
|
||||
<span style="color: #880000">t</span>))))
|
||||
</pre></div>
|
||||
<p>And specify the condition for a snippet that you're going to expand in
|
||||
comment to be evaluated to the symbol <tt class="docutils literal"><span class="pre">force-in-comment</span></tt>. Then it
|
||||
can be expanded as you expected, while other snippets like <tt class="docutils literal"><span class="pre">if</span></tt>
|
||||
still can't expanded in comment.</p>
|
||||
</div>
|
||||
<div class="section" id="multiple-snippet-with-the-same-key">
|
||||
<h2><a class="toc-backref" href="#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">'</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">'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">"TAB")</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">'yasnippet</span>)
|
||||
(<span style="color: #19177C">add-to-list</span> <span style="color: #19177C">'yas/extra-mode-hooks</span>
|
||||
<span style="color: #19177C">'ruby-mode-hook</span>)
|
||||
(<span style="color: #19177C">yas/initialize</span>)
|
||||
</pre></div>
|
||||
<p>Note that <strong>should</strong> be put after <tt class="docutils literal"><span class="pre">(require</span> <span class="pre">'yasnippet)</span></tt> and before
|
||||
<tt class="docutils literal"><span class="pre">(yas/initialize)</span></tt>. Further more, you may report it to me, I'll add
|
||||
that to the default value.</p>
|
||||
<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">$></span></tt> in your snippet, an <tt class="docutils literal"><span class="pre">(indent-according-to-mode)</span></tt> will
|
||||
be executed there to indent the line. So you'll not need to hard-code
|
||||
the indenting in the snippet template, and it will be very convenient
|
||||
when you need to work with several different project where coding
|
||||
styles are different.</p>
|
||||
<p>The reason why this feature wasn't added to YASnippet until after
|
||||
0.5.6 is that it doesn't work well for all modes. In some cases
|
||||
(e.g. python-mode), calling <tt class="docutils literal"><span class="pre">indent-according-to-mode</span></tt> will break
|
||||
the overlays created by YASnippet.</p>
|
||||
<p>However, since many people asked for this feature, I finally added
|
||||
this to YASnippet. Here's an example of the usage:</p>
|
||||
<div class="highlight"><pre>for (${int i = 0}; ${i < 10}; ${++i})
|
||||
{$>
|
||||
$0$>
|
||||
}$>
|
||||
</pre></div>
|
||||
<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>
|
||||
|
||||
@ -2,157 +2,242 @@
|
||||
Expanding snippets
|
||||
==================
|
||||
|
||||
:Author: pluskid, joaotavora
|
||||
:Contact: pluskid@gmail.com
|
||||
:Date: 2009-08-18
|
||||
.. _Organizing Snippets: snippet-organization.html
|
||||
.. _Expanding Snippets: snippet-expansion.html
|
||||
.. _Writing Snippets: snippet-development.html
|
||||
.. _The YASnippet Menu: snippet-menu.html
|
||||
|
||||
.. contents::
|
||||
|
||||
Some stuff
|
||||
==========
|
||||
|
||||
File content
|
||||
------------
|
||||
Triggering expansion
|
||||
====================
|
||||
|
||||
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.
|
||||
You can use YASnippet to expand snippets in different ways:
|
||||
|
||||
Generally speaking, if the file contains a line of ``# --``, then all
|
||||
contents above that line are considered as meta data and comments;
|
||||
below are template. Or else the whole file content is considered as
|
||||
the template.
|
||||
* By typing a snippet abbrev and then pressing the key defined in
|
||||
``yas/trigger-key`` (which defaults to "TAB"). This works in a
|
||||
buffer where the minor mode ``yas/minor-mode`` is active;
|
||||
|
||||
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>
|
||||
#name : __...__
|
||||
# --
|
||||
__${init}__
|
||||
* By expanding directly from the "YASnippet" menu in the menu-bar
|
||||
|
||||
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
|
||||
ignored. Here's a list of currently supported meta data:
|
||||
When ``yas/minor-mode`` is enabled, the keybinding taken from
|
||||
``yas/trigger-key`` will take effect.
|
||||
|
||||
.. image:: images/group.png
|
||||
:align: right
|
||||
``yas/trigger-key`` invokes ``yas/expand``, which tries to expand a
|
||||
*snippet abbrev* (also known as *snippet key*) before point.
|
||||
|
||||
* ``name``: The name of the snippet. This is a one-line description of
|
||||
the snippet. It will be displayed in the menu. So it's a good idea
|
||||
to select a descriptive name fo a snippet -- especially
|
||||
distinguishable among similar snippets.
|
||||
* ``contributor``: The contributor of the snippet.
|
||||
* ``condition``: The condition of the snippet. This is a piece of
|
||||
elisp code. If a snippet has a condition, then it will only be
|
||||
expanded when the condition code evaluate to some non-nil value.
|
||||
* ``key``: The key to expand the snippet. Sometimes the key of a
|
||||
snippet is non-ASCII or not valid filename (e.g. contains
|
||||
``/``). One can then define the ``key`` property which will
|
||||
overwrite the filename as the key to expand the snippet.
|
||||
* ``group``: The snippets for a mode can be grouped. Grouped snippets
|
||||
will be grouped in sub-menu. This is useful if one has too many
|
||||
snippets for a mode which will make the menu too long. ``group``
|
||||
property only affect menu construction (See `Organizing snippets <snippet-organization.html>`_). Refer to
|
||||
the snippets for ``ruby-mode`` for examples. Group can also be
|
||||
nested, e.g. ``control structure.loops`` tells that the snippet is
|
||||
under the ``loops`` group which is under the ``control structure``
|
||||
group.
|
||||
The default key is ``"TAB"``, however, you can freely set it to some
|
||||
other key.
|
||||
|
||||
.. 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
|
||||
proper snippet to expand. The strategy to find such a snippet is
|
||||
explained here.
|
||||
Trouble when using or understanding the ``yas/trigger-key`` is easily
|
||||
the most controversial issue in YASsnippet. See the `FAQ <faq.html>`_.
|
||||
|
||||
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
|
||||
snippet to be expanded. The default searching strategy is quite
|
||||
powerful. For example, in ``c-mode``, ``"bar"``, ``"foo_bar"``,
|
||||
``"#foo_bar"`` can all be recognized as a template key. Further more,
|
||||
the searching is in that order. In other words, if ``"bar"`` is found
|
||||
to be a key to some *valid* snippet, then ``"foo_bar"`` and
|
||||
``"#foobar"`` won't be searched.
|
||||
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.
|
||||
|
||||
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:
|
||||
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``.
|
||||
|
||||
* 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.
|
||||
The prompting methods used are again controlled by
|
||||
``yas/prompt-functions``.
|
||||
|
||||
But you'd better keep the default value unless you understand what
|
||||
Emacs's syntax rule mean.
|
||||
Snippet keybinding
|
||||
------------------
|
||||
|
||||
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
|
||||
--------------------
|
||||
|
||||
I write forked snippet.el to make the smart-snippet.el. I call it
|
||||
*smart*-snippet because a condition can be attached to a snippet. This
|
||||
is really a good idea. However, writing condition for a snippet
|
||||
usually needs good elisp and Emacs knowledge, so it is strange to many
|
||||
user.
|
||||
|
||||
Later I write YASnippet and persuade people to use it instead of
|
||||
smart-snippet.el. However, some user still love smart-snippet because
|
||||
it is smart. So I make YASnippet smart. Even smarter than
|
||||
smart-snippet.el. :p
|
||||
|
||||
Consider this scenario: you are an old Emacs hacker. You like the
|
||||
abbrev-way and set ``yas/trigger-key`` to ``(kbd "SPC")``. However,
|
||||
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
|
||||
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``,
|
||||
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
|
||||
(python-in-string/comment))`` in ``python-mode-hook``. There's no way
|
||||
to do this in smart-snippet.el!
|
||||
(python-in-string/comment))`` in ``python-mode-hook``.
|
||||
|
||||
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:
|
||||
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:
|
||||
|
||||
* If ``yas/buffer-local-condition`` evaluate to nil, snippet won't be
|
||||
expanded.
|
||||
* If it evaluate to the a cons cell where the ``car`` is the symbol
|
||||
* If ``yas/buffer-local-condition`` evaluate to nil, no snippets will
|
||||
be considered for expansion.
|
||||
|
||||
* 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
|
||||
call it ``requirement``):
|
||||
call it ``requirement``), then:
|
||||
|
||||
* If the snippet has no condition, then it won't be expanded.
|
||||
* If the snippet has a condition but evaluate to nil or error
|
||||
occured during evaluation, it won't be expanded.
|
||||
* If the snippet has a condition that evaluate to non-nil (let's
|
||||
* Snippets having no ``# condition:`` directive won't be considered;
|
||||
|
||||
* Snippets with conditions that evaluate to nil (or produce an
|
||||
error) won't be considered;
|
||||
|
||||
* If the snippet has a condition that evaluates to non-nil (let's
|
||||
call it ``result``):
|
||||
|
||||
* 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.
|
||||
to be expanded;
|
||||
|
||||
* Otherwise the snippet won't be considered.
|
||||
|
||||
* If it evaluate to other non-nil value:
|
||||
* 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
|
||||
to non-nil, it is ready to be expanded.
|
||||
* Otherwise, it won't be expanded.
|
||||
|
||||
* Otherwise, it won't be considered.
|
||||
|
||||
So set ``yas/buffer-local-condition`` like this
|
||||
In the mentioned scenario, set ``yas/buffer-local-condition`` like
|
||||
this
|
||||
|
||||
.. sourcecode:: common-lisp
|
||||
|
||||
@ -163,28 +248,19 @@ So set ``yas/buffer-local-condition`` like this
|
||||
'(require-snippet-condition . force-in-comment)
|
||||
t))))
|
||||
|
||||
And specify the condition for a snippet that you're going to expand in
|
||||
comment to be evaluated to the symbol ``force-in-comment``. Then it
|
||||
can be expanded as you expected, while other snippets like ``if``
|
||||
still can't expanded in comment.
|
||||
... and specify the condition for a snippet that you're going to
|
||||
expand in comment to be evaluated to the symbol
|
||||
``force-in-comment``. Then it can be expanded as you expected, while
|
||||
other snippets like ``if`` still can't expanded in comment.
|
||||
|
||||
Multiple snippet with the same key
|
||||
----------------------------------
|
||||
Multiples snippet with the same key
|
||||
-----------------------------------
|
||||
|
||||
There can be multiple snippet bind to the same key. If you define a
|
||||
snippet with a key that is already used, you'll overwrite the original
|
||||
snippet definition. However, you can add a different *postfix* to the
|
||||
key.
|
||||
|
||||
In general, the *extension* (consider a file name) is *ignored* when
|
||||
defining a snippet. So ``def``, ``def.1`` and ``def.mine`` will all be
|
||||
valid candidates when the key is ``def``.
|
||||
The rules outlined `above <Eligible snippets>`_ can return more than
|
||||
one snippet to be expanded at point.
|
||||
|
||||
When there are multiple candidates, YASnippet will let you select
|
||||
one. The UI for selecting multiple candidate can be
|
||||
customized. There're two variable related:
|
||||
|
||||
From version 0.6 of YASnippet this has changed significantly. A new
|
||||
one. The UI for selecting multiple candidate can be customized. A
|
||||
customization variable, called ``yas/prompt-functions`` defines your
|
||||
preferred method of being prompted for snippets.
|
||||
|
||||
@ -198,7 +274,7 @@ emacs-file:
|
||||
|
||||
Currently there are some alternatives solution with YASnippet.
|
||||
|
||||
.. image:: images/popup-menu.png
|
||||
.. image:: images/x-menu.png
|
||||
:align: right
|
||||
|
||||
Use the X window system
|
||||
@ -214,6 +290,9 @@ which means:
|
||||
``C-p`` to navigate.
|
||||
* This function can't be used when in a terminal.
|
||||
|
||||
.. image:: images/ido-menu.png
|
||||
:align: right
|
||||
|
||||
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
|
||||
method. The best way is to try it. This works in a terminal.
|
||||
|
||||
.. image:: images/idrop-menu.png
|
||||
:align: center
|
||||
.. image:: images/dropdown-menu.png
|
||||
:align: right
|
||||
|
||||
Use ``dropdown-menu.el``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@ -230,181 +309,97 @@ Use ``dropdown-menu.el``
|
||||
The function ``yas/dropdown-prompt`` can also be placed in the
|
||||
``yas/prompt-functions`` list.
|
||||
|
||||
.. image:: images/dropdown-menu.png
|
||||
:align: right
|
||||
This works in both window system and terminal and is customizable, you
|
||||
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
|
||||
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!
|
||||
Roll your own
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
* It works in both window system and terminal.
|
||||
* It is customizable, you can use ``C-n``, ``C-p`` to navigate, ``q``
|
||||
to quite and even press ``6`` as a shortcut to select the 6th
|
||||
candidate.
|
||||
See below for the documentation on variable ``yas/prompt-functions``
|
||||
|
||||
So I added ``yas/dropdown-list-popup-for-template`` to support
|
||||
``dropdown-list.el``. And upload ``dropdown-list.el`` to YASnippet
|
||||
hompage for an optional download (since Jaeyoun didn't provide a URL).
|
||||
Customizable Variables
|
||||
======================
|
||||
|
||||
Then finally, in 0.4.0, I included a copy of the content of
|
||||
``dropdown-list.el`` in ``yasnippet.el`` and made it the default
|
||||
way for selecting multiple candidates.
|
||||
|
||||
However, the original functions are still there, you can still use this
|
||||
|
||||
.. sourcecode:: common-lisp
|
||||
|
||||
(setq yas/window-system-popup-function
|
||||
'yas/x-popup-menu-for-template)
|
||||
|
||||
if you prefer a *modern* UI. :)
|
||||
|
||||
The Trigger Key
|
||||
---------------
|
||||
|
||||
YASnippet is implemented as a minor-mode (``yas/minor-mode``). The
|
||||
trigger key ``yas/trigger-key`` is defined in ``yas/minor-mode-map``
|
||||
to call ``yas/expand`` to try to expand a snippet.
|
||||
|
||||
The Minor Mode
|
||||
~~~~~~~~~~~~~~
|
||||
|
||||
.. image:: images/minor-mode-indicator.png
|
||||
:align: left
|
||||
|
||||
When ``yas/minor-mode`` is enabled, the trigger key will take
|
||||
effect. The default key is ``(kbd "TAB")``, however, you can freely
|
||||
set it to some other key.
|
||||
|
||||
In version 0.5, YASnippet add a hook to
|
||||
``after-change-major-mode-hook`` to enable ``yas/minor-mode`` in
|
||||
every buffer. This works fine for most modes, however, some mode
|
||||
doesn't follow the Emacs convention and doens't call this hook. You
|
||||
can either explicitly hook for those mode or just add it to
|
||||
``yas/extra-mode-hooks`` to let YASnippet do it for you:
|
||||
|
||||
.. sourcecode:: common-lisp
|
||||
|
||||
(require 'yasnippet)
|
||||
(add-to-list 'yas/extra-mode-hooks
|
||||
'ruby-mode-hook)
|
||||
(yas/initialize)
|
||||
|
||||
Note that **should** be put after ``(require 'yasnippet)`` and before
|
||||
``(yas/initialize)``. Further more, you may report it to me, I'll add
|
||||
that to the default value.
|
||||
|
||||
In version 0.6, just use ``yas/global-mode`` to enable YASnippet in
|
||||
all major modes. Or put ``yas/minor-mode-on`` in that modes hook. See
|
||||
the `FAQ <faq.html>`_.
|
||||
|
||||
The Fallback
|
||||
~~~~~~~~~~~~
|
||||
|
||||
If ``yas/expand`` failed to find any suitable snippet to expand, it
|
||||
will disable the minor mode temporarily and find if there's any other
|
||||
command bind the ``yas/trigger-key``. If found, the command will be
|
||||
called. Usually this works very well -- when there's a snippet, expand
|
||||
it, otherwise, call whatever command originally bind to the trigger
|
||||
key.
|
||||
|
||||
However, you can change this behavior by customizing the
|
||||
``yas/fallback-behavior`` variable. If you set this variable to
|
||||
``'return-nil``, it will return ``nil`` instead of trying to call the
|
||||
*original* command when no snippet is found. This is useful when you
|
||||
would like YASnippet to work with other extensions,
|
||||
e.g. ``hippie-expand``. I'm also glad to tell you that integration
|
||||
with ``hippie-expand`` is already included in YASnippet.
|
||||
|
||||
Integration with ``hippie-expand``
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To integrate with ``hippie-expand``, just put
|
||||
``yas/hippie-try-expand`` in
|
||||
``hippie-expand-try-functions-list``. Personally I would like to put
|
||||
in front of the list, but it can be put anywhere you prefer.
|
||||
|
||||
Other way to select a snippet
|
||||
-----------------------------
|
||||
|
||||
When you use the trigger key (so ``yas/expand``) to expand a snippet,
|
||||
the key for the snippet is deleted before the template for the snippet
|
||||
is inserted.
|
||||
|
||||
However, there're other ways to insert a snippet.
|
||||
|
||||
``yas/insert-snippet``
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The command ``M-x yas/insert-snippet`` lets you insert snippets at
|
||||
point *for you current major mode*. It prompts you for the snippet
|
||||
key first, and then for a snippet template if more than one template
|
||||
exists for the same key.
|
||||
|
||||
The list presented contains the snippets that can be inserted at
|
||||
point, according to the condition system. If you want to see all
|
||||
applicable snippets for the major mode, prefix this command with
|
||||
``C-u``.
|
||||
|
||||
The prompting methods used are again controlled by
|
||||
``yas/prompt-functions``.
|
||||
``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
|
||||
functin from elisp code. You should call ``yas/expand-snippet``
|
||||
instead of ``yas/expand`` in this case.
|
||||
* CHOICES: A list of strings or objects;
|
||||
|
||||
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:
|
||||
* optional DISPLAY-FN : A function. When applied to each of the
|
||||
objects in CHOICES it will return a string;
|
||||
|
||||
.. 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 belong to any snippet -- you can even make up it on the fly. The
|
||||
1st and 2nd parameter defines the region to be deleted after YASnippet
|
||||
inserted the template. It is used by ``yas/expand`` to indicate the
|
||||
region of the key. There's usually no need to delete any region when
|
||||
we are expanding a snippet from elisp code, so passing two ``(point)``
|
||||
is fine. Note only ``(point)`` will be fine because the 1st parameter
|
||||
also indicate where to insert and expand the ``template``.
|
||||
|
||||
|
||||
|
||||
Indenting
|
||||
---------
|
||||
|
||||
Many people miss the indenting feature of smart-snippet: when you
|
||||
place a ``$>`` in your snippet, an ``(indent-according-to-mode)`` will
|
||||
be executed there to indent the line. So you'll not need to hard-code
|
||||
the indenting in the snippet template, and it will be very convenient
|
||||
when you need to work with several different project where coding
|
||||
styles are different.
|
||||
|
||||
The reason why this feature wasn't added to YASnippet until after
|
||||
0.5.6 is that it doesn't work well for all modes. In some cases
|
||||
(e.g. python-mode), calling ``indent-according-to-mode`` will break
|
||||
the overlays created by YASnippet.
|
||||
|
||||
However, since many people asked for this feature, I finally added
|
||||
this to YASnippet. Here's an example of the usage:
|
||||
|
||||
.. sourcecode:: text
|
||||
|
||||
for (${int i = 0}; ${i < 10}; ${++i})
|
||||
{$>
|
||||
$0$>
|
||||
}$>
|
||||
|
||||
In 0.6.0 You should **not** need to use this feature although it's
|
||||
supported for backward compatibility. Just set ``yas/indent-line`` to
|
||||
``'auto``.
|
||||
* To signal that the user quit the prompting process, you can signal
|
||||
``quit`` with ``(signal 'quit "user quit!")``
|
||||
|
||||
``yas/fallback-behavior``
|
||||
-------------------------
|
||||
|
||||
How to act when ``yas/expand`` does *not* expand a snippet.
|
||||
|
||||
``call-other-command`` means try to temporarily disable YASnippet and
|
||||
call the next command bound to ``yas/trigger-key``.
|
||||
|
||||
``return-nil`` means return nil. (i.e. do nothing)
|
||||
|
||||
An entry (apply COMMAND . ARGS) means interactively call COMMAND, if
|
||||
ARGS is non-nil, call COMMAND non-interactively with ARGS as
|
||||
arguments.
|
||||
|
||||
``yas/choose-keys-first``
|
||||
-------------------------
|
||||
|
||||
If non-nil, prompt for snippet key first, then for template.
|
||||
|
||||
Otherwise prompts for all possible snippet names.
|
||||
|
||||
This affects ``yas/insert-snippet`` and ``yas/visit-snippet-file``.
|
||||
|
||||
``yas/choose-tables-first``
|
||||
---------------------------
|
||||
|
||||
If non-nil, and multiple eligible snippet tables, prompts user for
|
||||
tables first.
|
||||
|
||||
Otherwise, user chooses between the merging together of all
|
||||
eligible tables.
|
||||
|
||||
This affects ``yas/insert-snippet``, ``yas/visit-snippet-file``
|
||||
|
||||
``yas/key-syntaxes``
|
||||
--------------------
|
||||
|
||||
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.
|
||||
|
||||
|
||||
|
||||
@ -3,20 +3,18 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<title>The menu</title>
|
||||
<meta name="author" content="pluskid, joaotavora" />
|
||||
<meta name="date" content="2009-08-18" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<title>YASnippet menu</title>
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
<div class="document" id="the-menu">
|
||||
<div class="document" id="yasnippet-menu">
|
||||
<div id="header-region" class="clear-block"></div>
|
||||
<div id="wrapper">
|
||||
<div id="container" class="clear-block">
|
||||
<div id="header">
|
||||
<div id="logo-floater">
|
||||
<h1 class="title">The menu</h1>
|
||||
<h1 class="title">YASnippet menu</h1>
|
||||
</div>
|
||||
<ul class="primary-links">
|
||||
<li>
|
||||
@ -49,35 +47,72 @@
|
||||
<div id="squeeze">
|
||||
<div class="right-corner">
|
||||
<div class="left-corner">
|
||||
<p>YASnippet will setup a menu just after the <em>Buffers</em> Menu in the
|
||||
menubar. The snippets for all <em>real</em> modes are listed there under the
|
||||
menu. You can select a snippet from the menu to expand it. Since you
|
||||
select manually from the menu, you can expand any snippet. For
|
||||
example, you can expand a snippet defined for <tt class="docutils literal"><span class="pre">python-mode</span></tt> in a
|
||||
<tt class="docutils literal"><span class="pre">c-mode</span></tt> buffer by selecting it from the menu:</p>
|
||||
<img align="right" alt="images/menubar.png" class="align-right" src="images/menubar.png" />
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li>Condition system is ignored since you select to expand it
|
||||
explicitly.</li>
|
||||
<li>There will be no muliple candidates since they are listed in the
|
||||
menu as different items.</li>
|
||||
<li><a class="reference internal" href="#loading-snippets-from-menu" id="id1">Loading snippets from menu</a></li>
|
||||
<li><a class="reference internal" href="#snippet-menu-behavior" id="id2">Snippet menu behavior</a></li>
|
||||
<li><a class="reference internal" href="#controlling-indenting" id="id3">Controlling indenting</a></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>
|
||||
<p>This can be convenient sometimes. However, if you don't like the
|
||||
menubar of Emacs and never use it. You can tell YASnippet don't boring
|
||||
to build a menu by setting <tt class="docutils literal"><span class="pre">yas/use-menu</span></tt> to nil.</p>
|
||||
<p>Another thing to note is that only <em>real</em> modes are listed under the
|
||||
menu. As you know, common snippets can be shared by making up a
|
||||
<em>virtual</em> parent mode. It's too bad if the menu is floored by those
|
||||
<em>virtual</em> modes. So YASnippet only show menus for those <em>real</em>
|
||||
modes. But the snippets fo the <em>virtual</em> modes can still be accessed
|
||||
through the <tt class="docutils literal"><span class="pre">parent</span></tt> submenu of some <em>real</em> mode.</p>
|
||||
<p>YASnippet use a simple way to check whether a mode is <em>real</em> or
|
||||
<em>virtual</em>: <tt class="docutils literal"><span class="pre">(fboundp</span> <span class="pre">mode)</span></tt>. For example, the symbol <tt class="docutils literal"><span class="pre">c-mode</span></tt> is
|
||||
bound to a function while <tt class="docutils literal"><span class="pre">cc-mode</span></tt> is not. But this is not enough,
|
||||
some modes aren't part of Emacs, and maybe when initializing
|
||||
YASnippet, those modes haven't been initialized. So YASnippet also
|
||||
maintain a list of known modes (<tt class="docutils literal"><span class="pre">yas/known-modes</span></tt>). You can add item
|
||||
to that list if you need.</p>
|
||||
</div>
|
||||
<p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active, YASnippet will setup a menu just
|
||||
after the Buffers Menu in the menubar.</p>
|
||||
<p>In this menu, you can find</p>
|
||||
<ul class="simple">
|
||||
<li>The currently loaded snippet definitions, organized by major mode,
|
||||
and optional grouping.</li>
|
||||
<li>A rundown of the most common commands, (followed by their
|
||||
keybindings) including commands to load directories and reload all
|
||||
snippet definitions.</li>
|
||||
<li>A series of submenus for customizing and exploring YASnippet
|
||||
behavior.</li>
|
||||
</ul>
|
||||
<img align="right" alt="images/menu-1.png" class="align-right" src="images/menu-1.png" />
|
||||
<div class="section" id="loading-snippets-from-menu">
|
||||
<h1><a class="toc-backref" href="#id1">Loading snippets from menu</a></h1>
|
||||
<p>Invoking "Load snippets..." 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 "Reload all" 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 "real" 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
|
||||
"Snippet menu behavior" submenu.</p>
|
||||
</div>
|
||||
<div class="section" id="controlling-indenting">
|
||||
<h1><a class="toc-backref" href="#id3">Controlling indenting</a></h1>
|
||||
<p>The "Indenting" 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 "Prompting method" 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 "Misc" submenu contains options to control the values of more
|
||||
variables.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
85
doc/snippet-menu.rst
Normal file
85
doc/snippet-menu.rst
Normal 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.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@ -3,10 +3,8 @@
|
||||
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
||||
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
|
||||
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
|
||||
<title>Organizing snippets</title>
|
||||
<meta name="author" content="pluskid, joaotavora" />
|
||||
<meta name="date" content="2009-08-18" />
|
||||
<link rel="stylesheet" href="styles.css" type="text/css" />
|
||||
</head>
|
||||
<body>
|
||||
@ -52,26 +50,33 @@
|
||||
<div class="contents topic" id="contents">
|
||||
<p class="topic-title first">Contents</p>
|
||||
<ul class="simple">
|
||||
<li><a class="reference internal" href="#loading-snippets" id="id2">Loading snippets</a></li>
|
||||
<li><a class="reference internal" href="#id1" id="id3">Organizing snippets</a><ul>
|
||||
<li><a class="reference internal" href="#nested-organization" id="id4">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-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="#using-plain-file-names" id="id7">Using plain file names</a></li>
|
||||
<li><a class="reference internal" href="#loading-snippets" id="id4">Loading snippets</a></li>
|
||||
<li><a class="reference internal" href="#id2" id="id5">Organizing snippets</a><ul>
|
||||
<li><a class="reference internal" href="#nested-organization" id="id6">Nested organization</a></li>
|
||||
<li><a class="reference internal" href="#the-yas-parents-file" id="id7">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></li>
|
||||
<li><a class="reference internal" href="#the-yas-make-groups-file" id="id8">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></li>
|
||||
<li><a class="reference internal" href="#using-plain-file-names" id="id9">Using plain file names</a></li>
|
||||
</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>
|
||||
</li>
|
||||
<li><a class="reference internal" href="#no-storage-bundle" id="id8">No storage (bundle)</a></li>
|
||||
</ul>
|
||||
</div>
|
||||
<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
|
||||
to arrange for YASnippet to load them (unless you use a <a class="reference external" href="mailto:index.html@bundle-install">YASnippet
|
||||
bundle</a> (see <a class="reference internal" href="#no-storage-bundle">No storage (bundle)</a>),</p>
|
||||
<p>The non-bundle version of YASsnippet, once unpacked, comes with a full
|
||||
bundle</a>) into <em>snippet tables</em>.</p>
|
||||
<p>The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will look up
|
||||
these snippet tables and (hopefully) expand your intended snippet.</p>
|
||||
<p>The non-bundle version of YASnippet, once unpacked, comes with a full
|
||||
directory of snippets, which you can copy somewhere and use. You can
|
||||
also create or download, one or more directories.</p>
|
||||
<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>
|
||||
<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">"~/emacs.d/mysnippets"</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
|
||||
<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> directly) is considering "~/emacs.d/mysnippets"
|
||||
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>
|
||||
<p>If you make this variable a list and store more items into it...</p>
|
||||
<div class="highlight"><pre>;; Develop in ~/emacs.d/mysnippets, but also
|
||||
;; try out snippets in ~/Downloads/interesting-snippets
|
||||
(setq yas/root-directory '("~/emacs.d/mysnippets"
|
||||
"~/Downloads/interesting-snippets"))
|
||||
<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
|
||||
Snippets</a>.</p>
|
||||
<p>You can make this variable a list and store more items into it:</p>
|
||||
<div class="highlight"><pre><span style="color: #408080; font-style: italic">;; Develop in ~/emacs.d/mysnippets, but also</span>
|
||||
<span style="color: #408080; font-style: italic">;; try out snippets in ~/Downloads/interesting-snippets</span>
|
||||
(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/root-directory</span> <span style="color: #666666">'</span>(<span style="color: #BA2121">"~/emacs.d/mysnippets"</span>
|
||||
<span style="color: #BA2121">"~/Downloads/interesting-snippets"</span>))
|
||||
|
||||
;; Map `yas/load-directory' to every element
|
||||
(mapc 'yas/load-directory yas/root-directory)
|
||||
<span style="color: #408080; font-style: italic">;; Map `yas/load-directory' to every element</span>
|
||||
(<span style="color: #008000">mapc</span> <span style="color: #19177C">'yas/load-directory</span> <span style="color: #19177C">yas/root-directory</span>)
|
||||
</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
|
||||
"~/emacs.d/mysnippets"</p>
|
||||
</div>
|
||||
<div class="section" id="id1">
|
||||
<h1><a class="toc-backref" href="#id3">Organizing snippets</a></h1>
|
||||
<div class="section" id="id2">
|
||||
<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
|
||||
inside subdirectories of these directories.</p>
|
||||
<p>Common to <em>both</em> cases, snippet definitions are put in plain text
|
||||
files. They are arranged by subdirectories, and the name of these
|
||||
directories correspond to the Emacs mode where you want expansion to
|
||||
inside sub-directories of these directories.</p>
|
||||
<p>Snippet definitions are put in plain text files. They are arranged by
|
||||
sub-directories, and the snippet tables are named after these directories.</p>
|
||||
<p>The name corresponds to the Emacs mode where you want expansion to
|
||||
take place. For example, snippets for <tt class="docutils literal"><span class="pre">c-mode</span></tt> are put in the
|
||||
<tt class="docutils literal"><span class="pre">c-mode</span></tt> subdirectory. 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>
|
||||
<tt class="docutils literal"><span class="pre">c-mode</span></tt> sub-directory. You can also skip snippet storage altogether
|
||||
and use the bundle (see <a class="reference external" href="mailto:index.html@bundle-install">YASnippet bundle</a>).</p>
|
||||
<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
|
||||
for some modes:</p>
|
||||
<div class="highlight"><pre>$ tree
|
||||
@ -126,18 +132,20 @@ for some modes:</p>
|
||||
| `-- for
|
||||
`-- time
|
||||
</pre></div>
|
||||
<p>The parent directory acts as the <em>parent mode</em>. This is the way of
|
||||
YASnippet to share snippet definitions among different modes. As you
|
||||
can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and <tt class="docutils literal"><span class="pre">java-mode</span></tt> share the same parents
|
||||
<tt class="docutils literal"><span class="pre">cc-mode</span></tt>, while all modes are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>. This can
|
||||
be also used to as an <em>alias</em> -- <tt class="docutils literal"><span class="pre">cperl-mode</span></tt> is an empty directory
|
||||
whose parent is <tt class="docutils literal"><span class="pre">perl-mode</span></tt>.</p>
|
||||
<p>A parent directory acts as a <em>parent table</em> of any of its
|
||||
sub-directories. This is one of the ways YASnippet can share snippet
|
||||
definitions among different modes. As you can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt>
|
||||
and <tt class="docutils literal"><span class="pre">java-mode</span></tt> share the same parents <tt class="docutils literal"><span class="pre">cc-mode</span></tt>, while all modes
|
||||
are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>.</p>
|
||||
<p>This can be also used to as an <em>alias</em> -- <tt class="docutils literal"><span class="pre">cperl-mode</span></tt> is an empty
|
||||
directory whose parent is <tt class="docutils literal"><span class="pre">perl-mode</span></tt>.</p>
|
||||
<img align="right" alt="images/menu-parent.png" class="align-right" src="images/menu-parent.png" />
|
||||
</div>
|
||||
<div class="section" id="the-yas-parents-file">
|
||||
<h2><a class="toc-backref" href="#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
|
||||
subdirectories you can bypass nesting and still have parent modes. In
|
||||
this file you just write whitespace-separated names of modes. This
|
||||
sub-directories you can bypass nesting and still have parent modes. In
|
||||
this file you just write white-space-separated names of modes. This
|
||||
allows more flexibility and readability of your snippet hierarchy.</p>
|
||||
<div class="highlight"><pre>$ tree
|
||||
.
|
||||
@ -156,14 +164,14 @@ allows more flexibility and readability of your snippet hierarchy.</p>
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="the-yas-make-groups-file">
|
||||
<h2><a class="toc-backref" href="#id6">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" />
|
||||
<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/menu-groups.png" class="align-right" src="images/menu-groups.png" />
|
||||
<p>If you place an empty plain text file <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> inside one
|
||||
of the mode directories, the names of these subdirectories are
|
||||
considered groups of snippets and the <cite>YASsnippet menu</cite> is organized
|
||||
of the mode directories, the names of these sub-directories are
|
||||
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>
|
||||
<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/
|
||||
ruby-mode/
|
||||
|-- .yas-make-groups
|
||||
@ -180,13 +188,15 @@ ruby-mode/
|
||||
</pre></div>
|
||||
</div>
|
||||
<div class="section" id="using-plain-file-names">
|
||||
<h2><a class="toc-backref" href="#id7">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
|
||||
snippets</a>. However, if you customize the
|
||||
variable <tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> to be true <em>or</em> place an
|
||||
empty 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 (but not mandatory) if many
|
||||
snippets within a mode share the same trigger key.</p>
|
||||
<h2><a class="toc-backref" href="#id9">Using plain file names</a></h2>
|
||||
<p>Normally, file names act as the snippet expansion <em>abbreviation</em> (also
|
||||
known as the <em>snippet key</em> or <em>snippet trigger</em>, see <a class="reference external" href="snippet-expansion.html">Expanding
|
||||
Snippets</a>).</p>
|
||||
<p>However, if you customize the variable
|
||||
<tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> to be true <em>or</em> place an empty
|
||||
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/
|
||||
rails-mode/
|
||||
|-- .yas-make-groups
|
||||
@ -205,14 +215,14 @@ rails-mode/
|
||||
</pre></div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="section" id="no-storage-bundle">
|
||||
<h1><a class="toc-backref" href="#id8">No storage (bundle)</a></h1>
|
||||
<div class="section" id="id3">
|
||||
<h1><a class="toc-backref" href="#id10">YASnippet bundle</a></h1>
|
||||
<p>The most convenient way to define snippets for YASnippet is to put
|
||||
them in a directory arranged by the mode and use
|
||||
<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> to load them.</p>
|
||||
<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 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
|
||||
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>
|
||||
@ -223,8 +233,32 @@ snippets.</p>
|
||||
<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
|
||||
generated this way.</p>
|
||||
<p>See the internal documentation for the functions
|
||||
<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>
|
||||
<p>See the internal documentation for these functions</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>
|
||||
|
||||
@ -2,9 +2,10 @@
|
||||
Organizing snippets
|
||||
===================
|
||||
|
||||
:Author: pluskid, joaotavora
|
||||
:Contact: pluskid@gmail.com
|
||||
:Date: 2009-08-18
|
||||
.. _Organizing Snippets: snippet-organization.html
|
||||
.. _Expanding Snippets: snippet-expansion.html
|
||||
.. _Writing Snippets: snippet-development.html
|
||||
.. _The YASnippet Menu: snippet-menu.html
|
||||
|
||||
.. contents::
|
||||
|
||||
@ -13,13 +14,16 @@ Loading snippets
|
||||
|
||||
Snippet definitions are stored in files in the filesystem and you have
|
||||
to arrange for YASnippet to load them (unless you use a `YASnippet
|
||||
bundle <index.html@bundle-install>`_ (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
|
||||
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``:
|
||||
|
||||
.. 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
|
||||
``yas/load-directory`` directly) is considering "~/emacs.d/mysnippets"
|
||||
for snippet development, so you can use commands like
|
||||
``yas/new-snippet`` and others described `here
|
||||
<snippet-development.html>`_)
|
||||
``yas/new-snippet`` and others described in section `Writing
|
||||
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
|
||||
:align: right
|
||||
|
||||
;; Develop in ~/emacs.d/mysnippets, but also
|
||||
;; 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
|
||||
(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
|
||||
"~/emacs.d/mysnippets"
|
||||
|
||||
@ -57,14 +60,15 @@ Organizing 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
|
||||
files. They are arranged by subdirectories, and the name of these
|
||||
directories correspond to the Emacs mode where you want expansion to
|
||||
Snippet definitions are put in plain text files. They are arranged by
|
||||
sub-directories, and the snippet tables are named after these directories.
|
||||
|
||||
The name corresponds to the Emacs mode where you want expansion to
|
||||
take place. For example, snippets for ``c-mode`` are put in the
|
||||
``c-mode`` subdirectory. You can also skip snippet storage altogether
|
||||
and use the bundle (see `No storage (bundle)`_).
|
||||
``c-mode`` sub-directory. You can also skip snippet storage altogether
|
||||
and use the bundle (see `YASnippet bundle`_).
|
||||
|
||||
Nested organization
|
||||
-------------------
|
||||
@ -90,19 +94,24 @@ for some modes:
|
||||
| `-- for
|
||||
`-- time
|
||||
|
||||
The parent directory acts as the *parent mode*. This is the way of
|
||||
YASnippet to share snippet definitions among different modes. As you
|
||||
can see above, ``c-mode`` and ``java-mode`` share the same parents
|
||||
``cc-mode``, while all modes are derived from ``text-mode``. This can
|
||||
be also used to as an *alias* -- ``cperl-mode`` is an empty directory
|
||||
whose parent is ``perl-mode``.
|
||||
A parent directory acts as a *parent table* of any of its
|
||||
sub-directories. This is one of the ways YASnippet can share snippet
|
||||
definitions among different modes. As you can see above, ``c-mode``
|
||||
and ``java-mode`` share the same parents ``cc-mode``, while all modes
|
||||
are derived from ``text-mode``.
|
||||
|
||||
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
|
||||
------------------------------
|
||||
|
||||
If you place a plain text file ``.yas-parents`` inside one of the
|
||||
subdirectories you can bypass nesting and still have parent modes. In
|
||||
this file you just write whitespace-separated names of modes. This
|
||||
sub-directories you can bypass nesting and still have parent modes. In
|
||||
this file you just write white-space-separated names of modes. This
|
||||
allows more flexibility and readability of your snippet hierarchy.
|
||||
|
||||
.. sourcecode:: text
|
||||
@ -125,17 +134,16 @@ allows more flexibility and readability of your snippet hierarchy.
|
||||
The ``.yas-make-groups`` file
|
||||
-----------------------------
|
||||
|
||||
.. image:: images/group.png
|
||||
.. image:: images/menu-groups.png
|
||||
:align: right
|
||||
|
||||
If you place an empty plain text file ``.yas-make-groups`` inside one
|
||||
of the mode directories, the names of these subdirectories are
|
||||
considered groups of snippets and the `YASsnippet menu` is organized
|
||||
of the mode directories, the names of these sub-directories are
|
||||
considered groups of snippets and `The YASnippet Menu`_ is organized
|
||||
much more cleanly, as you can see in the image.
|
||||
|
||||
Another alternative way to achieve this is to place a ``# group:``
|
||||
directive inside the snippet definition. See `Writing snippets
|
||||
<snippet-development.html>`_
|
||||
directive inside the snippet definition. See `Writing Snippets`_.
|
||||
|
||||
.. sourcecode:: text
|
||||
|
||||
@ -157,12 +165,15 @@ directive inside the snippet definition. See `Writing snippets
|
||||
Using plain file names
|
||||
----------------------
|
||||
|
||||
Normally, file names act as the snippet trigger *key*, see `Expanding
|
||||
snippets <snippet-expansion.html>`_. However, if you customize the
|
||||
variable ``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 (but not mandatory) if many
|
||||
snippets within a mode share the same trigger key.
|
||||
Normally, file names act as the snippet expansion *abbreviation* (also
|
||||
known as the *snippet key* or *snippet trigger*, see `Expanding
|
||||
Snippets`_).
|
||||
|
||||
However, if you customize the variable
|
||||
``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
|
||||
|
||||
@ -183,17 +194,16 @@ snippets within a mode share the same trigger key.
|
||||
| `-- assert_select.yasnippet
|
||||
|
||||
|
||||
|
||||
No storage (bundle)
|
||||
===================
|
||||
YASnippet bundle
|
||||
================
|
||||
|
||||
The most convenient way to define snippets for YASnippet is to put
|
||||
them in a directory arranged by the mode and use
|
||||
``yas/load-directory`` to load them.
|
||||
|
||||
However, this might slow down the Emacs startup speed if you have many
|
||||
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 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
|
||||
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
|
||||
generated this way.
|
||||
|
||||
See the internal documentation for the functions
|
||||
``yas/define-snippets`` and ``yas/compile-bundle``.
|
||||
See the internal documentation for these functions
|
||||
|
||||
* ``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
|
||||
|
||||
64
yasnippet.el
64
yasnippet.el
@ -160,7 +160,29 @@ bulk reloading of all snippets using `yas/reload-all'"
|
||||
yas/completing-prompt
|
||||
yas/ido-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
|
||||
:group 'yasnippet)
|
||||
|
||||
@ -238,9 +260,6 @@ field"
|
||||
(defcustom yas/fallback-behavior 'call-other-command
|
||||
"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
|
||||
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)]
|
||||
["Show all modes" (setq yas/use-menu 't)
|
||||
: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)
|
||||
:help "Show only snippet submenus for the current active modes"
|
||||
: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")
|
||||
nil
|
||||
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
|
||||
(car major-mode-and-parents)))
|
||||
(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
|
||||
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
|
||||
dropdown-list.el library.
|
||||
|
||||
Here's the default value for all the parameters:
|
||||
|
||||
(yas/compile-bundle \"yasnippet.el\"
|
||||
\"./yasnippet-bundle.el\"
|
||||
'(\"snippets\")
|
||||
\"(yas/initialize-bundle)\"
|
||||
\"dropdown-list.el\")
|
||||
(yas/compile-bundle \"yasnippet.el\"
|
||||
\"yasnippet-bundle.el\"
|
||||
\"snippets\")
|
||||
\"(yas/initialize-bundle)
|
||||
### autoload
|
||||
(require 'yasnippet-bundle)`\"
|
||||
\"dropdown-list.el\")
|
||||
"
|
||||
(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
|
||||
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.
|
||||
|
||||
Optional PARENT-MODE can be used to specify the parent modes of
|
||||
MODE. It can be a mode symbol of a list of mode symbols. It does
|
||||
not need to be a real mode.
|
||||
All the elelements are strings, including CONDITION, EXPAND-ENV
|
||||
and KEYBINDING which will be `read' and eventually `eval'-ed.
|
||||
|
||||
That is, when looking a snippet in MODE failed, it can refer to
|
||||
its parent modes."
|
||||
FILE is probably of very little use if you're programatically
|
||||
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))
|
||||
(parent-tables (mapcar #'yas/snippet-table-get-create
|
||||
(if (listp parent-mode)
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user