Xah Lee, 2009-02-18, 2009-11, 2010-08, 2011-05-09
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”.
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 like: cc-mode, perl-mode, python-mode, html-mode, css-mode, etc. Each dir contains templates that will be active when you are in that mode.
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 named:
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 infomation purposes. For example: 〔.readme〕.
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 user types doctype then Tab, 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:
$0 is the position the cursor (after the snippte is inserted). You don't need to put a $0 if 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 a elisp code. The lisp code will be evaluated in the same buffer the snippet is being expanded.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, you might want to have a date stamp. Here's a example that insert user's email address and datestamp.
`user-mail-address`
`(current-time-string)`
Once you create a template file, you have to load it. Pull the menu 〖menu-bar▸yasnippet▸yas/Reload everything〗, or type【Alt+x】 “yas/reload-all”.
Then, your new template definition will show up in the menu. You can also type the abbrev word followed by Tab to insert the new template. (Note: you must be in the emacs major mode that template is defined for)