5.2.2 Template Macros

Template macros occur in the template text. The default escape characters are “{{“ and “}}”, though they can be changed in the top-level variables. See Variables.

Thus, if you have the template code that looks like this:

;; Author: {{AUTHOR}}

Then the text between {{ and }} are a macro, and substituted by the value of the variable AUTHOR.

Macros can be specialized to be more than just a text string. For example, the macro above could be augmented with an Emacs Lisp function.

;; Author: {{AUTHOR:upcase}}

In this case, the Emacs Lisp function upcase will be called on the text value of the AUTHOR variable.

Macros can also be specialized to have different behaviors by using a prefix, non-alpha character or symbol. For example:

{{! This is a comment inside macro escape characters }}

shows that the “!” symbol is for comments.

Alternately, a macro could query the user during insertion:

(defun {{?NAME}} ()
   {{^}}
   ) ;; End of {{NAME}}

the “?” symbol indicates that if the symbol NAME isn’t in the dictionary, then the user should be queried for the NAME variable. If NAME appears again in the template, the original value specified by the user will be inserted again.

If the text from a dictionary value is to be placed in column format, you can use the “|” symbol to indicate you want column control. For example:

   | this | that |{{#A}}
   | {{|THIS:4}} | {{|THAT:4}} |{{/A}}

For each repeated section “#A” the dictionary values for THIS and THAT will be inserted and either trimmed to, or expanded to 4 characters in width.

Macros that are prefixed with the “#” symbol denote a section. A macro of the same name with a “/” prefix denotes the end of that section.

{{#MOOSE}}
Here is some text describing moose.
{{/MOOSE}}

In this example if the section MOOSE was “shown” in the active dictionary, then the text between the # and / macros will also be inserted.

All the text and macros within a section are either not shown at all (if that section is not ’visible’) or the section is shown one time for each dictionary added to that symbol. See Developing Template Functions.

Macros prefixed with “>” will include another template. Include macros would look like this:

{{>FOO:defun}}

where FOO is the dictionary variable for the sub-dictionary used for expanding the template defun. The defun template will be looked up in the template repository for the current mode, or in any inherited modes.

Another way to include another template is with an include macro that will also wrap section text. The includewrap insertion method looks like this:

{{<FOO:defun}}Handy Text goes here{{/FOO}}

In this case, defun is included just as above. If the defun template has a {{^}} macro in it, then the section text “Handy Text goes here” will be inserted at that point, and that location will not be saved as the cursor location.

If there is no {{^}}, then the text will not be inserted.

For both kinds of include macros, you may need to include a template from a different context. You can use : separate the context from the name, like this:

{{>FOO:declaration:function}}