9. Template Minor Mode

There's a file called `tmpl-minor-mode.el' in the distribution of the package hm--html-menus. It provides functions to use templates for the hm--html-mode and also for other modes. It needs nothing from the rest of the package and therefore it can be used independently of hm--html-mode.

9.1 What Are Templates

Templates are special pieces of text, which can be expanded by emacs. Expansion means that the template is replaced by something else, determined by evaluating lisp forms or emacs commands. The expansion can be done automatically after the insertion of templates with the command tmpl-insert-template-file in a buffer or by hand with the commands tmpl-expand-templates-in-buffer or tmpl-expand-templates-in-region.

Templates can be put together with normal text in a so called template file to provide prototype files. You should name these files with the following naming scheme:

        <file>.<type>.tmpl

where <file> is a string which describes for what the template could be used and <type> the normal file extension, e.g. `c' for C- files or `html' for HTML- files.

9.2 Syntax Of Templates

The templates are marked with the sign ^@, which stands for the null character (\000). It can be inserted in a buffer with the keys C-q C-SPC. You can also use any other character or string of characters by changing the variable tmpl-sign.

At the moment, there are 3 major types of templates:

1. Emacs Lisp function templates: The expansion of such a template evals a lisp form. It is possible to use functions or variables as lisp forms. The following is a simple example:

   ^@LISP^@ (insert-file "~/.emacs") ^@END LISP^@

   inserts the contents of the file `~/.emacs' in the current buffer during the expansion.

2. Emacs command templates: The expansion of a command template evals a template in the same way as an interactive command, which is invoked with M-x command. For example:

   ^@COMMAND^@ insert-file ^@END COMMAND^@

   runs the interactive command insert-file during the expansion.

3. Template comments Nothing will be evaluated during the expansion of a template comment. It is only a comment. For example:

   ^@C^@ This is a comment

   The end of the comment is the end of the line. Therefore it has the same syntax as a lisp or C++ comment.

4. Point template After expanding the templates of a region (or the whole buffer), the point will be set at the beginning of this template, if such a template was in the region. You should use only one of these templates in a region, otherwise the behaviour is undefined.

   The point should be here^@POINT^@ after the expansion of the region.

By default, a template will be deleted after its expansion, but without the linefeed. Look at the following examples:

Before the expansion:

    Line before the template
    ^@C^@ The Text of a comment template
    Line after the template

After the expansion:

Line before the template

Line after the template

Templates can start in any column, and only the template will be deleted after its expansion.

It is also possible to put an attribute list in a template. The attributes of the list control the deletion of the template. It may be that this will be extended in the future with other attributes. The attribute list must be specified as an alist (assoc list) in the start tag of a template and after its type. Each element of the alist consists of the name of the attribute following its value. If no attribute list is specified or if an attribute is missing, then the default values are used. At the moment there are the following 2 attributes:

1. don't delete attribute (DONT_DELETE): If the value is t, then the template will not be deleted after its expansion. If the value is nil then the template will be deleted. The default is nil. For example:

   Before the expansion:

   Line before the template ^@LISP ((DONT-DELETE t))^@ (insert-file "~/.cshrc") ^@END LISP^@ Line after the template

   After the expansion:

   Line before the template ^@LISP ((DONT-DELETE t))^@ (insert-file "~/.cshrc") ^@END LISP^@ Line after the template

   It was assumed, that the file `~/.cshrc' was empty !

2. delete line attribute (DELETE-LINE): If the value is t, then the linefeed before or after the template will be deleted. If the value is nil then no linefeed will be deleted. The default is nil. For example: Before the expansion:

   Line before the template ^@LISP ((DELETE-LINE t))^@ (insert-file "~/.cshrc") ^@END LISP^@ Line after the template

   After the expansion:

   Line before the template Line after the template

   It was assumed, that the file `~/.cshrc' was empty !

These attributes can be combined. For example:

	^@COMMAND ((DELETE-LINE t) (DONT-DELETE nil))^@
	insert-file
	^@END COMMAND^@

The last examples show also that whitespace (blanks, tabs, linefeeds) is allowed at most positions in a template.

Look at the file `tmpl-minor-mode.el' for a description of the commands to expand templates.

9.3 Template Customization

Since the XEmacs 19.15 and 20.2 a special package can be used for the customization of lisp packages. The internal drag and drop package uses now also this feature. Therefore you can set all user variables with the help of the Customize submenu, which can be selected in the Option menu. If you use it, the variables will currently be saved in a special customization file. Please look at the `NEWS' file or the info manuals of the XEmacs to find out more about the customization package.

Templates may be used for all editing modes, not only for hm--html-mode. Therefore their general customization isn't done in `hm--html-configuration.el'. Template variables are defined in the file `tmpl-minor-mode.el' instead. You can set them in your `.emacs' or in one of the other emacs init files (e.g. `default.el'). The following are the main variables for customization.

• tmpl-template-dir-list: A list of directories with template files. If it is nil, the default-directory will be used. If more than one directory is specified, then the template filenames should differ in all directories.

  This variable is used in the commands for inserting templates. Look at tmpl-insert-template-file-from-fixed-dirs and at tmpl-insert-template-file. The command tmpl-insert-template-file uses only the car of the list (if it is a list.)

