Xah Lee, 2009-02-18, 2009-11-06
This page shows you how to define your own templates for emacs's YASnippet template system.
YASnippet is a template system for emacs. It allows you to type a abbrevation and automatically expand the abbreviation into function templates. Bundled language templates includes: C, C++, C#, Perl, Python, Ruby, SQL, LaTeX, HTML, CSS and more. But you can define your own template set for your own language, or for any text that you need a template. The template system is simple plain text based. You do not need to have emacs lisp knowledge to define your own templates.
You will need to have yasnippet installed. If you haven't already, see: http://code.google.com/p/yasnippet/.
In your yasnippet dir, you'll find a path like this: “~/Documents/emacs/yasnippet/yasnippet-0.5.9/snippets/text-mode”. All template definitions are inside this dir or subdir.
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”.
THE FILE'S NAME DEFINES 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 below that line is the actual template definition. Everything above that line is for info purposes.
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 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:
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”, 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)
YASnippet template system can be defined using elisp itself. If you are a elisp programer, you can define all your templates without using the file system. For detailed documentation on how to do this, see: http://yasnippet.googlecode.com/svn/trunk/doc/snippet-development.html.