diff options
Diffstat (limited to '')
| -rw-r--r-- | emacs.d/lisp/yasnippet/doc/snippet-organization.html | 292 |
1 files changed, 292 insertions, 0 deletions
diff --git a/emacs.d/lisp/yasnippet/doc/snippet-organization.html b/emacs.d/lisp/yasnippet/doc/snippet-organization.html new file mode 100644 index 0000000..efb3a2e --- /dev/null +++ b/emacs.d/lisp/yasnippet/doc/snippet-organization.html @@ -0,0 +1,292 @@ +<?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>Organizing snippets</title> +<link rel="stylesheet" href="styles.css" type="text/css" /> +</head> +<body> +<div class="document" id="organizing-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">Organizing 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="#loading-snippets" id="id3">Loading snippets</a></li> +<li><a class="reference internal" href="#id2" id="id4">Organizing snippets</a><ul> +<li><a class="reference internal" href="#nested-organization" id="id5">Nested organization</a></li> +<li><a class="reference internal" href="#the-yas-parents-file" id="id6">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></li> +<li><a class="reference internal" href="#the-yas-make-groups-file" id="id7">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></li> +<li><a class="reference internal" href="#using-plain-file-names" id="id8">Using plain file names</a></li> +</ul> +</li> +<li><a class="reference internal" href="#yasnippet-bundle" id="id9">YASnippet bundle</a></li> +<li><a class="reference internal" href="#customizable-variables" id="id10">Customizable variables</a><ul> +<li><a class="reference internal" href="#yas-root-directory" id="id11"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></li> +<li><a class="reference internal" href="#yas-ignore-filenames-as-triggers" id="id12"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></li> +</ul> +</li> +</ul> +</div> +<div class="section" id="loading-snippets"> +<h1><a class="toc-backref" href="#id3">Loading snippets</a></h1> +<p>Snippet definitions are stored in files in the filesystem. Unless you +use the simpler <a class="reference external" href="mailto:index.html@installation">bundle version</a>), these +are arranged so that YASnippet can load them into <em>snippet +tables</em>. The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will +look up these snippet tables and (hopefully) expand the snippet you +intended.</p> +<p>The non-bundle version of YASnippet, once unpacked, comes with a full +directory of snippets, which you can copy somewhere and use. You can +also create or download more directories.</p> +<p>Once these directories are in place reference them in the variable +<tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> and load them with <tt class="docutils literal"><span class="pre">yas/load-directory</span></tt>:</p> +<div class="highlight"><pre><span style="color: #408080; font-style: italic">;; Develop and keep personal snippets under ~/emacs.d/mysnippets</span> +(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/root-directory</span> <span style="color: #BA2121">"~/emacs.d/mysnippets"</span>) + +<span style="color: #408080; font-style: italic">;; Load the snippets</span> +(<span style="color: #19177C">yas/load-directory</span> <span style="color: #19177C">yas/root-directory</span>) +</pre></div> +<p>The point in using <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> (as opposed to calling +<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> directly) is considering "~/emacs.d/mysnippets" +for snippet development, so you can use commands like +<tt class="docutils literal"><span class="pre">yas/new-snippet</span></tt> and others described in section <a class="reference external" href="snippet-development.html">Writing +Snippets</a>.</p> +<p>You can make this variable a list and store more items into it:</p> +<div class="highlight"><pre><span style="color: #408080; font-style: italic">;; Develop in ~/emacs.d/mysnippets, but also</span> +<span style="color: #408080; font-style: italic">;; try out snippets in ~/Downloads/interesting-snippets</span> +(<span style="color: #008000; font-weight: bold">setq</span> <span style="color: #19177C">yas/root-directory</span> <span style="color: #666666">'</span>(<span style="color: #BA2121">"~/emacs.d/mysnippets"</span> + <span style="color: #BA2121">"~/Downloads/interesting-snippets"</span>)) + +<span style="color: #408080; font-style: italic">;; Map `yas/load-directory' to every element</span> +(<span style="color: #008000">mapc</span> <span style="color: #19177C">'yas/load-directory</span> <span style="color: #19177C">yas/root-directory</span>) +</pre></div> +<p>In this last example, the all the directories are loaded and their +snippets considered for expansion. However development still happens +in the first element, "~/emacs.d/mysnippets".</p> +</div> +<div class="section" id="id2"> +<h1><a class="toc-backref" href="#id4">Organizing snippets</a></h1> +<p>Once you've setup <tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> , you can store snippets +inside sub-directories of these directories.</p> +<p>Snippet definitions are put in plain text files. They are arranged by +sub-directories, and the snippet tables are named after these directories.</p> +<p>The name corresponds to the Emacs mode where you want expansion to +take place. For example, snippets for <tt class="docutils literal"><span class="pre">c-mode</span></tt> are put in the +<tt class="docutils literal"><span class="pre">c-mode</span></tt> sub-directory. You can also skip snippet storage altogether +and use the bundle (see <a class="reference internal" href="#yasnippet-bundle">YASnippet bundle</a>).</p> +<div class="section" id="nested-organization"> +<h2><a class="toc-backref" href="#id5">Nested organization</a></h2> +<p>Here is an excerpt of a directory hierarchy containing snippets +for some modes:</p> +<div class="highlight"><pre>$ tree +. +`-- text-mode + |-- cc-mode + | |-- c-mode + | | `-- printf + | |-- for + | |-- java-mode + | | `-- println + | `-- while + |-- email + |-- perl-mode + | |-- cperl-mode + | `-- for + `-- time +</pre></div> +<p>A parent directory acts as a <em>parent table</em> of any of its +sub-directories. This is one of the ways different Emacs major modes +can share snippet definitions. As you can see above, <tt class="docutils literal"><span class="pre">c-mode</span></tt> and +<tt class="docutils literal"><span class="pre">java-mode</span></tt> share the same parent <tt class="docutils literal"><span class="pre">cc-mode</span></tt> and its <tt class="docutils literal"><span class="pre">while</span></tt> +snipepts, while all modes are share the <tt class="docutils literal"><span class="pre">time</span></tt> snippet from +<tt class="docutils literal"><span class="pre">text-mode</span></tt>.</p> +<p>This can be also used to as an <em>alias</em> -- <tt class="docutils literal"><span class="pre">cperl-mode</span></tt> is an empty +directory whose parent is <tt class="docutils literal"><span class="pre">perl-mode</span></tt>.</p> +<img align="right" alt="images/menu-parent.png" class="align-right" src="images/menu-parent.png" /> +</div> +<div class="section" id="the-yas-parents-file"> +<h2><a class="toc-backref" href="#id6">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2> +<p>An alternate (and preferred) way of setting up parent tables consists +of placing a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the +sub-directories. By doing this, you avoid complex directory +nesting. In the <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file you just write +whitespace-separated names of modes. This allows more flexibility and +readability of your snippet hierarchy.</p> +<div class="highlight"><pre>$ tree +. +|-- c-mode +| |-- .yas-parents # contains "cc-mode text-mode" +| `-- printf +|-- cc-mode +| |-- for +| `-- while +|-- java-mode +| |-- .yas-parents # contains "cc-mode text-mode" +| `-- println +`-- text-mode + |-- email + `-- time +</pre></div> +</div> +<div class="section" id="the-yas-make-groups-file"> +<h2><a class="toc-backref" href="#id7">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2> +<img align="right" alt="images/menu-groups.png" class="align-right" src="images/menu-groups.png" /> +<p>If you place an empty plain text file <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> inside one +of the mode directories, the names of these sub-directories are +considered groups of snippets and <a class="reference external" href="snippet-menu.html">The YASnippet Menu</a> is organized +much more cleanly, as you can see in the image.</p> +<p>Another alternative way to achieve this is to place a <tt class="docutils literal"><span class="pre">#</span> <span class="pre">group:</span></tt> +directive inside the snippet definition. See <a class="reference external" href="snippet-development.html">Writing Snippets</a>.</p> +<div class="highlight"><pre>$ tree ruby-mode/ +ruby-mode/ +|-- .yas-make-groups +|-- collections +| |-- each +| `-- ... +|-- control structure +| |-- forin +| `-- ... +|-- definitions +| `-- ... +`-- general + `-- ... +</pre></div> +</div> +<div class="section" id="using-plain-file-names"> +<h2><a class="toc-backref" href="#id8">Using plain file names</a></h2> +<p>Normally, file names act as the snippet expansion <em>abbreviation</em> (also +known as the <em>snippet key</em> or <em>snippet trigger</em>, see <a class="reference external" href="snippet-expansion.html">Expanding +Snippets</a>).</p> +<p>However, if you customize the variable +<tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt> to be true <em>or</em> place an empty +file <tt class="docutils literal"><span class="pre">.yas-ignore-filename-triggers</span></tt> you can use much more +descriptive file names. This is useful if many snippets within a mode +share the same trigger key.</p> +<div class="highlight"><pre>$ tree rails-mode/ +rails-mode/ +|-- .yas-make-groups +|-- .yas-ignore-filename-triggers +|-- Insert ERb's <% __ %> or <%= __ %>.yasnippet +|-- asserts +| |-- assert(var = assigns(%3Avar)).yasnippet +| |-- assert_difference.yasnippet +| |-- assert_no_difference.yasnippet +| |-- assert_redirected_to (nested path plural).yasnippet +| |-- assert_redirected_to (nested path).yasnippet +| |-- assert_redirected_to (path plural).yasnippet +| |-- assert_redirected_to (path).yasnippet +| |-- assert_rjs.yasnippet +| `-- assert_select.yasnippet +</pre></div> +</div> +</div> +<div class="section" id="yasnippet-bundle"> +<h1><a class="toc-backref" href="#id9">YASnippet bundle</a></h1> +<p>The most convenient way to define snippets for YASnippet is to put +them in a directory arranged by the mode and use +<tt class="docutils literal"><span class="pre">yas/load-directory</span></tt> to load them.</p> +<p>However, this might slow down the Emacs start-up speed if you have many +snippets. You can use <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to define a bunch of +snippets for a particular mode in an Emacs-lisp file.</p> +<p>Since this is hard to maintain, there's a better way: define your +snippets in directory and then call <tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">yas/compile-bundle</span></tt> to +compile it into a bundle file when you modified your snippets.</p> +<p>The release bundle of YASnippet is produced by +<tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>. The bundle uses <tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> to +define snippets. This avoids the IO and parsing overhead when loading +snippets.</p> +<p>Further more, the generated bundle is a stand-alone file not depending +on <tt class="docutils literal"><span class="pre">yasnippet.el</span></tt>. The released bundles of YASnippet are all +generated this way.</p> +<p>See the internal documentation for these functions</p> +<ul class="simple"> +<li><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-function</span> <span class="pre">RET</span> <span class="pre">yas/define-snippets</span> <span class="pre">RET</span></tt></li> +<li><tt class="docutils literal"><span class="pre">M-x</span> <span class="pre">describe-function</span> <span class="pre">RET</span> <span class="pre">yas/compile-bundle</span> <span class="pre">RET</span></tt>.</li> +</ul> +</div> +<div class="section" id="customizable-variables"> +<h1><a class="toc-backref" href="#id10">Customizable variables</a></h1> +<div class="section" id="yas-root-directory"> +<h2><a class="toc-backref" href="#id11"><tt class="docutils literal"><span class="pre">yas/root-directory</span></tt></a></h2> +<p>Root directory that stores the snippets for each major mode.</p> +<p>If you set this from your .emacs, can also be a list of strings, +for multiple root directories. If you make this a list, the first +element is always the user-created snippets directory. Other +directories are used for bulk reloading of all snippets using +<tt class="docutils literal"><span class="pre">yas/reload-all</span></tt></p> +</div> +<div class="section" id="yas-ignore-filenames-as-triggers"> +<h2><a class="toc-backref" href="#id12"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></a></h2> +<p>If non-nil, don't derive tab triggers from filenames.</p> +<p>This means a snippet without a <tt class="docutils literal"><span class="pre">#</span> <span class="pre">key:</span></tt> directive wont have a tab +trigger.</p> +<!-- LocalWords: html YASnippet filesystem yas sourcecode setq mapc printf perl --> +<!-- LocalWords: println cperl forin filenames filename ERb's yasnippet Avar el --> +<!-- LocalWords: rjs RET --> +</div> +</div> + </div> + </div> + </div> + </div> + </div> +</div> +<script type="text/javascript"> + var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www."); + document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E")); +</script> +<script type="text/javascript"> + try { + var pageTracker = _gat._getTracker("UA-10536822-1"); + pageTracker._trackPageview(); + } catch(err) {} +</script> +</div> +</body> +</html> |