1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
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: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print
58 Most of the Lisp functions for reading text take an "input stream"
59 as an argument. The input stream specifies where or how to get the
60 characters of the text to be read. Here are the possible types of input
64 The input characters are read from BUFFER, starting with the
65 character directly after point. Point advances as characters are
69 The input characters are read from the buffer that MARKER is in,
70 starting with the character directly after the marker. The marker
71 position advances as characters are read. The value of point in
72 the buffer has no effect when the stream is a marker.
75 The input characters are taken from STRING, starting at the first
76 character in the string and using as many characters as required.
79 The input characters are generated by FUNCTION, one character per
80 call. Normally FUNCTION is called with no arguments, and should
83 Occasionally FUNCTION is called with one argument (always a
84 character). When that happens, FUNCTION should save the argument
85 and arrange to return it on the next call. This is called
86 "unreading" the character; it happens when the Lisp reader reads
87 one character too many and wants to "put it back where it came
91 `t' used as a stream means that the input is read from the
92 minibuffer. In fact, the minibuffer is invoked once and the text
93 given by the user is made into a string that is then used as the
97 `nil' supplied as an input stream means to use the value of
98 `standard-input' instead; that value is the "default input
99 stream", and must be a non-`nil' input stream.
102 A symbol as input stream is equivalent to the symbol's function
105 Here is an example of reading from a stream that is a buffer, showing
106 where point is located before and after:
108 ---------- Buffer: foo ----------
109 This-!- is the contents of foo.
110 ---------- Buffer: foo ----------
112 (read (get-buffer "foo"))
114 (read (get-buffer "foo"))
117 ---------- Buffer: foo ----------
118 This is the-!- contents of foo.
119 ---------- Buffer: foo ----------
121 Note that the first read skips a space. Reading skips any amount of
122 whitespace preceding the significant text.
124 In Emacs 18, reading a symbol discarded the delimiter terminating the
125 symbol. Thus, point would end up at the beginning of `contents' rather
126 than after `the'. The Emacs 19 behavior is superior because it
127 correctly handles input such as `bar(foo)', where the open-parenthesis
128 that ends one object is needed as the beginning of another object.
130 Here is an example of reading from a stream that is a marker,
131 initially positioned at the beginning of the buffer shown. The value
132 read is the symbol `This'.
135 ---------- Buffer: foo ----------
136 This is the contents of foo.
137 ---------- Buffer: foo ----------
139 (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
140 => #<marker at 1 in foo>
144 => #<marker at 5 in foo> ;; Before the first space.
146 Here we read from the contents of a string:
148 (read "(When in) the course")
151 The following example reads from the minibuffer. The prompt is:
152 `Lisp expression: '. (That is always the prompt used when you read
153 from the stream `t'.) The user's input is shown following the prompt.
157 ---------- Buffer: Minibuffer ----------
158 Lisp expression: 23 <RET>
159 ---------- Buffer: Minibuffer ----------
161 Finally, here is an example of a stream that is a function, named
162 `useless-stream'. Before we use the stream, we initialize the variable
163 `useless-list' to a list of characters. Then each call to the function
164 `useless-stream' obtains the next character in the list or unreads a
165 character by adding it to the front of the list.
167 (setq useless-list (append "XY()" nil))
170 (defun useless-stream (&optional unread)
172 (setq useless-list (cons unread useless-list))
173 (prog1 (car useless-list)
174 (setq useless-list (cdr useless-list)))))
177 Now we read using the stream thus constructed:
179 (read 'useless-stream)
185 Note that the open and close parentheses remains in the list. The Lisp
186 reader encountered the open parenthesis, decided that it ended the
187 input, and unread it. Another attempt to read from the stream at this
188 point would read `()' and return `nil'.
191 File: lispref.info, Node: Input Functions, Next: Output Streams, Prev: Input Streams, Up: Read and Print
196 This section describes the Lisp functions and variables that pertain
199 In the functions below, STREAM stands for an input stream (see the
200 previous section). If STREAM is `nil' or omitted, it defaults to the
201 value of `standard-input'.
203 An `end-of-file' error is signaled if reading encounters an
204 unterminated list, vector, or string.
206 - Function: read &optional STREAM
207 This function reads one textual Lisp expression from STREAM,
208 returning it as a Lisp object. This is the basic Lisp input
211 - Function: read-from-string STRING &optional START END
212 This function reads the first textual Lisp expression from the
213 text in STRING. It returns a cons cell whose CAR is that
214 expression, and whose CDR is an integer giving the position of the
215 next remaining character in the string (i.e., the first one not
218 If START is supplied, then reading begins at index START in the
219 string (where the first character is at index 0). If END is also
220 supplied, then reading stops just before that index, as if the rest
221 of the string were not there.
225 (read-from-string "(setq x 55) (setq y 5)")
226 => ((setq x 55) . 11)
227 (read-from-string "\"A short string\"")
228 => ("A short string" . 16)
230 ;; Read starting at the first character.
231 (read-from-string "(list 112)" 0)
233 ;; Read starting at the second character.
234 (read-from-string "(list 112)" 1)
236 ;; Read starting at the seventh character,
237 ;; and stopping at the ninth.
238 (read-from-string "(list 112)" 6 8)
241 - Variable: standard-input
242 This variable holds the default input stream--the stream that
243 `read' uses when the STREAM argument is `nil'.
246 File: lispref.info, Node: Output Streams, Next: Output Functions, Prev: Input Functions, Up: Read and Print
251 An output stream specifies what to do with the characters produced
252 by printing. Most print functions accept an output stream as an
253 optional argument. Here are the possible types of output stream:
256 The output characters are inserted into BUFFER at point. Point
257 advances as characters are inserted.
260 The output characters are inserted into the buffer that MARKER
261 points into, at the marker position. The marker position advances
262 as characters are inserted. The value of point in the buffer has
263 no effect on printing when the stream is a marker.
266 The output characters are passed to FUNCTION, which is responsible
267 for storing them away. It is called with a single character as
268 argument, as many times as there are characters to be output, and
269 is free to do anything at all with the characters it receives.
272 The output characters are displayed in the echo area.
275 `nil' specified as an output stream means to the value of
276 `standard-output' instead; that value is the "default output
277 stream", and must be a non-`nil' output stream.
280 A symbol as output stream is equivalent to the symbol's function
283 Many of the valid output streams are also valid as input streams.
284 The difference between input and output streams is therefore mostly one
285 of how you use a Lisp object, not a distinction of types of object.
287 Here is an example of a buffer used as an output stream. Point is
288 initially located as shown immediately before the `h' in `the'. At the
289 end, point is located directly before that same `h'.
291 ---------- Buffer: foo ----------
292 This is t-!-he contents of foo.
293 ---------- Buffer: foo ----------
295 (print "This is the output" (get-buffer "foo"))
296 => "This is the output"
298 ---------- Buffer: foo ----------
301 -!-he contents of foo.
302 ---------- Buffer: foo ----------
304 Now we show a use of a marker as an output stream. Initially, the
305 marker is in buffer `foo', between the `t' and the `h' in the word
306 `the'. At the end, the marker has advanced over the inserted text so
307 that it remains positioned before the same `h'. Note that the location
308 of point, shown in the usual fashion, has no effect.
310 ---------- Buffer: foo ----------
311 "This is the -!-output"
312 ---------- Buffer: foo ----------
315 => #<marker at 11 in foo>
317 (print "More output for foo." m)
318 => "More output for foo."
320 ---------- Buffer: foo ----------
322 "More output for foo."
324 ---------- Buffer: foo ----------
327 => #<marker at 35 in foo>
329 The following example shows output to the echo area:
331 (print "Echo Area output" t)
332 => "Echo Area output"
333 ---------- Echo Area ----------
335 ---------- Echo Area ----------
337 Finally, we show the use of a function as an output stream. The
338 function `eat-output' takes each character that it is given and conses
339 it onto the front of the list `last-output' (*note Building Lists::.).
340 At the end, the list contains all the characters output, but in reverse
343 (setq last-output nil)
346 (defun eat-output (c)
347 (setq last-output (cons c last-output)))
350 (print "This is the output" 'eat-output)
351 => "This is the output"
354 => (?\n ?\" ?t ?u ?p ?t ?u ?o ?\ ?e ?h ?t
355 ?\ ?s ?i ?\ ?s ?i ?h ?T ?\" ?\n)
357 Now we can put the output in the proper order by reversing the list:
359 (concat (nreverse last-output))
361 \"This is the output\"
364 Calling `concat' converts the list to a string so you can see its
365 contents more clearly.
368 File: lispref.info, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Read and Print
373 This section describes the Lisp functions for printing Lisp objects.
375 Some of the XEmacs printing functions add quoting characters to the
376 output when necessary so that it can be read properly. The quoting
377 characters used are `"' and `\'; they distinguish strings from symbols,
378 and prevent punctuation characters in strings and symbols from being
379 taken as delimiters when reading. *Note Printed Representation::, for
380 full details. You specify quoting or no quoting by the choice of
383 If the text is to be read back into Lisp, then it is best to print
384 with quoting characters to avoid ambiguity. Likewise, if the purpose is
385 to describe a Lisp object clearly for a Lisp programmer. However, if
386 the purpose of the output is to look nice for humans, then it is better
387 to print without quoting.
389 Printing a self-referent Lisp object requires an infinite amount of
390 text. In certain cases, trying to produce this text leads to a stack
391 overflow. XEmacs detects such recursion and prints `#LEVEL' instead of
392 recursively printing an object already being printed. For example,
393 here `#0' indicates a recursive reference to the object at level 0 of
394 the current print operation:
396 (setq foo (list nil))
401 In the functions below, STREAM stands for an output stream. (See
402 the previous section for a description of output streams.) If STREAM
403 is `nil' or omitted, it defaults to the value of `standard-output'.
405 - Function: print OBJECT &optional STREAM
406 The `print' function is a convenient way of printing. It outputs
407 the printed representation of OBJECT to STREAM, printing in
408 addition one newline before OBJECT and another after it. Quoting
409 characters are used. `print' returns OBJECT. For example:
411 (progn (print 'The\ cat\ in)
413 (print " came back"))
423 - Function: prin1 OBJECT &optional STREAM
424 This function outputs the printed representation of OBJECT to
425 STREAM. It does not print newlines to separate output as `print'
426 does, but it does use quoting characters just like `print'. It
429 (progn (prin1 'The\ cat\ in)
431 (prin1 " came back"))
432 -| The\ cat\ in"the hat"" came back"
435 - Function: princ OBJECT &optional STREAM
436 This function outputs the printed representation of OBJECT to
437 STREAM. It returns OBJECT.
439 This function is intended to produce output that is readable by
440 people, not by `read', so it doesn't insert quoting characters and
441 doesn't put double-quotes around the contents of strings. It does
442 not add any spacing between calls.
446 (princ " in the \"hat\""))
447 -| The cat in the "hat"
450 - Function: terpri &optional STREAM
451 This function outputs a newline to STREAM. The name stands for
454 - Function: write-char CHARACTER &optional STREAM
455 This function outputs CHARACTER to STREAM. It returns CHARACTER.
457 - Function: prin1-to-string OBJECT &optional NOESCAPE
458 This function returns a string containing the text that `prin1'
459 would have printed for the same argument.
461 (prin1-to-string 'foo)
463 (prin1-to-string (mark-marker))
464 => "#<marker at 2773 in strings.texi>"
466 If NOESCAPE is non-`nil', that inhibits use of quoting characters
467 in the output. (This argument is supported in Emacs versions 19
470 (prin1-to-string "foo")
472 (prin1-to-string "foo" t)
475 See `format', in *Note String Conversion::, for other ways to
476 obtain the printed representation of a Lisp object as a string.
479 File: lispref.info, Node: Output Variables, Prev: Output Functions, Up: Read and Print
481 Variables Affecting Output
482 ==========================
484 - Variable: standard-output
485 The value of this variable is the default output stream--the stream
486 that print functions use when the STREAM argument is `nil'.
488 - Variable: print-escape-newlines
489 If this variable is non-`nil', then newline characters in strings
490 are printed as `\n' and formfeeds are printed as `\f'. Normally
491 these characters are printed as actual newlines and formfeeds.
493 This variable affects the print functions `prin1' and `print', as
494 well as everything that uses them. It does not affect `princ'.
495 Here is an example using `prin1':
503 (let ((print-escape-newlines t))
509 In the second expression, the local binding of
510 `print-escape-newlines' is in effect during the call to `prin1',
511 but not during the printing of the result.
513 - Variable: print-readably
514 If non-`nil', then all objects will be printed in a readable form.
515 If an object has no readable representation, then an error is
516 signalled. When `print-readably' is true, compiled-function
517 objects will be written in `#[...]' form instead of in
518 `#<compiled-function [...]>' form, and two-element lists of the
519 form `(quote object)' will be written as the equivalent `'object'.
520 Do not *set* this variable; bind it instead.
522 - Variable: print-length
523 The value of this variable is the maximum number of elements of a
524 list that will be printed. If a list being printed has more than
525 this many elements, it is abbreviated with an ellipsis.
527 If the value is `nil' (the default), then there is no limit.
529 (setq print-length 2)
535 - Variable: print-level
536 The value of this variable is the maximum depth of nesting of
537 parentheses and brackets when printed. Any list or vector at a
538 depth exceeding this limit is abbreviated with an ellipsis. A
539 value of `nil' (which is the default) means no limit.
541 This variable exists in version 19 and later versions.
543 - Variable: print-string-length
544 The value of this variable is the maximum number of characters of
545 a string that will be printed. If a string being printed has more
546 than this many characters, it is abbreviated with an ellipsis.
548 - Variable: print-gensym
549 If non-`nil', then uninterned symbols will be printed specially.
550 Uninterned symbols are those which are not present in `obarray',
551 that is, those which were made with `make-symbol' or by calling
552 `intern' with a second argument.
554 When `print-gensym' is true, such symbols will be preceded by
555 `#:', which causes the reader to create a new symbol instead of
556 interning and returning an existing one. Beware: The `#:' syntax
557 creates a new symbol each time it is seen, so if you print an
558 object which contains two pointers to the same uninterned symbol,
559 `read' will not duplicate that structure.
561 Also, since XEmacs has no real notion of packages, there is no way
562 for the printer to distinguish between symbols interned in no
563 obarray, and symbols interned in an alternate obarray.
565 - Variable: float-output-format
566 This variable holds the format descriptor string that Lisp uses to
567 print floats. This is a `%'-spec like those accepted by `printf'
568 in C, but with some restrictions. It must start with the two
569 characters `%.'. After that comes an integer precision
570 specification, and then a letter which controls the format. The
571 letters allowed are `e', `f' and `g'.
573 * Use `e' for exponential notation `DIG.DIGITSeEXPT'.
575 * Use `f' for decimal point notation `DIGITS.DIGITS'.
577 * Use `g' to choose the shorter of those two formats for the
580 The precision in any of these cases is the number of digits
581 following the decimal point. With `f', a precision of 0 means to
582 omit the decimal point. 0 is not allowed with `f' or `g'.
584 A value of nil means to use `%.16g'.
586 Regardless of the value of `float-output-format', a floating point
587 number will never be printed in such a way that it is ambiguous
588 with an integer; that is, a floating-point number will always be
589 printed with a decimal point and/or an exponent, even if the
590 digits following the decimal point are all zero. This is to
591 preserve read-equivalence.
594 File: lispref.info, Node: Minibuffers, Next: Command Loop, Prev: Read and Print, Up: Top
599 A "minibuffer" is a special buffer that XEmacs commands use to read
600 arguments more complicated than the single numeric prefix argument.
601 These arguments include file names, buffer names, and command names (as
602 in `M-x'). The minibuffer is displayed on the bottom line of the
603 frame, in the same place as the echo area, but only while it is in use
604 for reading an argument.
608 * Intro to Minibuffers:: Basic information about minibuffers.
609 * Text from Minibuffer:: How to read a straight text string.
610 * Object from Minibuffer:: How to read a Lisp object or expression.
611 * Minibuffer History:: Recording previous minibuffer inputs
612 so the user can reuse them.
613 * Completion:: How to invoke and customize completion.
614 * Yes-or-No Queries:: Asking a question with a simple answer.
615 * Multiple Queries:: Asking a series of similar questions.
616 * Minibuffer Misc:: Various customization hooks and variables.
619 File: lispref.info, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers
621 Introduction to Minibuffers
622 ===========================
624 In most ways, a minibuffer is a normal XEmacs buffer. Most
625 operations *within* a buffer, such as editing commands, work normally
626 in a minibuffer. However, many operations for managing buffers do not
627 apply to minibuffers. The name of a minibuffer always has the form
628 ` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are
629 displayed only in special windows used only for minibuffers; these
630 windows always appear at the bottom of a frame. (Sometime frames have
631 no minibuffer window, and sometimes a special kind of frame contains
632 nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
634 The minibuffer's window is normally a single line. You can resize it
635 temporarily with the window sizing commands; it reverts to its normal
636 size when the minibuffer is exited. You can resize it permanently by
637 using the window sizing commands in the frame's other window, when the
638 minibuffer is not active. If the frame contains just a minibuffer, you
639 can change the minibuffer's size by changing the frame's size.
641 If a command uses a minibuffer while there is an active minibuffer,
642 this is called a "recursive minibuffer". The first minibuffer is named
643 ` *Minibuf-0*'. Recursive minibuffers are named by incrementing the
644 number at the end of the name. (The names begin with a space so that
645 they won't show up in normal buffer lists.) Of several recursive
646 minibuffers, the innermost (or most recently entered) is the active
647 minibuffer. We usually call this "the" minibuffer. You can permit or
648 forbid recursive minibuffers by setting the variable
649 `enable-recursive-minibuffers'.
651 Like other buffers, a minibuffer may use any of several local keymaps
652 (*note Keymaps::.); these contain various exit commands and in some
653 cases completion commands (*note Completion::.).
655 * `minibuffer-local-map' is for ordinary input (no completion).
657 * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
658 like <RET>. This is used mainly for Mocklisp compatibility.
660 * `minibuffer-local-completion-map' is for permissive completion.
662 * `minibuffer-local-must-match-map' is for strict completion and for
666 File: lispref.info, Node: Text from Minibuffer, Next: Object from Minibuffer, Prev: Intro to Minibuffers, Up: Minibuffers
668 Reading Text Strings with the Minibuffer
669 ========================================
671 Most often, the minibuffer is used to read text as a string. It can
672 also be used to read a Lisp object in textual form. The most basic
673 primitive for minibuffer input is `read-from-minibuffer'; it can do
676 In most cases, you should not call minibuffer input functions in the
677 middle of a Lisp function. Instead, do all minibuffer input as part of
678 reading the arguments for a command, in the `interactive' spec. *Note
681 - Function: read-from-minibuffer PROMPT-STRING &optional
682 INITIAL-CONTENTS KEYMAP READ HIST
683 This function is the most general way to get input through the
684 minibuffer. By default, it accepts arbitrary text and returns it
685 as a string; however, if READ is non-`nil', then it uses `read' to
686 convert the text into a Lisp object (*note Input Functions::.).
688 The first thing this function does is to activate a minibuffer and
689 display it with PROMPT-STRING as the prompt. This value must be a
692 Then, if INITIAL-CONTENTS is a string, `read-from-minibuffer'
693 inserts it into the minibuffer, leaving point at the end. The
694 minibuffer appears with this text as its contents.
696 The value of INITIAL-CONTENTS may also be a cons cell of the form
697 `(STRING . POSITION)'. This means to insert STRING in the
698 minibuffer but put point POSITION characters from the beginning,
699 rather than at the end.
701 If KEYMAP is non-`nil', that keymap is the local keymap to use in
702 the minibuffer. If KEYMAP is omitted or `nil', the value of
703 `minibuffer-local-map' is used as the keymap. Specifying a keymap
704 is the most important way to customize the minibuffer for various
705 applications such as completion.
707 The argument HIST specifies which history list variable to use for
708 saving the input and for history commands used in the minibuffer.
709 It defaults to `minibuffer-history'. *Note Minibuffer History::.
711 When the user types a command to exit the minibuffer,
712 `read-from-minibuffer' uses the text in the minibuffer to produce
713 its return value. Normally it simply makes a string containing
714 that text. However, if READ is non-`nil', `read-from-minibuffer'
715 reads the text and returns the resulting Lisp object, unevaluated.
716 (*Note Input Functions::, for information about reading.)
718 - Function: read-string PROMPT &optional INITIAL
719 This function reads a string from the minibuffer and returns it.
720 The arguments PROMPT and INITIAL are used as in
721 `read-from-minibuffer'. The keymap used is `minibuffer-local-map'.
723 This is a simplified interface to the `read-from-minibuffer'
726 (read-string PROMPT INITIAL)
728 (read-from-minibuffer PROMPT INITIAL nil nil nil)
730 - Variable: minibuffer-local-map
731 This is the default local keymap for reading from the minibuffer.
732 By default, it makes the following bindings:
741 `abort-recursive-edit'
744 `next-history-element'
747 `previous-history-element'
750 `next-matching-history-element'
753 `previous-matching-history-element'
755 - Function: read-no-blanks-input PROMPT &optional INITIAL
756 This function reads a string from the minibuffer, but does not
757 allow whitespace characters as part of the input: instead, those
758 characters terminate the input. The arguments PROMPT and INITIAL
759 are used as in `read-from-minibuffer'.
761 This is a simplified interface to the `read-from-minibuffer'
762 function, and passes the value of the `minibuffer-local-ns-map'
763 keymap as the KEYMAP argument for that function. Since the keymap
764 `minibuffer-local-ns-map' does not rebind `C-q', it *is* possible
765 to put a space into the string, by quoting it.
767 (read-no-blanks-input PROMPT INITIAL)
769 (read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map)
771 - Variable: minibuffer-local-ns-map
772 This built-in variable is the keymap used as the minibuffer local
773 keymap in the function `read-no-blanks-input'. By default, it
774 makes the following bindings, in addition to those of
775 `minibuffer-local-map':
784 `self-insert-and-exit'
787 File: lispref.info, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers
789 Reading Lisp Objects with the Minibuffer
790 ========================================
792 This section describes functions for reading Lisp objects with the
795 - Function: read-minibuffer PROMPT &optional INITIAL
796 This function reads a Lisp object in the minibuffer and returns it,
797 without evaluating it. The arguments PROMPT and INITIAL are used
798 as in `read-from-minibuffer'.
800 This is a simplified interface to the `read-from-minibuffer'
803 (read-minibuffer PROMPT INITIAL)
805 (read-from-minibuffer PROMPT INITIAL nil t)
807 Here is an example in which we supply the string `"(testing)"' as
811 "Enter an expression: " (format "%s" '(testing)))
813 ;; Here is how the minibuffer is displayed:
815 ---------- Buffer: Minibuffer ----------
816 Enter an expression: (testing)-!-
817 ---------- Buffer: Minibuffer ----------
819 The user can type <RET> immediately to use the initial input as a
820 default, or can edit the input.
822 - Function: eval-minibuffer PROMPT &optional INITIAL
823 This function reads a Lisp expression in the minibuffer, evaluates
824 it, then returns the result. The arguments PROMPT and INITIAL are
825 used as in `read-from-minibuffer'.
827 This function simply evaluates the result of a call to
830 (eval-minibuffer PROMPT INITIAL)
832 (eval (read-minibuffer PROMPT INITIAL))
834 - Function: edit-and-eval-command PROMPT FORM
835 This function reads a Lisp expression in the minibuffer, and then
836 evaluates it. The difference between this command and
837 `eval-minibuffer' is that here the initial FORM is not optional
838 and it is treated as a Lisp object to be converted to printed
839 representation rather than as a string of text. It is printed with
840 `prin1', so if it is a string, double-quote characters (`"')
841 appear in the initial text. *Note Output Functions::.
843 The first thing `edit-and-eval-command' does is to activate the
844 minibuffer with PROMPT as the prompt. Then it inserts the printed
845 representation of FORM in the minibuffer, and lets the user edit.
846 When the user exits the minibuffer, the edited text is read with
847 `read' and then evaluated. The resulting value becomes the value
848 of `edit-and-eval-command'.
850 In the following example, we offer the user an expression with
851 initial text which is a valid form already:
853 (edit-and-eval-command "Please edit: " '(forward-word 1))
855 ;; After evaluation of the preceding expression,
856 ;; the following appears in the minibuffer:
858 ---------- Buffer: Minibuffer ----------
859 Please edit: (forward-word 1)-!-
860 ---------- Buffer: Minibuffer ----------
862 Typing <RET> right away would exit the minibuffer and evaluate the
863 expression, thus moving point forward one word.
864 `edit-and-eval-command' returns `t' in this example.
867 File: lispref.info, Node: Minibuffer History, Next: Completion, Prev: Object from Minibuffer, Up: Minibuffers
872 A "minibuffer history list" records previous minibuffer inputs so
873 the user can reuse them conveniently. A history list is actually a
874 symbol, not a list; it is a variable whose value is a list of strings
875 (previous inputs), most recent first.
877 There are many separate history lists, used for different kinds of
878 inputs. It's the Lisp programmer's job to specify the right history
879 list for each use of the minibuffer.
881 The basic minibuffer input functions `read-from-minibuffer' and
882 `completing-read' both accept an optional argument named HIST which is
883 how you specify the history list. Here are the possible values:
886 Use VARIABLE (a symbol) as the history list.
888 (VARIABLE . STARTPOS)
889 Use VARIABLE (a symbol) as the history list, and assume that the
890 initial history position is STARTPOS (an integer, counting from
891 zero which specifies the most recent element of the history).
893 If you specify STARTPOS, then you should also specify that element
894 of the history as the initial minibuffer contents, for consistency.
896 If you don't specify HIST, then the default history list
897 `minibuffer-history' is used. For other standard history lists, see
898 below. You can also create your own history list variable; just
899 initialize it to `nil' before the first use.
901 Both `read-from-minibuffer' and `completing-read' add new elements
902 to the history list automatically, and provide commands to allow the
903 user to reuse items on the list. The only thing your program needs to
904 do to use a history list is to initialize it and to pass its name to
905 the input functions when you wish. But it is safe to modify the list
906 by hand when the minibuffer input functions are not using it.
908 - Variable: minibuffer-history
909 The default history list for minibuffer history input.
911 - Variable: query-replace-history
912 A history list for arguments to `query-replace' (and similar
913 arguments to other commands).
915 - Variable: file-name-history
916 A history list for file name arguments.
918 - Variable: regexp-history
919 A history list for regular expression arguments.
921 - Variable: extended-command-history
922 A history list for arguments that are names of extended commands.
924 - Variable: shell-command-history
925 A history list for arguments that are shell commands.
927 - Variable: read-expression-history
928 A history list for arguments that are Lisp expressions to evaluate.
930 - Variable: Info-minibuffer-history
931 A history list for Info mode's minibuffer.
933 - Variable: Manual-page-minibuffer-history
934 A history list for `manual-entry'.
936 There are many other minibuffer history lists, defined by various
937 libraries. An `M-x apropos' search for `history' should prove fruitful
941 File: lispref.info, Node: Completion, Next: Yes-or-No Queries, Prev: Minibuffer History, Up: Minibuffers
946 "Completion" is a feature that fills in the rest of a name starting
947 from an abbreviation for it. Completion works by comparing the user's
948 input against a list of valid names and determining how much of the
949 name is determined uniquely by what the user has typed. For example,
950 when you type `C-x b' (`switch-to-buffer') and then type the first few
951 letters of the name of the buffer to which you wish to switch, and then
952 type <TAB> (`minibuffer-complete'), Emacs extends the name as far as it
955 Standard XEmacs commands offer completion for names of symbols,
956 files, buffers, and processes; with the functions in this section, you
957 can implement completion for other kinds of names.
959 The `try-completion' function is the basic primitive for completion:
960 it returns the longest determined completion of a given initial string,
961 with a given set of strings to match against.
963 The function `completing-read' provides a higher-level interface for
964 completion. A call to `completing-read' specifies how to determine the
965 list of valid names. The function then activates the minibuffer with a
966 local keymap that binds a few keys to commands useful for completion.
967 Other functions provide convenient simple interfaces for reading
968 certain kinds of names with completion.
972 * Basic Completion:: Low-level functions for completing strings.
973 (These are too low level to use the minibuffer.)
974 * Minibuffer Completion:: Invoking the minibuffer with completion.
975 * Completion Commands:: Minibuffer commands that do completion.
976 * High-Level Completion:: Convenient special cases of completion
977 (reading buffer name, file name, etc.)
978 * Reading File Names:: Using completion to read file names.
979 * Programmed Completion:: Finding the completions for a given file name.
982 File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion
984 Basic Completion Functions
985 --------------------------
987 The two functions `try-completion' and `all-completions' have
988 nothing in themselves to do with minibuffers. We describe them in this
989 chapter so as to keep them near the higher-level completion features
990 that do use the minibuffer.
992 - Function: try-completion STRING COLLECTION &optional PREDICATE
993 This function returns the longest common substring of all possible
994 completions of STRING in COLLECTION. The value of COLLECTION must
995 be an alist, an obarray, or a function that implements a virtual
996 set of strings (see below).
998 Completion compares STRING against each of the permissible
999 completions specified by COLLECTION; if the beginning of the
1000 permissible completion equals STRING, it matches. If no
1001 permissible completions match, `try-completion' returns `nil'. If
1002 only one permissible completion matches, and the match is exact,
1003 then `try-completion' returns `t'. Otherwise, the value is the
1004 longest initial sequence common to all the permissible completions
1007 If COLLECTION is an alist (*note Association Lists::.), the CARs
1008 of the alist elements form the set of permissible completions.
1010 If COLLECTION is an obarray (*note Creating Symbols::.), the names
1011 of all symbols in the obarray form the set of permissible
1012 completions. The global variable `obarray' holds an obarray
1013 containing the names of all interned Lisp symbols.
1015 Note that the only valid way to make a new obarray is to create it
1016 empty and then add symbols to it one by one using `intern'. Also,
1017 you cannot intern a given symbol in more than one obarray.
1019 If the argument PREDICATE is non-`nil', then it must be a function
1020 of one argument. It is used to test each possible match, and the
1021 match is accepted only if PREDICATE returns non-`nil'. The
1022 argument given to PREDICATE is either a cons cell from the alist
1023 (the CAR of which is a string) or else it is a symbol (*not* a
1024 symbol name) from the obarray.
1026 You can also use a symbol that is a function as COLLECTION. Then
1027 the function is solely responsible for performing completion;
1028 `try-completion' returns whatever this function returns. The
1029 function is called with three arguments: STRING, PREDICATE and
1030 `nil'. (The reason for the third argument is so that the same
1031 function can be used in `all-completions' and do the appropriate
1032 thing in either case.) *Note Programmed Completion::.
1034 In the first of the following examples, the string `foo' is
1035 matched by three of the alist CARs. All of the matches begin with
1036 the characters `fooba', so that is the result. In the second
1037 example, there is only one possible match, and it is exact, so the
1042 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
1045 (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
1048 In the following example, numerous symbols begin with the
1049 characters `forw', and all of them begin with the word `forward'.
1050 In most of the symbols, this is followed with a `-', but not in
1051 all, so no more than `forward' can be completed.
1053 (try-completion "forw" obarray)
1056 Finally, in the following example, only two of the three possible
1057 matches pass the predicate `test' (the string `foobaz' is too
1058 short). Both of those begin with the string `foobar'.
1061 (> (length (car s)) 6))
1066 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
1070 - Function: all-completions STRING COLLECTION &optional PREDICATE
1072 This function returns a list of all possible completions of
1073 STRING. The parameters to this function are the same as to
1076 If COLLECTION is a function, it is called with three arguments:
1077 STRING, PREDICATE and `t'; then `all-completions' returns whatever
1078 the function returns. *Note Programmed Completion::.
1080 If NOSPACE is non-`nil', completions that start with a space are
1081 ignored unless STRING also starts with a space.
1083 Here is an example, using the function `test' shown in the example
1084 for `try-completion':
1087 (> (length (car s)) 6))
1092 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
1094 => ("foobar1" "foobar2")
1096 - Variable: completion-ignore-case
1097 If the value of this variable is non-`nil', XEmacs does not
1098 consider case significant in completion.
1101 File: lispref.info, Node: Minibuffer Completion, Next: Completion Commands, Prev: Basic Completion, Up: Completion
1103 Completion and the Minibuffer
1104 -----------------------------
1106 This section describes the basic interface for reading from the
1107 minibuffer with completion.
1109 - Function: completing-read PROMPT COLLECTION &optional PREDICATE
1110 REQUIRE-MATCH INITIAL HIST
1111 This function reads a string in the minibuffer, assisting the user
1112 by providing completion. It activates the minibuffer with prompt
1113 PROMPT, which must be a string. If INITIAL is non-`nil',
1114 `completing-read' inserts it into the minibuffer as part of the
1115 input. Then it allows the user to edit the input, providing
1116 several commands to attempt completion.
1118 The actual completion is done by passing COLLECTION and PREDICATE
1119 to the function `try-completion'. This happens in certain
1120 commands bound in the local keymaps used for completion.
1122 If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't
1123 exit unless the input completes to an element of COLLECTION. If
1124 REQUIRE-MATCH is neither `nil' nor `t', then the exit commands
1125 won't exit unless the input typed is itself an element of
1126 COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work
1127 regardless of the input in the minibuffer.
1129 The user can exit with null input by typing <RET> with an empty
1130 minibuffer. Then `completing-read' returns `nil'. This is how
1131 the user requests whatever default the command uses for the value
1132 being read. The user can return using <RET> in this way regardless
1133 of the value of REQUIRE-MATCH.
1135 The function `completing-read' works by calling `read-minibuffer'.
1136 It uses `minibuffer-local-completion-map' as the keymap if
1137 REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map'
1138 if REQUIRE-MATCH is non-`nil'. *Note Completion Commands::.
1140 The argument HIST specifies which history list variable to use for
1141 saving the input and for minibuffer history commands. It defaults
1142 to `minibuffer-history'. *Note Minibuffer History::.
1144 Completion ignores case when comparing the input against the
1145 possible matches, if the built-in variable
1146 `completion-ignore-case' is non-`nil'. *Note Basic Completion::.
1148 Here's an example of using `completing-read':
1152 '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
1155 ;; After evaluation of the preceding expression,
1156 ;; the following appears in the minibuffer:
1158 ---------- Buffer: Minibuffer ----------
1159 Complete a foo: fo-!-
1160 ---------- Buffer: Minibuffer ----------
1162 If the user then types `<DEL> <DEL> b <RET>', `completing-read'
1165 The `completing-read' function binds three variables to pass
1166 information to the commands that actually do completion. These
1167 variables are `minibuffer-completion-table',
1168 `minibuffer-completion-predicate' and
1169 `minibuffer-completion-confirm'. For more information about them,
1170 see *Note Completion Commands::.
1173 File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
1175 Minibuffer Commands That Do Completion
1176 --------------------------------------
1178 This section describes the keymaps, commands and user options used in
1179 the minibuffer to do completion.
1181 - Variable: minibuffer-local-completion-map
1182 `completing-read' uses this value as the local keymap when an
1183 exact match of one of the completions is not required. By
1184 default, this keymap makes the following bindings:
1187 `minibuffer-completion-help'
1190 `minibuffer-complete-word'
1193 `minibuffer-complete'
1195 with other characters bound as in `minibuffer-local-map' (*note
1196 Text from Minibuffer::.).
1198 - Variable: minibuffer-local-must-match-map
1199 `completing-read' uses this value as the local keymap when an
1200 exact match of one of the completions is required. Therefore, no
1201 keys are bound to `exit-minibuffer', the command that exits the
1202 minibuffer unconditionally. By default, this keymap makes the
1206 `minibuffer-completion-help'
1209 `minibuffer-complete-word'
1212 `minibuffer-complete'
1215 `minibuffer-complete-and-exit'
1218 `minibuffer-complete-and-exit'
1220 with other characters bound as in `minibuffer-local-map'.
1222 - Variable: minibuffer-completion-table
1223 The value of this variable is the alist or obarray used for
1224 completion in the minibuffer. This is the global variable that
1225 contains what `completing-read' passes to `try-completion'. It is
1226 used by minibuffer completion commands such as
1227 `minibuffer-complete-word'.
1229 - Variable: minibuffer-completion-predicate
1230 This variable's value is the predicate that `completing-read'
1231 passes to `try-completion'. The variable is also used by the other
1232 minibuffer completion functions.
1234 - Command: minibuffer-complete-word
1235 This function completes the minibuffer contents by at most a single
1236 word. Even if the minibuffer contents have only one completion,
1237 `minibuffer-complete-word' does not add any characters beyond the
1238 first character that is not a word constituent. *Note Syntax
1241 - Command: minibuffer-complete
1242 This function completes the minibuffer contents as far as possible.
1244 - Command: minibuffer-complete-and-exit
1245 This function completes the minibuffer contents, and exits if
1246 confirmation is not required, i.e., if
1247 `minibuffer-completion-confirm' is non-`nil'. If confirmation
1248 *is* required, it is given by repeating this command
1249 immediately--the command is programmed to work without confirmation
1250 when run twice in succession.
1252 - Variable: minibuffer-completion-confirm
1253 When the value of this variable is non-`nil', XEmacs asks for
1254 confirmation of a completion before exiting the minibuffer. The
1255 function `minibuffer-complete-and-exit' checks the value of this
1256 variable before it exits.
1258 - Command: minibuffer-completion-help
1259 This function creates a list of the possible completions of the
1260 current minibuffer contents. It works by calling `all-completions'
1261 using the value of the variable `minibuffer-completion-table' as
1262 the COLLECTION argument, and the value of
1263 `minibuffer-completion-predicate' as the PREDICATE argument. The
1264 list of completions is displayed as text in a buffer named
1267 - Function: display-completion-list COMPLETIONS
1268 This function displays COMPLETIONS to the stream in
1269 `standard-output', usually a buffer. (*Note Read and Print::, for
1270 more information about streams.) The argument COMPLETIONS is
1271 normally a list of completions just returned by `all-completions',
1272 but it does not have to be. Each element may be a symbol or a
1273 string, either of which is simply printed, or a list of two
1274 strings, which is printed as if the strings were concatenated.
1276 This function is called by `minibuffer-completion-help'. The most
1277 common way to use it is together with
1278 `with-output-to-temp-buffer', like this:
1280 (with-output-to-temp-buffer "*Completions*"
1281 (display-completion-list
1282 (all-completions (buffer-string) my-alist)))
1284 - User Option: completion-auto-help
1285 If this variable is non-`nil', the completion commands
1286 automatically display a list of possible completions whenever
1287 nothing can be completed because the next character is not
1288 uniquely determined.