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: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug
58 These options affect the behavior of Edebug:
60 - User Option: edebug-setup-hook
61 Functions to call before Edebug is used. Each time it is set to a
62 new value, Edebug will call those functions once and then
63 `edebug-setup-hook' is reset to `nil'. You could use this to load
64 up Edebug specifications associated with a package you are using
65 but only when you also use Edebug. See *Note Instrumenting::.
67 - User Option: edebug-all-defs
68 If non-`nil', normal evaluation of any defining forms (e.g.
69 `defun' and `defmacro') will instrument them for Edebug. This
70 applies to `eval-defun', `eval-region', and `eval-current-buffer'.
72 Use the command `M-x edebug-all-defs' to toggle the value of this
73 variable. You may want to make this variable local to each buffer
74 by calling `(make-local-variable 'edebug-all-defs)' in your
75 `emacs-lisp-mode-hook'. See *Note Instrumenting::.
77 - User Option: edebug-all-forms
78 If non-`nil', normal evaluation of any forms by `eval-defun',
79 `eval-region', and `eval-current-buffer' will instrument them for
82 Use the command `M-x edebug-all-forms' to toggle the value of this
83 option. See *Note Instrumenting::.
85 - User Option: edebug-save-windows
86 If non-`nil', save and restore window configuration on Edebug
87 calls. It takes some time to do this, so if your program does not
88 care what happens to data about windows, you may want to set this
91 If the value is a list, only the listed windows are saved and
94 `M-x edebug-toggle-save-windows' may be used to change this
95 variable. This command is bound to `W' in source code buffers.
96 See *Note Edebug Display Update::.
98 - User Option: edebug-save-displayed-buffer-points
99 If non-`nil', save and restore point in all displayed buffers.
100 This is necessary if you are debugging code that changes the point
101 of a buffer which is displayed in a non-selected window. If
102 Edebug or the user then selects the window, the buffer's point
103 will be changed to the window's point.
105 This is an expensive operation since it visits each window and
106 therefore each displayed buffer twice for each Edebug activation,
107 so it is best to avoid it if you can. See *Note Edebug Display
110 - User Option: edebug-initial-mode
111 If this variable is non-`nil', it specifies the initial execution
112 mode for Edebug when it is first activated. Possible values are
113 `step', `next', `go', `Go-nonstop', `trace', `Trace-fast',
114 `continue', and `Continue-fast'.
116 The default value is `step'. See *Note Edebug Execution Modes::.
118 - User Option: edebug-trace
119 Non-`nil' means display a trace of function entry and exit.
120 Tracing output is displayed in a buffer named `*edebug-trace*', one
121 function entry or exit per line, indented by the recursion level.
123 The default value is `nil'.
125 Also see `edebug-tracing'. See *Note Tracing::.
127 - User Option: edebug-test-coverage
128 If non-`nil', Edebug tests coverage of all expressions debugged.
129 This is done by comparing the result of each expression with the
130 previous result. Coverage is considered OK if two different
131 results are found. So to sufficiently test the coverage of your
132 code, try to execute it under conditions that evaluate all
133 expressions more than once, and produce different results for each
136 Use `M-x edebug-display-freq-count' to display the frequency count
137 and coverage information for a definition. See *Note Coverage
140 - User Option: edebug-continue-kbd-macro
141 If non-`nil', continue defining or executing any keyboard macro
142 that is executing outside of Edebug. Use this with caution since
143 it is not debugged. See *Note Edebug Execution Modes::.
145 - User Option: edebug-print-length
146 If non-`nil', bind `print-length' to this while printing results
147 in Edebug. The default value is `50'. See *Note Printing in
150 - User Option: edebug-print-level
151 If non-`nil', bind `print-level' to this while printing results in
152 Edebug. The default value is `50'.
154 - User Option: edebug-print-circle
155 If non-`nil', bind `print-circle' to this while printing results
156 in Edebug. The default value is `nil'.
158 - User Option: edebug-on-error
159 `debug-on-error' is bound to this while Edebug is active. See
160 *Note Trapping Errors::.
162 - User Option: edebug-on-quit
163 `debug-on-quit' is bound to this while Edebug is active. See
164 *Note Trapping Errors::.
166 - User Option: edebug-unwrap-results
167 Non-`nil' if Edebug should unwrap results of expressions. This is
168 useful when debugging macros where the results of expressions are
169 instrumented expressions. But don't do this when results might be
170 circular or an infinite loop will result. See *Note Debugging
173 - User Option: edebug-global-break-condition
174 If non-`nil', an expression to test for at every stop point. If
175 the result is non-`nil', then break. Errors are ignored. See
176 *Note Global Break Condition::.
179 File: lispref.info, Node: Read and Print, Next: Minibuffers, Prev: Debugging, Up: Top
181 Reading and Printing Lisp Objects
182 *********************************
184 "Printing" and "reading" are the operations of converting Lisp
185 objects to textual form and vice versa. They use the printed
186 representations and read syntax described in *Note Lisp Data Types::.
188 This chapter describes the Lisp functions for reading and printing.
189 It also describes "streams", which specify where to get the text (if
190 reading) or where to put it (if printing).
194 * Streams Intro:: Overview of streams, reading and printing.
195 * Input Streams:: Various data types that can be used as input streams.
196 * Input Functions:: Functions to read Lisp objects from text.
197 * Output Streams:: Various data types that can be used as output streams.
198 * Output Functions:: Functions to print Lisp objects as text.
199 * Output Variables:: Variables that control what the printing functions do.
202 File: lispref.info, Node: Streams Intro, Next: Input Streams, Up: Read and Print
204 Introduction to Reading and Printing
205 ====================================
207 "Reading" a Lisp object means parsing a Lisp expression in textual
208 form and producing a corresponding Lisp object. This is how Lisp
209 programs get into Lisp from files of Lisp code. We call the text the
210 "read syntax" of the object. For example, the text `(a . 5)' is the
211 read syntax for a cons cell whose CAR is `a' and whose CDR is the
214 "Printing" a Lisp object means producing text that represents that
215 object--converting the object to its printed representation. Printing
216 the cons cell described above produces the text `(a . 5)'.
218 Reading and printing are more or less inverse operations: printing
219 the object that results from reading a given piece of text often
220 produces the same text, and reading the text that results from printing
221 an object usually produces a similar-looking object. For example,
222 printing the symbol `foo' produces the text `foo', and reading that text
223 returns the symbol `foo'. Printing a list whose elements are `a' and
224 `b' produces the text `(a b)', and reading that text produces a list
225 (but not the same list) with elements `a' and `b'.
227 However, these two operations are not precisely inverses. There are
228 three kinds of exceptions:
230 * Printing can produce text that cannot be read. For example,
231 buffers, windows, frames, subprocesses and markers print into text
232 that starts with `#'; if you try to read this text, you get an
233 error. There is no way to read those data types.
235 * One object can have multiple textual representations. For example,
236 `1' and `01' represent the same integer, and `(a b)' and `(a .
237 (b))' represent the same list. Reading will accept any of the
238 alternatives, but printing must choose one of them.
240 * Comments can appear at certain points in the middle of an object's
241 read sequence without affecting the result of reading it.
244 File: lispref.info, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print
249 Most of the Lisp functions for reading text take an "input stream"
250 as an argument. The input stream specifies where or how to get the
251 characters of the text to be read. Here are the possible types of input
255 The input characters are read from BUFFER, starting with the
256 character directly after point. Point advances as characters are
260 The input characters are read from the buffer that MARKER is in,
261 starting with the character directly after the marker. The marker
262 position advances as characters are read. The value of point in
263 the buffer has no effect when the stream is a marker.
266 The input characters are taken from STRING, starting at the first
267 character in the string and using as many characters as required.
270 The input characters are generated by FUNCTION, one character per
271 call. Normally FUNCTION is called with no arguments, and should
274 Occasionally FUNCTION is called with one argument (always a
275 character). When that happens, FUNCTION should save the argument
276 and arrange to return it on the next call. This is called
277 "unreading" the character; it happens when the Lisp reader reads
278 one character too many and wants to "put it back where it came
282 `t' used as a stream means that the input is read from the
283 minibuffer. In fact, the minibuffer is invoked once and the text
284 given by the user is made into a string that is then used as the
288 `nil' supplied as an input stream means to use the value of
289 `standard-input' instead; that value is the "default input
290 stream", and must be a non-`nil' input stream.
293 A symbol as input stream is equivalent to the symbol's function
296 Here is an example of reading from a stream that is a buffer, showing
297 where point is located before and after:
299 ---------- Buffer: foo ----------
300 This-!- is the contents of foo.
301 ---------- Buffer: foo ----------
303 (read (get-buffer "foo"))
305 (read (get-buffer "foo"))
308 ---------- Buffer: foo ----------
309 This is the-!- contents of foo.
310 ---------- Buffer: foo ----------
312 Note that the first read skips a space. Reading skips any amount of
313 whitespace preceding the significant text.
315 In Emacs 18, reading a symbol discarded the delimiter terminating the
316 symbol. Thus, point would end up at the beginning of `contents' rather
317 than after `the'. The Emacs 19 behavior is superior because it
318 correctly handles input such as `bar(foo)', where the open-parenthesis
319 that ends one object is needed as the beginning of another object.
321 Here is an example of reading from a stream that is a marker,
322 initially positioned at the beginning of the buffer shown. The value
323 read is the symbol `This'.
326 ---------- Buffer: foo ----------
327 This is the contents of foo.
328 ---------- Buffer: foo ----------
330 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
331 => #<marker at 1 in foo>
335 => #<marker at 5 in foo> ;; Before the first space.
337 Here we read from the contents of a string:
339 (read "(When in) the course")
342 The following example reads from the minibuffer. The prompt is:
343 `Lisp expression: '. (That is always the prompt used when you read
344 from the stream `t'.) The user's input is shown following the prompt.
348 ---------- Buffer: Minibuffer ----------
349 Lisp expression: 23 <RET>
350 ---------- Buffer: Minibuffer ----------
352 Finally, here is an example of a stream that is a function, named
353 `useless-stream'. Before we use the stream, we initialize the variable
354 `useless-list' to a list of characters. Then each call to the function
355 `useless-stream' obtains the next character in the list or unreads a
356 character by adding it to the front of the list.
358 (setq useless-list (append "XY()" nil))
361 (defun useless-stream (&optional unread)
363 (setq useless-list (cons unread useless-list))
364 (prog1 (car useless-list)
365 (setq useless-list (cdr useless-list)))))
368 Now we read using the stream thus constructed:
370 (read 'useless-stream)
376 Note that the open and close parentheses remains in the list. The Lisp
377 reader encountered the open parenthesis, decided that it ended the
378 input, and unread it. Another attempt to read from the stream at this
379 point would read `()' and return `nil'.
382 File: lispref.info, Node: Input Functions, Next: Output Streams, Prev: Input Streams, Up: Read and Print
387 This section describes the Lisp functions and variables that pertain
390 In the functions below, STREAM stands for an input stream (see the
391 previous section). If STREAM is `nil' or omitted, it defaults to the
392 value of `standard-input'.
394 An `end-of-file' error is signaled if reading encounters an
395 unterminated list, vector, or string.
397 - Function: read &optional stream
398 This function reads one textual Lisp expression from STREAM,
399 returning it as a Lisp object. This is the basic Lisp input
402 - Function: read-from-string string &optional start end
403 This function reads the first textual Lisp expression from the
404 text in STRING. It returns a cons cell whose CAR is that
405 expression, and whose CDR is an integer giving the position of the
406 next remaining character in the string (i.e., the first one not
409 If START is supplied, then reading begins at index START in the
410 string (where the first character is at index 0). If END is also
411 supplied, then reading stops just before that index, as if the rest
412 of the string were not there.
416 (read-from-string "(setq x 55) (setq y 5)")
417 => ((setq x 55) . 11)
418 (read-from-string "\"A short string\"")
419 => ("A short string" . 16)
421 ;; Read starting at the first character.
422 (read-from-string "(list 112)" 0)
424 ;; Read starting at the second character.
425 (read-from-string "(list 112)" 1)
427 ;; Read starting at the seventh character,
428 ;; and stopping at the ninth.
429 (read-from-string "(list 112)" 6 8)
432 - Variable: standard-input
433 This variable holds the default input stream--the stream that
434 `read' uses when the STREAM argument is `nil'.
437 File: lispref.info, Node: Output Streams, Next: Output Functions, Prev: Input Functions, Up: Read and Print
442 An output stream specifies what to do with the characters produced
443 by printing. Most print functions accept an output stream as an
444 optional argument. Here are the possible types of output stream:
447 The output characters are inserted into BUFFER at point. Point
448 advances as characters are inserted.
451 The output characters are inserted into the buffer that MARKER
452 points into, at the marker position. The marker position advances
453 as characters are inserted. The value of point in the buffer has
454 no effect on printing when the stream is a marker.
457 The output characters are passed to FUNCTION, which is responsible
458 for storing them away. It is called with a single character as
459 argument, as many times as there are characters to be output, and
460 is free to do anything at all with the characters it receives.
463 The output characters are displayed in the echo area.
466 `nil' specified as an output stream means to the value of
467 `standard-output' instead; that value is the "default output
468 stream", and must be a non-`nil' output stream.
471 A symbol as output stream is equivalent to the symbol's function
474 Many of the valid output streams are also valid as input streams.
475 The difference between input and output streams is therefore mostly one
476 of how you use a Lisp object, not a distinction of types of object.
478 Here is an example of a buffer used as an output stream. Point is
479 initially located as shown immediately before the `h' in `the'. At the
480 end, point is located directly before that same `h'.
482 ---------- Buffer: foo ----------
483 This is t-!-he contents of foo.
484 ---------- Buffer: foo ----------
486 (print "This is the output" (get-buffer "foo"))
487 => "This is the output"
489 ---------- Buffer: foo ----------
492 -!-he contents of foo.
493 ---------- Buffer: foo ----------
495 Now we show a use of a marker as an output stream. Initially, the
496 marker is in buffer `foo', between the `t' and the `h' in the word
497 `the'. At the end, the marker has advanced over the inserted text so
498 that it remains positioned before the same `h'. Note that the location
499 of point, shown in the usual fashion, has no effect.
501 ---------- Buffer: foo ----------
502 "This is the -!-output"
503 ---------- Buffer: foo ----------
506 => #<marker at 11 in foo>
508 (print "More output for foo." m)
509 => "More output for foo."
511 ---------- Buffer: foo ----------
513 "More output for foo."
515 ---------- Buffer: foo ----------
518 => #<marker at 35 in foo>
520 The following example shows output to the echo area:
522 (print "Echo Area output" t)
523 => "Echo Area output"
524 ---------- Echo Area ----------
526 ---------- Echo Area ----------
528 Finally, we show the use of a function as an output stream. The
529 function `eat-output' takes each character that it is given and conses
530 it onto the front of the list `last-output' (*note Building Lists::).
531 At the end, the list contains all the characters output, but in reverse
534 (setq last-output nil)
537 (defun eat-output (c)
538 (setq last-output (cons c last-output)))
541 (print "This is the output" 'eat-output)
542 => "This is the output"
545 => (?\n ?\" ?t ?u ?p ?t ?u ?o ?\ ?e ?h ?t
546 ?\ ?s ?i ?\ ?s ?i ?h ?T ?\" ?\n)
548 Now we can put the output in the proper order by reversing the list:
550 (concat (nreverse last-output))
552 \"This is the output\"
555 Calling `concat' converts the list to a string so you can see its
556 contents more clearly.
559 File: lispref.info, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Read and Print
564 This section describes the Lisp functions for printing Lisp objects.
566 Some of the XEmacs printing functions add quoting characters to the
567 output when necessary so that it can be read properly. The quoting
568 characters used are `"' and `\'; they distinguish strings from symbols,
569 and prevent punctuation characters in strings and symbols from being
570 taken as delimiters when reading. *Note Printed Representation::, for
571 full details. You specify quoting or no quoting by the choice of
574 If the text is to be read back into Lisp, then it is best to print
575 with quoting characters to avoid ambiguity. Likewise, if the purpose is
576 to describe a Lisp object clearly for a Lisp programmer. However, if
577 the purpose of the output is to look nice for humans, then it is better
578 to print without quoting.
580 Printing a self-referent Lisp object requires an infinite amount of
581 text. In certain cases, trying to produce this text leads to a stack
582 overflow. XEmacs detects such recursion and prints `#LEVEL' instead of
583 recursively printing an object already being printed. For example,
584 here `#0' indicates a recursive reference to the object at level 0 of
585 the current print operation:
587 (setq foo (list nil))
592 In the functions below, STREAM stands for an output stream. (See
593 the previous section for a description of output streams.) If STREAM
594 is `nil' or omitted, it defaults to the value of `standard-output'.
596 - Function: print object &optional stream
597 The `print' function is a convenient way of printing. It outputs
598 the printed representation of OBJECT to STREAM, printing in
599 addition one newline before OBJECT and another after it. Quoting
600 characters are used. `print' returns OBJECT. For example:
602 (progn (print 'The\ cat\ in)
604 (print " came back"))
614 - Function: prin1 object &optional stream
615 This function outputs the printed representation of OBJECT to
616 STREAM. It does not print newlines to separate output as `print'
617 does, but it does use quoting characters just like `print'. It
620 (progn (prin1 'The\ cat\ in)
622 (prin1 " came back"))
623 -| The\ cat\ in"the hat"" came back"
626 - Function: princ object &optional stream
627 This function outputs the printed representation of OBJECT to
628 STREAM. It returns OBJECT.
630 This function is intended to produce output that is readable by
631 people, not by `read', so it doesn't insert quoting characters and
632 doesn't put double-quotes around the contents of strings. It does
633 not add any spacing between calls.
637 (princ " in the \"hat\""))
638 -| The cat in the "hat"
641 - Function: terpri &optional stream
642 This function outputs a newline to STREAM. The name stands for
645 - Function: write-char character &optional stream
646 This function outputs CHARACTER to STREAM. It returns CHARACTER.
648 - Function: prin1-to-string object &optional noescape
649 This function returns a string containing the text that `prin1'
650 would have printed for the same argument.
652 (prin1-to-string 'foo)
654 (prin1-to-string (mark-marker))
655 => "#<marker at 2773 in strings.texi>"
657 If NOESCAPE is non-`nil', that inhibits use of quoting characters
658 in the output. (This argument is supported in Emacs versions 19
661 (prin1-to-string "foo")
663 (prin1-to-string "foo" t)
666 See `format', in *Note String Conversion::, for other ways to
667 obtain the printed representation of a Lisp object as a string.
670 File: lispref.info, Node: Output Variables, Prev: Output Functions, Up: Read and Print
672 Variables Affecting Output
673 ==========================
675 - Variable: standard-output
676 The value of this variable is the default output stream--the stream
677 that print functions use when the STREAM argument is `nil'.
679 - Variable: print-escape-newlines
680 If this variable is non-`nil', then newline characters in strings
681 are printed as `\n' and formfeeds are printed as `\f'. Normally
682 these characters are printed as actual newlines and formfeeds.
684 This variable affects the print functions `prin1' and `print', as
685 well as everything that uses them. It does not affect `princ'.
686 Here is an example using `prin1':
694 (let ((print-escape-newlines t))
700 In the second expression, the local binding of
701 `print-escape-newlines' is in effect during the call to `prin1',
702 but not during the printing of the result.
704 - Variable: print-readably
705 If non-`nil', then all objects will be printed in a readable form.
706 If an object has no readable representation, then an error is
707 signalled. When `print-readably' is true, compiled-function
708 objects will be written in `#[...]' form instead of in
709 `#<compiled-function [...]>' form, and two-element lists of the
710 form `(quote object)' will be written as the equivalent `'object'.
711 Do not _set_ this variable; bind it instead.
713 - Variable: print-length
714 The value of this variable is the maximum number of elements of a
715 list that will be printed. If a list being printed has more than
716 this many elements, it is abbreviated with an ellipsis.
718 If the value is `nil' (the default), then there is no limit.
720 (setq print-length 2)
726 - Variable: print-level
727 The value of this variable is the maximum depth of nesting of
728 parentheses and brackets when printed. Any list or vector at a
729 depth exceeding this limit is abbreviated with an ellipsis. A
730 value of `nil' (which is the default) means no limit.
732 This variable exists in version 19 and later versions.
734 - Variable: print-string-length
735 The value of this variable is the maximum number of characters of
736 a string that will be printed. If a string being printed has more
737 than this many characters, it is abbreviated with an ellipsis.
739 - Variable: print-gensym
740 If non-`nil', then uninterned symbols will be printed specially.
741 Uninterned symbols are those which are not present in `obarray',
742 that is, those which were made with `make-symbol' or by calling
743 `intern' with a second argument.
745 When `print-gensym' is true, such symbols will be preceded by
746 `#:', which causes the reader to create a new symbol instead of
747 interning and returning an existing one. Beware: The `#:' syntax
748 creates a new symbol each time it is seen, so if you print an
749 object which contains two pointers to the same uninterned symbol,
750 `read' will not duplicate that structure.
752 Also, since XEmacs has no real notion of packages, there is no way
753 for the printer to distinguish between symbols interned in no
754 obarray, and symbols interned in an alternate obarray.
756 - Variable: float-output-format
757 This variable holds the format descriptor string that Lisp uses to
758 print floats. This is a `%'-spec like those accepted by `printf'
759 in C, but with some restrictions. It must start with the two
760 characters `%.'. After that comes an integer precision
761 specification, and then a letter which controls the format. The
762 letters allowed are `e', `f' and `g'.
764 * Use `e' for exponential notation `DIG.DIGITSeEXPT'.
766 * Use `f' for decimal point notation `DIGITS.DIGITS'.
768 * Use `g' to choose the shorter of those two formats for the
771 The precision in any of these cases is the number of digits
772 following the decimal point. With `f', a precision of 0 means to
773 omit the decimal point. 0 is not allowed with `f' or `g'.
775 A value of `nil' means to use `%.16g'.
777 Regardless of the value of `float-output-format', a floating point
778 number will never be printed in such a way that it is ambiguous
779 with an integer; that is, a floating-point number will always be
780 printed with a decimal point and/or an exponent, even if the
781 digits following the decimal point are all zero. This is to
782 preserve read-equivalence.
785 File: lispref.info, Node: Minibuffers, Next: Command Loop, Prev: Read and Print, Up: Top
790 A "minibuffer" is a special buffer that XEmacs commands use to read
791 arguments more complicated than the single numeric prefix argument.
792 These arguments include file names, buffer names, and command names (as
793 in `M-x'). The minibuffer is displayed on the bottom line of the
794 frame, in the same place as the echo area, but only while it is in use
795 for reading an argument.
799 * Intro to Minibuffers:: Basic information about minibuffers.
800 * Text from Minibuffer:: How to read a straight text string.
801 * Object from Minibuffer:: How to read a Lisp object or expression.
802 * Minibuffer History:: Recording previous minibuffer inputs
803 so the user can reuse them.
804 * Completion:: How to invoke and customize completion.
805 * Yes-or-No Queries:: Asking a question with a simple answer.
806 * Multiple Queries:: Asking a series of similar questions.
807 * Reading a Password:: Reading a password from the terminal.
808 * Minibuffer Misc:: Various customization hooks and variables.
811 File: lispref.info, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers
813 Introduction to Minibuffers
814 ===========================
816 In most ways, a minibuffer is a normal XEmacs buffer. Most
817 operations _within_ a buffer, such as editing commands, work normally
818 in a minibuffer. However, many operations for managing buffers do not
819 apply to minibuffers. The name of a minibuffer always has the form
820 ` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are
821 displayed only in special windows used only for minibuffers; these
822 windows always appear at the bottom of a frame. (Sometimes frames have
823 no minibuffer window, and sometimes a special kind of frame contains
824 nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
826 The minibuffer's window is normally a single line. You can resize it
827 temporarily with the window sizing commands; it reverts to its normal
828 size when the minibuffer is exited. You can resize it permanently by
829 using the window sizing commands in the frame's other window, when the
830 minibuffer is not active. If the frame contains just a minibuffer, you
831 can change the minibuffer's size by changing the frame's size.
833 If a command uses a minibuffer while there is an active minibuffer,
834 this is called a "recursive minibuffer". The first minibuffer is named
835 ` *Minibuf-0*'. Recursive minibuffers are named by incrementing the
836 number at the end of the name. (The names begin with a space so that
837 they won't show up in normal buffer lists.) Of several recursive
838 minibuffers, the innermost (or most recently entered) is the active
839 minibuffer. We usually call this "the" minibuffer. You can permit or
840 forbid recursive minibuffers by setting the variable
841 `enable-recursive-minibuffers'.
843 Like other buffers, a minibuffer may use any of several local keymaps
844 (*note Keymaps::); these contain various exit commands and in some cases
845 completion commands (*note Completion::).
847 * `minibuffer-local-map' is for ordinary input (no completion).
849 * `minibuffer-local-completion-map' is for permissive completion.
851 * `minibuffer-local-must-match-map' is for strict completion and for
855 File: lispref.info, Node: Text from Minibuffer, Next: Object from Minibuffer, Prev: Intro to Minibuffers, Up: Minibuffers
857 Reading Text Strings with the Minibuffer
858 ========================================
860 Most often, the minibuffer is used to read text as a string. It can
861 also be used to read a Lisp object in textual form. The most basic
862 primitive for minibuffer input is `read-from-minibuffer'; it can do
865 In most cases, you should not call minibuffer input functions in the
866 middle of a Lisp function. Instead, do all minibuffer input as part of
867 reading the arguments for a command, in the `interactive' spec. *Note
870 - Function: read-from-minibuffer prompt-string &optional
871 initial-contents keymap read hist abbrev-table default
872 This function is the most general way to get input through the
873 minibuffer. By default, it accepts arbitrary text and returns it
874 as a string; however, if READ is non-`nil', then it uses `read' to
875 convert the text into a Lisp object (*note Input Functions::).
877 The first thing this function does is to activate a minibuffer and
878 display it with PROMPT-STRING as the prompt. This value must be a
881 Then, if INITIAL-CONTENTS is a string, `read-from-minibuffer'
882 inserts it into the minibuffer, leaving point at the end. The
883 minibuffer appears with this text as its contents.
885 The value of INITIAL-CONTENTS may also be a cons cell of the form
886 `(STRING . POSITION)'. This means to insert STRING in the
887 minibuffer but put point POSITION characters from the beginning,
888 rather than at the end.
890 When the user types a command to exit the minibuffer,
891 `read-from-minibuffer' constructs the return value from the text in
892 the minibuffer. Normally it returns a string containing that text.
893 However, if READ is non-`nil', `read-from-minibuffer' reads the
894 text and returns the resulting Lisp object, unevaluated. (*Note
895 Input Functions::, for information about reading.)
897 The argument DEFAULT specifies a default value to make available
898 through the history commands. It should be a string, or `nil'.
900 If KEYMAP is non-`nil', that keymap is the local keymap to use in
901 the minibuffer. If KEYMAP is omitted or `nil', the value of
902 `minibuffer-local-map' is used as the keymap. Specifying a keymap
903 is the most important way to customize the minibuffer for various
904 applications such as completion.
906 The argument ABBREV-TABLE specifies `local-abbrev-table' in the
907 minibuffer (*note Standard Abbrev Tables::).
909 The argument HIST specifies which history list variable to use for
910 saving the input and for history commands used in the minibuffer.
911 It defaults to `minibuffer-history'. *Note Minibuffer History::.
913 When the user types a command to exit the minibuffer,
914 `read-from-minibuffer' uses the text in the minibuffer to produce
915 its return value. Normally it simply makes a string containing
916 that text. However, if READ is non-`nil', `read-from-minibuffer'
917 reads the text and returns the resulting Lisp object, unevaluated.
918 (*Note Input Functions::, for information about reading.)
920 *Usage note:* The INITIAL-CONTENTS argument and the DEFAULT
921 argument are two alternative features for more or less the same
922 job. It does not make sense to use both features in a single call
923 to `read-from-minibuffer'. In general, we recommend using
924 DEFAULT, since this permits the user to insert the default value
925 when it is wanted, but does not burden the user with deleting it
926 from the minibuffer on other occasions. However, if user is
927 supposed to edit default value, INITIAL-CONTENTS may be preferred.
929 - Function: read-string prompt &optional initial history default-value
930 This function reads a string from the minibuffer and returns it.
931 The arguments PROMPT and INITIAL are used as in
932 `read-from-minibuffer'. The keymap used is `minibuffer-local-map'.
934 The optional argument HISTORY, if non-`nil', specifies a history
935 list and optionally the initial position in the list. The optional
936 argument DEFAULT-VALUE specifies a default value to return if the
937 user enters null input; it should be a string.
939 This function is a simplified interface to the
940 `read-from-minibuffer' function:
942 (read-string PROMPT INITIAL HISTORY DEFAULT)
944 (read-from-minibuffer PROMPT INITIAL nil nil
945 HISTORY nil DEFAULT)))
947 - Variable: minibuffer-local-map
948 This is the default local keymap for reading from the minibuffer.
949 By default, it makes the following bindings:
958 `abort-recursive-edit'
961 `next-history-element'
964 `previous-history-element'
967 `next-matching-history-element'
970 `previous-matching-history-element'
973 File: lispref.info, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers
975 Reading Lisp Objects with the Minibuffer
976 ========================================
978 This section describes functions for reading Lisp objects with the
981 - Function: read-expression prompt &optional initial history
983 This function reads a Lisp object using the minibuffer, and
984 returns it without evaluating it. The arguments PROMPT and
985 INITIAL are used as in `read-from-minibuffer'.
987 The optional argument HISTORY, if non-`nil', specifies a history
988 list and optionally the initial position in the list. The optional
989 argument DEFAULT-VALUE specifies a default value to return if the
990 user enters null input; it should be a string.
992 This is a simplified interface to the `read-from-minibuffer'
995 (read-expression PROMPT INITIAL HISTORY DEFAULT-VALUE)
997 (read-from-minibuffer PROMPT INITIAL nil t
998 HISTORY nil DEFAULT-VALUE)
1000 Here is an example in which we supply the string `"(testing)"' as
1004 "Enter an expression: " (format "%s" '(testing)))
1006 ;; Here is how the minibuffer is displayed:
1008 ---------- Buffer: Minibuffer ----------
1009 Enter an expression: (testing)-!-
1010 ---------- Buffer: Minibuffer ----------
1012 The user can type <RET> immediately to use the initial input as a
1013 default, or can edit the input.
1015 - Function: read-minibuffer prompt &optional initial history
1017 This is a FSF Emacs compatible function. Use `read-expression'
1020 - Function: eval-minibuffer prompt &optional initial history
1022 This function reads a Lisp expression using the minibuffer,
1023 evaluates it, then returns the result. The arguments PROMPT and
1024 INITIAL are used as in `read-from-minibuffer'.
1026 The optional argument HISTORY, if non-`nil', specifies a history
1027 list and optionally the initial position in the list. The optional
1028 argument DEFAULT-VALUE specifies a default value to return if the
1029 user enters null input; it should be a string.
1031 This function simply evaluates the result of a call to
1034 (eval-minibuffer PROMPT INITIAL)
1036 (eval (read-expression PROMPT INITIAL))
1038 - Function: edit-and-eval-command prompt form &optional history
1039 This function reads a Lisp expression in the minibuffer, and then
1040 evaluates it. The difference between this command and
1041 `eval-minibuffer' is that here the initial FORM is not optional
1042 and it is treated as a Lisp object to be converted to printed
1043 representation rather than as a string of text. It is printed with
1044 `prin1', so if it is a string, double-quote characters (`"')
1045 appear in the initial text. *Note Output Functions::.
1047 The first thing `edit-and-eval-command' does is to activate the
1048 minibuffer with PROMPT as the prompt. Then it inserts the printed
1049 representation of FORM in the minibuffer, and lets the user edit
1050 it. When the user exits the minibuffer, the edited text is read
1051 with `read' and then evaluated. The resulting value becomes the
1052 value of `edit-and-eval-command'.
1054 In the following example, we offer the user an expression with
1055 initial text which is a valid form already:
1057 (edit-and-eval-command "Please edit: " '(forward-word 1))
1059 ;; After evaluation of the preceding expression,
1060 ;; the following appears in the minibuffer:
1062 ---------- Buffer: Minibuffer ----------
1063 Please edit: (forward-word 1)-!-
1064 ---------- Buffer: Minibuffer ----------
1066 Typing <RET> right away would exit the minibuffer and evaluate the
1067 expression, thus moving point forward one word.
1068 `edit-and-eval-command' returns `t' in this example.
1071 File: lispref.info, Node: Minibuffer History, Next: Completion, Prev: Object from Minibuffer, Up: Minibuffers
1076 A "minibuffer history list" records previous minibuffer inputs so
1077 the user can reuse them conveniently. A history list is actually a
1078 symbol, not a list; it is a variable whose value is a list of strings
1079 (previous inputs), most recent first.
1081 There are many separate history lists, used for different kinds of
1082 inputs. It's the Lisp programmer's job to specify the right history
1083 list for each use of the minibuffer.
1085 The basic minibuffer input functions `read-from-minibuffer' and
1086 `completing-read' both accept an optional argument named HIST which is
1087 how you specify the history list. Here are the possible values:
1090 Use VARIABLE (a symbol) as the history list.
1092 (VARIABLE . STARTPOS)
1093 Use VARIABLE (a symbol) as the history list, and assume that the
1094 initial history position is STARTPOS (an integer, counting from
1095 zero which specifies the most recent element of the history).
1097 If you specify STARTPOS, then you should also specify that element
1098 of the history as the initial minibuffer contents, for consistency.
1100 If you don't specify HIST, then the default history list
1101 `minibuffer-history' is used. For other standard history lists, see
1102 below. You can also create your own history list variable; just
1103 initialize it to `nil' before the first use.
1105 Both `read-from-minibuffer' and `completing-read' add new elements
1106 to the history list automatically, and provide commands to allow the
1107 user to reuse items on the list. The only thing your program needs to
1108 do to use a history list is to initialize it and to pass its name to
1109 the input functions when you wish. But it is safe to modify the list
1110 by hand when the minibuffer input functions are not using it.
1112 Here are some of the standard minibuffer history list variables:
1114 - Variable: minibuffer-history
1115 The default history list for minibuffer history input.
1117 - Variable: query-replace-history
1118 A history list for arguments to `query-replace' (and similar
1119 arguments to other commands).
1121 - Variable: file-name-history
1122 A history list for file name arguments.
1124 - Variable: regexp-history
1125 A history list for regular expression arguments.
1127 - Variable: extended-command-history
1128 A history list for arguments that are names of extended commands.
1130 - Variable: shell-command-history
1131 A history list for arguments that are shell commands.
1133 - Variable: read-expression-history
1134 A history list for arguments that are Lisp expressions to evaluate.
1136 - Variable: Info-minibuffer-history
1137 A history list for Info mode's minibuffer.
1139 - Variable: Manual-page-minibuffer-history
1140 A history list for `manual-entry'.
1142 There are many other minibuffer history lists, defined by various
1143 libraries. An `M-x apropos' search for `history' should prove fruitful
1144 in discovering them.
1147 File: lispref.info, Node: Completion, Next: Yes-or-No Queries, Prev: Minibuffer History, Up: Minibuffers
1152 "Completion" is a feature that fills in the rest of a name starting
1153 from an abbreviation for it. Completion works by comparing the user's
1154 input against a list of valid names and determining how much of the
1155 name is determined uniquely by what the user has typed. For example,
1156 when you type `C-x b' (`switch-to-buffer') and then type the first few
1157 letters of the name of the buffer to which you wish to switch, and then
1158 type <TAB> (`minibuffer-complete'), Emacs extends the name as far as it
1161 Standard XEmacs commands offer completion for names of symbols,
1162 files, buffers, and processes; with the functions in this section, you
1163 can implement completion for other kinds of names.
1165 The `try-completion' function is the basic primitive for completion:
1166 it returns the longest determined completion of a given initial string,
1167 with a given set of strings to match against.
1169 The function `completing-read' provides a higher-level interface for
1170 completion. A call to `completing-read' specifies how to determine the
1171 list of valid names. The function then activates the minibuffer with a
1172 local keymap that binds a few keys to commands useful for completion.
1173 Other functions provide convenient simple interfaces for reading
1174 certain kinds of names with completion.
1178 * Basic Completion:: Low-level functions for completing strings.
1179 (These are too low level to use the minibuffer.)
1180 * Minibuffer Completion:: Invoking the minibuffer with completion.
1181 * Completion Commands:: Minibuffer commands that do completion.
1182 * High-Level Completion:: Convenient special cases of completion
1183 (reading buffer name, file name, etc.)
1184 * Reading File Names:: Using completion to read file names.
1185 * Programmed Completion:: Finding the completions for a given file name.