-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file 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
* 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.
+* Reading a Password:: Reading a password from the terminal.
* Minibuffer Misc:: Various customization hooks and variables.
\1f
===========================
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
displayed only in special windows used only for minibuffers; these
-windows always appear at the bottom of a frame. (Sometime frames have
+windows always appear at the bottom of a frame. (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see *Note Minibuffers and Frames::.)
`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).
- * `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
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
+ - 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
minibuffer but put point POSITION characters from the beginning,
rather than at the end.
+ When the user types a command to exit the minibuffer,
+ `read-from-minibuffer' constructs the return value from the text in
+ the minibuffer. Normally it returns 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.)
+
+ The argument DEFAULT specifies a default value to make available
+ through the history commands. It should be a string, or `nil'.
+
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 ABBREV-TABLE specifies `local-abbrev-table' in the
+ 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.
It defaults to `minibuffer-history'. *Note Minibuffer History::.
reads the text and returns the resulting Lisp object, unevaluated.
(*Note Input Functions::, for information about reading.)
- - Function: read-string PROMPT &optional INITIAL
+ *Usage note:* The INITIAL-CONTENTS argument and the DEFAULT
+ argument are two alternative features for more or less the same
+ job. It does not make sense to use both features in a single call
+ to `read-from-minibuffer'. In general, we recommend using
+ DEFAULT, since this permits the user to insert the default value
+ when it is wanted, but does not burden the user with deleting it
+ 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 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'.
- This is a simplified interface to the `read-from-minibuffer'
- function:
+ 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.
By default, it makes the following bindings:
- <LFD>
+ `C-j'
`exit-minibuffer'
<RET>
`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
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'.
+ - 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
- 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'.
+ - 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
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'.
+ representation of FORM in the minibuffer, and lets the user edit
+ it. 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:
;; After evaluation of the preceding expression,
;; the following appears in the minibuffer:
-
+
---------- Buffer: Minibuffer ----------
Please edit: (forward-word 1)-!-
---------- Buffer: Minibuffer ----------
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.
+ Here are some of the standard minibuffer history list variables:
+
- Variable: minibuffer-history
The default history list for minibuffer history input.
* 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 / blobdiff