code.delx.au - gnu-emacs-elpa/blob - doc/snippet-expansion.html

   1 <?xml version="1.0" encoding="utf-8" ?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
   4 <head>
   5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
   6 <meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
   7 <title>Expanding snippets</title>
   8 <link rel="stylesheet" href="styles.css" type="text/css" />
   9 </head>
  10 <body>
  11 <div class="document" id="expanding-snippets">
  12 <div id="header-region" class="clear-block"></div>
  13 <div id="wrapper">
  14   <div id="container" class="clear-block">
  15     <div id="header">
  16     <div id="logo-floater">
  17     <h1 class="title">Expanding snippets</h1>
  18     </div>
  19     <ul class="primary-links">
  20       <li>
  21         <a title="" href="index.html">Intro and tutorial</a>
  22       </li>
  23       <li>
  24         <a title="" href="snippet-organization.html">Howto: organize</a>
  25       </li>
  26       <li>
  27         <a title="" href="snippet-expansion.html">Howto: expand</a>
  28       </li>
  29       <li>
  30         <a title="" href="snippet-development.html">Howto: write </a>
  31       </li>
  32       <li>
  33         <a title="" href="snippet-menu.html">Howto: menu </a>
  34       </li>
  35       <li>
  36         <a title="" href="faq.html">FAQ</a>
  37       </li>
  38       <li>
  39         <a title="" href="changelog.html">ChangeLog</a>
  40       </li>
  41       <li>
  42         <a title="" href="http://code.google.com/p/yasnippet/downloads/list">Download</a>
  43       </li>
  44     </ul>
  45     </div>
  46     <div id="center">
  47       <div id="squeeze">
  48         <div class="right-corner">
  49           <div class="left-corner">
  50             <p>
  51               <b>Important:</b> This documentation applies to
  52               the <b>SVN trunk</b> of YASnippet, which you
  53               get <a href="http://code.google.com/p/yasnippet/source/checkout">here</a>. Documentation
  54               for other versions can be found <a title=""
  55               href="http://code.google.com/p/yasnippet/downloads/list">here</a>.
  56             </p>
  57             <div class="contents topic" id="contents">
  58 <p class="topic-title first">Contents</p>
  59 <ul class="simple">
  60 <li><a class="reference internal" href="#triggering-expansion" id="id2">Triggering expansion</a><ul>
  61 <li><a class="reference internal" href="#trigger-key" id="id3">Trigger key</a><ul>
  62 <li><a class="reference internal" href="#fallback-bahaviour" id="id4">Fallback bahaviour</a></li>
  63 </ul>
  64 </li>
  65 <li><a class="reference internal" href="#insert-at-point" id="id5">Insert at point</a></li>
  66 <li><a class="reference internal" href="#snippet-keybinding" id="id6">Snippet keybinding</a></li>
  67 <li><a class="reference internal" href="#expanding-from-the-menu" id="id7">Expanding from the menu</a></li>
  68 <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>
  69 <li><a class="reference internal" href="#expanding-from-emacs-lisp-code" id="id9">Expanding from emacs-lisp code</a></li>
  70 </ul>
  71 </li>
  72 <li><a class="reference internal" href="#controlling-expansion" id="id10">Controlling expansion</a><ul>
  73 <li><a class="reference internal" href="#eligible-snippets" id="id11">Eligible snippets</a></li>
  74 <li><a class="reference internal" href="#the-condition-system" id="id12">The condition system</a></li>
  75 <li><a class="reference internal" href="#multiples-snippet-with-the-same-key" id="id13">Multiples snippet with the same key</a><ul>
  76 <li><a class="reference internal" href="#use-the-x-window-system" id="id14">Use the X window system</a></li>
  77 <li><a class="reference internal" href="#minibuffer-prompting" id="id15">Minibuffer prompting</a></li>
  78 <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>
  79 <li><a class="reference internal" href="#roll-your-own" id="id17">Roll your own</a></li>
  80 </ul>
  81 </li>
  82 </ul>
  83 </li>
  84 <li><a class="reference internal" href="#customizable-variables" id="id18">Customizable Variables</a><ul>
  85 <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>
  86 <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>
  87 <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>
  88 <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>
  89 <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>
  90 </ul>
  91 </li>
  92 </ul>
  93 </div>
  94 <div class="section" id="triggering-expansion">
  95 <h1><a class="toc-backref" href="#id2">Triggering expansion</a></h1>
  96 <p>You can use YASnippet to expand snippets in different ways:</p>
  97 <ul class="simple">
  98 <li>By typing an abbrev, the snippet <em>trigger key</em>, and then pressing
  99 the key defined in <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> (which defaults to
 100 &quot;TAB&quot;). This works in buffers where the minor mode
 101 <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is active;</li>
 102 <li>By invoking the command <tt class="docutils literal"><span class="pre">yas/insert-snippet</span></tt> (either by typing
 103 <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>
 104 require <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active.</li>
 105 <li>By using the keybinding associated with an active snippet. This also
 106 requires <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> to be active;</li>
 107 <li>By expanding directly from the &quot;YASnippet&quot; menu in the menu-bar</li>
 108 <li>By using hippie-expand</li>
 109 <li>Expanding from emacs-lisp code</li>
 110 </ul>
 111 <div class="section" id="trigger-key">
 112 <h2><a class="toc-backref" href="#id3">Trigger key</a></h2>
 113 <p>When <tt class="docutils literal"><span class="pre">yas/minor-mode</span></tt> is enabled, the keybinding taken from
 114 <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> will take effect.</p>
 115 <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
 116 <em>snippet abbrev</em> (also known as <em>snippet key</em>) before point.</p>
 117 <p>The default key is <tt class="docutils literal"><span class="pre">&quot;TAB&quot;</span></tt>, however, you can freely set it to some
 118 other key.</p>
 119 <img align="left" alt="images/minor-mode-indicator.png" class="align-left" src="images/minor-mode-indicator.png" />
 120 <p>To enable the YASnippet minor mode in all buffers globally use the
 121 command <tt class="docutils literal"><span class="pre">yas/global-mode</span></tt>.</p>
 122 <p>When you use <tt class="docutils literal"><span class="pre">yas/global-mode</span></tt> you can also selectively disable
 123 YASnippet in some buffers by setting the buffer-local variable
 124 <tt class="docutils literal"><span class="pre">yas/dont-active</span></tt> in the buffer's mode hook.</p>
 125 <p>Trouble when using or understanding the <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> is easily
 126 the most controversial issue in YASsnippet. See the <a class="reference external" href="faq.html">FAQ</a>.</p>
 127 <div class="section" id="fallback-bahaviour">
 128 <h3><a class="toc-backref" href="#id4">Fallback bahaviour</a></h3>
 129 <p><tt class="docutils literal"><span class="pre">yas/fallback-behaviour</span></tt> is a customization variable bound to
 130 <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
 131 any suitable snippet to expand, it will disable the minor mode
 132 temporarily and find if there's any other command bound the
 133 <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</p>
 134 <p>If found, the command will be called. Usually this works very well --
 135 when there's a snippet, expand it, otherwise, call whatever command
 136 originally bind to the trigger key.</p>
 137 <p>However, you can change this behavior by customizing the
 138 <tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt> variable. If you set this variable to
 139 <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
 140 <em>original</em> command when no snippet is found.</p>
 141 </div>
 142 </div>
 143 <div class="section" id="insert-at-point">
 144 <h2><a class="toc-backref" href="#id5">Insert at point</a></h2>
 145 <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
 146 point <em>for you current major mode</em>. It prompts you for the snippet
 147 key first, and then for a snippet template if more than one template
 148 exists for the same key.</p>
 149 <p>The list presented contains the snippets that can be inserted at
 150 point, according to the condition system. If you want to see all
 151 applicable snippets for the major mode, prefix this command with
 152 <tt class="docutils literal"><span class="pre">C-u</span></tt>.</p>
 153 <p>The prompting methods used are again controlled by
 154 <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt>.</p>
 155 </div>
 156 <div class="section" id="snippet-keybinding">
 157 <h2><a class="toc-backref" href="#id6">Snippet keybinding</a></h2>
 158 <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
 159 Snippets</a>.</p>
 160 </div>
 161 <div class="section" id="expanding-from-the-menu">
 162 <h2><a class="toc-backref" href="#id7">Expanding from the menu</a></h2>
 163 <p>See <a class="reference external" href="snippet-menu.html">the YASnippet Menu</a>.</p>
 164 </div>
 165 <div class="section" id="expanding-with-hippie-expand">
 166 <h2><a class="toc-backref" href="#id8">Expanding with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt></a></h2>
 167 <p>To integrate with <tt class="docutils literal"><span class="pre">hippie-expand</span></tt>, just put
 168 <tt class="docutils literal"><span class="pre">yas/hippie-try-expand</span></tt> in
 169 <tt class="docutils literal"><span class="pre">hippie-expand-try-functions-list</span></tt>. This probably makes more sense
 170 when placed at the top of the list, but it can be put anywhere you
 171 prefer.</p>
 172 </div>
 173 <div class="section" id="expanding-from-emacs-lisp-code">
 174 <h2><a class="toc-backref" href="#id9">Expanding from emacs-lisp code</a></h2>
 175 <p>Sometimes you might want to expand a snippet directly from you own
 176 elisp code. You should call <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> instead of
 177 <tt class="docutils literal"><span class="pre">yas/expand</span></tt> in this case.</p>
 178 <p>As with expanding from the menubar, the condition system and multiple
 179 candidates doesn't affect expansion. In fact, expanding from the
 180 YASnippet menu has the same effect of evaluating the follow code:</p>
 181 <div class="highlight"><pre>(<span style="color: #19177C">yas/expand-snippet</span> <span style="color: #19177C">template</span>)
 182 </pre></div>
 183 <p>See the internal documentation on <tt class="docutils literal"><span class="pre">yas/expand-snippet</span></tt> for more
 184 information.</p>
 185 </div>
 186 </div>
 187 <div class="section" id="controlling-expansion">
 188 <h1><a class="toc-backref" href="#id10">Controlling expansion</a></h1>
 189 <div class="section" id="eligible-snippets">
 190 <h2><a class="toc-backref" href="#id11">Eligible snippets</a></h2>
 191 <p>YASnippet does quite a bit of filtering to find out which snippets are
 192 eligible for expanding at the current cursor position.</p>
 193 <p>In particular, the following things matter:</p>
 194 <ul>
 195 <li><p class="first">Currently loaded snippets tables</p>
 196 <p>These are loaded from a directory hierarchy in your file system. See
 197 <a class="reference external" href="snippet-organization.html">Organizing Snippets</a>. They are named after major modes like
 198 <tt class="docutils literal"><span class="pre">html-mode</span></tt>, <tt class="docutils literal"><span class="pre">ruby-mode</span></tt>, etc...</p>
 199 </li>
 200 <li><p class="first">Major mode of the current buffer</p>
 201 <p>If the currrent major mode matches one of the loaded snippet tables,
 202 then all that table's snippets are considered for expansion. Use
 203 <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-variable</span> <span class="pre">RET</span> <span class="pre">major-mode</span> <span class="pre">RET</span></tt> to find out which major
 204 mode you are in currently.</p>
 205 </li>
 206 <li><p class="first">Parent tables</p>
 207 <p>Snippet tables defined as the parent of some other eligible table
 208 are also considered. This works recursively, i.e. parents of parents
 209 of eligible tables are also considered.</p>
 210 </li>
 211 <li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/mode-symbol</span></tt> variable</p>
 212 <p>This can be used to consider snippet tables whose name does not
 213 correspond to a major mode. If you set this variable to a name ,
 214 like <tt class="docutils literal"><span class="pre">rinari-minor-mode</span></tt>, you can have some snippets expand only
 215 in that minor mode. Naturally, you want to set this conditionally,
 216 i.e. only when entering that minor mode, so using a hook is a good
 217 idea.</p>
 218 </li>
 219 </ul>
 220 <div class="highlight"><pre><span style="color: #408080; font-style: italic">;; When entering rinari-minor-mode, consider also the snippets in the</span>
 221 <span style="color: #408080; font-style: italic">;; snippet table &quot;rails-mode&quot;</span>
 222 (<span style="color: #19177C">add-hook</span> <span style="color: #19177C">&#39;rinari-minor-mode-hook</span>
 223           <span style="color: #0000FF">#&#39;</span>(<span style="color: #008000; font-weight: bold">lambda</span> ()
 224               (<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/mode-symbol</span> <span style="color: #19177C">&#39;rails-mode</span>)))
 225 </pre></div>
 226 <ul>
 227 <li><p class="first">Buffer-local <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> variable</p>
 228 <p>This variable provides finer grained control over what snippets can
 229 be expanded in the current buffer. The default value won't let you
 230 expand snippets inside comments or string literals for example. See
 231 <a class="reference internal" href="#the-condition-system">The condition system</a> for more info.</p>
 232 </li>
 233 </ul>
 234 </div>
 235 <div class="section" id="the-condition-system">
 236 <h2><a class="toc-backref" href="#id12">The condition system</a></h2>
 237 <p>Consider this scenario: you are an old Emacs hacker. You like the
 238 abbrev-way and set <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt> to <tt class="docutils literal"><span class="pre">&quot;SPC&quot;</span></tt>. However,
 239 you don't want <tt class="docutils literal"><span class="pre">if</span></tt> to be expanded as a snippet when you are typing
 240 in a comment block or a string (e.g. in <tt class="docutils literal"><span class="pre">python-mode</span></tt>).</p>
 241 <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>)
 242 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>
 243 <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>,
 244 etc. ? Writing the same condition for all the snippets is just
 245 boring. So has a buffer local variable
 246 <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>
 247 <span class="pre">(python-in-string/comment))</span></tt> in <tt class="docutils literal"><span class="pre">python-mode-hook</span></tt>.</p>
 248 <p>Then, what if you really want some particular snippet to expand even
 249 inside a comment? This is also possible! But let's stop telling the
 250 story and look at the rules:</p>
 251 <ul class="simple">
 252 <li>If <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> evaluate to nil, no snippets will
 253 be considered for expansion.</li>
 254 <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
 255 <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
 256 call it <tt class="docutils literal"><span class="pre">requirement</span></tt>), then:<ul>
 257 <li>Snippets having no <tt class="docutils literal"><span class="pre">#</span> <span class="pre">condition:</span></tt> directive won't be considered;</li>
 258 <li>Snippets with conditions that evaluate to nil (or produce an
 259 error) won't be considered;</li>
 260 <li>If the snippet has a condition that evaluates to non-nil (let's
 261 call it <tt class="docutils literal"><span class="pre">result</span></tt>):<ul>
 262 <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
 263 expanded;</li>
 264 <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
 265 to be expanded;</li>
 266 <li>Otherwise the snippet won't be considered.</li>
 267 </ul>
 268 </li>
 269 </ul>
 270 </li>
 271 <li>If it evaluates to the symbol <tt class="docutils literal"><span class="pre">always</span></tt>, all snippets are
 272 considered for expansion, regardless of any conditions.</li>
 273 <li>If it evaluate to <tt class="docutils literal"><span class="pre">t</span></tt> or some other non-nil value:<ul>
 274 <li>If the snippet has no condition, or has a condition that evaluate
 275 to non-nil, it is ready to be expanded.</li>
 276 <li>Otherwise, it won't be considered.</li>
 277 </ul>
 278 </li>
 279 </ul>
 280 <p>In the mentioned scenario, set <tt class="docutils literal"><span class="pre">yas/buffer-local-condition</span></tt> like
 281 this</p>
 282 <div class="highlight"><pre>(<span style="color: #19177C">add-hook</span> <span style="color: #19177C">&#39;python-mode-hook</span>
 283           <span style="color: #666666">&#39;</span>(<span style="color: #008000; font-weight: bold">lambda</span> ()
 284              (<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/buffer-local-condition</span>
 285                    <span style="color: #666666">&#39;</span>(<span style="color: #008000; font-weight: bold">if</span> (<span style="color: #19177C">python-in-string/comment</span>)
 286                         <span style="color: #666666">&#39;</span>(<span style="color: #19177C">require-snippet-condition</span> <span style="color: #666666">.</span> <span style="color: #19177C">force-in-comment</span>)
 287                       <span style="color: #880000">t</span>))))
 288 </pre></div>
 289 <p>... and specify the condition for a snippet that you're going to
 290 expand in comment to be evaluated to the symbol
 291 <tt class="docutils literal"><span class="pre">force-in-comment</span></tt>. Then it can be expanded as you expected, while
 292 other snippets like <tt class="docutils literal"><span class="pre">if</span></tt> still can't expanded in comment.</p>
 293 </div>
 294 <div class="section" id="multiples-snippet-with-the-same-key">
 295 <h2><a class="toc-backref" href="#id13">Multiples snippet with the same key</a></h2>
 296 <p>The rules outlined <a class="reference external" href="Eligiblesnippets">above</a> can return more than
 297 one snippet to be expanded at point.</p>
 298 <p>When there are multiple candidates, YASnippet will let you select
 299 one. The UI for selecting multiple candidate can be customized through
 300 <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> , which defines your preferred methods of
 301 being prompted for snippets.</p>
 302 <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>
 303 <span class="pre">yas/prompt-functions</span> <span class="pre">RET</span></tt>. Alternatively you can put in your
 304 emacs-file:</p>
 305 <div class="highlight"><pre>(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/prompt-functions</span> <span style="color: #666666">&#39;</span>(<span style="color: #19177C">yas/x-prompt</span> <span style="color: #19177C">yas/dropdown-prompt</span>))
 306 </pre></div>
 307 <p>Currently there are some alternatives solution with YASnippet.</p>
 308 <img align="right" alt="images/x-menu.png" class="align-right" src="images/x-menu.png" />
 309 <div class="section" id="use-the-x-window-system">
 310 <h3><a class="toc-backref" href="#id14">Use the X window system</a></h3>
 311 <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
 312 to select. This menu will be part of you native window system widget,
 313 which means:</p>
 314 <ul class="simple">
 315 <li>It usually looks beautiful. E.g. when you compile Emacs with gtk
 316 support, this menu will be rendered with your gtk theme.</li>
 317 <li>Emacs have little control over it. E.g. you can't use <tt class="docutils literal"><span class="pre">C-n</span></tt>,
 318 <tt class="docutils literal"><span class="pre">C-p</span></tt> to navigate.</li>
 319 <li>This function can't be used when in a terminal.</li>
 320 </ul>
 321 <img align="right" alt="images/ido-menu.png" class="align-right" src="images/ido-menu.png" />
 322 </div>
 323 <div class="section" id="minibuffer-prompting">
 324 <h3><a class="toc-backref" href="#id15">Minibuffer prompting</a></h3>
 325 <p>You can use functions <tt class="docutils literal"><span class="pre">yas/completing-prompt</span></tt> for the classic emacs
 326 completion method or <tt class="docutils literal"><span class="pre">yas/ido-prompt</span></tt> for a much nicer looking
 327 method. The best way is to try it. This works in a terminal.</p>
 328 <img align="right" alt="images/dropdown-menu.png" class="align-right" src="images/dropdown-menu.png" />
 329 </div>
 330 <div class="section" id="use-dropdown-menu-el">
 331 <h3><a class="toc-backref" href="#id16">Use <tt class="docutils literal"><span class="pre">dropdown-menu.el</span></tt></a></h3>
 332 <p>The function <tt class="docutils literal"><span class="pre">yas/dropdown-prompt</span></tt> can also be placed in the
 333 <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt> list.</p>
 334 <p>This works in both window system and terminal and is customizable, you
 335 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
 336 <tt class="docutils literal"><span class="pre">6</span></tt> as a shortcut to select the 6th candidate.</p>
 337 </div>
 338 <div class="section" id="roll-your-own">
 339 <h3><a class="toc-backref" href="#id17">Roll your own</a></h3>
 340 <p>See below for the documentation on variable <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt></p>
 341 </div>
 342 </div>
 343 </div>
 344 <div class="section" id="customizable-variables">
 345 <h1><a class="toc-backref" href="#id18">Customizable Variables</a></h1>
 346 <div class="section" id="yas-prompt-functions">
 347 <h2><a class="toc-backref" href="#id19"><tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt></a></h2>
 348 <p>You can write a function and add it to the <tt class="docutils literal"><span class="pre">yas/prompt-functions</span></tt>
 349 list. These functions are called with the following arguments:</p>
 350 <ul class="simple">
 351 <li>PROMPT: A string to prompt the user;</li>
 352 <li>CHOICES: A list of strings or objects;</li>
 353 <li>optional DISPLAY-FN : A function. When applied to each of the
 354 objects in CHOICES it will return a string;</li>
 355 </ul>
 356 <p>The return value of any function you put here should be one of
 357 the objects in CHOICES, properly formatted with DISPLAY-FN (if
 358 that is passed).</p>
 359 <ul class="simple">
 360 <li>To signal that your particular style of prompting is unavailable at
 361 the moment, you can also have the function return nil.</li>
 362 <li>To signal that the user quit the prompting process, you can signal
 363 <tt class="docutils literal"><span class="pre">quit</span></tt> with <tt class="docutils literal"><span class="pre">(signal</span> <span class="pre">'quit</span> <span class="pre">&quot;user</span> <span class="pre">quit!&quot;)</span></tt></li>
 364 </ul>
 365 </div>
 366 <div class="section" id="yas-fallback-behavior">
 367 <h2><a class="toc-backref" href="#id20"><tt class="docutils literal"><span class="pre">yas/fallback-behavior</span></tt></a></h2>
 368 <p>How to act when <tt class="docutils literal"><span class="pre">yas/expand</span></tt> does <em>not</em> expand a snippet.</p>
 369 <dl class="docutils">
 370 <dt><tt class="docutils literal"><span class="pre">call-other-command</span></tt> means try to temporarily disable YASnippet and</dt>
 371 <dd>call the next command bound to <tt class="docutils literal"><span class="pre">yas/trigger-key</span></tt>.</dd>
 372 </dl>
 373 <p><tt class="docutils literal"><span class="pre">return-nil</span></tt> means return nil. (i.e. do nothing)</p>
 374 <p>An entry (apply COMMAND . ARGS) means interactively call COMMAND, if
 375 ARGS is non-nil, call COMMAND non-interactively with ARGS as
 376 arguments.</p>
 377 </div>
 378 <div class="section" id="yas-choose-keys-first">
 379 <h2><a class="toc-backref" href="#id21"><tt class="docutils literal"><span class="pre">yas/choose-keys-first</span></tt></a></h2>
 380 <p>If non-nil, prompt for snippet key first, then for template.</p>
 381 <p>Otherwise prompts for all possible snippet names.</p>
 382 <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>
 383 </div>
 384 <div class="section" id="yas-choose-tables-first">
 385 <h2><a class="toc-backref" href="#id22"><tt class="docutils literal"><span class="pre">yas/choose-tables-first</span></tt></a></h2>
 386 <p>If non-nil, and multiple eligible snippet tables, prompts user for
 387 tables first.</p>
 388 <p>Otherwise, user chooses between the merging together of all
 389 eligible tables.</p>
 390 <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>
 391 </div>
 392 <div class="section" id="yas-key-syntaxes">
 393 <h2><a class="toc-backref" href="#id23"><tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt></a></h2>
 394 <p>The default searching strategy is quite powerful. For example, in
 395 <tt class="docutils literal"><span class="pre">c-mode</span></tt>, <tt class="docutils literal"><span class="pre">bar</span></tt>, <tt class="docutils literal"><span class="pre">foo_bar</span></tt>, <tt class="docutils literal"><span class="pre">&quot;#foo_bar&quot;</span></tt> can all be recognized
 396 as a snippet key. Furthermore, the searching is in that order. In
 397 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,
 398 then that snippet is expanded and replaces the <tt class="docutils literal"><span class="pre">bar</span></tt>. Snippets
 399 pointed to by <tt class="docutils literal"><span class="pre">foo_bar</span></tt> and <tt class="docutils literal"><span class="pre">&quot;#foobar</span></tt> won't be considered.</p>
 400 <p>However, this strategy can also be customized easily from the
 401 <tt class="docutils literal"><span class="pre">yas/key-syntaxes</span></tt> variable. It is a list of syntax rules, the
 402 default value is <tt class="docutils literal"><span class="pre">(&quot;w&quot;</span> <span class="pre">&quot;w_&quot;</span> <span class="pre">&quot;w_.&quot;</span> <span class="pre">&quot;^</span> <span class="pre">&quot;)</span></tt>. Which means search the
 403 following thing until found one:</p>
 404 <ul class="simple">
 405 <li>a word.</li>
 406 <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>
 407 <li>a sequence of characters of either word, symbol or punctuation.</li>
 408 <li>a sequence of characters of non-whitespace characters.</li>
 409 </ul>
 410 <p>But you'd better keep the default value unless you want to understand
 411 how Emacs's syntax rules work...</p>
 412 </div>
 413 </div>
 414           </div>
 415         </div>
 416       </div>
 417     </div>
 418   </div>
 419 </div>
 420 <script type="text/javascript">
 421   var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
 422   document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
 423 </script>
 424 <script type="text/javascript">
 425   try {
 426   var pageTracker = _gat._getTracker("UA-10536822-1");
 427   pageTracker._trackPageview();
 428   } catch(err) {}
 429 </script>
 430 </div>
 431 </body>
 432 </html>