Debra Cameron - Learning GNU Emacs, 3rd Edition

If you find that most of the time when you ask for a library, you end up with a file containing a lot of cryptic numeric codes and no comments, check if the filename ends in .elc. If that is usually what you end up with, it means that only the byte-compiled versions of the libraries (see the discussion at the end of this chapter) have been installed on your system. Ask your system administrator if you can get the source installed; that's an important part of being able to learn and tweak the Emacs Lisp environment.

The functions re-search-forward, re-search-backward, replace-regexp, query-replace-regexp, highlight-regexp, isearch-forward-regexp, and isearch-backward-regexpare all user commands that use regular expressions, and they can all be used within Lisp code (though it is hard to imagine incremental search being used within Lisp code). The section on customizing major modes later in this chapter contains an example function that uses re-search-forward. To find other commands that use regexps you can use the "apropos" help feature ( C-h a regexp Enter).

Other such functions aren't available as user commands. Perhaps the most widely used one is looking-at. This function takes a regular expression argument and does the following: it returns tif the text after point matches the regular expression ( nilotherwise); if there was a match, it saves the pieces surrounded by \\(and \\)for future use, as seen earlier. The function string-matchis similar: it takes two arguments, a regexp and a string. It returns the starting index of the portion of the string that matches the regexp, or nilif there is no match.

The functions match-beginningand match-endcan be used to retrieve the saved portions of the matched string. Each takes as an argument the number of the matched expression (as in \\ n in replace-regexpreplace strings) and returns the character position in the buffer that marks the beginning (for match-beginning) or end (for match-end) of the matched string. With the argument 0, the character position that marks the beginning/end of the entire string matched by the regular expression is returned.

Two more functions are needed to make the above useful: we need to know how to convert the text in a buffer to a string. No problem: buffer-stringreturns the entire buffer as a string; buffer-substringtakes two integer arguments, marking the beginning and end positions of the substring desired, and returns the substring.

With these functions, we can write a bit of Lisp code that returns a string containing the portion of the buffer that matches the n th parenthesized subexpression:

(buffer-substring (match-beginning n (match-end n )))

In fact, this construct is used so often that Emacs has a built-in function, match-string, that acts as a shorthand; (match-string n )returns the same result as in the previous example.

An example should show how this capability works. Assume you are writing the Lisp code that parses compiler error messages, as in our previous example. Your code goes through each element in compilation-error-regexp-alist, checking if the text in a buffer matches the regular expression. If it matches, your code needs to extract the filename and the line number, visit the file, and go to the line number.

Although the code for going down each element in the list is beyond what we have learned so far, the routine basically looks like this:

for each element in compilation-error-regexp-alist

(let ((regexp the regexp in the element )

(file-subexp the number of the filename subexpression )

(line-subexp the number of the line number subexpression ))

(if (looking-at regexp)

(let ((filename (match-string file-subexp))

(linenum (match-string line-subexp)))

(find-file-other-window filename)

(goto-line linenum))

( otherwise, try the next element in the list )))

The second letextracts the filename from the buffer from the beginning to the end of the match to the file-subexp-th subexpression, and it extracts the line number similarly from the line-subexp-th subexpression (and converts it from a string to a number). Then the code visits the file (in another window, not the same one as the error message buffer) and goes to the line number where the error occurred.

The code for the calculator mode later in this chapter contains a few other examples of looking-at, match-beginning, and match-end.

Emacs contains hundreds of built-in functions that may be of use to you in writing Lisp code. Yet finding which one to use for a given purpose is not so hard.

The first thing to realize is that you will often need to use functions that are already accessible as keyboard commands. You can use these by finding out what their function names are via the C-h k(for describe-key) command (see Chapter 14 Chapter 14. The Help System Emacs has the most comprehensive help facility of any text editor—and one of the best such facilities of any program at all. In fact, the Emacs help facilities probably cut down the time it took for us to write this book by an order of magnitude, and they can help you immeasurably in your ongoing quest to learn more about Emacs. In this chapter, we describe Emacs help in the following areas: • The tutorial. • The help key ( C-h ) and Help menu, which allow you to get help on a wide variety of topics. • The help facilities of complex commands like query-replace and dired . • Navigating Emacs manuals and using the info documentation reader. • Completion , in which Emacs helps you finish typing names of functions, variables, filenames, and more. Completion not only saves you time and helps you complete names of functions you know about but can help you discover new commands and variables. ). This gives the command's full documentation, as opposed to C-h c(for describe-key-briefly), which gives only the command's name. Be careful: in a few cases, some common keyboard commands require an argument when used as Lisp functions. An example is forward-word; to get the equivalent of typing M-f, you have to use (forward-word 1).

Another powerful tool for getting the right function for the job is the command-apropos( C-h a) help function. Given a regular expression, this help function searches for all commands that match it and display their key bindings (if any) and documentation in a *Help*window. This can be a great help if you are trying to find a command that does a certain "basic" thing. For example, if you want to know about commands that operate on words, type C-h afollowed by word , and you will see documentation on about a dozen and a half commands having to do with words.

The limitation with command-aproposis that it gives information only on functions that can be used as keyboard commands. Even more powerful is apropos, which is not accessible via any of the help keys (you must type M-x apropos Enter). Given a regular expression, aproposdisplays all functions, variables, and other symbols that match it. Be warned, though: aproposcan take a long time to run and can generate very long lists if you use it with a general enough concept (such as buffer).