-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls
+
+Specification Examples
+......................
+
+ Here we provide several examples of Edebug specifications to show
+many of its capabilities.
+
+ A `let' special form has a sequence of bindings and a body. Each of
+the bindings is either a symbol or a sublist with a symbol and optional
+value. In the specification below, notice the `gate' inside of the
+sublist to prevent backtracking.
+
+ (def-edebug-spec let
+ ((&rest
+ &or symbolp (gate symbolp &optional form))
+ body))
+
+ Edebug uses the following specifications for `defun' and `defmacro'
+and the associated argument list and `interactive' specifications. It
+is necessary to handle the expression argument of an interactive form
+specially since it is actually evaluated outside of the function body.
+
+ (def-edebug-spec defmacro defun) ; Indirect ref to `defun' spec
+ (def-edebug-spec defun
+ (&define name lambda-list
+ [&optional stringp] ; Match the doc string, if present.
+ [&optional ("interactive" interactive)]
+ def-body))
+
+ (def-edebug-spec lambda-list
+ (([&rest arg]
+ [&optional ["&optional" arg &rest arg]]
+ &optional ["&rest" arg]
+ )))
+
+ (def-edebug-spec interactive
+ (&optional &or stringp def-form)) ; Notice: `def-form'
+
+ The specification for backquote below illustrates how to match
+dotted lists and use `nil' to terminate recursion. It also illustrates
+how components of a vector may be matched. (The actual specification
+provided by Edebug does not support dotted lists because doing so
+causes very deep recursion that could fail.)
+
+ (def-edebug-spec ` (backquote-form)) ;; alias just for clarity
+
+ (def-edebug-spec backquote-form
+ (&or ([&or "," ",@"] &or ("quote" backquote-form) form)
+ (backquote-form . [&or nil backquote-form])
+ (vector &rest backquote-form)
+ sexp))
+
+\1f
+File: lispref.info, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug
+
+Edebug Options
+--------------
+
+ These options affect the behavior of Edebug:
+
+ - User Option: edebug-setup-hook
+ Functions to call before Edebug is used. Each time it is set to a
+ new value, Edebug will call those functions once and then
+ `edebug-setup-hook' is reset to `nil'. You could use this to load
+ up Edebug specifications associated with a package you are using
+ but only when you also use Edebug. See *Note Instrumenting::.
+
+ - User Option: edebug-all-defs
+ If non-`nil', normal evaluation of any defining forms (e.g.
+ `defun' and `defmacro') will instrument them for Edebug. This
+ applies to `eval-defun', `eval-region', and `eval-current-buffer'.
+
+ Use the command `M-x edebug-all-defs' to toggle the value of this
+ variable. You may want to make this variable local to each buffer
+ by calling `(make-local-variable 'edebug-all-defs)' in your
+ `emacs-lisp-mode-hook'. See *Note Instrumenting::.
+
+ - User Option: edebug-all-forms
+ If non-`nil', normal evaluation of any forms by `eval-defun',
+ `eval-region', and `eval-current-buffer' will instrument them for
+ Edebug.
+
+ Use the command `M-x edebug-all-forms' to toggle the value of this
+ option. See *Note Instrumenting::.
+
+ - User Option: edebug-save-windows
+ If non-`nil', save and restore window configuration on Edebug
+ calls. It takes some time to do this, so if your program does not
+ care what happens to data about windows, you may want to set this
+ variable to `nil'.
+
+ If the value is a list, only the listed windows are saved and
+ restored.
+
+ `M-x edebug-toggle-save-windows' may be used to change this
+ variable. This command is bound to `W' in source code buffers.
+ See *Note Edebug Display Update::.
+
+ - User Option: edebug-save-displayed-buffer-points
+ If non-`nil', save and restore point in all displayed buffers.
+ This is necessary if you are debugging code that changes the point
+ of a buffer which is displayed in a non-selected window. If
+ Edebug or the user then selects the window, the buffer's point
+ will be changed to the window's point.
+
+ This is an expensive operation since it visits each window and
+ therefore each displayed buffer twice for each Edebug activation,
+ so it is best to avoid it if you can. See *Note Edebug Display
+ Update::.
+
+ - User Option: edebug-initial-mode
+ If this variable is non-`nil', it specifies the initial execution
+ mode for Edebug when it is first activated. Possible values are
+ `step', `next', `go', `Go-nonstop', `trace', `Trace-fast',
+ `continue', and `Continue-fast'.
+
+ The default value is `step'. See *Note Edebug Execution Modes::.
+
+ - User Option: edebug-trace
+ Non-`nil' means display a trace of function entry and exit.
+ Tracing output is displayed in a buffer named `*edebug-trace*', one
+ function entry or exit per line, indented by the recursion level.
+
+ The default value is `nil'.
+
+ Also see `edebug-tracing'. See *Note Tracing::.
+
+ - User Option: edebug-test-coverage
+ If non-`nil', Edebug tests coverage of all expressions debugged.
+ This is done by comparing the result of each expression with the
+ previous result. Coverage is considered OK if two different
+ results are found. So to sufficiently test the coverage of your
+ code, try to execute it under conditions that evaluate all
+ expressions more than once, and produce different results for each
+ expression.
+
+ Use `M-x edebug-display-freq-count' to display the frequency count
+ and coverage information for a definition. See *Note Coverage
+ Testing::.
+
+ - User Option: edebug-continue-kbd-macro
+ If non-`nil', continue defining or executing any keyboard macro
+ that is executing outside of Edebug. Use this with caution since
+ it is not debugged. See *Note Edebug Execution Modes::.
+
+ - User Option: edebug-print-length
+ If non-`nil', bind `print-length' to this while printing results
+ in Edebug. The default value is `50'. See *Note Printing in
+ Edebug::.
+
+ - User Option: edebug-print-level
+ If non-`nil', bind `print-level' to this while printing results in
+ Edebug. The default value is `50'.
+
+ - User Option: edebug-print-circle
+ If non-`nil', bind `print-circle' to this while printing results
+ in Edebug. The default value is `nil'.
+
+ - User Option: edebug-on-error
+ `debug-on-error' is bound to this while Edebug is active. See
+ *Note Trapping Errors::.
+
+ - User Option: edebug-on-quit
+ `debug-on-quit' is bound to this while Edebug is active. See
+ *Note Trapping Errors::.
+
+ - User Option: edebug-unwrap-results
+ Non-`nil' if Edebug should unwrap results of expressions. This is
+ useful when debugging macros where the results of expressions are
+ instrumented expressions. But don't do this when results might be
+ circular or an infinite loop will result. See *Note Debugging
+ Backquote::.
+
+ - User Option: edebug-global-break-condition
+ If non-`nil', an expression to test for at every stop point. If
+ the result is non-`nil', then break. Errors are ignored. See
+ *Note Global Break Condition::.
+
+\1f
+File: lispref.info, Node: Read and Print, Next: Minibuffers, Prev: Debugging, Up: Top
+
+Reading and Printing Lisp Objects
+*********************************
+
+ "Printing" and "reading" are the operations of converting Lisp
+objects to textual form and vice versa. They use the printed
+representations and read syntax described in *Note Lisp Data Types::.
+
+ This chapter describes the Lisp functions for reading and printing.
+It also describes "streams", which specify where to get the text (if
+reading) or where to put it (if printing).
+
+* Menu:
+
+* Streams Intro:: Overview of streams, reading and printing.
+* Input Streams:: Various data types that can be used as input streams.
+* Input Functions:: Functions to read Lisp objects from text.
+* Output Streams:: Various data types that can be used as output streams.
+* Output Functions:: Functions to print Lisp objects as text.
+* Output Variables:: Variables that control what the printing functions do.
+
+\1f
+File: lispref.info, Node: Streams Intro, Next: Input Streams, Up: Read and Print
+
+Introduction to Reading and Printing
+====================================
+
+ "Reading" a Lisp object means parsing a Lisp expression in textual
+form and producing a corresponding Lisp object. This is how Lisp
+programs get into Lisp from files of Lisp code. We call the text the
+"read syntax" of the object. For example, the text `(a . 5)' is the
+read syntax for a cons cell whose CAR is `a' and whose CDR is the
+number 5.
+
+ "Printing" a Lisp object means producing text that represents that
+object--converting the object to its printed representation. Printing
+the cons cell described above produces the text `(a . 5)'.
+
+ Reading and printing are more or less inverse operations: printing
+the object that results from reading a given piece of text often
+produces the same text, and reading the text that results from printing
+an object usually produces a similar-looking object. For example,
+printing the symbol `foo' produces the text `foo', and reading that text
+returns the symbol `foo'. Printing a list whose elements are `a' and
+`b' produces the text `(a b)', and reading that text produces a list
+(but not the same list) with elements `a' and `b'.
+
+ However, these two operations are not precisely inverses. There are
+three kinds of exceptions:
+
+ * Printing can produce text that cannot be read. For example,
+ buffers, windows, frames, subprocesses and markers print into text
+ that starts with `#'; if you try to read this text, you get an
+ error. There is no way to read those data types.
+
+ * One object can have multiple textual representations. For example,
+ `1' and `01' represent the same integer, and `(a b)' and `(a .
+ (b))' represent the same list. Reading will accept any of the
+ alternatives, but printing must choose one of them.
+
+ * Comments can appear at certain points in the middle of an object's
+ read sequence without affecting the result of reading it.
+
+\1f
File: lispref.info, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print
Input Streams
An `end-of-file' error is signaled if reading encounters an
unterminated list, vector, or string.
- - Function: read &optional STREAM
+ - 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
+ - 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
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::.).
+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.
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
+ - 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
-|
=> " came back"
- - Function: prin1 OBJECT &optional STREAM
+ - 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
-| The\ cat\ in"the hat"" came back"
=> " came back"
- - Function: princ OBJECT &optional STREAM
+ - Function: princ object &optional stream
This function outputs the printed representation of OBJECT to
STREAM. It returns OBJECT.
-| The cat in the "hat"
=> " in the \"hat\""
- - Function: terpri &optional STREAM
+ - Function: terpri &optional stream
This function outputs a newline to STREAM. The name stands for
"terminate print".
- - Function: write-char CHARACTER &optional STREAM
+ - Function: write-char character &optional stream
This function outputs CHARACTER to STREAM. It returns CHARACTER.
- - Function: prin1-to-string OBJECT &optional NOESCAPE
+ - Function: prin1-to-string object &optional noescape
This function returns a string containing the text that `prin1'
would have printed for the same argument.
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.
+ Do not _set_ this variable; bind it instead.
- Variable: print-length
The value of this variable is the maximum number of elements of a
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'.
+ 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
===========================
In most ways, a minibuffer is a normal XEmacs buffer. Most
-operations *within* a buffer, such as editing commands, work normally
+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
`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::.).
+(*note Keymaps::); these contain various exit commands and in some cases
+completion commands (*note Completion::).
* `minibuffer-local-map' is for ordinary input (no completion).
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 ABBREV-TABLE DEFAULT
+ - Function: read-from-minibuffer prompt-string &optional
+ initial-contents keymap read hist abbrev-table default
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::.).
+ 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
applications such as completion.
The argument ABBREV-TABLE specifies `local-abbrev-table' in the
- minibuffer (*note Standard Abbrev Tables::.).
+ minibuffer (*note Standard Abbrev Tables::).
The argument HIST specifies which history list variable to use for
saving the input and for history commands used in the minibuffer.
from the minibuffer on other occasions. However, if user is
supposed to edit default value, INITIAL-CONTENTS may be preferred.
- - Function: read-string PROMPT &optional INITIAL HISTORY
+ - Function: read-string prompt &optional initial history default-value
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'.
- The optional argument HISTORY, if non-nil, specifies a history
- list and optionally the initial position in the list.
+ The optional argument HISTORY, if non-`nil', specifies a history
+ list and optionally the initial position in the list. The optional
+ argument DEFAULT-VALUE specifies a default value to return if the
+ user enters null input; it should be a string.
This function is a simplified interface to the
`read-from-minibuffer' function:
- (read-string PROMPT INITIAL)
+ (read-string PROMPT INITIAL HISTORY DEFAULT)
==
- (read-from-minibuffer PROMPT INITIAL nil nil nil)
+ (read-from-minibuffer PROMPT INITIAL nil nil
+ HISTORY nil DEFAULT)))
- Variable: minibuffer-local-map
This is the default local keymap for reading from the minibuffer.
This section describes functions for reading Lisp objects with the
minibuffer.
- - Function: read-minibuffer PROMPT &optional INITIAL
+ - Function: read-expression prompt &optional initial history
+ default-value
This function reads a Lisp object using the minibuffer, and
returns it without evaluating it. The arguments PROMPT and
INITIAL are used as in `read-from-minibuffer'.
+ The optional argument HISTORY, if non-`nil', specifies a history
+ list and optionally the initial position in the list. The optional
+ argument DEFAULT-VALUE specifies a default value to return if the
+ user enters null input; it should be a string.
+
This is a simplified interface to the `read-from-minibuffer'
function:
- (read-minibuffer PROMPT INITIAL)
+ (read-expression PROMPT INITIAL HISTORY DEFAULT-VALUE)
==
- (read-from-minibuffer PROMPT INITIAL nil t)
+ (read-from-minibuffer PROMPT INITIAL nil t
+ HISTORY nil DEFAULT-VALUE)
Here is an example in which we supply the string `"(testing)"' as
initial input:
- (read-minibuffer
+ (read-expression
"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
+ - Function: read-minibuffer prompt &optional initial history
+ default-value
+ This is a FSF Emacs compatible function. Use `read-expression'
+ instead.
+
+ - Function: eval-minibuffer prompt &optional initial history
+ default-value
This function reads a Lisp expression using the minibuffer,
evaluates it, then returns the result. The arguments PROMPT and
INITIAL are used as in `read-from-minibuffer'.
+ The optional argument HISTORY, if non-`nil', specifies a history
+ list and optionally the initial position in the list. The optional
+ argument DEFAULT-VALUE specifies a default value to return if the
+ user enters null input; it should be a string.
+
This function simply evaluates the result of a call to
- `read-minibuffer':
+ `read-expression':
(eval-minibuffer PROMPT INITIAL)
==
- (eval (read-minibuffer PROMPT INITIAL))
+ (eval (read-expression PROMPT INITIAL))
- - Function: edit-and-eval-command PROMPT FORM
+ - Function: edit-and-eval-command prompt form &optional history
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
;; After evaluation of the preceding expression,
;; the following appears in the minibuffer:
-
+
---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)-!-
---------- Buffer: Minibuffer ----------
* 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 arguments to this function are the same as those of
- `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 DEFAULT
- 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.
-
- However, empty input is always permitted, regardless of the value
- of REQUIRE-MATCH; in that case, `completing-read' returns DEFAULT.
- The value of DEFAULT (if non-`nil') is also available to the user
- through the history commands.
-
- The user can exit with null input by typing <RET> with an empty
- minibuffer. Then `completing-read' returns `""'. 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, and regardless of whether the empty
- string is included in COLLECTION.
-
- 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'
-
- `C-j'
- `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 `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 / blobdiff