ld/yasnippet
1
0
Fork 0
mirror of https://github.com/joaotavora/yasnippet.git synced 2026-02-04 14:32:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc almost complete. Drawing closer to 0.6.1b

Browse Source
This commit is contained in:
capitaomorte
2009-08-23 19:52:33 +00:00
parent 5b8671f8c3
commit 6c88b24bf8
27 changed files with 1806 additions and 988 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
doc/snippet-organization.html
View File

@@ -3,10 +3,8 @@
<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/" />
<meta name="generator" content="Docutils 0.5: 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>
@@ -52,26 +50,33 @@
<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>
<li><a class="reference internal" href="#loading-snippets" id="id4">Loading snippets</a></li>
<li><a class="reference internal" href="#id2" id="id5">Organizing snippets</a><ul>
<li><a class="reference internal" href="#nested-organization" id="id6">Nested organization</a></li>
<li><a class="reference internal" href="#the-yas-parents-file" id="id7">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="id8">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="id9">Using plain file names</a></li>
</ul>
</li>
<li><a class="reference internal" href="#id3" id="id10">YASnippet bundle</a></li>
<li><a class="reference internal" href="#customizable-variables" id="id11">Customizable variables</a><ul>
<li><a class="reference internal" href="#yas-root-directory" id="id12"><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="id13"><tt class="docutils literal"><span class="pre">yas/ignore-filenames-as-triggers</span></tt></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>
<h1><a class="toc-backref" href="#id4">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&#64;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
bundle</a>) into <em>snippet tables</em>.</p>
<p>The triggering mechanisms (see <a class="reference external" href="snippet-expansion.html">Expanding snippets</a>) will look up
these snippet tables and (hopefully) expand your intended snippet.</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, one or more directories.</p>
<p>Once these are in place reference them in the variable
<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 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">&quot;~/emacs.d/mysnippets&quot;</span>)
@@ -82,32 +87,33 @@ also create or download, one or more directories.</p>
<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 &quot;~/emacs.d/mysnippets&quot;
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 &#39;(&quot;~/emacs.d/mysnippets&quot;
&quot;~/Downloads/interesting-snippets&quot;))
<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">&#39;</span>(<span style="color: #BA2121">&quot;~/emacs.d/mysnippets&quot;</span>
<span style="color: #BA2121">&quot;~/Downloads/interesting-snippets&quot;</span>))
;; Map `yas/load-directory&#39; to every element
(mapc &#39;yas/load-directory yas/root-directory)
<span style="color: #408080; font-style: italic">;; Map `yas/load-directory&#39; to every element</span>
(<span style="color: #008000">mapc</span> <span style="color: #19177C">&#39;yas/load-directory</span> <span style="color: #19177C">yas/root-directory</span>)
</pre></div>
<p>, the directories after the first are loaded, their snippets
<p>Here the directories after the first are loaded, their snippets
considered for expansion, but development still happens in
&quot;~/emacs.d/mysnippets&quot;</p>
</div>
<div class="section" id="id1">
<h1><a class="toc-backref" href="#id3">Organizing snippets</a></h1>
<div class="section" id="id2">
<h1><a class="toc-backref" href="#id5">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
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> 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>
<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 external" href="mailto:index.html&#64;bundle-install">YASnippet bundle</a>).</p>
<div class="section" id="nested-organization">
<h2><a class="toc-backref" href="#id4">Nested organization</a></h2>
<h2><a class="toc-backref" href="#id6">Nested organization</a></h2>
<p>Here is an excerpt of a directory hierarchy containing snippets
for some modes:</p>
<div class="highlight"><pre>$ tree
@@ -126,18 +132,20 @@ for some modes:</p>
| `-- 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>
<p>A parent directory acts as a <em>parent table</em> of any of its
sub-directories. This is one of the ways YASnippet can 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>.</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="#id5">The <tt class="docutils literal"><span class="pre">.yas-parents</span></tt> file</a></h2>
<h2><a class="toc-backref" href="#id7">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
sub-directories you can bypass nesting and still have parent modes. In
this file you just write white-space-separated names of modes. This
allows more flexibility and readability of your snippet hierarchy.</p>
<div class="highlight"><pre>$ tree
.
@@ -156,14 +164,14 @@ allows more flexibility and readability of your snippet hierarchy.</p>
</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" />
<h2><a class="toc-backref" href="#id8">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 subdirectories are
considered groups of snippets and the <cite>YASsnippet menu</cite> is organized
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>
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
@@ -180,13 +188,15 @@ ruby-mode/
</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>
<h2><a class="toc-backref" href="#id9">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
@@ -205,14 +215,14 @@ rails-mode/
</pre></div>
</div>
</div>
<div class="section" id="no-storage-bundle">
<h1><a class="toc-backref" href="#id8">No storage (bundle)</a></h1>
<div class="section" id="id3">
<h1><a class="toc-backref" href="#id10">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 startup speed if you have many
<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>
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>
@@ -223,8 +233,32 @@ 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>
<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="#id11">Customizable variables</a></h1>
<div class="section" id="yas-root-directory">
<h2><a class="toc-backref" href="#id12"><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>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.</p>
<p>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="#id13"><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>