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: Truncation, Next: The Echo Area, Prev: Refresh Screen, Up: Display
58 When a line of text extends beyond the right edge of a window, the
59 line can either be truncated or continued on the next line. When a line
60 is truncated, this is normally shown with a `\' in the rightmost column
61 of the window on X displays, and with a `$' on TTY devices. When a
62 line is continued or "wrapped" onto the next line, this is shown with a
63 curved arrow in the rightmost column of the window (or with a `\' on
64 TTY devices). The additional screen lines used to display a long text
65 line are called "continuation" lines.
67 Normally, whenever line truncation is in effect for a particular
68 window, a horizontal scrollbar is displayed in that window if the
69 device supports scrollbars. *Note Scrollbars::.
71 Note that continuation is different from filling; continuation
72 happens on the screen only, not in the buffer contents, and it breaks a
73 line precisely at the right margin, not at a word boundary. *Note
76 - User Option: truncate-lines
77 This buffer-local variable controls how XEmacs displays lines that
78 extend beyond the right edge of the window. If it is non-`nil',
79 then XEmacs does not display continuation lines; rather each line
80 of text occupies exactly one screen line, and a backslash appears
81 at the edge of any line that extends to or beyond the edge of the
82 window. The default is `nil'.
84 If the variable `truncate-partial-width-windows' is non-`nil',
85 then truncation is always used for side-by-side windows (within one
86 frame) regardless of the value of `truncate-lines'.
88 - User Option: default-truncate-lines
89 This variable is the default value for `truncate-lines', for
90 buffers that do not have local values for it.
92 - User Option: truncate-partial-width-windows
93 This variable controls display of lines that extend beyond the
94 right edge of the window, in side-by-side windows (*note Splitting
95 Windows::). If it is non-`nil', these lines are truncated;
96 otherwise, `truncate-lines' says what to do with them.
98 The backslash and curved arrow used to indicate truncated or
99 continued lines are only defaults, and can be changed. These images
100 are actually glyphs (*note Glyphs::). XEmacs provides a great deal of
101 flexibility in how glyphs can be controlled. (This differs from FSF
102 Emacs, which uses display tables to control these images.)
104 For details, *Note Redisplay Glyphs::.
107 File: lispref.info, Node: The Echo Area, Next: Warnings, Prev: Truncation, Up: Display
112 The "echo area" is used for displaying messages made with the
113 `message' primitive, and for echoing keystrokes. It is not the same as
114 the minibuffer, despite the fact that the minibuffer appears (when
115 active) in the same place on the screen as the echo area. The `XEmacs
116 Reference Manual' specifies the rules for resolving conflicts between
117 the echo area and the minibuffer for use of that screen space (*note
118 The Minibuffer: (emacs)Minibuffer.). Error messages appear in the echo
119 area; see *Note Errors::.
121 You can write output in the echo area by using the Lisp printing
122 functions with `t' as the stream (*note Output Functions::), or as
125 - Function: message string &rest arguments
126 This function displays a one-line message in the echo area. The
127 argument STRING is similar to a C language `printf' control
128 string. See `format' in *Note String Conversion::, for the details
129 on the conversion specifications. `message' returns the
132 In batch mode, `message' prints the message text on the standard
133 error stream, followed by a newline.
135 If STRING is `nil', `message' clears the echo area. If the
136 minibuffer is active, this brings the minibuffer contents back onto
137 the screen immediately.
139 (message "Minibuffer depth is %d."
141 -| Minibuffer depth is 0.
142 => "Minibuffer depth is 0."
144 ---------- Echo Area ----------
145 Minibuffer depth is 0.
146 ---------- Echo Area ----------
148 In addition to only displaying a message, XEmacs allows you to
149 "label" your messages, giving you fine-grained control of their
150 display. Message label is a symbol denoting the message type. Some
153 * `message'--default label used by the `message' function;
155 * `error'--default label used for reporting errors;
157 * `progress'--progress indicators like `Converting... 45%' (not
160 * `prompt'--prompt-like messages like `Isearch: foo' (not logged by
163 * `command'--helper command messages like `Mark set' (not logged by
166 * `no-log'--messages that should never be logged
168 Several messages may be stacked in the echo area at once. Lisp
169 programs may access these messages, or remove them as appropriate, via
172 - Function: display-message label message &optional frame stdout-p
173 This function displays MESSAGE (a string) labeled as LABEL, as
176 The FRAME argument specifies the frame to whose minibuffer the
177 message should be printed. This is currently unimplemented. The
178 STDOUT-P argument is used internally.
180 (display-message 'command "Mark set")
182 - Function: lmessage label string &rest arguments
183 This function displays a message STRING with label LABEL. It is
184 similar to `message' in that it accepts a `printf'-like strings
185 and any number of arguments.
187 ;; Display a command message.
188 (lmessage 'command "Comment column set to %d" comment-column)
190 ;; Display a progress message.
191 (lmessage 'progress "Fontifying %s... (%d)" buffer percentage)
193 ;; Display a message that should not be logged.
194 (lmessage 'no-log "Done")
196 - Function: clear-message &optional label frame stdout-p no-restore
197 This function remove any message with the given LABEL from the
198 message-stack, erasing it from the echo area if it's currently
201 If a message remains at the head of the message-stack and
202 NO-RESTORE is `nil', it will be displayed. The string which
203 remains in the echo area will be returned, or `nil' if the
204 message-stack is now empty. If LABEL is nil, the entire
205 message-stack is cleared.
207 ;; Show a message, wait for 2 seconds, and restore old minibuffer
209 (message "A message")
212 (lmessage 'my-label "Newsflash! Newsflash!")
213 -| Newsflash! Newsflash!
214 => "Newsflash! Newsflash!"
216 (clear-message 'my-label)
220 Unless you need the return value or you need to specify a label,
221 you should just use `(message nil)'.
223 - Function: current-message &optional frame
224 This function returns the current message in the echo area, or
225 `nil'. The FRAME argument is currently unused.
227 Some of the messages displayed in the echo area are also recorded in
228 the ` *Message-Log*' buffer. Exactly which messages will be recorded
229 can be tuned using the following variables.
231 - User Option: log-message-max-size
232 This variable specifies the maximum size of the ` *Message-log*'
235 - Variable: log-message-ignore-labels
236 This variable specifies the labels whose messages will not be
237 logged. It should be a list of symbols.
239 - Variable: log-message-ignore-regexps
240 This variable specifies the regular expressions matching messages
241 that will not be logged. It should be a list of regular
244 Normally, packages that generate messages that might need to be
245 ignored should label them with `progress', `prompt', or `no-log',
246 so they can be filtered by `log-message-ignore-labels'.
248 - Variable: echo-keystrokes
249 This variable determines how much time should elapse before command
250 characters echo. Its value must be a number, which specifies the
251 number of seconds to wait before echoing. If the user types a
252 prefix key (such as `C-x') and then delays this many seconds
253 before continuing, the prefix key is echoed in the echo area. Any
254 subsequent characters in the same command will be echoed as well.
256 If the value is zero, then command input is not echoed.
258 - Variable: cursor-in-echo-area
259 This variable controls where the cursor appears when a message is
260 displayed in the echo area. If it is non-`nil', then the cursor
261 appears at the end of the message. Otherwise, the cursor appears
262 at point--not in the echo area at all.
264 The value is normally `nil'; Lisp programs bind it to `t' for
265 brief periods of time.
268 File: lispref.info, Node: Warnings, Next: Invisible Text, Prev: The Echo Area, Up: Display
273 XEmacs contains a facility for unified display of various warnings.
274 Unlike errors, warnings are displayed in the situations when XEmacs
275 encounters a problem that is recoverable, but which should be fixed for
276 safe future operation.
278 For example, warnings are printed by the startup code when it
279 encounters problems with X keysyms, when there is an error in `.emacs',
280 and in other problematic situations. Unlike messages, warnings are
281 displayed in a separate buffer, and include an explanatory message that
282 may span across several lines. Here is an example of how a warning is
285 (1) (initialization/error) An error has occurred while loading ~/.emacs:
287 Symbol's value as variable is void: bogus-variable
289 To ensure normal operation, you should investigate the cause of the error
290 in your initialization file and remove it. Use the `-debug-init' option
291 to XEmacs to view a complete error backtrace.
293 Each warning has a "class" and a "priority level". The class is a
294 symbol describing what sort of warning this is, such as
295 `initialization', `resource' or `key-mapping'.
297 The warning priority level specifies how important the warning is.
298 The recognized warning levels, in increased order of priority, are:
299 `debug', `info', `notice', `warning', `error', `critical', `alert' and
302 - Function: display-warning class message &optional level
303 This function displays a warning message MESSAGE (a string).
304 CLASS should be a warning class symbol, as described above, or a
305 list of such symbols. LEVEL describes the warning priority level.
306 If unspecified, it default to `warning'.
308 (display-warning 'resource
309 "Bad resource specification encountered:
314 You should replace the * with a . in order to get proper behavior when
315 you use the specifier and/or `set-face-*' functions.")
317 ---------- Warning buffer ----------
318 (1) (resource/warning) Bad resource specification encountered:
323 You should replace the * with a . in order to get proper behavior when
324 you use the specifier and/or `set-face-*' functions.
325 ---------- Warning buffer ----------
327 - Function: lwarn class level message &rest args
328 This function displays a formatted labeled warning message. As
329 above, CLASS should be the warning class symbol, or a list of such
330 symbols, and LEVEL should specify the warning priority level
331 (`warning' by default).
333 Unlike in `display-warning', MESSAGE may be a formatted message,
334 which will be, together with the rest of the arguments, passed to
337 (lwarn 'message-log 'warning
338 "Error caught in `remove-message-hook': %s"
339 (error-message-string e))
341 - Variable: log-warning-minimum-level
342 This variable specifies the minimum level of warnings that should
343 be generated. Warnings with level lower than defined by this
344 variable are completely ignored, as if they never happened.
346 - Variable: display-warning-minimum-level
347 This variable specifies the minimum level of warnings that should
348 be displayed. Unlike `log-warning-minimum-level', setting this
349 function does not suppress warnings entirely--they are still
350 generated in the `*Warnings*' buffer, only they are not displayed
353 - Variable: log-warning-suppressed-classes
354 This variable specifies a list of classes that should not be
355 logged or displayed. If any of the class symbols associated with
356 a warning is the same as any of the symbols listed here, the
357 warning will be completely ignored, as it they never happened.
359 - Variable: display-warning-suppressed-classes
360 This variable specifies a list of classes that should not be
361 logged or displayed. If any of the class symbols associated with
362 a warning is the same as any of the symbols listed here, the
363 warning will not be displayed. The warning will still logged in
364 the *Warnings* buffer (unless also contained in
365 `log-warning-suppressed-classes'), but the buffer will not be
366 automatically popped up.
369 File: lispref.info, Node: Invisible Text, Next: Selective Display, Prev: Warnings, Up: Display
374 You can make characters "invisible", so that they do not appear on
375 the screen, with the `invisible' property. This can be either a text
376 property or a property of an overlay.
378 In the simplest case, any non-`nil' `invisible' property makes a
379 character invisible. This is the default case--if you don't alter the
380 default value of `buffer-invisibility-spec', this is how the
381 `invisibility' property works. This feature is much like selective
382 display (*note Selective Display::), but more general and cleaner.
384 More generally, you can use the variable `buffer-invisibility-spec'
385 to control which values of the `invisible' property make text
386 invisible. This permits you to classify the text into different subsets
387 in advance, by giving them different `invisible' values, and
388 subsequently make various subsets visible or invisible by changing the
389 value of `buffer-invisibility-spec'.
391 Controlling visibility with `buffer-invisibility-spec' is especially
392 useful in a program to display the list of entries in a data base. It
393 permits the implementation of convenient filtering commands to view
394 just a part of the entries in the data base. Setting this variable is
395 very fast, much faster than scanning all the text in the buffer looking
396 for properties to change.
398 - Variable: buffer-invisibility-spec
399 This variable specifies which kinds of `invisible' properties
400 actually make a character invisible.
403 A character is invisible if its `invisible' property is
404 non-`nil'. This is the default.
407 Each element of the list makes certain characters invisible.
408 Ultimately, a character is invisible if any of the elements
409 of this list applies to it. The list can have two kinds of
413 A character is invisible if its `invisible' property
414 value is ATOM or if it is a list with ATOM as a member.
417 A character is invisible if its `invisible' property
418 value is ATOM or if it is a list with ATOM as a member.
419 Moreover, if this character is at the end of a line and
420 is followed by a visible newline, it displays an
423 Ordinarily, commands that operate on text or move point do not care
424 whether the text is invisible. However, the user-level line motion
425 commands explicitly ignore invisible newlines.
428 File: lispref.info, Node: Selective Display, Next: Overlay Arrow, Prev: Invisible Text, Up: Display
433 "Selective display" is a pair of features that hide certain lines on
436 The first variant, explicit selective display, is designed for use in
437 a Lisp program. The program controls which lines are hidden by altering
438 the text. Outline mode has traditionally used this variant. It has
439 been partially replaced by the invisible text feature (*note Invisible
440 Text::); there is a new version of Outline mode which uses that instead.
442 In the second variant, the choice of lines to hide is made
443 automatically based on indentation. This variant is designed to be a
446 The way you control explicit selective display is by replacing a
447 newline (control-j) with a carriage return (control-m). The text that
448 was formerly a line following that newline is now invisible. Strictly
449 speaking, it is temporarily no longer a line at all, since only newlines
450 can separate lines; it is now part of the previous line.
452 Selective display does not directly affect editing commands. For
453 example, `C-f' (`forward-char') moves point unhesitatingly into
454 invisible text. However, the replacement of newline characters with
455 carriage return characters affects some editing commands. For example,
456 `next-line' skips invisible lines, since it searches only for newlines.
457 Modes that use selective display can also define commands that take
458 account of the newlines, or that make parts of the text visible or
461 When you write a selectively displayed buffer into a file, all the
462 control-m's are output as newlines. This means that when you next read
463 in the file, it looks OK, with nothing invisible. The selective display
464 effect is seen only within XEmacs.
466 - Variable: selective-display
467 This buffer-local variable enables selective display. This means
468 that lines, or portions of lines, may be made invisible.
470 * If the value of `selective-display' is `t', then any portion
471 of a line that follows a control-m is not displayed.
473 * If the value of `selective-display' is a positive integer,
474 then lines that start with more than that many columns of
475 indentation are not displayed.
477 When some portion of a buffer is invisible, the vertical movement
478 commands operate as if that portion did not exist, allowing a
479 single `next-line' command to skip any number of invisible lines.
480 However, character movement commands (such as `forward-char') do
481 not skip the invisible portion, and it is possible (if tricky) to
482 insert or delete text in an invisible portion.
484 In the examples below, we show the _display appearance_ of the
485 buffer `foo', which changes with the value of `selective-display'.
486 The _contents_ of the buffer do not change.
488 (setq selective-display nil)
491 ---------- Buffer: foo ----------
498 ---------- Buffer: foo ----------
500 (setq selective-display 2)
503 ---------- Buffer: foo ----------
508 ---------- Buffer: foo ----------
510 - Variable: selective-display-ellipses
511 If this buffer-local variable is non-`nil', then XEmacs displays
512 `...' at the end of a line that is followed by invisible text.
513 This example is a continuation of the previous one.
515 (setq selective-display-ellipses t)
518 ---------- Buffer: foo ----------
523 ---------- Buffer: foo ----------
525 You can use a display table to substitute other text for the
526 ellipsis (`...'). *Note Display Tables::.
529 File: lispref.info, Node: Overlay Arrow, Next: Temporary Displays, Prev: Selective Display, Up: Display
534 The "overlay arrow" is useful for directing the user's attention to
535 a particular line in a buffer. For example, in the modes used for
536 interface to debuggers, the overlay arrow indicates the line of code
537 about to be executed.
539 - Variable: overlay-arrow-string
540 This variable holds the string to display to call attention to a
541 particular line, or `nil' if the arrow feature is not in use.
542 Despite its name, the value of this variable can be either a string
543 or a glyph (*note Glyphs::).
545 - Variable: overlay-arrow-position
546 This variable holds a marker that indicates where to display the
547 overlay arrow. It should point at the beginning of a line. The
548 arrow text appears at the beginning of that line, overlaying any
549 text that would otherwise appear. Since the arrow is usually
550 short, and the line usually begins with indentation, normally
551 nothing significant is overwritten.
553 The overlay string is displayed only in the buffer that this marker
554 points into. Thus, only one buffer can have an overlay arrow at
557 You can do the same job by creating an extent with a `begin-glyph'
558 property. *Note Extent Properties::.
561 File: lispref.info, Node: Temporary Displays, Next: Blinking, Prev: Overlay Arrow, Up: Display
566 Temporary displays are used by commands to put output into a buffer
567 and then present it to the user for perusal rather than for editing.
568 Many of the help commands use this feature.
570 - Special Form: with-output-to-temp-buffer buffer-name forms...
571 This function executes FORMS while arranging to insert any output
572 they print into the buffer named BUFFER-NAME. The buffer is then
573 shown in some window for viewing, displayed but not selected.
575 The string BUFFER-NAME specifies the temporary buffer, which need
576 not already exist. The argument must be a string, not a buffer.
577 The buffer is erased initially (with no questions asked), and it is
578 marked as unmodified after `with-output-to-temp-buffer' exits.
580 `with-output-to-temp-buffer' binds `standard-output' to the
581 temporary buffer, then it evaluates the forms in FORMS. Output
582 using the Lisp output functions within FORMS goes by default to
583 that buffer (but screen display and messages in the echo area,
584 although they are "output" in the general sense of the word, are
585 not affected). *Note Output Functions::.
587 The value of the last form in FORMS is returned.
589 ---------- Buffer: foo ----------
590 This is the contents of foo.
591 ---------- Buffer: foo ----------
593 (with-output-to-temp-buffer "foo"
595 (print standard-output))
598 ---------- Buffer: foo ----------
603 ---------- Buffer: foo ----------
605 - Variable: temp-buffer-show-function
606 If this variable is non-`nil', `with-output-to-temp-buffer' calls
607 it as a function to do the job of displaying a help buffer. The
608 function gets one argument, which is the buffer it should display.
610 In Emacs versions 18 and earlier, this variable was called
611 `temp-buffer-show-hook'.
613 - Function: momentary-string-display string position &optional char
615 This function momentarily displays STRING in the current buffer at
616 POSITION. It has no effect on the undo list or on the buffer's
619 The momentary display remains until the next input event. If the
620 next input event is CHAR, `momentary-string-display' ignores it
621 and returns. Otherwise, that event remains buffered for
622 subsequent use as input. Thus, typing CHAR will simply remove the
623 string from the display, while typing (say) `C-f' will remove the
624 string from the display and later (presumably) move point forward.
625 The argument CHAR is a space by default.
627 The return value of `momentary-string-display' is not meaningful.
629 You can do the same job in a more general way by creating an extent
630 with a begin-glyph property. *Note Extent Properties::.
632 If MESSAGE is non-`nil', it is displayed in the echo area while
633 STRING is displayed in the buffer. If it is `nil', a default
634 message says to type CHAR to continue.
636 In this example, point is initially located at the beginning of the
639 ---------- Buffer: foo ----------
640 This is the contents of foo.
642 ---------- Buffer: foo ----------
644 (momentary-string-display
645 "**** Important Message! ****"
647 "Type RET when done reading")
650 ---------- Buffer: foo ----------
651 This is the contents of foo.
652 **** Important Message! ****Second line.
653 ---------- Buffer: foo ----------
655 ---------- Echo Area ----------
656 Type RET when done reading
657 ---------- Echo Area ----------
659 This function works by actually changing the text in the buffer.
660 As a result, if you later undo in this buffer, you will see the
664 File: lispref.info, Node: Blinking, Next: Usual Display, Prev: Temporary Displays, Up: Display
669 This section describes the mechanism by which XEmacs shows a matching
670 open parenthesis when the user inserts a close parenthesis.
672 - Variable: blink-paren-function
673 The value of this variable should be a function (of no arguments)
674 to be called whenever a character with close parenthesis syntax is
675 inserted. The value of `blink-paren-function' may be `nil', in
676 which case nothing is done.
678 *Please note:* This variable was named `blink-paren-hook' in
679 older Emacs versions, but since it is not called with the
680 standard convention for hooks, it was renamed to
681 `blink-paren-function' in version 19.
683 - Variable: blink-matching-paren
684 If this variable is `nil', then `blink-matching-open' does nothing.
686 - Variable: blink-matching-paren-distance
687 This variable specifies the maximum distance to scan for a matching
688 parenthesis before giving up.
690 - Variable: blink-matching-paren-delay
691 This variable specifies the number of seconds for the cursor to
692 remain at the matching parenthesis. A fraction of a second often
693 gives good results, but the default is 1, which works on all
696 - Function: blink-matching-open
697 This function is the default value of `blink-paren-function'. It
698 assumes that point follows a character with close parenthesis
699 syntax and moves the cursor momentarily to the matching opening
700 character. If that character is not already on the screen, it
701 displays the character's context in the echo area. To avoid long
702 delays, this function does not search farther than
703 `blink-matching-paren-distance' characters.
705 Here is an example of calling this function explicitly.
707 (defun interactive-blink-matching-open ()
708 "Indicate momentarily the start of sexp before point."
710 (let ((blink-matching-paren-distance
712 (blink-matching-paren t))
713 (blink-matching-open)))
716 File: lispref.info, Node: Usual Display, Next: Display Tables, Prev: Blinking, Up: Display
718 Usual Display Conventions
719 =========================
721 The usual display conventions define how to display each character
722 code. You can override these conventions by setting up a display table
723 (*note Display Tables::). Here are the usual display conventions:
725 * Character codes 32 through 126 map to glyph codes 32 through 126.
726 Normally this means they display as themselves.
728 * Character code 9 is a horizontal tab. It displays as whitespace
729 up to a position determined by `tab-width'.
731 * Character code 10 is a newline.
733 * All other codes in the range 0 through 31, and code 127, display
734 in one of two ways according to the value of `ctl-arrow'. If it is
735 non-`nil', these codes map to sequences of two glyphs, where the
736 first glyph is the ASCII code for `^'. (A display table can
737 specify a glyph to use instead of `^'.) Otherwise, these codes map
738 just like the codes in the range 128 to 255.
740 * Character codes 128 through 255 map to sequences of four glyphs,
741 where the first glyph is the ASCII code for `\', and the others are
742 digit characters representing the code in octal. (A display table
743 can specify a glyph to use instead of `\'.)
745 The usual display conventions apply even when there is a display
746 table, for any character whose entry in the active display table is
747 `nil'. Thus, when you set up a display table, you need only specify
748 the characters for which you want unusual behavior.
750 These variables affect the way certain characters are displayed on
751 the screen. Since they change the number of columns the characters
752 occupy, they also affect the indentation functions.
754 - User Option: ctl-arrow
755 This buffer-local variable controls how control characters are
756 displayed. If it is non-`nil', they are displayed as a caret
757 followed by the character: `^A'. If it is `nil', they are
758 displayed as a backslash followed by three octal digits: `\001'.
760 - Variable: default-ctl-arrow
761 The value of this variable is the default value for `ctl-arrow' in
762 buffers that do not override it. *Note Default Value::.
764 - User Option: tab-width
765 The value of this variable is the spacing between tab stops used
766 for displaying tab characters in Emacs buffers. The default is 8.
767 Note that this feature is completely independent from the
768 user-settable tab stops used by the command `tab-to-tab-stop'.
772 File: lispref.info, Node: Display Tables, Next: Beeping, Prev: Usual Display, Up: Display
777 You can use the "display table" feature to control how all 256
778 possible character codes display on the screen. This is useful for
779 displaying European languages that have letters not in the ASCII
782 The display table maps each character code into a sequence of
783 "runes", each rune being an image that takes up one character position
784 on the screen. You can also define how to display each rune on your
785 terminal, using the "rune table".
789 * Display Table Format:: What a display table consists of.
790 * Active Display Table:: How XEmacs selects a display table to use.
791 * Character Descriptors:: Format of an individual element of a
795 File: lispref.info, Node: Display Table Format, Next: Active Display Table, Up: Display Tables
800 A display table is an array of 256 elements. (In FSF Emacs, a display
801 table is 262 elements. The six extra elements specify the truncation
802 and continuation glyphs, etc. This method is very kludgey, and in
803 XEmacs the variables `truncation-glyph', `continuation-glyph', etc. are
804 used. *Note Truncation::.)
806 - Function: make-display-table
807 This creates and returns a display table. The table initially has
808 `nil' in all elements.
810 The 256 elements correspond to character codes; the Nth element says
811 how to display the character code N. The value should be `nil', a
812 string, a glyph, or a vector of strings and glyphs (*note Character
813 Descriptors::). If an element is `nil', it says to display that
814 character according to the usual display conventions (*note Usual
817 If you use the display table to change the display of newline
818 characters, the whole buffer will be displayed as one long "line."
820 For example, here is how to construct a display table that mimics the
821 effect of setting `ctl-arrow' to a non-`nil' value:
823 (setq disptab (make-display-table))
826 (or (= i ?\t) (= i ?\n)
827 (aset disptab i (concat "^" (char-to-string (+ i 64)))))
829 (aset disptab 127 "^?"))
832 File: lispref.info, Node: Active Display Table, Next: Character Descriptors, Prev: Display Table Format, Up: Display Tables
837 The active display table is controlled by the variable
838 `current-display-table'. This is a specifier, which means that you can
839 specify separate values for it in individual buffers, windows, frames,
840 and devices, as well as a global value. It also means that you cannot
841 set this variable using `setq'; use `set-specifier' instead. *Note
842 Specifiers::. (FSF Emacs uses `window-display-table',
843 `buffer-display-table', `standard-display-table', etc. to control the
844 display table. However, specifiers are a cleaner and more powerful way
845 of doing the same thing. FSF Emacs also uses a different format for
846 the contents of a display table, using additional indirection to a
847 "glyph table" and such. Note that "glyph" has a different meaning in
850 - Variable: current-display-table
851 The display table currently in use. This is a specifier.
853 Display tables are used to control how characters are displayed.
854 Each time that redisplay processes a character, it is looked up in
855 all the display tables that apply (obtained by calling
856 `specifier-instance' on `current-display-table' and any overriding
857 display tables specified in currently active faces). The first
858 entry found that matches the character determines how the
859 character is displayed. If there is no matching entry, the
860 default display method is used. (Non-control characters are
861 displayed as themselves and control characters are displayed
862 according to the buffer-local variable `ctl-arrow'. Control
863 characters are further affected by `control-arrow-glyph' and
864 `octal-escape-glyph'.)
866 Each instantiator in this specifier and the display-table
867 specifiers in faces is a display table or a list of such tables.
868 If a list, each table will be searched in turn for an entry
869 matching a particular character. Each display table is one of
871 * A vector, specifying values for characters starting at 0.
873 * A char table, either of type `char' or `generic'.
877 Each entry in a display table should be one of
879 * nil (this entry is ignored and the search continues).
881 * A character (use this character; if it happens to be the same
882 as the original character, default processing happens,
883 otherwise redisplay attempts to display this character
884 directly; #### At some point recursive display-table lookup
885 will be implemented).
887 * A string (display each character in the string directly; ####
888 At some point recursive display-table lookup will be
891 * A glyph (display the glyph; #### At some point recursive
892 display-table lookup will be implemented when a string glyph
895 * A cons of the form (format "STRING") where STRING is a
896 printf-like spec used to process the character. ####
897 Unfortunately no formatting directives other than %% are
900 * A vector (each element of the vector is processed recursively;
901 in such a case, nil elements in the vector are simply
904 #### At some point in the near future, display tables are
905 likely to be expanded to include other features, such as
906 referencing characters in particular fonts and allowing the
907 character search to continue all the way up the chain of
908 specifier instantiators. These features are necessary to
909 properly display Unicode characters.
911 Individual faces can also specify an overriding display table; this
912 is set using `set-face-display-table'. *Note Faces::.
914 If no display table can be determined for a particular window, then
915 XEmacs uses the usual display conventions. *Note Usual Display::.
918 File: lispref.info, Node: Character Descriptors, Prev: Active Display Table, Up: Display Tables
920 Character Descriptors
921 ---------------------
923 Each element of the display-table vector describes how to display a
924 particular character and is called a "character descriptor". A
925 character descriptor can be:
928 Display this particular string wherever the character is to be
932 Display this particular glyph wherever the character is to be
936 The vector may contain strings and/or glyphs. Display the
937 elements of the vector one after another wherever the character is
941 Display according to the standard interpretation (*note Usual
945 File: lispref.info, Node: Beeping, Prev: Display Tables, Up: Display
950 You can make XEmacs ring a bell, play a sound, or blink the screen to
951 attract the user's attention. Be conservative about how often you do
952 this; frequent bells can become irritating. Also be careful not to use
953 beeping alone when signaling an error is appropriate. (*Note Errors::.)
955 - Function: ding &optional dont-terminate sound device
956 This function beeps, or flashes the screen (see `visible-bell'
957 below). It also terminates any keyboard macro currently executing
958 unless DONT-TERMINATE is non-`nil'. If SOUND is specified, it
959 should be a symbol specifying which sound to make. This sound
960 will be played if `visible-bell' is `nil'. (This only works if
961 sound support was compiled into the executable and you are running
962 on the console of a Sun SparcStation, SGI, HP9000s700, or Linux
963 PC. Otherwise you just get a beep.) The optional third argument
964 specifies what device to make the sound on, and defaults to the
967 - Function: beep &optional dont-terminate sound device
968 This is a synonym for `ding'.
970 - User Option: visible-bell
971 This variable determines whether XEmacs should flash the screen to
972 represent a bell. Non-`nil' means yes, `nil' means no. On TTY
973 devices, this is effective only if the Termcap entry for the
974 terminal type has the visible bell flag (`vb') set.
976 - Variable: sound-alist
977 This variable holds an alist associating names with sounds. When
978 `beep' or `ding' is called with one of the name symbols, the
979 associated sound will be generated instead of the standard beep.
981 Each element of `sound-alist' is a list describing a sound. The
982 first element of the list is the name of the sound being defined.
983 Subsequent elements of the list are alternating keyword/value
987 A string of raw sound data, or the name of another sound to
988 play. The symbol `t' here means use the default X beep.
991 An integer from 0-100, defaulting to `bell-volume'.
994 If using the default X beep, the pitch (Hz) to generate.
997 If using the default X beep, the duration (milliseconds).
999 For compatibility, elements of `sound-alist' may also be:
1001 * `( sound-name . <sound> )'
1003 * `( sound-name <volume> <sound> )'
1005 You should probably add things to this list by calling the function
1010 - You can only play audio data if running on the console screen
1011 of a Sun SparcStation, SGI, or HP9000s700.
1013 - The pitch, duration, and volume options are available
1014 everywhere, but many X servers ignore the `pitch' option.
1016 The following beep-types are used by XEmacs itself:
1019 when an auto-save does not succeed
1022 when the XEmacs command loop catches an error
1025 when you type a key that is undefined
1028 when you use an undefined mouse-click combination
1031 during completing-read
1034 when you type something other than 'y' or 'n'
1037 when you type something other than 'yes' or 'no'
1040 used when nothing else is appropriate.
1042 Other lisp packages may use other beep types, but these are the
1043 ones that the C kernel of XEmacs uses.
1045 - User Option: bell-volume
1046 This variable specifies the default volume for sounds, from 0 to
1049 - Command: load-default-sounds
1050 This function loads and installs some sound files as beep-types.
1052 - Command: load-sound-file filename sound-name &optional volume
1053 This function reads in an audio file and adds it to `sound-alist'.
1054 The sound file must be in the Sun/NeXT U-LAW format. SOUND-NAME
1055 should be a symbol, specifying the name of the sound. If VOLUME
1056 is specified, the sound will be played at that volume; otherwise,
1057 the value of BELL-VOLUME will be used.
1059 - Function: play-sound sound &optional volume device
1060 This function plays sound SOUND, which should be a symbol
1061 mentioned in `sound-alist'. If VOLUME is specified, it overrides
1062 the value (if any) specified in `sound-alist'. DEVICE specifies
1063 the device to play the sound on, and defaults to the selected
1066 - Command: play-sound-file file &optional volume device
1067 This function plays the named sound file at volume VOLUME, which
1068 defaults to `bell-volume'. DEVICE specifies the device to play
1069 the sound on, and defaults to the selected device.
1072 File: lispref.info, Node: Hash Tables, Next: Range Tables, Prev: Display, Up: Top
1077 - Function: hash-table-p object
1078 This function returns `t' if OBJECT is a hash table, else `nil'.
1082 * Introduction to Hash Tables:: Hash tables are fast data structures for
1083 implementing simple tables (i.e. finite
1084 mappings from keys to values).
1085 * Working With Hash Tables:: Hash table functions.
1086 * Weak Hash Tables:: Hash tables with special garbage-collection
1090 File: lispref.info, Node: Introduction to Hash Tables, Next: Working With Hash Tables, Up: Hash Tables
1092 Introduction to Hash Tables
1093 ===========================
1095 A "hash table" is a data structure that provides mappings from
1096 arbitrary Lisp objects called "keys" to other arbitrary Lisp objects
1097 called "values". A key/value pair is sometimes called an "entry" in
1098 the hash table. There are many ways other than hash tables of
1099 implementing the same sort of mapping, e.g. association lists (*note
1100 Association Lists::) and property lists (*note Property Lists::), but
1101 hash tables provide much faster lookup when there are many entries in
1102 the mapping. Hash tables are an implementation of the abstract data
1103 type "dictionary", also known as "associative array".
1105 Internally, hash tables are hashed using the "linear probing" hash
1106 table implementation method. This method hashes each key to a
1107 particular spot in the hash table, and then scans forward sequentially
1108 until a blank entry is found. To look up a key, hash to the appropriate
1109 spot, then search forward for the key until either a key is found or a
1110 blank entry stops the search. This method is used in preference to
1111 double hashing because of changes in recent hardware. The penalty for
1112 non-sequential access to memory has been increasing, and this
1113 compensates for the problem of clustering that linear probing entails.
1115 When hash tables are created, the user may (but is not required to)
1116 specify initial properties that influence performance.
1118 Use the `:size' parameter to specify the number of entries that are
1119 likely to be stored in the hash table, to avoid the overhead of resizing
1120 the table. But if the pre-allocated space for the entries is never
1121 used, it is simply wasted and makes XEmacs slower. Excess unused hash
1122 table entries exact a small continuous performance penalty, since they
1123 must be scanned at every garbage collection. If the number of entries
1124 in the hash table is unknown, simply avoid using the `:size' keyword.
1126 Use the `:rehash-size' and `:rehash-threshold' keywords to adjust
1127 the algorithm for deciding when to rehash the hash table. For
1128 temporary hash tables that are going to be very heavily used, use a
1129 small rehash threshold, for example, 0.4 and a large rehash size, for
1130 example 2.0. For permanent hash tables that will be infrequently used,
1131 specify a large rehash threshold, for example 0.8.
1133 Hash tables can also be created by the lisp reader using structure
1134 syntax, for example:
1135 #s(hash-table size 20 data (foo 1 bar 2))
1137 The structure syntax accepts the same keywords as `make-hash-table'
1138 (without the `:' character), as well as the additional keyword `data',
1139 which specifies the initial hash table contents.
1141 - Function: make-hash-table &key `test' `size' `rehash-size'
1142 `rehash-threshold' `weakness'
1143 This function returns a new empty hash table object.
1145 Keyword `:test' can be `eq', `eql' (default) or `equal'.
1146 Comparison between keys is done using this function. If speed is
1147 important, consider using `eq'. When storing strings in the hash
1148 table, you will likely need to use `equal'.
1150 Keyword `:size' specifies the number of keys likely to be inserted.
1151 This number of entries can be inserted without enlarging the hash
1154 Keyword `:rehash-size' must be a float greater than 1.0, and
1155 specifies the factor by which to increase the size of the hash
1156 table when enlarging.
1158 Keyword `:rehash-threshold' must be a float between 0.0 and 1.0,
1159 and specifies the load factor of the hash table which triggers
1162 Keyword `:weakness' can be `nil' (default), `t', `key' or `value'.
1164 A weak hash table is one whose pointers do not count as GC
1165 referents: for any key-value pair in the hash table, if the only
1166 remaining pointer to either the key or the value is in a weak hash
1167 table, then the pair will be removed from the hash table, and the
1168 key and value collected. A non-weak hash table (or any other
1169 pointer) would prevent the object from being collected.
1171 A key-weak hash table is similar to a fully-weak hash table except
1172 that a key-value pair will be removed only if the key remains
1173 unmarked outside of weak hash tables. The pair will remain in the
1174 hash table if the key is pointed to by something other than a weak
1175 hash table, even if the value is not.
1177 A value-weak hash table is similar to a fully-weak hash table
1178 except that a key-value pair will be removed only if the value
1179 remains unmarked outside of weak hash tables. The pair will
1180 remain in the hash table if the value is pointed to by something
1181 other than a weak hash table, even if the key is not.
1183 - Function: copy-hash-table hash-table
1184 This function returns a new hash table which contains the same
1185 keys and values as HASH-TABLE. The keys and values will not
1186 themselves be copied.
1188 - Function: hash-table-count hash-table
1189 This function returns the number of entries in HASH-TABLE.
1191 - Function: hash-table-test hash-table
1192 This function returns the test function of HASH-TABLE. This can
1193 be one of `eq', `eql' or `equal'.
1195 - Function: hash-table-size hash-table
1196 This function returns the current number of slots in HASH-TABLE,
1197 whether occupied or not.
1199 - Function: hash-table-rehash-size hash-table
1200 This function returns the current rehash size of HASH-TABLE. This
1201 is a float greater than 1.0; the factor by which HASH-TABLE is
1202 enlarged when the rehash threshold is exceeded.
1204 - Function: hash-table-rehash-threshold hash-table
1205 This function returns the current rehash threshold of HASH-TABLE.
1206 This is a float between 0.0 and 1.0; the maximum "load factor" of
1207 HASH-TABLE, beyond which the HASH-TABLE is enlarged by rehashing.
1209 - Function: hash-table-weakness hash-table
1210 This function returns the weakness of HASH-TABLE. This can be one
1211 of `nil', `t', `key' or `value'.
1214 File: lispref.info, Node: Working With Hash Tables, Next: Weak Hash Tables, Prev: Introduction to Hash Tables, Up: Hash Tables
1216 Working With Hash Tables
1217 ========================
1219 - Function: puthash key value hash-table
1220 This function hashes KEY to VALUE in HASH-TABLE.
1222 - Function: gethash key hash-table &optional default
1223 This function finds the hash value for KEY in HASH-TABLE. If
1224 there is no entry for KEY in HASH-TABLE, DEFAULT is returned
1225 (which in turn defaults to `nil').
1227 - Function: remhash key hash-table
1228 This function removes the entry for KEY from HASH-TABLE. Does
1229 nothing if there is no entry for KEY in HASH-TABLE.
1231 - Function: clrhash hash-table
1232 This function removes all entries from HASH-TABLE, leaving it
1235 - Function: maphash function hash-table
1236 This function maps FUNCTION over entries in HASH-TABLE, calling it
1237 with two args, each key and value in the hash table.
1239 FUNCTION may not modify HASH-TABLE, with the one exception that
1240 FUNCTION may remhash or puthash the entry currently being
1241 processed by FUNCTION.