+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print
-
-Input Streams
-=============
-
- Most of the Lisp functions for reading text take an "input stream"
-as an argument. The input stream specifies where or how to get the
-characters of the text to be read. Here are the possible types of input
-stream:
-
-BUFFER
- The input characters are read from BUFFER, starting with the
- character directly after point. Point advances as characters are
- read.
-
-MARKER
- The input characters are read from the buffer that MARKER is in,
- starting with the character directly after the marker. The marker
- position advances as characters are read. The value of point in
- the buffer has no effect when the stream is a marker.
-
-STRING
- The input characters are taken from STRING, starting at the first
- character in the string and using as many characters as required.
-
-FUNCTION
- The input characters are generated by FUNCTION, one character per
- call. Normally FUNCTION is called with no arguments, and should
- return a character.
-
- Occasionally FUNCTION is called with one argument (always a
- character). When that happens, FUNCTION should save the argument
- and arrange to return it on the next call. This is called
- "unreading" the character; it happens when the Lisp reader reads
- one character too many and wants to "put it back where it came
- from".
-
-`t'
- `t' used as a stream means that the input is read from the
- minibuffer. In fact, the minibuffer is invoked once and the text
- given by the user is made into a string that is then used as the
- input stream.
-
-`nil'
- `nil' supplied as an input stream means to use the value of
- `standard-input' instead; that value is the "default input
- stream", and must be a non-`nil' input stream.
-
-SYMBOL
- A symbol as input stream is equivalent to the symbol's function
- definition (if any).
-
- Here is an example of reading from a stream that is a buffer, showing
-where point is located before and after:
-
- ---------- Buffer: foo ----------
- This-!- is the contents of foo.
- ---------- Buffer: foo ----------
-
- (read (get-buffer "foo"))
- => is
- (read (get-buffer "foo"))
- => the
-
- ---------- Buffer: foo ----------
- This is the-!- contents of foo.
- ---------- Buffer: foo ----------
-
-Note that the first read skips a space. Reading skips any amount of
-whitespace preceding the significant text.
-
- In Emacs 18, reading a symbol discarded the delimiter terminating the
-symbol. Thus, point would end up at the beginning of `contents' rather
-than after `the'. The Emacs 19 behavior is superior because it
-correctly handles input such as `bar(foo)', where the open-parenthesis
-that ends one object is needed as the beginning of another object.
-
- Here is an example of reading from a stream that is a marker,
-initially positioned at the beginning of the buffer shown. The value
-read is the symbol `This'.
-
-
- ---------- Buffer: foo ----------
- This is the contents of foo.
- ---------- Buffer: foo ----------
-
- (setq m (set-marker (make-marker) 1 (get-buffer "foo")))
- => #<marker at 1 in foo>
- (read m)
- => This
- m
- => #<marker at 5 in foo> ;; Before the first space.
-
- Here we read from the contents of a string:
-
- (read "(When in) the course")
- => (When in)
-
- The following example reads from the minibuffer. The prompt is:
-`Lisp expression: '. (That is always the prompt used when you read
-from the stream `t'.) The user's input is shown following the prompt.
-
- (read t)
- => 23
- ---------- Buffer: Minibuffer ----------
- Lisp expression: 23 <RET>
- ---------- Buffer: Minibuffer ----------
-
- Finally, here is an example of a stream that is a function, named
-`useless-stream'. Before we use the stream, we initialize the variable
-`useless-list' to a list of characters. Then each call to the function
-`useless-stream' obtains the next character in the list or unreads a
-character by adding it to the front of the list.
-
- (setq useless-list (append "XY()" nil))
- => (88 89 40 41)
-
- (defun useless-stream (&optional unread)
- (if unread
- (setq useless-list (cons unread useless-list))
- (prog1 (car useless-list)
- (setq useless-list (cdr useless-list)))))
- => useless-stream
-
-Now we read using the stream thus constructed:
-
- (read 'useless-stream)
- => XY
-
- useless-list
- => (40 41)
-
-Note that the open and close parentheses remains in the list. The Lisp
-reader encountered the open parenthesis, decided that it ended the
-input, and unread it. Another attempt to read from the stream at this
-point would read `()' and return `nil'.
-
-\1f
-File: lispref.info, Node: Input Functions, Next: Output Streams, Prev: Input Streams, Up: Read and Print
-
-Input Functions
-===============
-
- This section describes the Lisp functions and variables that pertain
-to reading.
-
- In the functions below, STREAM stands for an input stream (see the
-previous section). If STREAM is `nil' or omitted, it defaults to the
-value of `standard-input'.
-
- An `end-of-file' error is signaled if reading encounters an
-unterminated list, vector, or string.
-
- - Function: read &optional STREAM
- This function reads one textual Lisp expression from STREAM,
- returning it as a Lisp object. This is the basic Lisp input
- function.
-
- - Function: read-from-string STRING &optional START END
- This function reads the first textual Lisp expression from the
- text in STRING. It returns a cons cell whose CAR is that
- expression, and whose CDR is an integer giving the position of the
- next remaining character in the string (i.e., the first one not
- read).
-
- If START is supplied, then reading begins at index START in the
- string (where the first character is at index 0). If END is also
- supplied, then reading stops just before that index, as if the rest
- of the string were not there.
-
- For example:
-
- (read-from-string "(setq x 55) (setq y 5)")
- => ((setq x 55) . 11)
- (read-from-string "\"A short string\"")
- => ("A short string" . 16)
-
- ;; Read starting at the first character.
- (read-from-string "(list 112)" 0)
- => ((list 112) . 10)
- ;; Read starting at the second character.
- (read-from-string "(list 112)" 1)
- => (list . 5)
- ;; Read starting at the seventh character,
- ;; and stopping at the ninth.
- (read-from-string "(list 112)" 6 8)
- => (11 . 8)
-
- - Variable: standard-input
- This variable holds the default input stream--the stream that
- `read' uses when the STREAM argument is `nil'.
-
-\1f
-File: lispref.info, Node: Output Streams, Next: Output Functions, Prev: Input Functions, Up: Read and Print
-
-Output Streams
-==============
-
- An output stream specifies what to do with the characters produced
-by printing. Most print functions accept an output stream as an
-optional argument. Here are the possible types of output stream:
-
-BUFFER
- The output characters are inserted into BUFFER at point. Point
- advances as characters are inserted.
-
-MARKER
- The output characters are inserted into the buffer that MARKER
- points into, at the marker position. The marker position advances
- as characters are inserted. The value of point in the buffer has
- no effect on printing when the stream is a marker.
-
-FUNCTION
- The output characters are passed to FUNCTION, which is responsible
- for storing them away. It is called with a single character as
- argument, as many times as there are characters to be output, and
- is free to do anything at all with the characters it receives.
-
-`t'
- The output characters are displayed in the echo area.
-
-`nil'
- `nil' specified as an output stream means to the value of
- `standard-output' instead; that value is the "default output
- stream", and must be a non-`nil' output stream.
-
-SYMBOL
- A symbol as output stream is equivalent to the symbol's function
- definition (if any).
-
- Many of the valid output streams are also valid as input streams.
-The difference between input and output streams is therefore mostly one
-of how you use a Lisp object, not a distinction of types of object.
-
- Here is an example of a buffer used as an output stream. Point is
-initially located as shown immediately before the `h' in `the'. At the
-end, point is located directly before that same `h'.
-
- ---------- Buffer: foo ----------
- This is t-!-he contents of foo.
- ---------- Buffer: foo ----------
-
- (print "This is the output" (get-buffer "foo"))
- => "This is the output"
-
- ---------- Buffer: foo ----------
- This is t
- "This is the output"
- -!-he contents of foo.
- ---------- Buffer: foo ----------
-
- Now we show a use of a marker as an output stream. Initially, the
-marker is in buffer `foo', between the `t' and the `h' in the word
-`the'. At the end, the marker has advanced over the inserted text so
-that it remains positioned before the same `h'. Note that the location
-of point, shown in the usual fashion, has no effect.
-
- ---------- Buffer: foo ----------
- "This is the -!-output"
- ---------- Buffer: foo ----------
-
- m
- => #<marker at 11 in foo>
-
- (print "More output for foo." m)
- => "More output for foo."
-
- ---------- Buffer: foo ----------
- "This is t
- "More output for foo."
- he -!-output"
- ---------- Buffer: foo ----------
-
- m
- => #<marker at 35 in foo>
-
- The following example shows output to the echo area:
-
- (print "Echo Area output" t)
- => "Echo Area output"
- ---------- Echo Area ----------
- "Echo Area output"
- ---------- Echo Area ----------
-
- Finally, we show the use of a function as an output stream. The
-function `eat-output' takes each character that it is given and conses
-it onto the front of the list `last-output' (*note Building Lists::.).
-At the end, the list contains all the characters output, but in reverse
-order.
-
- (setq last-output nil)
- => nil
-
- (defun eat-output (c)
- (setq last-output (cons c last-output)))
- => eat-output
-
- (print "This is the output" 'eat-output)
- => "This is the output"
-
- last-output
- => (?\n ?\" ?t ?u ?p ?t ?u ?o ?\ ?e ?h ?t
- ?\ ?s ?i ?\ ?s ?i ?h ?T ?\" ?\n)
-
-Now we can put the output in the proper order by reversing the list:
-
- (concat (nreverse last-output))
- => "
- \"This is the output\"
- "
-
-Calling `concat' converts the list to a string so you can see its
-contents more clearly.
-
-\1f
-File: lispref.info, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Read and Print
-
-Output Functions
-================
-
- This section describes the Lisp functions for printing Lisp objects.
-
- Some of the XEmacs printing functions add quoting characters to the
-output when necessary so that it can be read properly. The quoting
-characters used are `"' and `\'; they distinguish strings from symbols,
-and prevent punctuation characters in strings and symbols from being
-taken as delimiters when reading. *Note Printed Representation::, for
-full details. You specify quoting or no quoting by the choice of
-printing function.
-
- If the text is to be read back into Lisp, then it is best to print
-with quoting characters to avoid ambiguity. Likewise, if the purpose is
-to describe a Lisp object clearly for a Lisp programmer. However, if
-the purpose of the output is to look nice for humans, then it is better
-to print without quoting.
-
- Printing a self-referent Lisp object requires an infinite amount of
-text. In certain cases, trying to produce this text leads to a stack
-overflow. XEmacs detects such recursion and prints `#LEVEL' instead of
-recursively printing an object already being printed. For example,
-here `#0' indicates a recursive reference to the object at level 0 of
-the current print operation:
-
- (setq foo (list nil))
- => (nil)
- (setcar foo foo)
- => (#0)
-
- In the functions below, STREAM stands for an output stream. (See
-the previous section for a description of output streams.) If STREAM
-is `nil' or omitted, it defaults to the value of `standard-output'.
-
- - Function: print OBJECT &optional STREAM
- The `print' function is a convenient way of printing. It outputs
- the printed representation of OBJECT to STREAM, printing in
- addition one newline before OBJECT and another after it. Quoting
- characters are used. `print' returns OBJECT. For example:
-
- (progn (print 'The\ cat\ in)
- (print "the hat")
- (print " came back"))
- -|
- -| The\ cat\ in
- -|
- -| "the hat"
- -|
- -| " came back"
- -|
- => " came back"
-
- - Function: prin1 OBJECT &optional STREAM
- This function outputs the printed representation of OBJECT to
- STREAM. It does not print newlines to separate output as `print'
- does, but it does use quoting characters just like `print'. It
- returns OBJECT.
-
- (progn (prin1 'The\ cat\ in)
- (prin1 "the hat")
- (prin1 " came back"))
- -| The\ cat\ in"the hat"" came back"
- => " came back"
-
- - Function: princ OBJECT &optional STREAM
- This function outputs the printed representation of OBJECT to
- STREAM. It returns OBJECT.
-
- This function is intended to produce output that is readable by
- people, not by `read', so it doesn't insert quoting characters and
- doesn't put double-quotes around the contents of strings. It does
- not add any spacing between calls.
-
- (progn
- (princ 'The\ cat)
- (princ " in the \"hat\""))
- -| The cat in the "hat"
- => " in the \"hat\""
-
- - Function: terpri &optional STREAM
- This function outputs a newline to STREAM. The name stands for
- "terminate print".
-
- - Function: write-char CHARACTER &optional STREAM
- This function outputs CHARACTER to STREAM. It returns CHARACTER.
-
- - Function: prin1-to-string OBJECT &optional NOESCAPE
- This function returns a string containing the text that `prin1'
- would have printed for the same argument.
-
- (prin1-to-string 'foo)
- => "foo"
- (prin1-to-string (mark-marker))
- => "#<marker at 2773 in strings.texi>"
-
- If NOESCAPE is non-`nil', that inhibits use of quoting characters
- in the output. (This argument is supported in Emacs versions 19
- and later.)
-
- (prin1-to-string "foo")
- => "\"foo\""
- (prin1-to-string "foo" t)
- => "foo"
-
- See `format', in *Note String Conversion::, for other ways to
- obtain the printed representation of a Lisp object as a string.
-
-\1f
-File: lispref.info, Node: Output Variables, Prev: Output Functions, Up: Read and Print
-
-Variables Affecting Output
-==========================
-
- - Variable: standard-output
- The value of this variable is the default output stream--the stream
- that print functions use when the STREAM argument is `nil'.
-
- - Variable: print-escape-newlines
- If this variable is non-`nil', then newline characters in strings
- are printed as `\n' and formfeeds are printed as `\f'. Normally
- these characters are printed as actual newlines and formfeeds.
-
- This variable affects the print functions `prin1' and `print', as
- well as everything that uses them. It does not affect `princ'.
- Here is an example using `prin1':
-
- (prin1 "a\nb")
- -| "a
- -| b"
- => "a
- b"
-
- (let ((print-escape-newlines t))
- (prin1 "a\nb"))
- -| "a\nb"
- => "a
- b"
-
- In the second expression, the local binding of
- `print-escape-newlines' is in effect during the call to `prin1',
- but not during the printing of the result.
-
- - Variable: print-readably
- If non-`nil', then all objects will be printed in a readable form.
- If an object has no readable representation, then an error is
- signalled. When `print-readably' is true, compiled-function
- objects will be written in `#[...]' form instead of in
- `#<compiled-function [...]>' form, and two-element lists of the
- form `(quote object)' will be written as the equivalent `'object'.
- Do not *set* this variable; bind it instead.
-
- - Variable: print-length
- The value of this variable is the maximum number of elements of a
- list that will be printed. If a list being printed has more than
- this many elements, it is abbreviated with an ellipsis.
-
- If the value is `nil' (the default), then there is no limit.
-
- (setq print-length 2)
- => 2
- (print '(1 2 3 4 5))
- -| (1 2 ...)
- => (1 2 ...)
-
- - Variable: print-level
- The value of this variable is the maximum depth of nesting of
- parentheses and brackets when printed. Any list or vector at a
- depth exceeding this limit is abbreviated with an ellipsis. A
- value of `nil' (which is the default) means no limit.
-
- This variable exists in version 19 and later versions.
-
- - Variable: print-string-length
- The value of this variable is the maximum number of characters of
- a string that will be printed. If a string being printed has more
- than this many characters, it is abbreviated with an ellipsis.
-
- - Variable: print-gensym
- If non-`nil', then uninterned symbols will be printed specially.
- Uninterned symbols are those which are not present in `obarray',
- that is, those which were made with `make-symbol' or by calling
- `intern' with a second argument.
-
- When `print-gensym' is true, such symbols will be preceded by
- `#:', which causes the reader to create a new symbol instead of
- interning and returning an existing one. Beware: The `#:' syntax
- creates a new symbol each time it is seen, so if you print an
- object which contains two pointers to the same uninterned symbol,
- `read' will not duplicate that structure.
-
- Also, since XEmacs has no real notion of packages, there is no way
- for the printer to distinguish between symbols interned in no
- obarray, and symbols interned in an alternate obarray.
-
- - Variable: float-output-format
- This variable holds the format descriptor string that Lisp uses to
- print floats. This is a `%'-spec like those accepted by `printf'
- in C, but with some restrictions. It must start with the two
- characters `%.'. After that comes an integer precision
- specification, and then a letter which controls the format. The
- letters allowed are `e', `f' and `g'.
-
- * Use `e' for exponential notation `DIG.DIGITSeEXPT'.
-
- * Use `f' for decimal point notation `DIGITS.DIGITS'.
-
- * Use `g' to choose the shorter of those two formats for the
- number at hand.
-
- The precision in any of these cases is the number of digits
- following the decimal point. With `f', a precision of 0 means to
- omit the decimal point. 0 is not allowed with `f' or `g'.
-
- A value of nil means to use `%.16g'.
-
- Regardless of the value of `float-output-format', a floating point
- number will never be printed in such a way that it is ambiguous
- with an integer; that is, a floating-point number will always be
- printed with a decimal point and/or an exponent, even if the
- digits following the decimal point are all zero. This is to
- preserve read-equivalence.
-
-\1f
-File: lispref.info, Node: Minibuffers, Next: Command Loop, Prev: Read and Print, Up: Top
-
-Minibuffers
-***********
-
- A "minibuffer" is a special buffer that XEmacs commands use to read
-arguments more complicated than the single numeric prefix argument.
-These arguments include file names, buffer names, and command names (as
-in `M-x'). The minibuffer is displayed on the bottom line of the
-frame, in the same place as the echo area, but only while it is in use
-for reading an argument.
-
-* Menu:
-
-* Intro to Minibuffers:: Basic information about minibuffers.
-* Text from Minibuffer:: How to read a straight text string.
-* Object from Minibuffer:: How to read a Lisp object or expression.
-* Minibuffer History:: Recording previous minibuffer inputs
- so the user can reuse them.
-* Completion:: How to invoke and customize completion.
-* Yes-or-No Queries:: Asking a question with a simple answer.
-* Multiple Queries:: Asking a series of similar questions.
-* Minibuffer Misc:: Various customization hooks and variables.
-
-\1f
-File: lispref.info, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers
-
-Introduction to Minibuffers
-===========================
-
- In most ways, a minibuffer is a normal XEmacs buffer. Most
-operations *within* a buffer, such as editing commands, work normally
-in a minibuffer. However, many operations for managing buffers do not
-apply to minibuffers. The name of a minibuffer always has the form
-` *Minibuf-NUMBER', and it cannot be changed. Minibuffers are
-displayed only in special windows used only for minibuffers; these
-windows always appear at the bottom of a frame. (Sometime frames have
-no minibuffer window, and sometimes a special kind of frame contains
-nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
-
- The minibuffer's window is normally a single line. You can resize it
-temporarily with the window sizing commands; it reverts to its normal
-size when the minibuffer is exited. You can resize it permanently by
-using the window sizing commands in the frame's other window, when the
-minibuffer is not active. If the frame contains just a minibuffer, you
-can change the minibuffer's size by changing the frame's size.
-
- If a command uses a minibuffer while there is an active minibuffer,
-this is called a "recursive minibuffer". The first minibuffer is named
-` *Minibuf-0*'. Recursive minibuffers are named by incrementing the
-number at the end of the name. (The names begin with a space so that
-they won't show up in normal buffer lists.) Of several recursive
-minibuffers, the innermost (or most recently entered) is the active
-minibuffer. We usually call this "the" minibuffer. You can permit or
-forbid recursive minibuffers by setting the variable
-`enable-recursive-minibuffers'.
-
- Like other buffers, a minibuffer may use any of several local keymaps
-(*note Keymaps::.); these contain various exit commands and in some
-cases completion commands (*note Completion::.).
-
- * `minibuffer-local-map' is for ordinary input (no completion).
-
- * `minibuffer-local-ns-map' is similar, except that <SPC> exits just
- like <RET>. This is used mainly for Mocklisp compatibility.
-
- * `minibuffer-local-completion-map' is for permissive completion.
-
- * `minibuffer-local-must-match-map' is for strict completion and for
- cautious completion.
-
-\1f
-File: lispref.info, Node: Text from Minibuffer, Next: Object from Minibuffer, Prev: Intro to Minibuffers, Up: Minibuffers
-
-Reading Text Strings with the Minibuffer
-========================================
-
- Most often, the minibuffer is used to read text as a string. It can
-also be used to read a Lisp object in textual form. The most basic
-primitive for minibuffer input is `read-from-minibuffer'; it can do
-either one.
-
- In most cases, you should not call minibuffer input functions in the
-middle of a Lisp function. Instead, do all minibuffer input as part of
-reading the arguments for a command, in the `interactive' spec. *Note
-Defining Commands::.
-
- - Function: read-from-minibuffer PROMPT-STRING &optional
- INITIAL-CONTENTS KEYMAP READ HIST
- This function is the most general way to get input through the
- minibuffer. By default, it accepts arbitrary text and returns it
- as a string; however, if READ is non-`nil', then it uses `read' to
- convert the text into a Lisp object (*note Input Functions::.).
-
- The first thing this function does is to activate a minibuffer and
- display it with PROMPT-STRING as the prompt. This value must be a
- string.
-
- Then, if INITIAL-CONTENTS is a string, `read-from-minibuffer'
- inserts it into the minibuffer, leaving point at the end. The
- minibuffer appears with this text as its contents.
-
- The value of INITIAL-CONTENTS may also be a cons cell of the form
- `(STRING . POSITION)'. This means to insert STRING in the
- minibuffer but put point POSITION characters from the beginning,
- rather than at the end.
-
- If KEYMAP is non-`nil', that keymap is the local keymap to use in
- the minibuffer. If KEYMAP is omitted or `nil', the value of
- `minibuffer-local-map' is used as the keymap. Specifying a keymap
- is the most important way to customize the minibuffer for various
- applications such as completion.
-
- The argument HIST specifies which history list variable to use for
- saving the input and for history commands used in the minibuffer.
- It defaults to `minibuffer-history'. *Note Minibuffer History::.
-
- When the user types a command to exit the minibuffer,
- `read-from-minibuffer' uses the text in the minibuffer to produce
- its return value. Normally it simply makes a string containing
- that text. However, if READ is non-`nil', `read-from-minibuffer'
- reads the text and returns the resulting Lisp object, unevaluated.
- (*Note Input Functions::, for information about reading.)
-
- - Function: read-string PROMPT &optional INITIAL
- This function reads a string from the minibuffer and returns it.
- The arguments PROMPT and INITIAL are used as in
- `read-from-minibuffer'. The keymap used is `minibuffer-local-map'.
-
- This is a simplified interface to the `read-from-minibuffer'
- function:
-
- (read-string PROMPT INITIAL)
- ==
- (read-from-minibuffer PROMPT INITIAL nil nil nil)
-
- - Variable: minibuffer-local-map
- This is the default local keymap for reading from the minibuffer.
- By default, it makes the following bindings:
-
- <LFD>
- `exit-minibuffer'
-
- <RET>
- `exit-minibuffer'
-
- `C-g'
- `abort-recursive-edit'
-
- `M-n'
- `next-history-element'
-
- `M-p'
- `previous-history-element'
-
- `M-r'
- `next-matching-history-element'
-
- `M-s'
- `previous-matching-history-element'
-
- - Function: read-no-blanks-input PROMPT &optional INITIAL
- This function reads a string from the minibuffer, but does not
- allow whitespace characters as part of the input: instead, those
- characters terminate the input. The arguments PROMPT and INITIAL
- are used as in `read-from-minibuffer'.
-
- This is a simplified interface to the `read-from-minibuffer'
- function, and passes the value of the `minibuffer-local-ns-map'
- keymap as the KEYMAP argument for that function. Since the keymap
- `minibuffer-local-ns-map' does not rebind `C-q', it *is* possible
- to put a space into the string, by quoting it.
-
- (read-no-blanks-input PROMPT INITIAL)
- ==
- (read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map)
-
- - Variable: minibuffer-local-ns-map
- This built-in variable is the keymap used as the minibuffer local
- keymap in the function `read-no-blanks-input'. By default, it
- makes the following bindings, in addition to those of
- `minibuffer-local-map':
-
- <SPC>
- `exit-minibuffer'
-
- <TAB>
- `exit-minibuffer'
-
- `?'
- `self-insert-and-exit'
-
-\1f
-File: lispref.info, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers
-
-Reading Lisp Objects with the Minibuffer
-========================================
-
- This section describes functions for reading Lisp objects with the
-minibuffer.
-
- - Function: read-minibuffer PROMPT &optional INITIAL
- This function reads a Lisp object in the minibuffer and returns it,
- without evaluating it. The arguments PROMPT and INITIAL are used
- as in `read-from-minibuffer'.
-
- This is a simplified interface to the `read-from-minibuffer'
- function:
-
- (read-minibuffer PROMPT INITIAL)
- ==
- (read-from-minibuffer PROMPT INITIAL nil t)
-
- Here is an example in which we supply the string `"(testing)"' as
- initial input:
-
- (read-minibuffer
- "Enter an expression: " (format "%s" '(testing)))
-
- ;; Here is how the minibuffer is displayed:
-
- ---------- Buffer: Minibuffer ----------
- Enter an expression: (testing)-!-
- ---------- Buffer: Minibuffer ----------
-
- The user can type <RET> immediately to use the initial input as a
- default, or can edit the input.
-
- - Function: eval-minibuffer PROMPT &optional INITIAL
- This function reads a Lisp expression in the minibuffer, evaluates
- it, then returns the result. The arguments PROMPT and INITIAL are
- used as in `read-from-minibuffer'.
-
- This function simply evaluates the result of a call to
- `read-minibuffer':
-
- (eval-minibuffer PROMPT INITIAL)
- ==
- (eval (read-minibuffer PROMPT INITIAL))
-
- - Function: edit-and-eval-command PROMPT FORM
- This function reads a Lisp expression in the minibuffer, and then
- evaluates it. The difference between this command and
- `eval-minibuffer' is that here the initial FORM is not optional
- and it is treated as a Lisp object to be converted to printed
- representation rather than as a string of text. It is printed with
- `prin1', so if it is a string, double-quote characters (`"')
- appear in the initial text. *Note Output Functions::.
-
- The first thing `edit-and-eval-command' does is to activate the
- minibuffer with PROMPT as the prompt. Then it inserts the printed
- representation of FORM in the minibuffer, and lets the user edit.
- When the user exits the minibuffer, the edited text is read with
- `read' and then evaluated. The resulting value becomes the value
- of `edit-and-eval-command'.
-
- In the following example, we offer the user an expression with
- initial text which is a valid form already:
-
- (edit-and-eval-command "Please edit: " '(forward-word 1))
-
- ;; After evaluation of the preceding expression,
- ;; the following appears in the minibuffer:
-
- ---------- Buffer: Minibuffer ----------
- Please edit: (forward-word 1)-!-
- ---------- Buffer: Minibuffer ----------
-
- Typing <RET> right away would exit the minibuffer and evaluate the
- expression, thus moving point forward one word.
- `edit-and-eval-command' returns `t' in this example.
-
-\1f
-File: lispref.info, Node: Minibuffer History, Next: Completion, Prev: Object from Minibuffer, Up: Minibuffers
-
-Minibuffer History
-==================
-
- A "minibuffer history list" records previous minibuffer inputs so
-the user can reuse them conveniently. A history list is actually a
-symbol, not a list; it is a variable whose value is a list of strings
-(previous inputs), most recent first.
-
- There are many separate history lists, used for different kinds of
-inputs. It's the Lisp programmer's job to specify the right history
-list for each use of the minibuffer.
-
- The basic minibuffer input functions `read-from-minibuffer' and
-`completing-read' both accept an optional argument named HIST which is
-how you specify the history list. Here are the possible values:
-
-VARIABLE
- Use VARIABLE (a symbol) as the history list.
-
-(VARIABLE . STARTPOS)
- Use VARIABLE (a symbol) as the history list, and assume that the
- initial history position is STARTPOS (an integer, counting from
- zero which specifies the most recent element of the history).
-
- If you specify STARTPOS, then you should also specify that element
- of the history as the initial minibuffer contents, for consistency.
-
- If you don't specify HIST, then the default history list
-`minibuffer-history' is used. For other standard history lists, see
-below. You can also create your own history list variable; just
-initialize it to `nil' before the first use.
-
- Both `read-from-minibuffer' and `completing-read' add new elements
-to the history list automatically, and provide commands to allow the
-user to reuse items on the list. The only thing your program needs to
-do to use a history list is to initialize it and to pass its name to
-the input functions when you wish. But it is safe to modify the list
-by hand when the minibuffer input functions are not using it.
-
- - Variable: minibuffer-history
- The default history list for minibuffer history input.
-
- - Variable: query-replace-history
- A history list for arguments to `query-replace' (and similar
- arguments to other commands).
-
- - Variable: file-name-history
- A history list for file name arguments.
-
- - Variable: regexp-history
- A history list for regular expression arguments.
-
- - Variable: extended-command-history
- A history list for arguments that are names of extended commands.
-
- - Variable: shell-command-history
- A history list for arguments that are shell commands.
-
- - Variable: read-expression-history
- A history list for arguments that are Lisp expressions to evaluate.
-
- - Variable: Info-minibuffer-history
- A history list for Info mode's minibuffer.
-
- - Variable: Manual-page-minibuffer-history
- A history list for `manual-entry'.
-
- There are many other minibuffer history lists, defined by various
-libraries. An `M-x apropos' search for `history' should prove fruitful
-in discovering them.
-
-\1f
-File: lispref.info, Node: Completion, Next: Yes-or-No Queries, Prev: Minibuffer History, Up: Minibuffers
-
-Completion
-==========
-
- "Completion" is a feature that fills in the rest of a name starting
-from an abbreviation for it. Completion works by comparing the user's
-input against a list of valid names and determining how much of the
-name is determined uniquely by what the user has typed. For example,
-when you type `C-x b' (`switch-to-buffer') and then type the first few
-letters of the name of the buffer to which you wish to switch, and then
-type <TAB> (`minibuffer-complete'), Emacs extends the name as far as it
-can.
-
- Standard XEmacs commands offer completion for names of symbols,
-files, buffers, and processes; with the functions in this section, you
-can implement completion for other kinds of names.
-
- The `try-completion' function is the basic primitive for completion:
-it returns the longest determined completion of a given initial string,
-with a given set of strings to match against.
-
- The function `completing-read' provides a higher-level interface for
-completion. A call to `completing-read' specifies how to determine the
-list of valid names. The function then activates the minibuffer with a
-local keymap that binds a few keys to commands useful for completion.
-Other functions provide convenient simple interfaces for reading
-certain kinds of names with completion.
-
-* Menu:
-
-* Basic Completion:: Low-level functions for completing strings.
- (These are too low level to use the minibuffer.)
-* Minibuffer Completion:: Invoking the minibuffer with completion.
-* Completion Commands:: Minibuffer commands that do completion.
-* High-Level Completion:: Convenient special cases of completion
- (reading buffer name, file name, etc.)
-* Reading File Names:: Using completion to read file names.
-* Programmed Completion:: Finding the completions for a given file name.
-
-\1f
-File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion
-
-Basic Completion Functions
---------------------------
-
- The two functions `try-completion' and `all-completions' have
-nothing in themselves to do with minibuffers. We describe them in this
-chapter so as to keep them near the higher-level completion features
-that do use the minibuffer.
-
- - Function: try-completion STRING COLLECTION &optional PREDICATE
- This function returns the longest common substring of all possible
- completions of STRING in COLLECTION. The value of COLLECTION must
- be an alist, an obarray, or a function that implements a virtual
- set of strings (see below).
-
- Completion compares STRING against each of the permissible
- completions specified by COLLECTION; if the beginning of the
- permissible completion equals STRING, it matches. If no
- permissible completions match, `try-completion' returns `nil'. If
- only one permissible completion matches, and the match is exact,
- then `try-completion' returns `t'. Otherwise, the value is the
- longest initial sequence common to all the permissible completions
- that match.
-
- If COLLECTION is an alist (*note Association Lists::.), the CARs
- of the alist elements form the set of permissible completions.
-
- If COLLECTION is an obarray (*note Creating Symbols::.), the names
- of all symbols in the obarray form the set of permissible
- completions. The global variable `obarray' holds an obarray
- containing the names of all interned Lisp symbols.
-
- Note that the only valid way to make a new obarray is to create it
- empty and then add symbols to it one by one using `intern'. Also,
- you cannot intern a given symbol in more than one obarray.
-
- If the argument PREDICATE is non-`nil', then it must be a function
- of one argument. It is used to test each possible match, and the
- match is accepted only if PREDICATE returns non-`nil'. The
- argument given to PREDICATE is either a cons cell from the alist
- (the CAR of which is a string) or else it is a symbol (*not* a
- symbol name) from the obarray.
-
- You can also use a symbol that is a function as COLLECTION. Then
- the function is solely responsible for performing completion;
- `try-completion' returns whatever this function returns. The
- function is called with three arguments: STRING, PREDICATE and
- `nil'. (The reason for the third argument is so that the same
- function can be used in `all-completions' and do the appropriate
- thing in either case.) *Note Programmed Completion::.
-
- In the first of the following examples, the string `foo' is
- matched by three of the alist CARs. All of the matches begin with
- the characters `fooba', so that is the result. In the second
- example, there is only one possible match, and it is exact, so the
- value is `t'.
-
- (try-completion
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
- => "fooba"
-
- (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
- => t
-
- In the following example, numerous symbols begin with the
- characters `forw', and all of them begin with the word `forward'.
- In most of the symbols, this is followed with a `-', but not in
- all, so no more than `forward' can be completed.
-
- (try-completion "forw" obarray)
- => "forward"
-
- Finally, in the following example, only two of the three possible
- matches pass the predicate `test' (the string `foobaz' is too
- short). Both of those begin with the string `foobar'.
-
- (defun test (s)
- (> (length (car s)) 6))
- => test
-
- (try-completion
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- 'test)
- => "foobar"
-
- - Function: all-completions STRING COLLECTION &optional PREDICATE
- NOSPACE
- This function returns a list of all possible completions of
- STRING. The parameters to this function are the same as to
- `try-completion'.
-
- If COLLECTION is a function, it is called with three arguments:
- STRING, PREDICATE and `t'; then `all-completions' returns whatever
- the function returns. *Note Programmed Completion::.
-
- If NOSPACE is non-`nil', completions that start with a space are
- ignored unless STRING also starts with a space.
-
- Here is an example, using the function `test' shown in the example
- for `try-completion':
-
- (defun test (s)
- (> (length (car s)) 6))
- => test
-
- (all-completions
- "foo"
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- 'test)
- => ("foobar1" "foobar2")
-
- - Variable: completion-ignore-case
- If the value of this variable is non-`nil', XEmacs does not
- consider case significant in completion.
-
-\1f
-File: lispref.info, Node: Minibuffer Completion, Next: Completion Commands, Prev: Basic Completion, Up: Completion
-
-Completion and the Minibuffer
------------------------------
-
- This section describes the basic interface for reading from the
-minibuffer with completion.
-
- - Function: completing-read PROMPT COLLECTION &optional PREDICATE
- REQUIRE-MATCH INITIAL HIST
- This function reads a string in the minibuffer, assisting the user
- by providing completion. It activates the minibuffer with prompt
- PROMPT, which must be a string. If INITIAL is non-`nil',
- `completing-read' inserts it into the minibuffer as part of the
- input. Then it allows the user to edit the input, providing
- several commands to attempt completion.
-
- The actual completion is done by passing COLLECTION and PREDICATE
- to the function `try-completion'. This happens in certain
- commands bound in the local keymaps used for completion.
-
- If REQUIRE-MATCH is `t', the usual minibuffer exit commands won't
- exit unless the input completes to an element of COLLECTION. If
- REQUIRE-MATCH is neither `nil' nor `t', then the exit commands
- won't exit unless the input typed is itself an element of
- COLLECTION. If REQUIRE-MATCH is `nil', the exit commands work
- regardless of the input in the minibuffer.
-
- The user can exit with null input by typing <RET> with an empty
- minibuffer. Then `completing-read' returns `nil'. This is how
- the user requests whatever default the command uses for the value
- being read. The user can return using <RET> in this way regardless
- of the value of REQUIRE-MATCH.
-
- The function `completing-read' works by calling `read-minibuffer'.
- It uses `minibuffer-local-completion-map' as the keymap if
- REQUIRE-MATCH is `nil', and uses `minibuffer-local-must-match-map'
- if REQUIRE-MATCH is non-`nil'. *Note Completion Commands::.
-
- The argument HIST specifies which history list variable to use for
- saving the input and for minibuffer history commands. It defaults
- to `minibuffer-history'. *Note Minibuffer History::.
-
- Completion ignores case when comparing the input against the
- possible matches, if the built-in variable
- `completion-ignore-case' is non-`nil'. *Note Basic Completion::.
-
- Here's an example of using `completing-read':
-
- (completing-read
- "Complete a foo: "
- '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
- nil t "fo")
-
- ;; After evaluation of the preceding expression,
- ;; the following appears in the minibuffer:
-
- ---------- Buffer: Minibuffer ----------
- Complete a foo: fo-!-
- ---------- Buffer: Minibuffer ----------
-
- If the user then types `<DEL> <DEL> b <RET>', `completing-read'
- returns `barfoo'.
-
- The `completing-read' function binds three variables to pass
- information to the commands that actually do completion. These
- variables are `minibuffer-completion-table',
- `minibuffer-completion-predicate' and
- `minibuffer-completion-confirm'. For more information about them,
- see *Note Completion Commands::.
-
-\1f
-File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
-
-Minibuffer Commands That Do Completion
---------------------------------------
-
- This section describes the keymaps, commands and user options used in
-the minibuffer to do completion.
-
- - Variable: minibuffer-local-completion-map
- `completing-read' uses this value as the local keymap when an
- exact match of one of the completions is not required. By
- default, this keymap makes the following bindings:
-
- `?'
- `minibuffer-completion-help'
-
- <SPC>
- `minibuffer-complete-word'
-
- <TAB>
- `minibuffer-complete'
-
- with other characters bound as in `minibuffer-local-map' (*note
- Text from Minibuffer::.).
-
- - Variable: minibuffer-local-must-match-map
- `completing-read' uses this value as the local keymap when an
- exact match of one of the completions is required. Therefore, no
- keys are bound to `exit-minibuffer', the command that exits the
- minibuffer unconditionally. By default, this keymap makes the
- following bindings:
-
- `?'
- `minibuffer-completion-help'
-
- <SPC>
- `minibuffer-complete-word'
-
- <TAB>
- `minibuffer-complete'
-
- <LFD>
- `minibuffer-complete-and-exit'
-
- <RET>
- `minibuffer-complete-and-exit'
-
- with other characters bound as in `minibuffer-local-map'.
-
- - Variable: minibuffer-completion-table
- The value of this variable is the alist or obarray used for
- completion in the minibuffer. This is the global variable that
- contains what `completing-read' passes to `try-completion'. It is
- used by minibuffer completion commands such as
- `minibuffer-complete-word'.
-
- - Variable: minibuffer-completion-predicate
- This variable's value is the predicate that `completing-read'
- passes to `try-completion'. The variable is also used by the other
- minibuffer completion functions.
-
- - Command: minibuffer-complete-word
- This function completes the minibuffer contents by at most a single
- word. Even if the minibuffer contents have only one completion,
- `minibuffer-complete-word' does not add any characters beyond the
- first character that is not a word constituent. *Note Syntax
- Tables::.
-
- - Command: minibuffer-complete
- This function completes the minibuffer contents as far as possible.
-
- - Command: minibuffer-complete-and-exit
- This function completes the minibuffer contents, and exits if
- confirmation is not required, i.e., if
- `minibuffer-completion-confirm' is non-`nil'. If confirmation
- *is* required, it is given by repeating this command
- immediately--the command is programmed to work without confirmation
- when run twice in succession.
-
- - Variable: minibuffer-completion-confirm
- When the value of this variable is non-`nil', XEmacs asks for
- confirmation of a completion before exiting the minibuffer. The
- function `minibuffer-complete-and-exit' checks the value of this
- variable before it exits.
-
- - Command: minibuffer-completion-help
- This function creates a list of the possible completions of the
- current minibuffer contents. It works by calling `all-completions'
- using the value of the variable `minibuffer-completion-table' as
- the COLLECTION argument, and the value of
- `minibuffer-completion-predicate' as the PREDICATE argument. The
- list of completions is displayed as text in a buffer named
- `*Completions*'.
-
- - Function: display-completion-list COMPLETIONS
- This function displays COMPLETIONS to the stream in
- `standard-output', usually a buffer. (*Note Read and Print::, for
- more information about streams.) The argument COMPLETIONS is
- normally a list of completions just returned by `all-completions',
- but it does not have to be. Each element may be a symbol or a
- string, either of which is simply printed, or a list of two
- strings, which is printed as if the strings were concatenated.
-
- This function is called by `minibuffer-completion-help'. The most
- common way to use it is together with
- `with-output-to-temp-buffer', like this:
-
- (with-output-to-temp-buffer "*Completions*"
- (display-completion-list
- (all-completions (buffer-string) my-alist)))
-
- - User Option: completion-auto-help
- If this variable is non-`nil', the completion commands
- automatically display a list of possible completions whenever
- nothing can be completed because the next character is not
- uniquely determined.
-
projects / chise / xemacs-chise.git.1 / blobdiff