Emacs: How to Define Templates in YASnippet
Emacs: How to Define Templates in YASnippet
by Xah Lee, 2009-02-18, …, 2012-03-25
This page shows you how to define your own templates for emacs's YASnippet template system. If you don't know what's yasnippet, see a intro here: Emacs Templates with YASnippet. This tutorial has been tested with YASnippet version “0.5.9” and “0.6.1c”.
Snippets are organized by Folders
Directory Structure by Emacs's Modes
In your yasnippet folder, you'll find a path like this:
~/.emacs.d/plugins/yasnippet/yasnippet-0.6.1c/snippets/text-mode/
All template definitions are inside this folder.
In the 〔text-mode〕 dir, there are subdirs: {c-mode, perl-mode, python-mode, html-mode, css-mode, …}. Each dir contains templates that will be active when you are in that mode.
One Template Definition Per File
Each template definition is a file. For example, suppose you have a template definition for “while” keyword for the Perl language. Then, there should be a file at this path: 〔text-mode/perl-mode/while〕.
Each file may end with the suffix “.yasnippet”.
By default, the file's name is the abbrev for the template. For example, if you have a file 〔html-mode/h1〕, then, typing h1 then Tab ⇆, will expand according to that template file's definition.
Technically, each file's name, up to the first period, defines the abbrev. For example: you might have these files:
doctype.xhml1
doctype.xhtml1_1
doctype.xhtml1_strict
doctype.xhtml1_transitional
When user types doctype then press Tab ⇆, a multiple choice menu will be shown.
File names starting with a period are not template definition but provide information purposes. For example: 〔.readme〕.
Template Syntax
Each template file has this line: # -- (there MUST be a space). Everything above that line is either comment or directive (don't worry about directives for now). Below the line is the actual template definition.
Here's a example of the template 〔html-mode/doctype〕.
#name : Doctype HTML 4.01 Strict
# --
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
When you type doctype then Tab ⇆, while in html-mode, it'll expand to:
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
The line #name : is for a short title for the template. This title is used in menus. For example, look at the menu 〖YASnippet〗. When there are multiple templates for the same abbrev, yasnippet will popup a multiple-choice menu, and each template's title is also shown in the menu.
In the template definition, some chars have special meaning:
$0is the position the cursor (after the snippte is inserted). You don't need to put a$0if you don't need to.$‹n›is a field, where the ‹n› is a integer starting with 1. (Example:$1,$2, …). Pressing tab will move cursor to these stops for user to fill in. Multiple occurrence of the same$‹n›means typing in one field will automatically fill the other. 同一个变量自动全部替换。
${‹n›:‹default text›}is same as$‹n›, but provides a default text.$&means indent the line according to the mode's indentation rule.`(backtick) is used to enclose elisp code. The lisp code will be evaluated in the same buffer the snippet is being expanded.
Sample Snippet Files
Examples of defining HTML tags with field stop points:
<h1>$1</h1>
<img src="$1" class="$2" alt="$3">
You can also include lisp code in your template. For example, youmight want to have a date stamp. Here's a example that insert user'semail address and datestamp.
`user-mail-address`
`(current-time-string)`
Loading Your Template
Once you create a template file, you have to load it. Pull the menu 〖menu-bar▸yasnippet▸yas/Reload everything〗, or call yas/reload-all.