By now, you should have a framework of Emacs Lisp that should be sufficient for writing many useful Emacs commands. We have covered examples of various kinds of functions, both Lisp primitives and built-in Emacs functions. You should be able to extrapolate many others from the ones given in this chapter along with help techniques such as those just provided. In other words, you are well on your way to becoming a fluent Emacs Lisp programmer. To test yourself, start with the code for count-words-buffer and try writing the following functions:
count-lines-buffer
Print the number of lines in the buffer.
count-words-region
Print the number of words in a region.
what-line
Print the number of the line point is currently on.
11.4 Building an Automatic Template System
You're probably starting to see how all these tools can be put together in really powerful ways. Most of the rest of the chapter consists of examples of building relatively real and useful new features for Emacs. You can use them as learning tools for how to build your own, and you may be able to use them as-is, or with a little tweaking, in your own daily work.
The example we're about to look at is something that one of the authors developed over a decade ago to help with the tedium of creating new files in development projects where a certain amount of structure and standard documentation were always needed. Many coding and writing projects have this characteristic; each file needs some boilerplate, but it needs to be adjusted to the details of the file. Emacs turned out to be very much up to the task of automating a lot of the drudge work, and this template system has been heavily used ever since.
Most of the code in this example should already make sense to you. A couple of aspects that will be explained more thoroughly in the next section about programming a major mode. In particular, don't worry too much yet about exactly what a "hook" function is, or funcall. For now it's sufficient to know that the file-not-found-hook allows us to run code when the user uses find-file to open a file that doesn't exist yet (exactly the time at which we'd like to offer our template services).
Before launching into the code, it's worth looking at an example of it in action. You'd set up your template by creating a file named file-template-java at the top level of a Java project directory hierarchy, containing something like the code shown in Example 11-2.
Example 11-2. file-template-java
/* %filename%
* Created on %date%
*
* (c) 2004 MyCorp, etc. etc.
*/
%package%
import org.apache.log4j.Logger;
/**
* [Documentation Here!]
*
* @author %author%
* @version $Id: ch11.xml,v 1.4 2004/12/17 16:10:05 kend Exp $
*
**/
public class %class% {
/**
* Provides access to the CVS version of this class.
**/
public static final String VERSION =
"$Id: ch11.xml,v 1.4 2004/12/17 16:10:05 kend Exp $";
/**
* Provides hierarchical control and configuration of debugging via
* class package structure.
**/
private static Logger log =
Logger.getLogger(%class%.class);
}
The template system shown in Example 11-3 causes an attempt to find a nonexistent Java source file within this project hierarchy (for example, via C-x C-f src/com/mycorp/util/FooManager.java) to result in the prompt Start with template file? (y or n) in the minibuffer, and if you answer y, you'll see your FooManager.java buffer start out with contents in the following example.
Example 11-3. FooManager.java
/* FooManager.java
* Created on Sun Nov 9 20:56:12 2003
*
* (c) 2004 MyCorp, etc. etc.
*/
package com.mycorp.util;
import org.apache.log4j.Logger;
/**
* [Documentation Here!]
*
* @author Jim Elliott
* @version $Id: ch11.xml,v 1.4 2004/12/17 16:10:05 kend Exp $
*
**/
public class FooManager {
/**
* Provides access to the CVS version of this class.
**/
public static final String VERSION =
"$Id: ch11.xml,v 1.4 2004/12/17 16:10:05 kend Exp $";
/**
* Provides hierarchical control and configuration of debugging via
* class package structure.
**/
private static Logger log =
Logger.getLogger(FooManager.class);
}
The template has been used to populate the buffer with the standard project header comments and a basic Java class skeleton, with proper contextual values filled in (such as the current time, the person creating the file, the file and class name, and so on). Even the Java package statement has been inferred by examining the directory path in which the source file is being created. The Logger declaration will look familiar to anyone who uses the excellent log4j system to add logging and debugging to their Java projects. (The strange version numbers in "$Id" strings are managed by the CVS version control system and will be updated to the proper file and version information when it's checked in. This topic is discussed in Chapter 12.)
To make this work, the template system needs to be able to do a couple of things:
• Intercept the user's attempt to find a nonexistent file.
• Check whether there is an appropriate template file somewhere in a parent directory.
• If so, offer to use it, and populate the buffer with the contents of the template file.
• Scan the template file for special placeholders (such as %filename%) and replace them with information about the file being created.
Let's look at the source code that makes this all happen! (As always, if you don't want to type the code listed in Example 11-4 yourself, you can download it from this book's web site.[79])
Example 11-4. template.el
;;;;;;;;;;;;;;;;;;;;;;;;;;; -*- Mode: Emacs-Lisp -*- ;;;;;;;;;;;;;;;;;;;;;;;;
;; template.el --- Routines for generating smart skeletal templates for files.
79
The version presented in this example is simplified for reasons of space and clarity. The full version, which adds the ability to insert templates for function definitions and process arbitrary Emacs Lisp functions within template files, is also available for download.