InfoMagic Source Code 1993 July

home *** CD-ROM | disk | FTP | other *** search

/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / gnu / elisp / elisp-35 < prev next >

Wrap

GNU Info File | 1993-05-11 | 49.0 KB | 947 lines

This is Info file elisp, produced by Makeinfo-1.52 from the input file elisp.texi. This file documents GNU Emacs Lisp. This is edition 2.0 of the GNU Emacs Lisp Reference Manual, for Emacs Version 19. Published by the Free Software Foundation, 675 Massachusetts Avenue, Cambridge, MA 02139 USA Copyright (C) 1990, 1991, 1992 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Foundation. File: elisp, Node: Sexp Diary Entries, Next: Appt Customizing, Prev: Including Diary Files, Up: Calendar Sexp Entries and the Fancy Diary Display ======================================== Sexp diary entries allow you to do more than just have complicated conditions under which a diary entry applies. If you use the fancy diary display, sexp entries can generate the text of the entry depending on the date itself. For example, the anniversary diary entry described above (*note Special Diary Entries::.) can insert the number of years since the anniversary date into the text of the diary entry. Thus the `%d' in the dairy entry %%(diary-anniversary 10 31 1948) Arthur's birthday (%d years old) gets replaced by the age, so on October 31, 1990 the entry appears in the fancy diary buffer as Arthur's birthday (42 years old) If the diary file instead contains the entry %%(diary-anniversary 10 31 1948) Arthur's %d%s birthday the entry in the fancy diary buffer for October 31, 1990 becomes Arthur's 42nd birthday Similarly, cyclic diary entries can interpolate the number of repetitions that have occurred: %%(diary-cyclic 50 1 1 1990) Renew medication (%d%s time) causes the diary entry Renew medication (5th time) to appear in the fancy diary display on September 8, 1990. The generality of sexp diary entries lets you specify any diary entry that you can describe algorithmically. Suppose you get paid on the 21st of the month if it is a weekday, and to the Friday before if the 21st is on a weekend. The diary entry &%%(let ((dayname (calendar-day-of-week date)) (day (car (cdr date)))) (or (and (= day 21) (memq dayname '(1 2 3 4 5))) (and (memq day '(19 20)) (= dayname 5))) ) Pay check deposited applies to just those dates. This example illustrates how the sexp can depend on the variable `date'; this variable is a list (MONTH DAY YEAR) that gives the Gregorian date for which the diary entries are being found. If the value of the expression is `t', the entry applies to that date. If the expression evaluates to `nil', the entry does *not* apply to that date. The following sexp diary entries take advantage of the ability (in the fancy diary display) to concoct diary entries based on the date: `%%(diary-sunrise-sunset)' Make a diary entry for the local times of today's sunrise and sunset. `%%(diary-phases-of-moon)' Make a diary entry for the phases (quarters) of the moon. `%%(diary-day-of-year)' Make a diary entry with today's day number in the current year and the number of days remaining in the current year. `%%(diary-iso-date)' Make a diary entry with today's equivalent ISO commercial date. `%%(diary-julian-date)' Make a diary entry with today's equivalent date on the Julian calendar. `%%(diary-astro-day-number)' Make a diary entry with today's equivalent astronomical (Julian) day number. `%%(diary-hebrew-date)' Make a diary entry with today's equivalent date on the Hebrew calendar. `%%(diary-islamic-date)' Make a diary entry with today's equivalent date on the Islamic calendar. `%%(diary-french-date)' Make a diary entry with today's equivalent date on the French Revolutionary calendar. `%%(diary-mayan-date)' Make a diary entry with today's equivalent date on the Mayan calendar. Thus including the diary entry &%%(diary-hebrew-date) causes every day's diary display to contain the equivalent date on the Hebrew calendar, if you are using the fancy diary display. (With simple diary display, the line `&%%(diary-hebrew-date)' appears in the diary for any date, but does nothing particularly useful.) There are a number of other available sexp diary entries that are important to those who follow the Hebrew calendar: `%%(diary-rosh-hodesh)' Make a diary entry that tells the occurrence and ritual announcement of each new Hebrew month. `%%(diary-parasha)' Make a Saturday diary entry that tells the weekly synagogue scripture reading. `%%(diary-sabbath-candles)' Make a Friday diary entry that tells the *local time* of Sabbath candle lighting. `%%(diary-omer)' Make a diary entry that gives the omer count, when appropriate. `%%(diary-yahrzeit MONTH DAY YEAR) NAME' Make a diary entry marking the anniversary of a date of death. The date is the *Gregorian* (civil) date of death. The diary entry appears on the proper Hebrew calendar anniversary and on the day before. (In the European style, the order of the parameters is changed to DAY, MONTH, YEAR.) File: elisp, Node: Appt Customizing, Prev: Sexp Diary Entries, Up: Calendar Customizing Appointment Reminders ================================= You can specify exactly how Emacs reminds you of an appointment and how far in advance it begins doing so. Here are the variables that you can set: `appt-message-warning-time' The time in minutes before an appointment that the reminder begins. The default is 10 minutes. `appt-audible' If this is `t' (the default), Emacs rings the terminal bell for appointment reminders. `appt-visible' If this is `t' (the default), Emacs displays the appointment message in echo area. `appt-display-mode-line' If this is `t' (the default), Emacs displays the number of minutes to the appointment on the mode line. `appt-msg-window' If this is `t' (the default), Emacs displays the appointment message in another window. `appt-display-duration' The number of seconds an appointment message is displayed. The default is 5 seconds. File: elisp, Node: Tips, Next: GNU Emacs Internals, Prev: Calendar, Up: Top Tips and Standards ****************** This chapter describes no additional features of Emacs Lisp. Instead it gives advice on making effective use of the features described in the previous chapters. * Menu: * Style Tips:: Writing clean and robust programs. * Compilation Tips:: Making compiled code run fast. * Documentation Tips:: Writing readable documentation strings. * Comment Tips:: Conventions for writing comments. * Library headers:: Standard headers for library packages. File: elisp, Node: Style Tips, Next: Compilation Tips, Prev: Tips, Up: Tips Writing Clean Lisp Programs =========================== Here are some tips for avoiding common errors in writing Lisp code intended for widespread use: * Since all global variables share the same name space, and all functions share another name space, you should choose a short word to distinguish your program from other Lisp programs. Then take care to begin the names of all global variables, constants, and functions with the chosen prefix. This helps avoid name conflicts. This recommendation applies even to names for traditional Lisp primitives that are not primitives in Emacs Lisp--even to `cadr'. Believe it or not, there is more than one plausible way to define `cadr'. Play it safe; append your name prefix to produce a name like `foo-cadr' or `mylib-cadr' instead. If one prefix is insufficient, your package may use two or three alternative common prefixes, so long as they make sense. Separate the prefix from the rest of the symbol name with a hyphen, `-'. This will be consistent with Emacs itself and with most Emacs Lisp programs. * It is often useful to put a call to `provide' in each separate library program, at least if there is more than one entry point to the program. * If one file FOO uses a macro defined in another file BAR, FOO should contain `(require 'BAR)' before the first use of the macro. (And BAR should contain `(provide 'BAR)', to make the `require' work.) This will cause BAR to be loaded when you byte-compile FOO. Otherwise, you risk compiling FOO without the necessary macro loaded, and that would produce compiled code that won't work right. *Note Compiling Macros::. * If you define a major mode, make sure to run a hook variable using `run-hooks', just as the existing major modes do. *Note Hooks::. * Please do not define `C-c LETTER' as a key in your major modes. These sequences are reserved for users; they are the *only* sequences reserved for users, so we cannot do without them. Instead, define sequences consisting of `C-c' followed by a non-letter. These sequences are reserved for major modes. Changing all the major modes in Emacs 18 so they would follow this convention was a lot of work. Abandoning this convention would waste that work and inconvenience the users. * It is a bad idea to define aliases for the Emacs primitives. Use the standard names instead. * Redefining an Emacs primitive is an even worse idea. It may do the right thing for a particular program, but there is no telling what other programs might break as a result. * If a file does replace any of the functions or library programs of standard Emacs, prominent comments at the beginning of the file should say which functions are replaced, and how the behavior of the replacements differs from that of the originals. * If a file requires certain standard library programs to be loaded beforehand, then the comments at the beginning of the file should say so. * Please keep the names of your Emacs Lisp source files to 13 characters or less. This way, if the files are compiled, the compiled files' names will be 14 characters or less, which is short enough to fit on all kinds of Unix systems. * Don't use `next-line' or `previous-line' in programs; nearly always, `forward-line' is more convenient as well as more predictable and robust. *Note Text Lines::. * Don't use functions that set the mark in your Lisp code (unless you are writing a command to set the mark). The mark is a user-level feature, so it is incorrect to change the mark except to supply a value for the user's benefit. *Note The Mark::. In particular, don't use these functions: * `beginning-of-buffer', `end-of-buffer' * `replace-string', `replace-regexp' If you just want to move point, or replace a certain string, without any of the other features intended for interactive users, you can replace these functions with one or two lines of simple Lisp code. * The recommended way to print a message in the echo area is with the `message' function, not `princ'. *Note The Echo Area::. * When you encounter an error condition, call the function `error' (or `signal'). The function `error' does not return. *Note Signaling Errors::. Do not use `message', `throw', `sleep-for', or `beep' to report errors. * Avoid using recursive edits. Instead, do what the Rmail `w' command does: use a new local keymap that contains one command defined to switch back to the old local keymap. Or do what the `edit-options' command does: switch to another buffer and let the user switch back at will. *Note Recursive Editing::. * In some other systems there is a convention of choosing variable names that begin and end with `*'. We don't use that convention in Emacs Lisp, so please don't use it in your library. (In fact, in Emacs names of this form are conventionally used for program-generated buffers.) The users will find Emacs more coherent if all libraries use the same conventions. * Indent each function with `C-M-q' (`indent-sexp') using the default indentation parameters. * Don't make a habit of putting close-parentheses on lines by themselves; Lisp programmers find this disconcerting. Once in a while, when there is a sequence of many consecutive close-parentheses, it may make sense to split them in one or two significant places. * Please put a copyright notice on the file if you give copies to anyone. Use the same lines that appear at the top of the Lisp files in Emacs itself. If you have not signed papers to assign the copyright to the Foundation, then place your name in the copyright notice in place of the Foundation's name. File: elisp, Node: Compilation Tips, Next: Documentation Tips, Prev: Style Tips, Up: Tips Tips for Making Compiled Code Fast ================================== Here are ways of improving the execution speed of byte-compiled lisp programs. * Use the `profile' library to profile your program. See the file `profile.el' for instructions. * Use iteration rather than recursion whenever possible. Function calls are slow in Emacs Lisp even when a compiled function is calling another compiled function. * Using the primitive list-searching functions `memq', `assq' or `assoc' is even faster than explicit iteration. It may be worth rearranging a data structure so that one of these primitive search functions can be used. * Certain built-in functions are handled specially by the byte compiler avoiding the need for an ordinary function call. It is a good idea to use these functions rather than alternatives. To see whether a function is handled specially by the compiler, examine its `byte-compile' property. If the property is non-`nil', then the function is handled specially. For example, the following input will show you that `aref' is compiled specially (*note Array Functions::.) while `elt' is not (*note Sequence Functions::.): (get 'aref 'byte-compile) => byte-compile-two-args (get 'elt 'byte-compile) => nil * Make small functions inline, so that calls to them in compiled code run faster. *Note Inline Functions::. File: elisp, Node: Documentation Tips, Next: Comment Tips, Prev: Compilation Tips, Up: Tips Tips for Documentation Strings ============================== Here are some tips for the writing of documentation strings. * Every command, function or variable intended for users to know about should have a documentation string. * An internal subroutine of a Lisp program need not have a documentation string, and you can save space by using a comment instead. * The first line of the documentation string should consist of one or two complete sentences which stand on their own as a summary. In particular, start the line with a capital letter and end with a period. The documentation string can have additional lines which expand on the details of how to use the function or variable. The additional lines should be made up of complete sentences also, but they may be filled if that looks good. * Do not start or end a documentation string with whitespace. * Format the documentation string so that it fits in an Emacs window on an 80 column screen. It is a good idea for most lines to be no wider than 60 characters. The first line can be wider if necessary to fit the information that ought to be there. However, rather than simply filling the entire documentation string, you can make it much more readable by choosing line breaks with care. Use blank lines between topics if the documentation string is long. * *Do not* indent subsequent lines of a documentation string so that the text is lined up in the source code with the text of the first line. This looks nice in the source code, but looks bizarre when users view the documentation. Remember that the indentation before the starting double-quote is not part of the string! * A variable's documentation string should start with `*' if the variable is one that users would want to set interactively often. If the value is a long list, or a function, or if the variable would only be set in init files, then don't start the documentation string with `*'. *Note Defining Variables::. * The documentation string for a variable that is a yes-or-no flag should start with words such as "Non-nil means...", to make it clear both that the variable only has two meaningfully distinct values and which value means "yes". * When a function's documentation string mentions the value of an argument of the function, use the argument name in capital letters as if it were a name for that value. Thus, the documentation string of the function `/' refers to its second argument as `DIVISOR'. Also use all caps for meta-syntactic variables, such as when you show the decomposition of a list or vector into subunits, some of which may be variable. * When a documentation string refers to a Lisp symbol, write it as it would be printed (which usually means in lower case), with single-quotes around it. For example: ``lambda''. There are two exceptions: write `t' and `nil' without single-quotes. * Don't write key sequences directly in documentation strings. Instead, use the `\\[...]' construct to stand for them. For example, instead of writing `C-f', write `\\[forward-char]'. When the documentation string is printed, Emacs will substitute whatever key is currently bound to `forward-char'. This will usually be `C-f', but if the user has moved key bindings, it will be the correct key for that user. *Note Keys in Documentation::. * In documentation strings for a major mode, you will want to refer to the key bindings of that mode's local map, rather than global ones. Therefore, use the construct `\\<...>' once in the documentation string to specify which key map to use. Do this before the first use of `\\[...]'. The text inside the `\\<...>' should be the name of the variable containing the local keymap for the major mode. It is not practical to use `\\[...]' very many times, because display of the documentation string will become slow. So use this to describe the most important commands in your major mode, and then use `\\{...}' to display the rest of the mode's keymap. * Don't use the term "Elisp", since that is or was a trademark. Use the term "Emacs Lisp". File: elisp, Node: Comment Tips, Next: Library Headers, Prev: Documentation Tips, Up: Tips Tips on Writing Comments ======================== We recommend these conventions for where to put comments and how to indent them: `;' Comments that start with a single semicolon, `;', should all be aligned to the same column on the right of the source code. Such comments usually explain how the code on the same line does its job. In Lisp mode and related modes, the `M-;' (`indent-for-comment') command automatically inserts such a `;' in the right place, or aligns such a comment if it is already inserted. (The following examples are taken from the Emacs sources.) (setq base-version-list ; there was a base (assoc (substring fn 0 start-vn) ; version to which file-version-assoc-list)) ; this looks like ; a subversion `;;' Comments that start with two semicolons, `;;', should be aligned to the same level of indentation as the code. Such comments are used to describe the purpose of the following lines or the state of the program at that point. For example: (prog1 (setq auto-fill-function ... ... ;; update mode-line (force-mode-line-update))) These comments are also written before a function definition to explain what the function does and how to call it properly. `;;;' Comments that start with three semicolons, `;;;', should start at the left margin. Such comments are not used within function definitions, but are used to make more general comments. For example: ;;; This Lisp code is run in Emacs ;;; when it is to operate asa server ;;; for other processes. `;;;;' Comments that start with four semicolons, `;;;;', should be aligned to the left margin and are used for headings of major sections of a program. For example: ;;;; The kill ring The indentation commands of the Lisp modes in Emacs, such as `M-;' (`indent-for-comment') and TAB (`lisp-indent-line') automatically indent comments according to these conventions, depending on the the number of semicolons. *Note Manipulating Comments: (emacs)Comments. If you wish to "comment out" a number of lines of code, use triple semicolons at the beginnings of the lines. Any character may be included in a comment, but it is advisable to precede a character with syntactic significance in Lisp (such as `\' or unpaired `(' or `)') with a `\', to prevent it from confusing the Emacs commands for editing Lisp. File: elisp, Node: Library Headers, Prev: Comment Tips, Up: Tips Conventional Headers for Emacs Library Packages =============================================== There are some standard identication headers used in Emacs 19 library packages to assist the help system, track authors and versions for maintainence purposes, and enable the generation of various kinds of databases and documentation. This section explains them and why you should try to use the same conventions in your packages, especially if you want to submit them to FSF. Here's the head of a file written using the library conventions: ;;; lisp-mnt.el --- minor mode for Emacs Lisp maintainers ;; Copyright (C) 1992 Free Software Foundation, Inc. ;; Author: Eric S. Raymond <esr ;; Maintainer: Eric S. Raymond <esr ;; Created: 14 Jul 1992 ;; Version: 1.2 ;; Keywords: docs ;; Bogus-Bureaucratic-Cruft: Gruad will get you if you don't watch out! ;; This file is part of GNU Emacs. Here are the new features: *Header line* -- makes it possible to extract a one-line summary of the package's uses automatically for use in library synopses, KWIC indexes and the like. Format is three semicolons, followed by the filename, followed by three dashes, followed by the summary. All fields space-separated. *Author line* -- contains the name and net address of at least the principal author. If there are multiple authors, they should be listed on continuation lines led by `;;<TAB>', like this: ;; Author: Ashwin Ram <Ram-Ashwin ;; Dave Sill <de5 ;; David Lawrence <tale ;; Noah Friedman <friedman ;; Joe Wells <jbw ;; Dave Brennan <brennan ;; Eric Raymond <esr This field may have some special values; notably "FSF", meaning "Free Software Foundation". *Maintainer line* -- should be a single name/address as in the Author line, or an address only, or the string "FSF". If there is no maintainer line, the person(s) in the Author field are presumed to be it. The example in this file is mildly bogus because the maintainer line is redundant. The idea behind these two fields is to be able to write a lisp function that does "send mail to the author" without having to mine the name out by hand. Please be careful about surrounding the network address with <> if there's also a name in the field. *Created line* -- optional, gives the original creation date of the file. For historical interest, basically. *Version line* -- intended to give the reader a clue if they're looking at a different version of the file than the one they're accustomed to. Not needed if you have an RCS or SCCS header. *Adapted-By line* -- this is for FSF's internal use. The person named in this field was the one responsible for installing and adapting the package for the distribution. (This file doesn't have one because the author *is* one of the maintainers.) *Keywords line* -- used by the package-finder code for finding elisp code related to a topic. This field is important; it's how people will find your package when they're looking forthings by topic area. *Bogus-Bureaucratic-Cruft line* -- this is a joke. We figured we should satirize this design before someone else did. Also, it illustrates the possibility that other headers may be added in the future for new purposes. There are a few other stylized comments all the distribution files comtain. These are: *Commentary line* -- optional, enables lisp code to find the developer's and maintainers' explanations of the package internals. It looks like this: smallexample ;;; Commentary: smallexample and should be located after the GNU copyright but before the package's header comments (if any). *Change log line* -- optional, exists to terminate the commentary section and start a change-log part, if one exists. It looks like this: smallexample ;;; Change Log: smallexample *Code line* -- exists so lisp can know where the commentary and/or change-log sections end. It looks like this: smallexample ;;; Code: smallexample *Footer line* -- marks end-of-file so it can be distinguished from an expanded formfeed or the results of truncation. This must be the *last* line in the file. Example: smallexample ;;; lisp-mnt.el ends here smallexample The mode used as an example actually exists and can actually be used to generate these headers semi-automatically. It provides functions which lisp programs can use to etract various useful pieces of information from these headers.