mirror of
https://github.com/joaotavora/yasnippet.git
synced 2025-10-13 13:13:03 +00:00
238 lines
12 KiB
HTML
238 lines
12 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>Organizing snippets</title>
|
|
<meta name="author" content="pluskid, joaotavora" />
|
|
<meta name="date" content="2009-08-18" />
|
|
<link rel="stylesheet" href="styles.css" type="text/css" />
|
|
</head>
|
|
<body>
|
|
<div class="document" id="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">
|
|
<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="id2">Loading snippets</a></li>
|
|
<li><a class="reference internal" href="#id1" id="id3">Organizing snippets</a><ul>
|
|
<li><a class="reference internal" href="#nested-organization" id="id4">Nested organization</a></li>
|
|
<li><a class="reference internal" href="#the-yas-parents-file" id="id5">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="id6">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="id7">Using plain file names</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a class="reference internal" href="#no-storage-bundle" id="id8">No storage (bundle)</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section" id="loading-snippets">
|
|
<h1><a class="toc-backref" href="#id2">Loading snippets</a></h1>
|
|
<p>Snippet definitions are stored in files in the filesystem and you have
|
|
to arrange for YASnippet to load them (unless you use a <a class="reference external" href="mailto:index.html@bundle-install">YASnippet
|
|
bundle</a> (see <a class="reference internal" href="#no-storage-bundle">No storage (bundle)</a>),</p>
|
|
<p>The non-bundle version of YASsnippet, once unpacked, comes with a full
|
|
directory of snippets, which you can copy somewhere and use. You can
|
|
also create or download, one or more directories.</p>
|
|
<p>Once these are in place reference them in the variable
|
|
<tt class="docutils literal"><span class="pre">yas/root-directory</span></tt> and then 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 <a class="reference external" href="snippet-development.html">here</a>)</p>
|
|
<p>If you make this variable a list and store more items into it...</p>
|
|
<div class="highlight"><pre>;; Develop in ~/emacs.d/mysnippets, but also
|
|
;; try out snippets in ~/Downloads/interesting-snippets
|
|
(setq yas/root-directory '("~/emacs.d/mysnippets"
|
|
"~/Downloads/interesting-snippets"))
|
|
|
|
;; Map `yas/load-directory' to every element
|
|
(mapc 'yas/load-directory yas/root-directory)
|
|
</pre></div>
|
|
<p>, the directories after the first are loaded, their snippets
|
|
considered for expansion, but development still happens in
|
|
"~/emacs.d/mysnippets"</p>
|
|
</div>
|
|
<div class="section" id="id1">
|
|
<h1><a class="toc-backref" href="#id3">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 subdirectories of these directories.</p>
|
|
<p>Common to <em>both</em> cases, snippet definitions are put in plain text
|
|
files. They are arranged by subdirectories, and the name of these
|
|
directories correspond 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> subdirectory. You can also skip snippet storage altogether
|
|
and use the bundle (see <a class="reference internal" href="#no-storage-bundle">No storage (bundle)</a>).</p>
|
|
<div class="section" id="nested-organization">
|
|
<h2><a class="toc-backref" href="#id4">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>The parent directory acts as the <em>parent mode</em>. This is the way of
|
|
YASnippet to share snippet definitions among different modes. 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 parents
|
|
<tt class="docutils literal"><span class="pre">cc-mode</span></tt>, while all modes are derived from <tt class="docutils literal"><span class="pre">text-mode</span></tt>. 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>
|
|
</div>
|
|
<div class="section" id="the-yas-parents-file">
|
|
<h2><a class="toc-backref" href="#id5">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2>
|
|
<p>If you place a plain text file <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> inside one of the
|
|
subdirectories you can bypass nesting and still have parent modes. In
|
|
this 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="#id6">The <tt class="docutils literal"><span class="pre">.yas-make-groups</span></tt> file</a></h2>
|
|
<img align="right" alt="images/group.png" class="align-right" src="images/group.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 subdirectories are
|
|
considered groups of snippets and the <cite>YASsnippet menu</cite> 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="#id7">Using plain file names</a></h2>
|
|
<p>Normally, file names act as the snippet trigger <em>key</em>, see <a class="reference external" href="snippet-expansion.html">Expanding
|
|
snippets</a>. 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 (but not mandatory) 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="no-storage-bundle">
|
|
<h1><a class="toc-backref" href="#id8">No storage (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 startup 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 the functions
|
|
<tt class="docutils literal"><span class="pre">yas/define-snippets</span></tt> and <tt class="docutils literal"><span class="pre">yas/compile-bundle</span></tt>.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</body>
|
|
</html>
|