How To Define Templates In YASnippet
How To Define Templates In YASnippet
Xah Lee, 2009-02-18
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.
You will need to have yasnippet installed. If you haven't already, see: http://code.google.com/p/yasnippet/.
Dir Structure By Emacs's Modes
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.
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”.
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: “.template_author”.
Each template file has this line: “# --” (Warning: 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. When there are multiple templates for the same abbrev, yasnippet will popup a multiple-choice menu, showing each template's name.
In the template definition, some chars have special meaning:
- “$” is a field. (This is the cursor position after the template expansion. If there are more than one (can be “$1”, “$2”, ...etc.), pressing tab will move cursor to these stops for user to fill in. (such as for function parameters))
- “`” (backtick) is used to include elisp code.
Examples of defining html tags with field stop points:
<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.
Loading Your Template
Once you create a template def 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)
Defining Templates with Lisp
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://code.google.com/p/yasnippet/wiki/HowtoDefineSnippet