Debra Cameron - Learning GNU Emacs, 3rd Edition

You should be able to use the aproposcommands on a small number of well-chosen keywords and find the function(s) you need. Because, if a function seems general and basic enough, the chances are excellent that Emacs has it built-in.

After you find the function you are interested in, you may find that the documentation that aproposprints does not give you enough information about what the function does, its arguments, how to use it, or whatever. The best thing to do at this point is to search Emacs's Lisp source code for examples of the function's use. "A Treasure Trove of Examples" earlier in this chapter provides ways of finding out the names of directories Emacs loads libraries from and an easy way of looking at a library once you know its name. To search the contents of the library files you'll need to use grep or some other search facility to find examples, then edit the files found to look at the surrounding context. If you're ambitious you could put together the examples and concepts we've discussed so far to write an extension of the find-library-filecommand that searches the contents of the library files in each directory on the load path! Although most of Emacs's built-in Lisp code is not profusely documented, the examples of function use that it provides should be helpful—and may even give you ideas for your own functions.

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-bufferand 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.

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-hookallows us to run code when the user uses find-fileto 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-3causes 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 packagestatement has been inferred by examining the directory path in which the source file is being created. The Loggerdeclaration 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.