• tmpl-template-configuration-file: Name of the configuration file for the tmpl minor mode. Its a name without a directory, because the file will be searched in all upper directories, until it (one) is found. The file must contain loadable Lisp code.

  If the command tmpl-insert-template-file-from-fixed-dirs is called, and the variable tmpl-template-dir-list is nil, the file determined by the variable tmpl-template-configuration-file will be searched in all upper directories and in the default one, starting with the default directory. If such a file is found and readable, then it is loaded. Therefore you can set the variable tmpl-template-dir-list, if you insert a line like the following in such a file:

  (setq tmpl-template-dir-list '("~/data/docs/latex/teTeX/templates/"))

• tmpl-filter-regexp: This defines a regular expression used for filtering out non-template files in template directories. It is used in the command tmpl-insert-template-file-from-fixed-dirs to allow only the selection of files which match the regexp. If it is nil, then the Filter ".*\\.tmpl$" is used. Set it to \".*\" if you want to disable the filter function or use the command tmpl-insert-template-file.
• tmpl-automatic-expand: If you insert a template file with tmpl-insert-template-file-from-fixed-dirs or with tmpl-insert-template-file, this variable is used. The templates in the buffer will be automatically expanded if the variable is set to t, which is the default.
• tmpl-sign: This determines the sign which marks the beginning and the end of template expressions. By default it is set to the null character (displayed in emacs as ^@). You can also set this to a string. Be careful if you change it, so that the templates will not be mixed up with other non-template text! Note: The expansion function looks at the whole template, so that it is very unlikely that the function will make a mistake.
• tmpl-minor-mode-map: The keymap for the template minor mode.

9.4 Template Commands

In this section the commands of the template package are described.

9.4.1 Insert Of Template Files

The template package provides the following two commands for inserting template files in an emacs buffer.

• tmpl-insert-template-file: This command can be used to insert a template file in the current buffer. It will expand the templates in the buffer if tmpl-automatic-expand is set to t. You can set a default directory for this command by setting the variable tmpl-template-dir-list. See section 9.3 Template Customization.
• tmpl-insert-template-file-from-fixed-dirs: The difference from the simpler command tmpl-insert-template-file is that this command will build a list for filename completion from a list of predefined directories (look at tmpl-template-dir-list). The filename completion list will also be filtered with the regular expression defined by tmpl-filer-regexp. See section 9.3 Template Customization. You can set the directory list and/or the filter differently in each mode where you use templates, so that you will get in the completion list only template files which could be used for the current mode.

  If the variable tmpl-template-dir-list is nil, it tries to find a file with a name determined by the variable tmpl-template-configuration-file. The file is searched at first in the default directory, at second in it's parent directory, at third in the parent directory of the parent directory and so on, until it is found or the root directory is reached. If such a readable file is found, then it is loaded. Therefore you can set this variable by inserting a line like the following in such a file: (setq tmpl-template-dir-list '("~/data/docs/latex/teTeX/templates/"))

  If you want to insert a template file with this command, which is not in one of the directories from tmpl-template-dir-list, then you have to enter the string "Change the directory" instead of a template file. This string is also in the completion list.

Both commands can also be used as functions. In this case the template file with is directory path must be given to them as an parameter.

You can also use commands like insert-file to insert template files and expand them by hand (see section 9.4.2 Expansion Of Templates).

9.4.2 Expansion Of Templates

You can expand templates by hand or automatically after their insertion. See section 9.4.1 Insert Of Template Files, for automatic expansion. Expansion by hand can be done with one of the following two functions:

• tmpl-expand-templates-in-region: Expands the templates in the region. The region is established by the optional arguments BEGIN and END. If the arguments are nil, or if the function is called interactively, then the current region will be used.
• tmpl-expand-templates-in-buffer: Expands all templates in the current buffer.

Both commands are bound to keys in the tmpl-minor-mode. See section 9.4.4 The Template Minor Mode.

9.4.3 Escaping Of Template Signs

It is possible to escape template signs in a buffer or in a region. Templates with escaped template signs are not expanded, but they are un-escaped by the expansion functions. Therefore it is possible to exclude single templates from the expansion by escaping them. Note: You can't escape a template twice. The commands which can be used for this are:

• tmpl-escape-tmpl-sign-in-region: Escapes all tmpl-signs (see section 9.3 Template Customization) with a tmpl-sign in a region. The region is established by the optional arguments BEGIN and END. If the arguments are nil, or if the function is called interactively, then the current region will be used.
• tmpl-escape-tmpl-sign-in-buffer: Same as tmpl-escape-tmpl-sign-in-region, but escapes all templates in the whole buffer.

Both commands are bound to keys in tmpl-minor-mode. See section 9.4.4 The Template Minor Mode.

9.4.4 The Template Minor Mode

The template minor mode can be toggled with the command tmpl-minor-mode. The purpose of this mode is only to provide key bindings for some of the commands of the package `tmpl-minor-mode'. If you don't want to use the key bindings, you don't need this minor mode.

Look at the key table tmpl-minor-mode-map (see section 9.3 Template Customization) for the definition of the keys.

It may be that I'll also provide a pulldown or popup menu for the minor mode in a future release.

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