Previous | Table of Contents | Next |
This section describes an example of a function definition that is not interactive; it comes from the source code for GNU Emacs version 19.34. You can find the function in the file texnfo-upd.el. (In Emacs you can use the find-tag command to find the source of a function.)
This file provides various tools for creating and updating menus and nodes in a Texinfo file. Texinfo is a markup language used for writing documentation. Manuals written in Texinfo can be converted to HTML and read using a Web browser, converted to Info and read online using one of the Info readers, or printed as a typeset book. The original version of this chapter was written in Texinfo.
The texnfo-upd.el file provides updating commands. One of the necessary actions an updating command must do is locate the beginning of a node, that is, the beginning of a particular stretch of text.
In the texinfo-menu-first-node definition shown next, the Lisp interpreter works within a region of text specified by another function in the same file. Within the region, the texinfo-menu-first-node definition uses a regular expression search, which is a kind of search that looks for a particular pattern.
In this example, I first show the whole definition, as it appears in the Emacs sources, then I describe what each part does:
(defun texinfo-menu-first-node (beginning end) Locate first node of the section the menu will be placed in. Return position; do not move point. The menu will be located just before this position. First argument is the position of the beginning of the section in which the menu will be located; second argument is the position of the end of that region; it limits the search. (save-excursion (goto-char beginning) (forward-line 1) (re-search-forward ^@node end t) (beginning-of-line) (point)))
The first line contains the symbol defun, which tells the Lisp interpreter that this is a function definition. Next comes the name for this definition. The name is quite long and self-explanatory. Like all other definitions involving Texinfo, it starts with texinfo; this is so neither you nor the computer confuse this definition with another definition for some other markup language.
After the name comes the argument list. This definition has two arguments, which use the somewhat self-explanatory words beginning and endthese words become self-explanatory when you learn that in this sort of programming, they customarily refer to the beginning and end of a region of text.
The following few lines are the definitions documentation. If you use the apropos command on a regular expression that matches the name, you will see the first line of the documentation. If you investigate the definition using C-h f (describe-function), you will see the functions full documentation.
This function definition has no interactive line because the function will be called by other functions, not interactively by a user.
Finally, the last part of the definition is the body, which is the code that does the job. I will repeat it here for your convenience:
(save-excursion (goto-char beginning) (forward-line 1) (re-search-forward ^@node end t) (beginning-of-line) (point)))
The body starts with a parenthesis and a symbolthe body is a list. The first element of the list is a function that is carried out. save-excursion saves point, mark, and the current buffer and then evaluates the arguments to save-excursion. After the evaluations, save-excursion restores point, mark, and the current buffer.
Point is the location at which editing commands take effect and is the location of the cursor. Mark is another location; the text between point and mark is called the region, and many editing commands operate on such a region. The current buffer is where you are working. Emacs does not work on a file directly, but on a copy of it, called a buffer.
In brief, save-excursion makes sure Emacs does not change its focal point, even when it moves away temporarily.
The first thing Emacs does after save-excursion is
(goto-char beginning)
This means that Emacs moves point, temporarily, to the location recorded by beginning; it goes to that character.
The next line is another list:
(forward-line 1)
This moves point forward one line and stops at the beginning of this next line. One consequence of this is that if the location indicated by beginning is in the middle of a line, point ends up at the beginning rather than the middle of the next line.
This forward-line command also means that the very first line to which point moves is not searched. It is not evident here, or even mentioned in the documentation, that the first node, which is what this function is searching for, is not on the first line of the section. Indeed, the first line often is the beginning of the preceding stretch of text, which is not the one that is wanted. Perhaps the documentation should be clearer, or perhaps it is clear enough if you read the source.
Regardless of the quality of the documentation, (forward-line 1) means to move forward one line.
The next line of code is
(re-search-forward ^@node end t)
This tells the computer to undertake a regular expression search for the string of letters spelling @node that start at the beginning of a line, to ignore @node elsewhere in a line, and to extend the search no farther than the location recorded by end. (In Texinfo, @node marks the beginning of a particular type of stretch of text. For information on regular expression searches, see the section Regular Expression Search in The GNU Emacs Manual.)
The last two lines in the body are
(beginning-of-line) (point)
Having found @node, (beginning-of-line) says to move point to the beginning of the line and (point) says to return that location. Finally, after returning the location of the beginning of the line containing @node, save-excursion causes Emacs to restore point to where it was.
Once you become accustomed to Emacs Lisp, it is much easier to read code such as this than to read a long-winded description of what it means. The purpose here has been to introduce you to a number of ideas, as well as to the basic outline of a simple function definition.
Previous | Table of Contents | Next |