mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 21:13:04 +00:00
421 lines
28 KiB
HTML
421 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>
|
|
<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">
|
|
<p>
|
|
<b>Important:</b> This documentation applies to
|
|
the <b>SVN trunk</b> of YASnippet, which you
|
|
get <a href="http://code.google.com/p/yasnippet/source/checkout">here</a>. Documentation
|
|
for other versions can be found <a title=""
|
|
href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
|
|
</p>
|
|
<div class="contents topic" id="contents">
|
|
<p class="topic-title first">Contents</p>
|
|
<ul class="simple">
|
|
<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="#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="#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>
|
|
</ul>
|
|
</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="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>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="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
|
|
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>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|