Details of Package Template
- Menus and Key-Bindings
- Using a Template
- Finding a Template
- Creating a Template
- Decorating a Comment
- Updating a Buffer
Menus and Key-Bindings
For Emacs-21.1+ and XEmacs, this package defines the following menu entries and key-bindings:
- In menu File, there is a new menu item New File Using Template.... The corresponding command is also bound to the key sequence C-x t.
- At the end of menu Cmds (in XEmacs if it exists) or menu Edit, there is a new submenu Template Creation.
-
Enter C-x C-= (command
template-single-comment
) to insert dashes and alike into the current line and end the comment. -
Enter C-x C-; (command
template-single-comment
) to insert dashes and alike around the current comment block. - At the end of menu Edit, there is a new submenu Comment. It also contains the two commands just mentioned.
Using a Template
Package Template offers various ways how to use template files:
-
In Emacs, the usual way to create a new file is by typing C-x
C-f, using the menu or the toolbar (running command
find-file
orffap
) and entering a non-existent file name. In this case, you will be asked whether to use a template for the new file. You can turn off this feature. -
There is a new command
template-new-file
(see above for the menu entry and its key-binding) to create a new file using a template. Here, you have the chance to edit the name of the template file. This command also supports file name refinement which is useful to create a file in a series of files likeexercise2.tex
etc. - There is also a command (M-x template-expand-template) to insert a template file into the current buffer and expand its expansion forms.
Technical detail: documentation of command
template-new-file
and variable
template-auto-insert
.
Finding a Template
The algorithm for finding the most appropriate template can be best explained with a little example:
-
You have a project
~/proj/
with subprojectsfoo/
andbar/
containing.java
files. -
You want to define a general template for the
.java
in your project files, although.java
files in subprojectfoo/
should use their own template. You also want to define a special template for all filesproj.java
in the project. -
Since you do not want to clutter the project directory with template files, you
first create a directory
~/proj/Templates/
. In this directory, you create new filesTEMPLATE.java.tpl
andproj.java.tpl
. In directory~/proj/foo/
, you create a new fileTEMPLATE.java.tpl
.
The creation of the template files in the right directory is already enough for packages Template to find the most appropriate template for a new file:
-
If you create a new file
~/proj/foo/abc.java
, this package tries to find a template based on the file extension of the new file. The generic base file name for a template isTEMPLATE
and the additional extension is.tpl
, a fileTEMPLATE.java.tpl
exists in~/proj/foo/
, so that file is used as the template. -
If you create a new file
~/proj/bar/abc.java
, this package again tries to findTEMPLATE.java.tpl
. Since this file doesn't exist in~/proj/bar/
, it first inspects the subdirectoryTemplates/
which doesn't exist. The search continues with the parent directory~/proj/
and then its subdirectoryTemplates/
. Thus~/proj/Templates/TEMPLATE.java.tpl
will be used. -
If you create a new file
~/proj/foo/proj.java
, this package finds a template file with the same base name: it uses~/proj/Templates/proj.java.tpl
. You might argue that~/proj/foo/TEMPLATE.java.tpl
resides in a more specific directory, but having the same base name is considered to be more important (remember that some file like Makefiles do not have file extensions). -
If you create a new file
~/other_proj/foo/proj.java
, i.e., a project where you have defined no template files, this package uses one of the default templates, in this case~/.templates/TEMPLATE.java.tpl
.
Technical detail: documentation of variable
template-derivation-alist
.
Creating a Template
There are various predefined expansions which are probably enough for most templates. A corresponding expansion forms can be easily inserted by selecting the appropriate entry in the new submenu Template Creation:
-
Remember positions: use
(>>>POINT<<<)
to set point (the cursor position),(>>>MARK<<<)
to set mark (e.g., the opposite position when a region is highlighted), and(>>>1<<<)
to(>>>0<<<)
to registers to the current position. Remember that C-x r j Key jumps to the position stored in register Key. -
Insert parts of the file name, e.g., when creating the new file
~/proj/foo/abc1.java
:(>>>DIR<<<)
is replaced by /home/user/proj/foo/,(>>>FILE<<<)
by abc1.java,(>>>FILE_SANS<<<)
by abc1,(>>>FILE_UPCASE<<<)
by ABC1,(>>>FILE_RAW<<<)
by abc,(>>>FILE_NUM<<<)
by 1, and(>>>FILE_EXT<<<)
by java. -
Insert the current date/time in two customizable and three fixed formats: use
(>>>DATE<<<)
for 20 Feb 2002,(>>>TIME<<<)
for 20:01:13,(>>>YEAR<<<)
for 2002,(>>>ISO_DATE<<<)
for 2002-02-20, and(>>>VC_DATE<<<)
for 2002/02/20 19:01:13 -
Insert the user/system name in various formats: use
(>>>AUTHOR<<<)
for Christoph Wedler <wedler@fmi.uni-passau.de>,(>>>USER_NAME<<<)
for Christoph Wedler,(>>>LOGIN_NAME<<<)
for wedler, and(>>>HOST_ADDR<<<)
for fmi.uni-passau.de. - Ask the user for some initial comment. If this expansion is used, the buffer for the new file will be marked as modified. For each undefined expansion, the user is also asked.
-
Disabling the search for expansion forms:
(>>>ZERO_FORM<<<)
can be inserted into a string which will be otherwise regarded as an expansion form, the region between(>>>LITERAL<<<)
and the first(>>>/LITERAL<<<)
after it will be skipped.
You can define your own expansions in your Emacs init file and at the end of a template file. A corresponding definition can be easily inserted by selecting the appropriate entry in the new submenu Template Creation:
- Define User Input. Ask the user to insert some text using some specific prompt. Optionally, ask for a text with completion, or for a sequence of user input (exit with empty input).
- Define Text Register. Define a text for register Reg which can be inserted with C-x r i Reg. Optionally, provide a comment for it which will be temporarily shown at point.
- Define Message. Define a message which will be temporarily shown at point or before/after the expansion in a special buffer. There is also a computed message in the echo area.
- Execute some Lisp coding defined at the end of the template. By default, you have to confirm it first, since it is insecure to execute unchecked coding. (You do not have menu support to define this kind of expansion.)
Technical detail: documentation of variables
template-default-expansion-alist
and
template-definition-start
.
Decorating a Comment
There are commands to decorate comments with dashes and alike
(-
, =
and
#
by default). Both commands are included in the new
submenu Comments and bound to keys:
-
Use command
template-single-comment
to jump to the end of the current line and insert the dashes and the final comment end-string up-to the fill position. This command works with any comment style, including for languages having mixed comments like C++ and Java. It also works in major modes without a defined comment syntax. -
Use command
template-block-comment
to surround the current comment block (i.e., contiguous comment lines) with extra lines containing dashes and alike and to put the correct number of newlines around the block. This command only works with comments which are terminated with the end of the line (like Java's//
comment).
The comment decoration style is highly customizable and can be controlled by
- The prefix argument given to the two commands.
- The existing comment decoration style when present.
-
Determined by the indentation or the repetition of a single-character comment
start (like Emacs-Lisp's
;
).
Technical detail: documentation of commands
template-single-comment
and
template-block-comment
, and variable
template-comment-specification-alist
.
Updating a Buffer
A buffer is automatically updated according to some rules when saving the file. This updating can be invoked explicitly by selecting the menu entry Update Buffer in the new submenu Comments.
-
Update the file name in the first three lines of the buffer if the file name is
indicated by
@(#) FileName
or;;; FileName --
where;;;
stands for any comment start (with optional repetition of a single-character comment start). -
Update the date if it is the last text inside the
address
element of a HTML buffer. - Automatic updating is optional, as is user confirmation for it. Automatic updating can be disabled for buffers whose file name matches a regular expression.
- If nothing will be changed by the updating, there will be no user confirmation and the buffer will not be marked as modified.
Technical detail: documentation of command
template-update-buffer
, and variables
template-auto-update
,
template-update-buffer-alist
, and
template-header-regexp-alist
.