1 This is ../info/lispref.info, produced by makeinfo version 4.0 from
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Hooks, Prev: Modeline Format, Up: Modes
58 A "hook" is a variable where you can store a function or functions
59 to be called on a particular occasion by an existing program. XEmacs
60 provides hooks for the sake of customization. Most often, hooks are set
61 up in the `.emacs' file, but Lisp programs can set them also. *Note
62 Standard Hooks::, for a list of standard hook variables.
64 Most of the hooks in XEmacs are "normal hooks". These variables
65 contain lists of functions to be called with no arguments. The reason
66 most hooks are normal hooks is so that you can use them in a uniform
67 way. You can usually tell when a hook is a normal hook, because its
70 The recommended way to add a hook function to a normal hook is by
71 calling `add-hook' (see below). The hook functions may be any of the
72 valid kinds of functions that `funcall' accepts (*note What Is a
73 Function::). Most normal hook variables are initially void; `add-hook'
74 knows how to deal with this.
76 As for abnormal hooks, those whose names end in `-function' have a
77 value that is a single function. Those whose names end in `-hooks'
78 have a value that is a list of functions. Any hook that is abnormal is
79 abnormal because a normal hook won't do the job; either the functions
80 are called with arguments, or their values are meaningful. The name
81 shows you that the hook is abnormal and that you should look at its
82 documentation string to see how to use it properly.
84 Major mode functions are supposed to run a hook called the "mode
85 hook" as the last step of initialization. This makes it easy for a user
86 to customize the behavior of the mode, by overriding the local variable
87 assignments already made by the mode. But hooks are used in other
88 contexts too. For example, the hook `suspend-hook' runs just before
89 XEmacs suspends itself (*note Suspending XEmacs::).
91 Here's an expression that uses a mode hook to turn on Auto Fill mode
92 when in Lisp Interaction mode:
94 (add-hook 'lisp-interaction-mode-hook 'turn-on-auto-fill)
96 The next example shows how to use a hook to customize the way XEmacs
97 formats C code. (People often have strong personal preferences for one
98 format or another.) Here the hook function is an anonymous lambda
101 (add-hook 'c-mode-hook
103 (setq c-indent-level 4
106 c-continued-statement-indent 0
108 comment-column 40))))
110 (setq c++-mode-hook c-mode-hook)
112 The final example shows how the appearance of the modeline can be
113 modified for a particular class of buffers only.
115 (add-hook 'text-mode-hook
117 (setq modeline-format
133 At the appropriate time, XEmacs uses the `run-hooks' function to run
134 particular hooks. This function calls the hook functions you have
135 added with `add-hooks'.
137 - Function: run-hooks &rest hookvar
138 This function takes one or more hook variable names as arguments,
139 and runs each hook in turn. Each HOOKVAR argument should be a
140 symbol that is a hook variable. These arguments are processed in
143 If a hook variable has a non-`nil' value, that value may be a
144 function or a list of functions. If the value is a function
145 (either a lambda expression or a symbol with a function
146 definition), it is called. If it is a list, the elements are
147 called, in order. The hook functions are called with no arguments.
149 For example, here's how `emacs-lisp-mode' runs its mode hook:
151 (run-hooks 'emacs-lisp-mode-hook)
153 - Function: add-hook hook function &optional append local
154 This function is the handy way to add function FUNCTION to hook
155 variable HOOK. The argument FUNCTION may be any valid Lisp
156 function with the proper number of arguments. For example,
158 (add-hook 'text-mode-hook 'my-text-hook-function)
160 adds `my-text-hook-function' to the hook called `text-mode-hook'.
162 You can use `add-hook' for abnormal hooks as well as for normal
165 It is best to design your hook functions so that the order in
166 which they are executed does not matter. Any dependence on the
167 order is "asking for trouble." However, the order is predictable:
168 normally, FUNCTION goes at the front of the hook list, so it will
169 be executed first (barring another `add-hook' call).
171 If the optional argument APPEND is non-`nil', the new hook
172 function goes at the end of the hook list and will be executed
175 If LOCAL is non-`nil', that says to make the new hook function
176 local to the current buffer. Before you can do this, you must
177 make the hook itself buffer-local by calling `make-local-hook'
178 (*not* `make-local-variable'). If the hook itself is not
179 buffer-local, then the value of LOCAL makes no difference--the
180 hook function is always global.
182 - Function: remove-hook hook function &optional local
183 This function removes FUNCTION from the hook variable HOOK.
185 If LOCAL is non-`nil', that says to remove FUNCTION from the local
186 hook list instead of from the global hook list. If the hook
187 itself is not buffer-local, then the value of LOCAL makes no
190 - Function: make-local-hook hook
191 This function makes the hook variable `hook' local to the current
192 buffer. When a hook variable is local, it can have local and
193 global hook functions, and `run-hooks' runs all of them.
195 This function works by making `t' an element of the buffer-local
196 value. That serves as a flag to use the hook functions in the
197 default value of the hook variable as well as those in the local
198 value. Since `run-hooks' understands this flag, `make-local-hook'
199 works with all normal hooks. It works for only some non-normal
200 hooks--those whose callers have been updated to understand this
203 Do not use `make-local-variable' directly for hook variables; it is
207 File: lispref.info, Node: Documentation, Next: Files, Prev: Modes, Up: Top
212 XEmacs Lisp has convenient on-line help facilities, most of which
213 derive their information from the documentation strings associated with
214 functions and variables. This chapter describes how to write good
215 documentation strings for your Lisp programs, as well as how to write
216 programs to access documentation.
218 Note that the documentation strings for XEmacs are not the same thing
219 as the XEmacs manual. Manuals have their own source files, written in
220 the Texinfo language; documentation strings are specified in the
221 definitions of the functions and variables they apply to. A collection
222 of documentation strings is not sufficient as a manual because a good
223 manual is not organized in that fashion; it is organized in terms of
224 topics of discussion.
228 * Documentation Basics:: Good style for doc strings.
229 Where to put them. How XEmacs stores them.
230 * Accessing Documentation:: How Lisp programs can access doc strings.
231 * Keys in Documentation:: Substituting current key bindings.
232 * Describing Characters:: Making printable descriptions of
233 non-printing characters and key sequences.
234 * Help Functions:: Subroutines used by XEmacs help facilities.
235 * Obsoleteness:: Upgrading Lisp functionality over time.
238 File: lispref.info, Node: Documentation Basics, Next: Accessing Documentation, Up: Documentation
243 A documentation string is written using the Lisp syntax for strings,
244 with double-quote characters surrounding the text of the string. This
245 is because it really is a Lisp string object. The string serves as
246 documentation when it is written in the proper place in the definition
247 of a function or variable. In a function definition, the documentation
248 string follows the argument list. In a variable definition, the
249 documentation string follows the initial value of the variable.
251 When you write a documentation string, make the first line a complete
252 sentence (or two complete sentences) since some commands, such as
253 `apropos', show only the first line of a multi-line documentation
254 string. Also, you should not indent the second line of a documentation
255 string, if you have one, because that looks odd when you use `C-h f'
256 (`describe-function') or `C-h v' (`describe-variable'). *Note
257 Documentation Tips::.
259 Documentation strings may contain several special substrings, which
260 stand for key bindings to be looked up in the current keymaps when the
261 documentation is displayed. This allows documentation strings to refer
262 to the keys for related commands and be accurate even when a user
263 rearranges the key bindings. (*Note Accessing Documentation::.)
265 Within the Lisp world, a documentation string is accessible through
266 the function or variable that it describes:
268 * The documentation for a function is stored in the function
269 definition itself (*note Lambda Expressions::). The function
270 `documentation' knows how to extract it.
272 * The documentation for a variable is stored in the variable's
273 property list under the property name `variable-documentation'.
274 The function `documentation-property' knows how to extract it.
276 To save space, the documentation for preloaded functions and
277 variables (including primitive functions and autoloaded functions) is
278 stored in the "internal doc file" `DOC'. The documentation for
279 functions and variables loaded during the XEmacs session from
280 byte-compiled files is stored in those very same byte-compiled files
281 (*note Docs and Compilation::).
283 XEmacs does not keep documentation strings in memory unless
284 necessary. Instead, XEmacs maintains, for preloaded symbols, an
285 integer offset into the internal doc file, and for symbols loaded from
286 byte-compiled files, a list containing the filename of the
287 byte-compiled file and an integer offset, in place of the documentation
288 string. The functions `documentation' and `documentation-property' use
289 that information to read the documentation from the appropriate file;
290 this is transparent to the user.
292 For information on the uses of documentation strings, see *Note
295 The `emacs/lib-src' directory contains two utilities that you can
296 use to print nice-looking hardcopy for the file
297 `emacs/etc/DOC-VERSION'. These are `sorted-doc.c' and `digest-doc.c'.
300 File: lispref.info, Node: Accessing Documentation, Next: Keys in Documentation, Prev: Documentation Basics, Up: Documentation
302 Access to Documentation Strings
303 ===============================
305 - Function: documentation-property symbol property &optional verbatim
306 This function returns the documentation string that is recorded in
307 SYMBOL's property list under property PROPERTY. It retrieves the
308 text from a file if necessary, and runs `substitute-command-keys'
309 to substitute actual key bindings. (This substitution is not done
310 if VERBATIM is non-`nil'; the VERBATIM argument exists only as of
313 (documentation-property 'command-line-processed
314 'variable-documentation)
315 => "t once command line has been processed"
316 (symbol-plist 'command-line-processed)
317 => (variable-documentation 188902)
319 - Function: documentation function &optional verbatim
320 This function returns the documentation string of FUNCTION. It
321 reads the text from a file if necessary. Then (unless VERBATIM is
322 non-`nil') it calls `substitute-command-keys', to return a value
323 containing the actual (current) key bindings.
325 The function `documentation' signals a `void-function' error if
326 FUNCTION has no function definition. However, it is ok if the
327 function definition has no documentation string. In that case,
328 `documentation' returns `nil'.
330 Here is an example of using the two functions, `documentation' and
331 `documentation-property', to display the documentation strings for
332 several symbols in a `*Help*' buffer.
334 (defun describe-symbols (pattern)
335 "Describe the XEmacs Lisp symbols matching PATTERN.
336 All symbols that have PATTERN in their name are described
337 in the `*Help*' buffer."
338 (interactive "sDescribe symbols matching: ")
342 ;; Print description of symbol.
343 (if (fboundp s) ; It is a function.
345 (format "%s\t%s\n%s\n\n" s
347 (let ((keys (where-is-internal s)))
351 (mapconcat 'key-description
355 (or (documentation s)
358 (if (boundp s) ; It is a variable.
360 (format "%s\t%s\n%s\n\n" s
361 (if (user-variable-p s)
362 "Option " "Variable")
363 (or (documentation-property
364 s 'variable-documentation)
365 "not documented")))))))
368 ;; Build a list of symbols that match pattern.
371 (if (string-match pattern (symbol-name sym))
372 (setq sym-list (cons sym sym-list))))))
375 (with-output-to-temp-buffer "*Help*"
376 (mapcar describe-func (sort sym-list 'string<))
377 (print-help-return-message))))
379 The `describe-symbols' function works like `apropos', but provides
382 (describe-symbols "goal")
384 ---------- Buffer: *Help* ----------
386 *Semipermanent goal column for vertical motion, as set by C-x C-n, or nil.
388 set-goal-column Command: C-x C-n
389 Set the current horizontal position as a goal for C-n and C-p.
390 Those commands will move to this position in the line moved to
391 rather than trying to keep the same horizontal position.
392 With a non-nil argument, clears out the goal column
393 so that C-n and C-p resume vertical motion.
394 The goal column is stored in the variable `goal-column'.
396 temporary-goal-column Variable
397 Current goal column for vertical motion.
398 It is the column where point was
399 at the start of current run of vertical motion commands.
400 When the `track-eol' feature is doing its job, the value is 9999.
401 ---------- Buffer: *Help* ----------
403 - Function: Snarf-documentation filename
404 This function is used only during XEmacs initialization, just
405 before the runnable XEmacs is dumped. It finds the file offsets
406 of the documentation strings stored in the file FILENAME, and
407 records them in the in-core function definitions and variable
408 property lists in place of the actual strings. *Note Building
411 XEmacs finds the file FILENAME in the `lib-src' directory. When
412 the dumped XEmacs is later executed, the same file is found in the
413 directory `doc-directory'. The usual value for FILENAME is `DOC',
414 but this can be changed by modifying the variable
415 `internal-doc-file-name'.
417 - Variable: internal-doc-file-name
418 This variable holds the name of the file containing documentation
419 strings of built-in symbols, usually `DOC'. The full pathname of
420 the internal doc file is `(concat doc-directory
421 internal-doc-file-name)'.
423 - Variable: doc-directory
424 This variable holds the name of the directory which contains the
425 "internal doc file" that contains documentation strings for
426 built-in and preloaded functions and variables.
428 In most cases, this is the same as `exec-directory'. They may be
429 different when you run XEmacs from the directory where you built
430 it, without actually installing it. See `exec-directory' in *Note
433 In older Emacs versions, `exec-directory' was used for this.
435 - Variable: data-directory
436 This variable holds the name of the directory in which XEmacs finds
437 certain system independent documentation and text files that come
438 with XEmacs. In older Emacs versions, `exec-directory' was used
442 File: lispref.info, Node: Keys in Documentation, Next: Describing Characters, Prev: Accessing Documentation, Up: Documentation
444 Substituting Key Bindings in Documentation
445 ==========================================
447 When documentation strings refer to key sequences, they should use
448 the current, actual key bindings. They can do so using certain special
449 text sequences described below. Accessing documentation strings in the
450 usual way substitutes current key binding information for these special
451 sequences. This works by calling `substitute-command-keys'. You can
452 also call that function yourself.
454 Here is a list of the special sequences and what they mean:
457 stands for a key sequence that will invoke COMMAND, or `M-x
458 COMMAND' if COMMAND has no key bindings.
461 stands for a summary of the value of MAPVAR, which should be a
462 keymap. The summary is made by `describe-bindings'.
465 stands for no text itself. It is used for a side effect: it
466 specifies MAPVAR as the keymap for any following `\[COMMAND]'
467 sequences in this documentation string.
470 quotes the following character and is discarded; this `\=\=' puts
471 `\=' into the output, and `\=\[' puts `\[' into the output.
473 *Please note:* Each `\' must be doubled when written in a string in
476 - Function: substitute-command-keys string
477 This function scans STRING for the above special sequences and
478 replaces them by what they stand for, returning the result as a
479 string. This permits display of documentation that refers
480 accurately to the user's own customized key bindings.
482 Here are examples of the special sequences:
484 (substitute-command-keys
485 "To abort recursive edit, type: \\[abort-recursive-edit]")
486 => "To abort recursive edit, type: C-]"
488 (substitute-command-keys
489 "The keys that are defined for the minibuffer here are:
490 \\{minibuffer-local-must-match-map}")
491 => "The keys that are defined for the minibuffer here are:
493 ? minibuffer-completion-help
494 SPC minibuffer-complete-word
495 TAB minibuffer-complete
496 LFD minibuffer-complete-and-exit
497 RET minibuffer-complete-and-exit
498 C-g abort-recursive-edit
501 (substitute-command-keys
502 "To abort a recursive edit from the minibuffer, type\
503 \\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
504 => "To abort a recursive edit from the minibuffer, type C-g."
506 (substitute-command-keys
507 "Substrings of the form \\=\\{MAPVAR} are replaced by summaries
508 \(made by describe-bindings) of the value of MAPVAR, taken as a keymap.
509 Substrings of the form \\=\\<MAPVAR> specify to use the value of MAPVAR
510 as the keymap for future \\=\\[COMMAND] substrings.
511 \\=\\= quotes the following character and is discarded;
512 thus, \\=\\=\\=\\= puts \\=\\= into the output,
513 and \\=\\=\\=\\[ puts \\=\\[ into the output.")
514 => "Substrings of the form \{MAPVAR} are replaced by summaries
515 (made by describe-bindings) of the value of MAPVAR, taken as a keymap.
516 Substrings of the form \<MAPVAR> specify to use the value of MAPVAR
517 as the keymap for future \[COMMAND] substrings.
518 \= quotes the following character and is discarded;
519 thus, \=\= puts \= into the output,
520 and \=\[ puts \[ into the output."
523 File: lispref.info, Node: Describing Characters, Next: Help Functions, Prev: Keys in Documentation, Up: Documentation
525 Describing Characters for Help Messages
526 =======================================
528 These functions convert events, key sequences or characters to
529 textual descriptions. These descriptions are useful for including
530 arbitrary text characters or key sequences in messages, because they
531 convert non-printing and whitespace characters to sequences of printing
532 characters. The description of a non-whitespace printing character is
533 the character itself.
535 - Function: key-description sequence
536 This function returns a string containing the XEmacs standard
537 notation for the input events in SEQUENCE. The argument SEQUENCE
538 may be a string, vector or list. *Note Events::, for more
539 information about valid events. See also the examples for
540 `single-key-description', below.
542 - Function: single-key-description key
543 This function returns a string describing KEY in the standard
544 XEmacs notation for keyboard input. A normal printing character
545 appears as itself, but a control character turns into a string
546 starting with `C-', a meta character turns into a string starting
547 with `M-', and space, linefeed, etc. appear as `SPC', `LFD', etc.
548 A symbol appears as the name of the symbol. An event that is a
549 list appears as the name of the symbol in the CAR of the list.
551 (single-key-description ?\C-x)
553 (key-description "\C-x \M-y \n \t \r \f123")
554 => "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
555 (single-key-description 'kp_next)
557 (single-key-description '(shift button1))
560 - Function: text-char-description character
561 This function returns a string describing CHARACTER in the
562 standard XEmacs notation for characters that appear in text--like
563 `single-key-description', except that control characters are
564 represented with a leading caret (which is how control characters
565 in XEmacs buffers are usually displayed).
567 (text-char-description ?\C-c)
569 (text-char-description ?\M-m)
571 (text-char-description ?\C-\M-m)
575 File: lispref.info, Node: Help Functions, Next: Obsoleteness, Prev: Describing Characters, Up: Documentation
580 XEmacs provides a variety of on-line help functions, all accessible
581 to the user as subcommands of the prefix `C-h', or on some keyboards,
582 `help'. For more information about them, see *Note Help: (emacs)Help.
583 Here we describe some program-level interfaces to the same information.
585 - Command: apropos regexp &optional do-all predicate
586 This function finds all symbols whose names contain a match for the
587 regular expression REGEXP, and returns a list of them (*note
588 Regular Expressions::). It also displays the symbols in a buffer
589 named `*Help*', each with a one-line description.
591 If DO-ALL is non-`nil', then `apropos' also shows key bindings for
592 the functions that are found.
594 If PREDICATE is non-`nil', it should be a function to be called on
595 each symbol that has matched REGEXP. Only symbols for which
596 PREDICATE returns a non-`nil' value are listed or displayed.
598 In the first of the following examples, `apropos' finds all the
599 symbols with names containing `exec'. In the second example, it
600 finds and returns only those symbols that are also commands. (We
601 don't show the output that results in the `*Help*' buffer.)
604 => (Buffer-menu-execute command-execute exec-directory
605 exec-path execute-extended-command execute-kbd-macro
606 executing-kbd-macro executing-macro)
608 (apropos "exec" nil 'commandp)
609 => (Buffer-menu-execute execute-extended-command)
611 `apropos' is used by various user-level commands, such as `C-h a'
612 (`hyper-apropos'), a graphical front-end to `apropos'; and `C-h A'
613 (`command-apropos'), which does an apropos over only those
614 functions which are user commands. `command-apropos' calls
615 `apropos', specifying a PREDICATE to restrict the output to
616 symbols that are commands. The call to `apropos' looks like this:
618 (apropos string t 'commandp)
621 The value of this variable is a local keymap for characters
622 following the Help key, `C-h'.
624 - Prefix Command: help-command
625 This symbol is not a function; its function definition is actually
626 the keymap known as `help-map'. It is defined in `help.el' as
629 (define-key global-map "\C-h" 'help-command)
630 (fset 'help-command help-map)
632 - Function: print-help-return-message &optional function
633 This function builds a string that explains how to restore the
634 previous state of the windows after a help command. After
635 building the message, it applies FUNCTION to it if FUNCTION is
636 non-`nil'. Otherwise it calls `message' to display it in the echo
639 This function expects to be called inside a
640 `with-output-to-temp-buffer' special form, and expects
641 `standard-output' to have the value bound by that special form.
642 For an example of its use, see the long example in *Note Accessing
645 - Variable: help-char
646 The value of this variable is the help character--the character
647 that XEmacs recognizes as meaning Help. By default, it is the
648 character `?\^H' (ASCII 8), which is `C-h'. When XEmacs reads this
649 character, if `help-form' is non-`nil' Lisp expression, it
650 evaluates that expression, and displays the result in a window if
653 `help-char' can be a character or a key description such as `help'
656 Usually the value of `help-form''s value is `nil'. Then the help
657 character has no special meaning at the level of command input, and
658 it becomes part of a key sequence in the normal way. The standard
659 key binding of `C-h' is a prefix key for several general-purpose
662 The help character is special after prefix keys, too. If it has no
663 binding as a subcommand of the prefix key, it runs
664 `describe-prefix-bindings', which displays a list of all the
665 subcommands of the prefix key.
667 - Variable: help-form
668 If this variable is non-`nil', its value is a form to evaluate
669 whenever the character `help-char' is read. If evaluating the form
670 produces a string, that string is displayed.
672 A command that calls `next-command-event' or `next-event' probably
673 should bind `help-form' to a non-`nil' expression while it does
674 input. (The exception is when `C-h' is meaningful input.)
675 Evaluating this expression should result in a string that explains
676 what the input is for and how to enter it properly.
678 Entry to the minibuffer binds this variable to the value of
679 `minibuffer-help-form' (*note Minibuffer Misc::).
681 - Variable: prefix-help-command
682 This variable holds a function to print help for a prefix
683 character. The function is called when the user types a prefix
684 key followed by the help character, and the help character has no
685 binding after that prefix. The variable's default value is
686 `describe-prefix-bindings'.
688 - Function: describe-prefix-bindings
689 This function calls `describe-bindings' to display a list of all
690 the subcommands of the prefix key of the most recent key sequence.
691 The prefix described consists of all but the last event of that
692 key sequence. (The last event is, presumably, the help character.)
694 The following two functions are found in the library `helper'. They
695 are for modes that want to provide help without relinquishing control,
696 such as the "electric" modes. You must load that library with
697 `(require 'helper)' in order to use them. Their names begin with
698 `Helper' to distinguish them from the ordinary help functions.
700 - Command: Helper-describe-bindings
701 This command pops up a window displaying a help buffer containing a
702 listing of all of the key bindings from both the local and global
703 keymaps. It works by calling `describe-bindings'.
705 - Command: Helper-help
706 This command provides help for the current mode. It prompts the
707 user in the minibuffer with the message `Help (Type ? for further
708 options)', and then provides assistance in finding out what the key
709 bindings are, and what the mode is intended for. It returns `nil'.
711 This can be customized by changing the map `Helper-help-map'.
714 File: lispref.info, Node: Obsoleteness, Prev: Help Functions, Up: Documentation
719 As you add functionality to a package, you may at times want to
720 replace an older function with a new one. To preserve compatibility
721 with existing code, the older function needs to still exist; but users
722 of that function should be told to use the newer one instead. XEmacs
723 Lisp lets you mark a function or variable as "obsolete", and indicate
724 what should be used instead.
726 - Function: make-obsolete function new
727 This function indicates that FUNCTION is an obsolete function, and
728 the function NEW should be used instead. The byte compiler will
729 issue a warning to this effect when it encounters a usage of the
730 older function, and the help system will also note this in the
731 function's documentation. NEW can also be a string (if there is
732 not a single function with the same functionality any more), and
733 should be a descriptive statement, such as "use FOO or BAR
734 instead" or "this function is unnecessary".
736 - Function: make-obsolete-variable variable new
737 This is like `make-obsolete' but is for variables instead of
740 - Function: define-obsolete-function-alias oldfun newfun
741 This function combines `make-obsolete' and `define-function',
742 declaring OLDFUN to be an obsolete variant of NEWFUN and defining
743 OLDFUN as an alias for NEWFUN.
745 - Function: define-obsolete-variable-alias oldvar newvar
746 This is like `define-obsolete-function-alias' but for variables.
748 Note that you should not normally put obsoleteness information
749 explicitly in a function or variable's doc string. The obsoleteness
750 information that you specify using the above functions will be displayed
751 whenever the doc string is displayed, and by adding it explicitly the
752 result is redundancy.
754 Also, if an obsolete function is substantially the same as a newer
755 one but is not actually an alias, you should consider omitting the doc
756 string entirely (use a null string `""' as the doc string). That way,
757 the user is told about the obsoleteness and is forced to look at the
758 documentation of the new function, making it more likely that he will
759 use the new function.
761 - Function: function-obsoleteness-doc function
762 If FUNCTION is obsolete, this function returns a string describing
763 this. This is the message that is printed out during byte
764 compilation or in the function's documentation. If FUNCTION is
765 not obsolete, `nil' is returned.
767 - Function: variable-obsoleteness-doc variable
768 This is like `function-obsoleteness-doc' but for variables.
770 The obsoleteness information is stored internally by putting a
771 property `byte-obsolete-info' (for functions) or
772 `byte-obsolete-variable' (for variables) on the symbol that specifies
773 the obsolete function or variable. For more information, see the
774 implementation of `make-obsolete' and `make-obsolete-variable' in
775 `lisp/bytecomp/bytecomp-runtime.el'.
778 File: lispref.info, Node: Files, Next: Backups and Auto-Saving, Prev: Documentation, Up: Top
783 In XEmacs, you can find, create, view, save, and otherwise work with
784 files and file directories. This chapter describes most of the
785 file-related functions of XEmacs Lisp, but a few others are described in
786 *Note Buffers::, and those related to backups and auto-saving are
787 described in *Note Backups and Auto-Saving::.
789 Many of the file functions take one or more arguments that are file
790 names. A file name is actually a string. Most of these functions
791 expand file name arguments using `expand-file-name', so that `~' is
792 handled correctly, as are relative file names (including `../'). These
793 functions don't recognize environment variable substitutions such as
794 `$HOME'. *Note File Name Expansion::.
798 * Visiting Files:: Reading files into Emacs buffers for editing.
799 * Saving Buffers:: Writing changed buffers back into files.
800 * Reading from Files:: Reading files into buffers without visiting.
801 * Writing to Files:: Writing new files from parts of buffers.
802 * File Locks:: Locking and unlocking files, to prevent
803 simultaneous editing by two people.
804 * Information about Files:: Testing existence, accessibility, size of files.
805 * Changing File Attributes:: Renaming files, changing protection, etc.
806 * File Names:: Decomposing and expanding file names.
807 * Contents of Directories:: Getting a list of the files in a directory.
808 * Create/Delete Dirs:: Creating and Deleting Directories.
809 * Magic File Names:: Defining "magic" special handling
810 for certain file names.
811 * Partial Files:: Treating a section of a buffer as a file.
812 * Format Conversion:: Conversion to and from various file formats.
813 * Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
816 File: lispref.info, Node: Visiting Files, Next: Saving Buffers, Up: Files
821 Visiting a file means reading a file into a buffer. Once this is
822 done, we say that the buffer is "visiting" that file, and call the file
823 "the visited file" of the buffer.
825 A file and a buffer are two different things. A file is information
826 recorded permanently in the computer (unless you delete it). A buffer,
827 on the other hand, is information inside of XEmacs that will vanish at
828 the end of the editing session (or when you kill the buffer). Usually,
829 a buffer contains information that you have copied from a file; then we
830 say the buffer is visiting that file. The copy in the buffer is what
831 you modify with editing commands. Such changes to the buffer do not
832 change the file; therefore, to make the changes permanent, you must
833 "save" the buffer, which means copying the altered buffer contents back
836 In spite of the distinction between files and buffers, people often
837 refer to a file when they mean a buffer and vice-versa. Indeed, we say,
838 "I am editing a file," rather than, "I am editing a buffer that I will
839 soon save as a file of the same name." Humans do not usually need to
840 make the distinction explicit. When dealing with a computer program,
841 however, it is good to keep the distinction in mind.
845 * Visiting Functions:: The usual interface functions for visiting.
846 * Subroutines of Visiting:: Lower-level subroutines that they use.
849 File: lispref.info, Node: Visiting Functions, Next: Subroutines of Visiting, Up: Visiting Files
851 Functions for Visiting Files
852 ----------------------------
854 This section describes the functions normally used to visit files.
855 For historical reasons, these functions have names starting with
856 `find-' rather than `visit-'. *Note Buffer File Name::, for functions
857 and variables that access the visited file name of a buffer or that
858 find an existing buffer by its visited file name.
860 In a Lisp program, if you want to look at the contents of a file but
861 not alter it, the fastest way is to use `insert-file-contents' in a
862 temporary buffer. Visiting the file is not necessary and takes longer.
863 *Note Reading from Files::.
865 - Command: find-file filename
866 This command selects a buffer visiting the file FILENAME, using an
867 existing buffer if there is one, and otherwise creating a new
868 buffer and reading the file into it. It also returns that buffer.
870 The body of the `find-file' function is very simple and looks like
873 (switch-to-buffer (find-file-noselect filename))
875 (See `switch-to-buffer' in *Note Displaying Buffers::.)
877 When `find-file' is called interactively, it prompts for FILENAME
880 - Function: find-file-noselect filename &optional nowarn
881 This function is the guts of all the file-visiting functions. It
882 finds or creates a buffer visiting the file FILENAME, and returns
883 it. It uses an existing buffer if there is one, and otherwise
884 creates a new buffer and reads the file into it. You may make the
885 buffer current or display it in a window if you wish, but this
886 function does not do so.
888 When `find-file-noselect' uses an existing buffer, it first
889 verifies that the file has not changed since it was last visited or
890 saved in that buffer. If the file has changed, then this function
891 asks the user whether to reread the changed file. If the user says
892 `yes', any changes previously made in the buffer are lost.
894 If `find-file-noselect' needs to create a buffer, and there is no
895 file named FILENAME, it displays the message `New file' in the
896 echo area, and leaves the buffer empty.
898 If NO-WARN is non-`nil', various warnings that XEmacs normally
899 gives (e.g. if another buffer is already visiting FILENAME but
900 FILENAME has been removed from disk since that buffer was created)
903 The `find-file-noselect' function calls `after-find-file' after
904 reading the file (*note Subroutines of Visiting::). That function
905 sets the buffer major mode, parses local variables, warns the user
906 if there exists an auto-save file more recent than the file just
907 visited, and finishes by running the functions in
910 The `find-file-noselect' function returns the buffer that is
911 visiting the file FILENAME.
913 (find-file-noselect "/etc/fstab")
916 - Command: find-file-other-window filename
917 This command selects a buffer visiting the file FILENAME, but does
918 so in a window other than the selected window. It may use another
919 existing window or split a window; see *Note Displaying Buffers::.
921 When this command is called interactively, it prompts for FILENAME.
923 - Command: find-file-read-only filename
924 This command selects a buffer visiting the file FILENAME, like
925 `find-file', but it marks the buffer as read-only. *Note Read
926 Only Buffers::, for related functions and variables.
928 When this command is called interactively, it prompts for FILENAME.
930 - Command: view-file filename
931 This command visits FILENAME in View mode, and displays it in a
932 recursive edit, returning to the previous buffer when done. View
933 mode is a mode that allows you to skim rapidly through the file
934 but does not let you modify it. Entering View mode runs the
935 normal hook `view-mode-hook'. *Note Hooks::.
937 When `view-file' is called interactively, it prompts for FILENAME.
939 - Variable: find-file-hooks
940 The value of this variable is a list of functions to be called
941 after a file is visited. The file's local-variables specification
942 (if any) will have been processed before the hooks are run. The
943 buffer visiting the file is current when the hook functions are
946 This variable works just like a normal hook, but we think that
947 renaming it would not be advisable.
949 - Variable: find-file-not-found-hooks
950 The value of this variable is a list of functions to be called when
951 `find-file' or `find-file-noselect' is passed a nonexistent file
952 name. `find-file-noselect' calls these functions as soon as it
953 detects a nonexistent file. It calls them in the order of the
954 list, until one of them returns non-`nil'. `buffer-file-name' is
957 This is not a normal hook because the values of the functions are
958 used and they may not all be called.
961 File: lispref.info, Node: Subroutines of Visiting, Prev: Visiting Functions, Up: Visiting Files
963 Subroutines of Visiting
964 -----------------------
966 The `find-file-noselect' function uses the `create-file-buffer' and
967 `after-find-file' functions as subroutines. Sometimes it is useful to
970 - Function: create-file-buffer filename
971 This function creates a suitably named buffer for visiting
972 FILENAME, and returns it. It uses FILENAME (sans directory) as
973 the name if that name is free; otherwise, it appends a string such
974 as `<2>' to get an unused name. See also *Note Creating Buffers::.
976 *Please note:* `create-file-buffer' does _not_ associate the new
977 buffer with a file and does not select the buffer. It also does
978 not use the default major mode.
980 (create-file-buffer "foo")
982 (create-file-buffer "foo")
984 (create-file-buffer "foo")
987 This function is used by `find-file-noselect'. It uses
988 `generate-new-buffer' (*note Creating Buffers::).
990 - Function: after-find-file &optional error warn noauto
991 This function sets the buffer major mode, and parses local
992 variables (*note Auto Major Mode::). It is called by
993 `find-file-noselect' and by the default revert function (*note
996 If reading the file got an error because the file does not exist,
997 but its directory does exist, the caller should pass a non-`nil'
998 value for ERROR. In that case, `after-find-file' issues a warning:
999 `(New File)'. For more serious errors, the caller should usually
1000 not call `after-find-file'.
1002 If WARN is non-`nil', then this function issues a warning if an
1003 auto-save file exists and is more recent than the visited file.
1005 If NOAUTO is non-`nil', then this function does not turn on
1006 auto-save mode; otherwise, it does.
1008 The last thing `after-find-file' does is call all the functions in
1012 File: lispref.info, Node: Saving Buffers, Next: Reading from Files, Prev: Visiting Files, Up: Files
1017 When you edit a file in XEmacs, you are actually working on a buffer
1018 that is visiting that file--that is, the contents of the file are
1019 copied into the buffer and the copy is what you edit. Changes to the
1020 buffer do not change the file until you "save" the buffer, which means
1021 copying the contents of the buffer into the file.
1023 - Command: save-buffer &optional backup-option
1024 This function saves the contents of the current buffer in its
1025 visited file if the buffer has been modified since it was last
1026 visited or saved. Otherwise it does nothing.
1028 `save-buffer' is responsible for making backup files. Normally,
1029 BACKUP-OPTION is `nil', and `save-buffer' makes a backup file only
1030 if this is the first save since visiting the file. Other values
1031 for BACKUP-OPTION request the making of backup files in other
1034 * With an argument of 4 or 64, reflecting 1 or 3 `C-u''s, the
1035 `save-buffer' function marks this version of the file to be
1036 backed up when the buffer is next saved.
1038 * With an argument of 16 or 64, reflecting 2 or 3 `C-u''s, the
1039 `save-buffer' function unconditionally backs up the previous
1040 version of the file before saving it.
1042 - Command: save-some-buffers &optional save-silently-p exiting
1043 This command saves some modified file-visiting buffers. Normally
1044 it asks the user about each buffer. But if SAVE-SILENTLY-P is
1045 non-`nil', it saves all the file-visiting buffers without querying
1048 The optional EXITING argument, if non-`nil', requests this
1049 function to offer also to save certain other buffers that are not
1050 visiting files. These are buffers that have a non-`nil' local
1051 value of `buffer-offer-save'. (A user who says yes to saving one
1052 of these is asked to specify a file name to use.) The
1053 `save-buffers-kill-emacs' function passes a non-`nil' value for
1056 - Variable: buffer-offer-save
1057 When this variable is non-`nil' in a buffer, XEmacs offers to save
1058 the buffer on exit even if the buffer is not visiting a file. The
1059 variable is automatically local in all buffers. Normally, Mail
1060 mode (used for editing outgoing mail) sets this to `t'.
1062 - Command: write-file filename
1063 This function writes the current buffer into file FILENAME, makes
1064 the buffer visit that file, and marks it not modified. Then it
1065 renames the buffer based on FILENAME, appending a string like `<2>'
1066 if necessary to make a unique buffer name. It does most of this
1067 work by calling `set-visited-file-name' and `save-buffer'.
1069 - Variable: write-file-hooks
1070 The value of this variable is a list of functions to be called
1071 before writing out a buffer to its visited file. If one of them
1072 returns non-`nil', the file is considered already written and the
1073 rest of the functions are not called, nor is the usual code for
1074 writing the file executed.
1076 If a function in `write-file-hooks' returns non-`nil', it is
1077 responsible for making a backup file (if that is appropriate). To
1078 do so, execute the following code:
1080 (or buffer-backed-up (backup-buffer))
1082 You might wish to save the file modes value returned by
1083 `backup-buffer' and use that to set the mode bits of the file that
1084 you write. This is what `save-buffer' normally does.
1086 Even though this is not a normal hook, you can use `add-hook' and
1087 `remove-hook' to manipulate the list. *Note Hooks::.
1089 - Variable: local-write-file-hooks
1090 This works just like `write-file-hooks', but it is intended to be
1091 made local to particular buffers. It's not a good idea to make
1092 `write-file-hooks' local to a buffer--use this variable instead.
1094 The variable is marked as a permanent local, so that changing the
1095 major mode does not alter a buffer-local value. This is
1096 convenient for packages that read "file" contents in special ways,
1097 and set up hooks to save the data in a corresponding way.
1099 - Variable: write-contents-hooks
1100 This works just like `write-file-hooks', but it is intended for
1101 hooks that pertain to the contents of the file, as opposed to
1102 hooks that pertain to where the file came from. Such hooks are
1103 usually set up by major modes, as buffer-local bindings for this
1104 variable. Switching to a new major mode always resets this
1107 - Variable: after-save-hook
1108 This normal hook runs after a buffer has been saved in its visited
1111 - Variable: file-precious-flag
1112 If this variable is non-`nil', then `save-buffer' protects against
1113 I/O errors while saving by writing the new file to a temporary
1114 name instead of the name it is supposed to have, and then renaming
1115 it to the intended name after it is clear there are no errors.
1116 This procedure prevents problems such as a lack of disk space from
1117 resulting in an invalid file.
1119 As a side effect, backups are necessarily made by copying. *Note
1120 Rename or Copy::. Yet, at the same time, saving a precious file
1121 always breaks all hard links between the file you save and other
1124 Some modes set this variable non-`nil' locally in particular
1127 - User Option: require-final-newline
1128 This variable determines whether files may be written out that do
1129 _not_ end with a newline. If the value of the variable is `t',
1130 then `save-buffer' silently adds a newline at the end of the file
1131 whenever the buffer being saved does not already end in one. If
1132 the value of the variable is non-`nil', but not `t', then
1133 `save-buffer' asks the user whether to add a newline each time the
1136 If the value of the variable is `nil', then `save-buffer' doesn't
1137 add newlines at all. `nil' is the default value, but a few major
1138 modes set it to `t' in particular buffers.
projects / chise / xemacs-chise.git- / blob