2. Templates

This node describes the syntax and semantics of templates defined by tempo-define-template. The first part deals with the syntax of the function itself, while the second part describes the different template elements.

2.1 Template syntax

Templates are defined with the function tempo-define-tempalate.

Function: tempo-define-template name elements [tag documentation [taglist]]]

Define a template named tempo-template-name.

This function creates a template and binds it to a new variable named tempo-template-name. It also creates a new command under the same name. This command expands the template at the current point, when invoked.

The parameter elements is a list of template elements. The possible elements are described in 2.2 Template elements.

If a tag is supplied, it must be a string which is placed in taglist or tempo-tags. This string is used for automatic completion. When tempo-complete-tag is called and tag is matched, the template template defined with tag is inserted. (see section 1.3 Tag lists and automatic completion for more information on tags and tag lists)

2.2 Template elements

These are the predefined elements you can use in a template definition:

STRING

A string in a template is first run through the string preprocessors in tempo-insert-string-functions and the result is inserted.

p

This denotes an "interesting" position in the template. When the template is expanded, this position is remembered with a mark on the tempo-marks list. See section 4. The mark list.

r

This works in a similar way to the above p element, but if the template command is given a prefix command, the current region is placed here. This means that the preceding part of the template is expanded before the region, and the rest is expanded after. There can be only one r in a template. If transient-mark-mode is active (see section `The Mark and the Region' in the GNU Emacs Manual) the current region is used and the prefix argument is ignored.

If the variable tempo-insert-region is non-nil, the behaviour of the r element is reversed.

(p prompt [name [noinsert]])

(P prompt [name [noinsert]])

(r prompt [name [noinsert]])

If the variable tempo-interactive is nil, the elements (p ...)) and (P ...) work exactly like a single p, and (r ...) works like a single r.

But, if you set tempo-interactive to t the user is prompted for a string to insert when the template is expanded. The prompt is taken from the prompt parameter. The element (P ...) works like (p ...) with the exception that tempo-interactive is forced to t, which means that the user will always (almost always, see below) be prompted.

If you provide a name to any of these, and interactive prompting is taking place, the resulting string is saved in a local list so it can be inserted again later with the (s ...) element. See section 5. The save list, for more detailed information.

As a special case, if the save list already contains something under name, it is used directly, and no prompting is done, even with a (P ...) element.

The third argument, noinsert, disables insertion of text. If tempo-interactive it non-nil, and a name has been provided, normally a string is read through the minibuffer and then inserted and saved. When noinsert is non-nil, nothing is inserted, and the text is only saved for later.

Stylistic conventions (invented by me) dictates that these elements should be placed as early as possible in template definitions.

r>

This element works like r, but it also indents the region it is expanded around.

(s name)

This looks up name in the save list and inserts what it finds. Note that if it finds a string, it is not run through the string preprocessors.

&

An ampersand inserts a newline if there are characters other than whitespace before the current point on the line. Otherwise it does nothing. This means that it makes sure that the following text always starts a new line, possibly with some leading whitespace.

%

A percent sign inserts a newline it there are characters other than whitespace after the current point on the line. Otherwise it does nothing.

n

Simply inserts a newline character.

>

This does not insert any text. Instead it indents the line according to the major mode, by calling indent-according-to-mode. Note that in order to get best results, you often should place this after the text you want to place on the line, as this could affect the indentation.

n>

Inserts a newline and indents line. It is the same as a n followed by a >.

o

Works like %, but leaves the point on the first line. Note that this can cause great confusion if you are not careful. If the o is the first element in a template which is inserted at the beginning of a line, strange things happen. This is due to odd behaviour in open-line.

nil

A nil element is simply igonred. That means that a lisp expression (see below) that returns nil does not insert anything.

(l element1 element2...)

This element is most useful as a return value from a lisp expression (see below). It inserts the elements using the same rules as all template elements.

Anything else

All unrecognized elements are checked to see if it is a user-defined elemet. See section 2.3 Defining your own elements. If isn't, it is assumed to be a lisp expression and is evaluated in a normal fashion. The result from such an expression is taken as a template element an is inserted according to the usual rules. If you don't want to insert anything, make your expression return nil. If you want to insert more than one element, use the (l element1 element2...) element.

2.3 Defining your own elements

The variable tempo-user-elements contains a list of functions to call when an unrecognized element is found.

Variable: tempo-user-elements

A list of functions. When tempo-insert is called with an element it doesn't recognize, it checks this list by calling each function with the element as the single argument. A function in this list should take a single element as argument and return nil for elements it doesn't recognize. If it does recognize an element, it should return another element to be inserted, e.g. a string. If the function wants to return an authorative nil, it could return either "" or (l).

Do not use any one-charachter tags for your own elements. These are reserved for future tempo enhancements.

This document was generated by XEmacs shared group account on December, 19 2009 using texi2html 1.65.