mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 21:13:04 +00:00
417 lines
28 KiB
HTML
417 lines
28 KiB
HTML
<?xml version="1.0" encoding="utf-8" ?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<meta name="generator" content="Docutils 0.6: 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>
|
|
<div class="document" id="expanding-snippets">
|
|
<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">Expanding snippets</h1>
|
|
</div>
|
|
<ul class="primary-links">
|
|
<li>
|
|
<a title="" href="index.html">Intro and tutorial</a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="snippet-organization.html">Howto: organize</a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="snippet-expansion.html">Howto: expand</a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="snippet-development.html">Howto: write </a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="snippet-menu.html">Howto: menu </a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="faq.html">FAQ</a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="changelog.html">ChangeLog</a>
|
|
</li>
|
|
<li>
|
|
<a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div id="center">
|
|
<div id="squeeze">
|
|
<div class="right-corner">
|
|
<div class="left-corner">
|
|
<div class="contents topic" id="contents">
|
|
<p class="topic-title first">Contents</p>
|
|
<ul class="simple">
|
|
<li><a class="reference internal" href="#some-stuff" id="id1">Some stuff</a><ul>
|
|
<li><a class="reference internal" href="#file-content" id="id2">File content</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>
|
|
</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>
|
|
</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>
|
|
</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" />
|
|
<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>
|
|
</ul>
|
|
</div>
|
|
</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>
|
|
<p>However, this strategy can also be customized easily from the
|
|
<tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt> variable. It is a list of syntax rules, the
|
|
default value is <tt class="docutils literal"><span class="pre">("w"</span> <span class="pre">"w_"</span> <span class="pre">"w_."</span> <span class="pre">"^</span> <span class="pre">")</span></tt>. Which means search the
|
|
following thing until found one:</p>
|
|
<ul class="simple">
|
|
<li>a word.</li>
|
|
<li>a symbol. In lisp, <tt class="docutils literal"><span class="pre">-</span></tt> and <tt class="docutils literal"><span class="pre">?</span></tt> can all be part of a symbol.</li>
|
|
<li>a sequence of characters of either word, symbol or punctuation.</li>
|
|
<li>a sequence of characters of non-whitespace characters.</li>
|
|
</ul>
|
|
<p>But you'd better keep the default value unless you understand what
|
|
Emacs's syntax rule mean.</p>
|
|
</div>
|
|
<div class="section" id="the-condition-system">
|
|
<h2><a class="toc-backref" href="#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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|