1 This is ../info/lispref.info, produced by makeinfo version 4.0b 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: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls
55 Specification Examples
56 ......................
58 Here we provide several examples of Edebug specifications to show
59 many of its capabilities.
61 A `let' special form has a sequence of bindings and a body. Each of
62 the bindings is either a symbol or a sublist with a symbol and optional
63 value. In the specification below, notice the `gate' inside of the
64 sublist to prevent backtracking.
68 &or symbolp (gate symbolp &optional form))
71 Edebug uses the following specifications for `defun' and `defmacro'
72 and the associated argument list and `interactive' specifications. It
73 is necessary to handle the expression argument of an interactive form
74 specially since it is actually evaluated outside of the function body.
76 (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec
77 (def-edebug-spec defun
78 (&define name lambda-list
79 [&optional stringp] ; Match the doc string, if present.
80 [&optional ("interactive" interactive)]
83 (def-edebug-spec lambda-list
85 [&optional ["&optional" arg &rest arg]]
86 &optional ["&rest" arg]
89 (def-edebug-spec interactive
90 (&optional &or stringp def-form)) ; Notice: `def-form'
92 The specification for backquote below illustrates how to match
93 dotted lists and use `nil' to terminate recursion. It also illustrates
94 how components of a vector may be matched. (The actual specification
95 provided by Edebug does not support dotted lists because doing so
96 causes very deep recursion that could fail.)
98 (def-edebug-spec ` (backquote-form)) ;; alias just for clarity
100 (def-edebug-spec backquote-form
101 (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
102 (backquote-form . [&or nil backquote-form])
103 (vector &rest backquote-form)
107 File: lispref.info, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug
112 These options affect the behavior of Edebug:
114 - User Option: edebug-setup-hook
115 Functions to call before Edebug is used. Each time it is set to a
116 new value, Edebug will call those functions once and then
117 `edebug-setup-hook' is reset to `nil'. You could use this to load
118 up Edebug specifications associated with a package you are using
119 but only when you also use Edebug. See *Note Instrumenting::.
121 - User Option: edebug-all-defs
122 If non-`nil', normal evaluation of any defining forms (e.g.
123 `defun' and `defmacro') will instrument them for Edebug. This
124 applies to `eval-defun', `eval-region', and `eval-current-buffer'.
126 Use the command `M-x edebug-all-defs' to toggle the value of this
127 variable. You may want to make this variable local to each buffer
128 by calling `(make-local-variable 'edebug-all-defs)' in your
129 `emacs-lisp-mode-hook'. See *Note Instrumenting::.
131 - User Option: edebug-all-forms
132 If non-`nil', normal evaluation of any forms by `eval-defun',
133 `eval-region', and `eval-current-buffer' will instrument them for
136 Use the command `M-x edebug-all-forms' to toggle the value of this
137 option. See *Note Instrumenting::.
139 - User Option: edebug-save-windows
140 If non-`nil', save and restore window configuration on Edebug
141 calls. It takes some time to do this, so if your program does not
142 care what happens to data about windows, you may want to set this
145 If the value is a list, only the listed windows are saved and
148 `M-x edebug-toggle-save-windows' may be used to change this
149 variable. This command is bound to `W' in source code buffers.
150 See *Note Edebug Display Update::.
152 - User Option: edebug-save-displayed-buffer-points
153 If non-`nil', save and restore point in all displayed buffers.
154 This is necessary if you are debugging code that changes the point
155 of a buffer which is displayed in a non-selected window. If
156 Edebug or the user then selects the window, the buffer's point
157 will be changed to the window's point.
159 This is an expensive operation since it visits each window and
160 therefore each displayed buffer twice for each Edebug activation,
161 so it is best to avoid it if you can. See *Note Edebug Display
164 - User Option: edebug-initial-mode
165 If this variable is non-`nil', it specifies the initial execution
166 mode for Edebug when it is first activated. Possible values are
167 `step', `next', `go', `Go-nonstop', `trace', `Trace-fast',
168 `continue', and `Continue-fast'.
170 The default value is `step'. See *Note Edebug Execution Modes::.
172 - User Option: edebug-trace
173 Non-`nil' means display a trace of function entry and exit.
174 Tracing output is displayed in a buffer named `*edebug-trace*', one
175 function entry or exit per line, indented by the recursion level.
177 The default value is `nil'.
179 Also see `edebug-tracing'. See *Note Tracing::.
181 - User Option: edebug-test-coverage
182 If non-`nil', Edebug tests coverage of all expressions debugged.
183 This is done by comparing the result of each expression with the
184 previous result. Coverage is considered OK if two different
185 results are found. So to sufficiently test the coverage of your
186 code, try to execute it under conditions that evaluate all
187 expressions more than once, and produce different results for each
190 Use `M-x edebug-display-freq-count' to display the frequency count
191 and coverage information for a definition. See *Note Coverage
194 - User Option: edebug-continue-kbd-macro
195 If non-`nil', continue defining or executing any keyboard macro
196 that is executing outside of Edebug. Use this with caution since
197 it is not debugged. See *Note Edebug Execution Modes::.
199 - User Option: edebug-print-length
200 If non-`nil', bind `print-length' to this while printing results
201 in Edebug. The default value is `50'. See *Note Printing in
204 - User Option: edebug-print-level
205 If non-`nil', bind `print-level' to this while printing results in
206 Edebug. The default value is `50'.
208 - User Option: edebug-print-circle
209 If non-`nil', bind `print-circle' to this while printing results
210 in Edebug. The default value is `nil'.
212 - User Option: edebug-on-error
213 `debug-on-error' is bound to this while Edebug is active. See
214 *Note Trapping Errors::.
216 - User Option: edebug-on-quit
217 `debug-on-quit' is bound to this while Edebug is active. See
218 *Note Trapping Errors::.
220 - User Option: edebug-unwrap-results
221 Non-`nil' if Edebug should unwrap results of expressions. This is
222 useful when debugging macros where the results of expressions are
223 instrumented expressions. But don't do this when results might be
224 circular or an infinite loop will result. See *Note Debugging
227 - User Option: edebug-global-break-condition
228 If non-`nil', an expression to test for at every stop point. If
229 the result is non-`nil', then break. Errors are ignored. See
230 *Note Global Break Condition::.
233 File: lispref.info, Node: Read and Print, Next: Minibuffers, Prev: Debugging, Up: Top
235 Reading and Printing Lisp Objects
236 *********************************
238 "Printing" and "reading" are the operations of converting Lisp
239 objects to textual form and vice versa. They use the printed
240 representations and read syntax described in *Note Lisp Data Types::.
242 This chapter describes the Lisp functions for reading and printing.
243 It also describes "streams", which specify where to get the text (if
244 reading) or where to put it (if printing).
248 * Streams Intro:: Overview of streams, reading and printing.
249 * Input Streams:: Various data types that can be used as input streams.
250 * Input Functions:: Functions to read Lisp objects from text.
251 * Output Streams:: Various data types that can be used as output streams.
252 * Output Functions:: Functions to print Lisp objects as text.
253 * Output Variables:: Variables that control what the printing functions do.
256 File: lispref.info, Node: Streams Intro, Next: Input Streams, Up: Read and Print
258 Introduction to Reading and Printing
259 ====================================
261 "Reading" a Lisp object means parsing a Lisp expression in textual
262 form and producing a corresponding Lisp object. This is how Lisp
263 programs get into Lisp from files of Lisp code. We call the text the
264 "read syntax" of the object. For example, the text `(a . 5)' is the
265 read syntax for a cons cell whose CAR is `a' and whose CDR is the
268 "Printing" a Lisp object means producing text that represents that
269 object--converting the object to its printed representation. Printing
270 the cons cell described above produces the text `(a . 5)'.
272 Reading and printing are more or less inverse operations: printing
273 the object that results from reading a given piece of text often
274 produces the same text, and reading the text that results from printing
275 an object usually produces a similar-looking object. For example,
276 printing the symbol `foo' produces the text `foo', and reading that text
277 returns the symbol `foo'. Printing a list whose elements are `a' and
278 `b' produces the text `(a b)', and reading that text produces a list
279 (but not the same list) with elements `a' and `b'.
281 However, these two operations are not precisely inverses. There are
282 three kinds of exceptions:
284 * Printing can produce text that cannot be read. For example,
285 buffers, windows, frames, subprocesses and markers print into text
286 that starts with `#'; if you try to read this text, you get an
287 error. There is no way to read those data types.
289 * One object can have multiple textual representations. For example,
290 `1' and `01' represent the same integer, and `(a b)' and `(a .
291 (b))' represent the same list. Reading will accept any of the
292 alternatives, but printing must choose one of them.
294 * Comments can appear at certain points in the middle of an object's
295 read sequence without affecting the result of reading it.
298 File: lispref.info, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print
303 Most of the Lisp functions for reading text take an "input stream"
304 as an argument. The input stream specifies where or how to get the
305 characters of the text to be read. Here are the possible types of input
309 The input characters are read from BUFFER, starting with the
310 character directly after point. Point advances as characters are
314 The input characters are read from the buffer that MARKER is in,
315 starting with the character directly after the marker. The marker
316 position advances as characters are read. The value of point in
317 the buffer has no effect when the stream is a marker.
320 The input characters are taken from STRING, starting at the first
321 character in the string and using as many characters as required.
324 The input characters are generated by FUNCTION, one character per
325 call. Normally FUNCTION is called with no arguments, and should
328 Occasionally FUNCTION is called with one argument (always a
329 character). When that happens, FUNCTION should save the argument
330 and arrange to return it on the next call. This is called
331 "unreading" the character; it happens when the Lisp reader reads
332 one character too many and wants to "put it back where it came
336 `t' used as a stream means that the input is read from the
337 minibuffer. In fact, the minibuffer is invoked once and the text
338 given by the user is made into a string that is then used as the
342 `nil' supplied as an input stream means to use the value of
343 `standard-input' instead; that value is the "default input
344 stream", and must be a non-`nil' input stream.
347 A symbol as input stream is equivalent to the symbol's function
350 Here is an example of reading from a stream that is a buffer, showing
351 where point is located before and after:
353 ---------- Buffer: foo ----------
354 This-!- is the contents of foo.
355 ---------- Buffer: foo ----------
357 (read (get-buffer "foo"))
359 (read (get-buffer "foo"))
362 ---------- Buffer: foo ----------
363 This is the-!- contents of foo.
364 ---------- Buffer: foo ----------
366 Note that the first read skips a space. Reading skips any amount of
367 whitespace preceding the significant text.
369 In Emacs 18, reading a symbol discarded the delimiter terminating the
370 symbol. Thus, point would end up at the beginning of `contents' rather
371 than after `the'. The Emacs 19 behavior is superior because it
372 correctly handles input such as `bar(foo)', where the open-parenthesis
373 that ends one object is needed as the beginning of another object.
375 Here is an example of reading from a stream that is a marker,
376 initially positioned at the beginning of the buffer shown. The value
377 read is the symbol `This'.
380 ---------- Buffer: foo ----------
381 This is the contents of foo.
382 ---------- Buffer: foo ----------
384 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
385 => #<marker at 1 in foo>
389 => #<marker at 5 in foo> ;; Before the first space.
391 Here we read from the contents of a string:
393 (read "(When in) the course")
396 The following example reads from the minibuffer. The prompt is:
397 `Lisp expression: '. (That is always the prompt used when you read
398 from the stream `t'.) The user's input is shown following the prompt.
402 ---------- Buffer: Minibuffer ----------
403 Lisp expression: 23 <RET>
404 ---------- Buffer: Minibuffer ----------
406 Finally, here is an example of a stream that is a function, named
407 `useless-stream'. Before we use the stream, we initialize the variable
408 `useless-list' to a list of characters. Then each call to the function
409 `useless-stream' obtains the next character in the list or unreads a
410 character by adding it to the front of the list.
412 (setq useless-list (append "XY()" nil))
415 (defun useless-stream (&optional unread)
417 (setq useless-list (cons unread useless-list))
418 (prog1 (car useless-list)
419 (setq useless-list (cdr useless-list)))))
422 Now we read using the stream thus constructed:
424 (read 'useless-stream)
430 Note that the open and close parentheses remains in the list. The Lisp
431 reader encountered the open parenthesis, decided that it ended the
432 input, and unread it. Another attempt to read from the stream at this
433 point would read `()' and return `nil'.
436 File: lispref.info, Node: Input Functions, Next: Output Streams, Prev: Input Streams, Up: Read and Print
441 This section describes the Lisp functions and variables that pertain
444 In the functions below, STREAM stands for an input stream (see the
445 previous section). If STREAM is `nil' or omitted, it defaults to the
446 value of `standard-input'.
448 An `end-of-file' error is signaled if reading encounters an
449 unterminated list, vector, or string.
451 - Function: read &optional stream
452 This function reads one textual Lisp expression from STREAM,
453 returning it as a Lisp object. This is the basic Lisp input
456 - Function: read-from-string string &optional start end
457 This function reads the first textual Lisp expression from the
458 text in STRING. It returns a cons cell whose CAR is that
459 expression, and whose CDR is an integer giving the position of the
460 next remaining character in the string (i.e., the first one not
463 If START is supplied, then reading begins at index START in the
464 string (where the first character is at index 0). If END is also
465 supplied, then reading stops just before that index, as if the rest
466 of the string were not there.
470 (read-from-string "(setq x 55) (setq y 5)")
471 => ((setq x 55) . 11)
472 (read-from-string "\"A short string\"")
473 => ("A short string" . 16)
475 ;; Read starting at the first character.
476 (read-from-string "(list 112)" 0)
478 ;; Read starting at the second character.
479 (read-from-string "(list 112)" 1)
481 ;; Read starting at the seventh character,
482 ;; and stopping at the ninth.
483 (read-from-string "(list 112)" 6 8)
486 - Variable: standard-input
487 This variable holds the default input stream--the stream that
488 `read' uses when the STREAM argument is `nil'.
491 File: lispref.info, Node: Output Streams, Next: Output Functions, Prev: Input Functions, Up: Read and Print
496 An output stream specifies what to do with the characters produced
497 by printing. Most print functions accept an output stream as an
498 optional argument. Here are the possible types of output stream:
501 The output characters are inserted into BUFFER at point. Point
502 advances as characters are inserted.
505 The output characters are inserted into the buffer that MARKER
506 points into, at the marker position. The marker position advances
507 as characters are inserted. The value of point in the buffer has
508 no effect on printing when the stream is a marker.
511 The output characters are passed to FUNCTION, which is responsible
512 for storing them away. It is called with a single character as
513 argument, as many times as there are characters to be output, and
514 is free to do anything at all with the characters it receives.
517 The output characters are displayed in the echo area.
520 `nil' specified as an output stream means to the value of
521 `standard-output' instead; that value is the "default output
522 stream", and must be a non-`nil' output stream.
525 A symbol as output stream is equivalent to the symbol's function
528 Many of the valid output streams are also valid as input streams.
529 The difference between input and output streams is therefore mostly one
530 of how you use a Lisp object, not a distinction of types of object.
532 Here is an example of a buffer used as an output stream. Point is
533 initially located as shown immediately before the `h' in `the'. At the
534 end, point is located directly before that same `h'.
536 ---------- Buffer: foo ----------
537 This is t-!-he contents of foo.
538 ---------- Buffer: foo ----------
540 (print "This is the output" (get-buffer "foo"))
541 => "This is the output"
543 ---------- Buffer: foo ----------
546 -!-he contents of foo.
547 ---------- Buffer: foo ----------
549 Now we show a use of a marker as an output stream. Initially, the
550 marker is in buffer `foo', between the `t' and the `h' in the word
551 `the'. At the end, the marker has advanced over the inserted text so
552 that it remains positioned before the same `h'. Note that the location
553 of point, shown in the usual fashion, has no effect.
555 ---------- Buffer: foo ----------
556 "This is the -!-output"
557 ---------- Buffer: foo ----------
560 => #<marker at 11 in foo>
562 (print "More output for foo." m)
563 => "More output for foo."
565 ---------- Buffer: foo ----------
567 "More output for foo."
569 ---------- Buffer: foo ----------
572 => #<marker at 35 in foo>
574 The following example shows output to the echo area:
576 (print "Echo Area output" t)
577 => "Echo Area output"
578 ---------- Echo Area ----------
580 ---------- Echo Area ----------
582 Finally, we show the use of a function as an output stream. The
583 function `eat-output' takes each character that it is given and conses
584 it onto the front of the list `last-output' (*note Building Lists::).
585 At the end, the list contains all the characters output, but in reverse
588 (setq last-output nil)
591 (defun eat-output (c)
592 (setq last-output (cons c last-output)))
595 (print "This is the output" 'eat-output)
596 => "This is the output"
599 => (?\n ?\" ?t ?u ?p ?t ?u ?o ?\ ?e ?h ?t
600 ?\ ?s ?i ?\ ?s ?i ?h ?T ?\" ?\n)
602 Now we can put the output in the proper order by reversing the list:
604 (concat (nreverse last-output))
606 \"This is the output\"
609 Calling `concat' converts the list to a string so you can see its
610 contents more clearly.
613 File: lispref.info, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Read and Print
618 This section describes the Lisp functions for printing Lisp objects.
620 Some of the XEmacs printing functions add quoting characters to the
621 output when necessary so that it can be read properly. The quoting
622 characters used are `"' and `\'; they distinguish strings from symbols,
623 and prevent punctuation characters in strings and symbols from being
624 taken as delimiters when reading. *Note Printed Representation::, for
625 full details. You specify quoting or no quoting by the choice of
628 If the text is to be read back into Lisp, then it is best to print
629 with quoting characters to avoid ambiguity. Likewise, if the purpose is
630 to describe a Lisp object clearly for a Lisp programmer. However, if
631 the purpose of the output is to look nice for humans, then it is better
632 to print without quoting.
634 Printing a self-referent Lisp object requires an infinite amount of
635 text. In certain cases, trying to produce this text leads to a stack
636 overflow. XEmacs detects such recursion and prints `#LEVEL' instead of
637 recursively printing an object already being printed. For example,
638 here `#0' indicates a recursive reference to the object at level 0 of
639 the current print operation:
641 (setq foo (list nil))
646 In the functions below, STREAM stands for an output stream. (See
647 the previous section for a description of output streams.) If STREAM
648 is `nil' or omitted, it defaults to the value of `standard-output'.
650 - Function: print object &optional stream
651 The `print' function is a convenient way of printing. It outputs
652 the printed representation of OBJECT to STREAM, printing in
653 addition one newline before OBJECT and another after it. Quoting
654 characters are used. `print' returns OBJECT. For example:
656 (progn (print 'The\ cat\ in)
658 (print " came back"))
668 - Function: prin1 object &optional stream
669 This function outputs the printed representation of OBJECT to
670 STREAM. It does not print newlines to separate output as `print'
671 does, but it does use quoting characters just like `print'. It
674 (progn (prin1 'The\ cat\ in)
676 (prin1 " came back"))
677 -| The\ cat\ in"the hat"" came back"
680 - Function: princ object &optional stream
681 This function outputs the printed representation of OBJECT to
682 STREAM. It returns OBJECT.
684 This function is intended to produce output that is readable by
685 people, not by `read', so it doesn't insert quoting characters and
686 doesn't put double-quotes around the contents of strings. It does
687 not add any spacing between calls.
691 (princ " in the \"hat\""))
692 -| The cat in the "hat"
695 - Function: terpri &optional stream
696 This function outputs a newline to STREAM. The name stands for
699 - Function: write-char character &optional stream
700 This function outputs CHARACTER to STREAM. It returns CHARACTER.
702 - Function: prin1-to-string object &optional noescape
703 This function returns a string containing the text that `prin1'
704 would have printed for the same argument.
706 (prin1-to-string 'foo)
708 (prin1-to-string (mark-marker))
709 => "#<marker at 2773 in strings.texi>"
711 If NOESCAPE is non-`nil', that inhibits use of quoting characters
712 in the output. (This argument is supported in Emacs versions 19
715 (prin1-to-string "foo")
717 (prin1-to-string "foo" t)
720 See `format', in *Note String Conversion::, for other ways to
721 obtain the printed representation of a Lisp object as a string.
724 File: lispref.info, Node: Output Variables, Prev: Output Functions, Up: Read and Print
726 Variables Affecting Output
727 ==========================
729 - Variable: standard-output
730 The value of this variable is the default output stream--the stream
731 that print functions use when the STREAM argument is `nil'.
733 - Variable: print-escape-newlines
734 If this variable is non-`nil', then newline characters in strings
735 are printed as `\n' and formfeeds are printed as `\f'. Normally
736 these characters are printed as actual newlines and formfeeds.
738 This variable affects the print functions `prin1' and `print', as
739 well as everything that uses them. It does not affect `princ'.
740 Here is an example using `prin1':
748 (let ((print-escape-newlines t))
754 In the second expression, the local binding of
755 `print-escape-newlines' is in effect during the call to `prin1',
756 but not during the printing of the result.
758 - Variable: print-readably
759 If non-`nil', then all objects will be printed in a readable form.
760 If an object has no readable representation, then an error is
761 signalled. When `print-readably' is true, compiled-function
762 objects will be written in `#[...]' form instead of in
763 `#<compiled-function [...]>' form, and two-element lists of the
764 form `(quote object)' will be written as the equivalent `'object'.
765 Do not _set_ this variable; bind it instead.
767 - Variable: print-length
768 The value of this variable is the maximum number of elements of a
769 list that will be printed. If a list being printed has more than
770 this many elements, it is abbreviated with an ellipsis.
772 If the value is `nil' (the default), then there is no limit.
774 (setq print-length 2)
780 - Variable: print-level
781 The value of this variable is the maximum depth of nesting of
782 parentheses and brackets when printed. Any list or vector at a
783 depth exceeding this limit is abbreviated with an ellipsis. A
784 value of `nil' (which is the default) means no limit.
786 This variable exists in version 19 and later versions.
788 - Variable: print-string-length
789 The value of this variable is the maximum number of characters of
790 a string that will be printed. If a string being printed has more
791 than this many characters, it is abbreviated with an ellipsis.
793 - Variable: print-gensym
794 If non-`nil', then uninterned symbols will be printed specially.
795 Uninterned symbols are those which are not present in `obarray',
796 that is, those which were made with `make-symbol' or by calling
797 `intern' with a second argument.
799 When `print-gensym' is true, such symbols will be preceded by
800 `#:', which causes the reader to create a new symbol instead of
801 interning and returning an existing one. Beware: The `#:' syntax
802 creates a new symbol each time it is seen, so if you print an
803 object which contains two pointers to the same uninterned symbol,
804 `read' will not duplicate that structure.
806 Also, since XEmacs has no real notion of packages, there is no way
807 for the printer to distinguish between symbols interned in no
808 obarray, and symbols interned in an alternate obarray.
810 - Variable: float-output-format
811 This variable holds the format descriptor string that Lisp uses to
812 print floats. This is a `%'-spec like those accepted by `printf'
813 in C, but with some restrictions. It must start with the two
814 characters `%.'. After that comes an integer precision
815 specification, and then a letter which controls the format. The
816 letters allowed are `e', `f' and `g'.
818 * Use `e' for exponential notation `DIG.DIGITSeEXPT'.
820 * Use `f' for decimal point notation `DIGITS.DIGITS'.
822 * Use `g' to choose the shorter of those two formats for the
825 The precision in any of these cases is the number of digits
826 following the decimal point. With `f', a precision of 0 means to
827 omit the decimal point. 0 is not allowed with `f' or `g'.
829 A value of `nil' means to use `%.16g'.
831 Regardless of the value of `float-output-format', a floating point
832 number will never be printed in such a way that it is ambiguous
833 with an integer; that is, a floating-point number will always be
834 printed with a decimal point and/or an exponent, even if the
835 digits following the decimal point are all zero. This is to
836 preserve read-equivalence.
839 File: lispref.info, Node: Minibuffers, Next: Command Loop, Prev: Read and Print, Up: Top
844 A "minibuffer" is a special buffer that XEmacs commands use to read
845 arguments more complicated than the single numeric prefix argument.
846 These arguments include file names, buffer names, and command names (as
847 in `M-x'). The minibuffer is displayed on the bottom line of the
848 frame, in the same place as the echo area, but only while it is in use
849 for reading an argument.
853 * Intro to Minibuffers:: Basic information about minibuffers.
854 * Text from Minibuffer:: How to read a straight text string.
855 * Object from Minibuffer:: How to read a Lisp object or expression.
856 * Minibuffer History:: Recording previous minibuffer inputs
857 so the user can reuse them.
858 * Completion:: How to invoke and customize completion.
859 * Yes-or-No Queries:: Asking a question with a simple answer.
860 * Multiple Queries:: Asking a series of similar questions.
861 * Reading a Password:: Reading a password from the terminal.
862 * Minibuffer Misc:: Various customization hooks and variables.
865 File: lispref.info, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers
867 Introduction to Minibuffers
868 ===========================
870 In most ways, a minibuffer is a normal XEmacs buffer. Most
871 operations _within_ a buffer, such as editing commands, work normally
872 in a minibuffer. However, many operations for managing buffers do not
873 apply to minibuffers. The name of a minibuffer always has the form
874 ` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are
875 displayed only in special windows used only for minibuffers; these
876 windows always appear at the bottom of a frame. (Sometimes frames have
877 no minibuffer window, and sometimes a special kind of frame contains
878 nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
880 The minibuffer's window is normally a single line. You can resize it
881 temporarily with the window sizing commands; it reverts to its normal
882 size when the minibuffer is exited. You can resize it permanently by
883 using the window sizing commands in the frame's other window, when the
884 minibuffer is not active. If the frame contains just a minibuffer, you
885 can change the minibuffer's size by changing the frame's size.
887 If a command uses a minibuffer while there is an active minibuffer,
888 this is called a "recursive minibuffer". The first minibuffer is named
889 ` *Minibuf-0*'. Recursive minibuffers are named by incrementing the
890 number at the end of the name. (The names begin with a space so that
891 they won't show up in normal buffer lists.) Of several recursive
892 minibuffers, the innermost (or most recently entered) is the active
893 minibuffer. We usually call this "the" minibuffer. You can permit or
894 forbid recursive minibuffers by setting the variable
895 `enable-recursive-minibuffers'.
897 Like other buffers, a minibuffer may use any of several local keymaps
898 (*note Keymaps::); these contain various exit commands and in some cases
899 completion commands (*note Completion::).
901 * `minibuffer-local-map' is for ordinary input (no completion).
903 * `minibuffer-local-completion-map' is for permissive completion.
905 * `minibuffer-local-must-match-map' is for strict completion and for
909 File: lispref.info, Node: Text from Minibuffer, Next: Object from Minibuffer, Prev: Intro to Minibuffers, Up: Minibuffers
911 Reading Text Strings with the Minibuffer
912 ========================================
914 Most often, the minibuffer is used to read text as a string. It can
915 also be used to read a Lisp object in textual form. The most basic
916 primitive for minibuffer input is `read-from-minibuffer'; it can do
919 In most cases, you should not call minibuffer input functions in the
920 middle of a Lisp function. Instead, do all minibuffer input as part of
921 reading the arguments for a command, in the `interactive' spec. *Note
924 - Function: read-from-minibuffer prompt-string &optional
925 initial-contents keymap read hist abbrev-table default
926 This function is the most general way to get input through the
927 minibuffer. By default, it accepts arbitrary text and returns it
928 as a string; however, if READ is non-`nil', then it uses `read' to
929 convert the text into a Lisp object (*note Input Functions::).
931 The first thing this function does is to activate a minibuffer and
932 display it with PROMPT-STRING as the prompt. This value must be a
935 Then, if INITIAL-CONTENTS is a string, `read-from-minibuffer'
936 inserts it into the minibuffer, leaving point at the end. The
937 minibuffer appears with this text as its contents.
939 The value of INITIAL-CONTENTS may also be a cons cell of the form
940 `(STRING . POSITION)'. This means to insert STRING in the
941 minibuffer but put point POSITION characters from the beginning,
942 rather than at the end.
944 When the user types a command to exit the minibuffer,
945 `read-from-minibuffer' constructs the return value from the text in
946 the minibuffer. Normally it returns a string containing that text.
947 However, if READ is non-`nil', `read-from-minibuffer' reads the
948 text and returns the resulting Lisp object, unevaluated. (*Note
949 Input Functions::, for information about reading.)
951 The argument DEFAULT specifies a default value to make available
952 through the history commands. It should be a string, or `nil'.
954 If KEYMAP is non-`nil', that keymap is the local keymap to use in
955 the minibuffer. If KEYMAP is omitted or `nil', the value of
956 `minibuffer-local-map' is used as the keymap. Specifying a keymap
957 is the most important way to customize the minibuffer for various
958 applications such as completion.
960 The argument ABBREV-TABLE specifies `local-abbrev-table' in the
961 minibuffer (*note Standard Abbrev Tables::).
963 The argument HIST specifies which history list variable to use for
964 saving the input and for history commands used in the minibuffer.
965 It defaults to `minibuffer-history'. *Note Minibuffer History::.
967 When the user types a command to exit the minibuffer,
968 `read-from-minibuffer' uses the text in the minibuffer to produce
969 its return value. Normally it simply makes a string containing
970 that text. However, if READ is non-`nil', `read-from-minibuffer'
971 reads the text and returns the resulting Lisp object, unevaluated.
972 (*Note Input Functions::, for information about reading.)
974 *Usage note:* The INITIAL-CONTENTS argument and the DEFAULT
975 argument are two alternative features for more or less the same
976 job. It does not make sense to use both features in a single call
977 to `read-from-minibuffer'. In general, we recommend using
978 DEFAULT, since this permits the user to insert the default value
979 when it is wanted, but does not burden the user with deleting it
980 from the minibuffer on other occasions. However, if user is
981 supposed to edit default value, INITIAL-CONTENTS may be preferred.
983 - Function: read-string prompt &optional initial history default-value
984 This function reads a string from the minibuffer and returns it.
985 The arguments PROMPT and INITIAL are used as in
986 `read-from-minibuffer'. The keymap used is `minibuffer-local-map'.
988 The optional argument HISTORY, if non-`nil', specifies a history
989 list and optionally the initial position in the list. The optional
990 argument DEFAULT-VALUE specifies a default value to return if the
991 user enters null input; it should be a string.
993 This function is a simplified interface to the
994 `read-from-minibuffer' function:
996 (read-string PROMPT INITIAL HISTORY DEFAULT)
998 (read-from-minibuffer PROMPT INITIAL nil nil
999 HISTORY nil DEFAULT)))
1001 - Variable: minibuffer-local-map
1002 This is the default local keymap for reading from the minibuffer.
1003 By default, it makes the following bindings:
1012 `abort-recursive-edit'
1015 `next-history-element'
1018 `previous-history-element'
1021 `next-matching-history-element'
1024 `previous-matching-history-element'
1027 File: lispref.info, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers
1029 Reading Lisp Objects with the Minibuffer
1030 ========================================
1032 This section describes functions for reading Lisp objects with the
1035 - Function: read-expression prompt &optional initial history
1037 This function reads a Lisp object using the minibuffer, and
1038 returns it without evaluating it. The arguments PROMPT and
1039 INITIAL are used as in `read-from-minibuffer'.
1041 The optional argument HISTORY, if non-`nil', specifies a history
1042 list and optionally the initial position in the list. The optional
1043 argument DEFAULT-VALUE specifies a default value to return if the
1044 user enters null input; it should be a string.
1046 This is a simplified interface to the `read-from-minibuffer'
1049 (read-expression PROMPT INITIAL HISTORY DEFAULT-VALUE)
1051 (read-from-minibuffer PROMPT INITIAL nil t
1052 HISTORY nil DEFAULT-VALUE)
1054 Here is an example in which we supply the string `"(testing)"' as
1058 "Enter an expression: " (format "%s" '(testing)))
1060 ;; Here is how the minibuffer is displayed:
1062 ---------- Buffer: Minibuffer ----------
1063 Enter an expression: (testing)-!-
1064 ---------- Buffer: Minibuffer ----------
1066 The user can type <RET> immediately to use the initial input as a
1067 default, or can edit the input.
1069 - Function: read-minibuffer prompt &optional initial history
1071 This is a FSF Emacs compatible function. Use `read-expression'
1074 - Function: eval-minibuffer prompt &optional initial history
1076 This function reads a Lisp expression using the minibuffer,
1077 evaluates it, then returns the result. The arguments PROMPT and
1078 INITIAL are used as in `read-from-minibuffer'.
1080 The optional argument HISTORY, if non-`nil', specifies a history
1081 list and optionally the initial position in the list. The optional
1082 argument DEFAULT-VALUE specifies a default value to return if the
1083 user enters null input; it should be a string.
1085 This function simply evaluates the result of a call to
1088 (eval-minibuffer PROMPT INITIAL)
1090 (eval (read-expression PROMPT INITIAL))
1092 - Function: edit-and-eval-command prompt form &optional history
1093 This function reads a Lisp expression in the minibuffer, and then
1094 evaluates it. The difference between this command and
1095 `eval-minibuffer' is that here the initial FORM is not optional
1096 and it is treated as a Lisp object to be converted to printed
1097 representation rather than as a string of text. It is printed with
1098 `prin1', so if it is a string, double-quote characters (`"')
1099 appear in the initial text. *Note Output Functions::.
1101 The first thing `edit-and-eval-command' does is to activate the
1102 minibuffer with PROMPT as the prompt. Then it inserts the printed
1103 representation of FORM in the minibuffer, and lets the user edit
1104 it. When the user exits the minibuffer, the edited text is read
1105 with `read' and then evaluated. The resulting value becomes the
1106 value of `edit-and-eval-command'.
1108 In the following example, we offer the user an expression with
1109 initial text which is a valid form already:
1111 (edit-and-eval-command "Please edit: " '(forward-word 1))
1113 ;; After evaluation of the preceding expression,
1114 ;; the following appears in the minibuffer:
1116 ---------- Buffer: Minibuffer ----------
1117 Please edit: (forward-word 1)-!-
1118 ---------- Buffer: Minibuffer ----------
1120 Typing <RET> right away would exit the minibuffer and evaluate the
1121 expression, thus moving point forward one word.
1122 `edit-and-eval-command' returns `t' in this example.
1125 File: lispref.info, Node: Minibuffer History, Next: Completion, Prev: Object from Minibuffer, Up: Minibuffers
1130 A "minibuffer history list" records previous minibuffer inputs so
1131 the user can reuse them conveniently. A history list is actually a
1132 symbol, not a list; it is a variable whose value is a list of strings
1133 (previous inputs), most recent first.
1135 There are many separate history lists, used for different kinds of
1136 inputs. It's the Lisp programmer's job to specify the right history
1137 list for each use of the minibuffer.
1139 The basic minibuffer input functions `read-from-minibuffer' and
1140 `completing-read' both accept an optional argument named HIST which is
1141 how you specify the history list. Here are the possible values:
1144 Use VARIABLE (a symbol) as the history list.
1146 (VARIABLE . STARTPOS)
1147 Use VARIABLE (a symbol) as the history list, and assume that the
1148 initial history position is STARTPOS (an integer, counting from
1149 zero which specifies the most recent element of the history).
1151 If you specify STARTPOS, then you should also specify that element
1152 of the history as the initial minibuffer contents, for consistency.
1154 If you don't specify HIST, then the default history list
1155 `minibuffer-history' is used. For other standard history lists, see
1156 below. You can also create your own history list variable; just
1157 initialize it to `nil' before the first use.
1159 Both `read-from-minibuffer' and `completing-read' add new elements
1160 to the history list automatically, and provide commands to allow the
1161 user to reuse items on the list. The only thing your program needs to
1162 do to use a history list is to initialize it and to pass its name to
1163 the input functions when you wish. But it is safe to modify the list
1164 by hand when the minibuffer input functions are not using it.
1166 Here are some of the standard minibuffer history list variables:
1168 - Variable: minibuffer-history
1169 The default history list for minibuffer history input.
1171 - Variable: query-replace-history
1172 A history list for arguments to `query-replace' (and similar
1173 arguments to other commands).
1175 - Variable: file-name-history
1176 A history list for file name arguments.
1178 - Variable: regexp-history
1179 A history list for regular expression arguments.
1181 - Variable: extended-command-history
1182 A history list for arguments that are names of extended commands.
1184 - Variable: shell-command-history
1185 A history list for arguments that are shell commands.
1187 - Variable: read-expression-history
1188 A history list for arguments that are Lisp expressions to evaluate.
1190 - Variable: Info-minibuffer-history
1191 A history list for Info mode's minibuffer.
1193 - Variable: Manual-page-minibuffer-history
1194 A history list for `manual-entry'.
1196 There are many other minibuffer history lists, defined by various
1197 libraries. An `M-x apropos' search for `history' should prove fruitful
1198 in discovering them.
1201 File: lispref.info, Node: Completion, Next: Yes-or-No Queries, Prev: Minibuffer History, Up: Minibuffers
1206 "Completion" is a feature that fills in the rest of a name starting
1207 from an abbreviation for it. Completion works by comparing the user's
1208 input against a list of valid names and determining how much of the
1209 name is determined uniquely by what the user has typed. For example,
1210 when you type `C-x b' (`switch-to-buffer') and then type the first few
1211 letters of the name of the buffer to which you wish to switch, and then
1212 type <TAB> (`minibuffer-complete'), Emacs extends the name as far as it
1215 Standard XEmacs commands offer completion for names of symbols,
1216 files, buffers, and processes; with the functions in this section, you
1217 can implement completion for other kinds of names.
1219 The `try-completion' function is the basic primitive for completion:
1220 it returns the longest determined completion of a given initial string,
1221 with a given set of strings to match against.
1223 The function `completing-read' provides a higher-level interface for
1224 completion. A call to `completing-read' specifies how to determine the
1225 list of valid names. The function then activates the minibuffer with a
1226 local keymap that binds a few keys to commands useful for completion.
1227 Other functions provide convenient simple interfaces for reading
1228 certain kinds of names with completion.
1232 * Basic Completion:: Low-level functions for completing strings.
1233 (These are too low level to use the minibuffer.)
1234 * Minibuffer Completion:: Invoking the minibuffer with completion.
1235 * Completion Commands:: Minibuffer commands that do completion.
1236 * High-Level Completion:: Convenient special cases of completion
1237 (reading buffer name, file name, etc.)
1238 * Reading File Names:: Using completion to read file names.
1239 * Programmed Completion:: Finding the completions for a given file name.