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