-This is ../info/lispref.info, produced by makeinfo version 4.6 from
+This is ../info/lispref.info, produced by makeinfo version 4.8 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
\1f
File: lispref.info, Node: Autoload, Next: Repeated Loading, Prev: How Programs Do Loading, Up: Loading
-Autoload
-========
+20.2 Autoload
+=============
The "autoload" facility allows you to make a function or macro known in
Lisp, but put off loading the file that defines it. The first call to
most convenient way to make a function autoload, but only for packages
installed along with Emacs.
- - Function: autoload function filename &optional docstring interactive
- type
+ -- Function: autoload function filename &optional docstring
+ interactive type
This function defines the function (or macro) named FUNCTION so as
to load automatically from FILENAME. The string FILENAME
specifies the file to load to get the real definition of FUNCTION.
\1f
File: lispref.info, Node: Repeated Loading, Next: Named Features, Prev: Autoload, Up: Loading
-Repeated Loading
-================
+20.3 Repeated Loading
+=====================
You may load one file more than once in an Emacs session. For example,
after you have rewritten and reinstalled a function definition by
has been loaded before:
(defvar foo-was-loaded)
-
+
(if (not (boundp 'foo-was-loaded))
EXECUTE-FIRST-TIME-ONLY)
-
+
(setq foo-was-loaded t)
If the library uses `provide' to provide a named feature, you can use
\1f
File: lispref.info, Node: Named Features, Next: Unloading, Prev: Repeated Loading, Up: Loading
-Features
-========
+20.4 Features
+=============
`provide' and `require' are an alternative to `autoload' for loading
files automatically. They work in terms of named "features".
`features' to see whether the desired feature has been provided
already. If not, it loads the feature from the appropriate file. This
file should call `provide' at the top level to add the feature to
-`features'; if it fails to do so, `require' signals an error.
+`features'; if it fails to do so, `require' signals an error.
Features are normally named after the files that provide them, so
that `require' need not be given the file name.
`provide' call, so the subsequent `require' call does nothing while
loading.
- - Function: provide feature
+ -- Function: provide feature
This function announces that FEATURE is now loaded, or being
loaded, into the current XEmacs session. This means that the
facilities associated with FEATURE are or will be available for
features
=> (bar bish)
-
+
(provide 'foo)
=> foo
features
or `provide' calls that occurred during the load are undone.
*Note Autoload::.
- - Function: require feature &optional filename
+ -- Function: require feature &optional filename
This function checks whether FEATURE is present in the current
XEmacs session (using `(featurep FEATURE)'; see below). If it is
not, then `require' loads FILENAME with `load'. If FILENAME is
If loading the file fails to provide FEATURE, `require' signals an
error, `Required feature FEATURE was not provided'.
- - Function: featurep fexp
+ -- Function: featurep fexp
This function returns `t' if feature FEXP is present in this
Emacs. Use this to conditionalize execution of lisp code based on
the presence or absence of emacs or environment extensions.
(featurep 'xemacs)
=> ; t on XEmacs.
-
+
(featurep '(and xemacs gnus))
=> ; t on XEmacs with Gnus loaded.
-
+
(featurep '(or tty-frames (and emacs 19.30)))
=> ; t if this Emacs supports TTY frames.
-
+
(featurep '(or (and xemacs 19.15) (and emacs 19.34)))
=> ; t on XEmacs 19.15 and later, or on
; FSF Emacs 19.34 and later.
feel they are useful for supporting multiple Emacs variants, lobby
Richard Stallman at `<bug-gnu-emacs@prep.ai.mit.edu>'.
- - Variable: features
+ -- Variable: features
The value of this variable is a list of symbols that are the
features loaded in the current XEmacs session. Each symbol was
put in this list with a call to `provide'. The order of the
\1f
File: lispref.info, Node: Unloading, Next: Hooks for Loading, Prev: Named Features, Up: Loading
-Unloading
-=========
+20.5 Unloading
+==============
You can discard the functions and variables loaded by a library to
reclaim memory for other Lisp objects. To do this, use the function
`unload-feature':
- - Command: unload-feature feature &optional force
+ -- Command: unload-feature feature &optional force
This command unloads the library that provided feature FEATURE.
It undefines all functions, macros, and variables defined in that
library with `defconst', `defvar', `defun', `defmacro',
The `unload-feature' function is written in Lisp; its actions are
based on the variable `load-history'.
- - Variable: load-history
+ -- Variable: load-history
This variable's value is an alist connecting library names with the
names of functions and variables they define, the features they
provide, and the features they require.
\1f
File: lispref.info, Node: Hooks for Loading, Prev: Unloading, Up: Loading
-Hooks for Loading
-=================
+20.6 Hooks for Loading
+======================
- - Variable: after-load-alist
+ -- Variable: after-load-alist
An alist of expressions to evaluate if and when particular
libraries are loaded. Each element looks like this:
\1f
File: lispref.info, Node: Byte Compilation, Next: Debugging, Prev: Loading, Up: Top
-Byte Compilation
-****************
+21 Byte Compilation
+*******************
XEmacs Lisp has a "compiler" that translates functions written in Lisp
into a special representation called "byte-code" that can be executed
\1f
File: lispref.info, Node: Speed of Byte-Code, Next: Compilation Functions, Up: Byte Compilation
-Performance of Byte-Compiled Code
-=================================
+21.1 Performance of Byte-Compiled Code
+======================================
A byte-compiled function is not as efficient as a primitive function
written in C, but runs much faster than the version written in Lisp.
0))
(list t1 (current-time-string))))
=> silly-loop
-
+
(silly-loop 5000000)
=> ("Mon Sep 14 15:51:49 1998"
"Mon Sep 14 15:52:07 1998") ; 18 seconds
-
+
(byte-compile 'silly-loop)
=> #<compiled-function
(n)
[current-time-string t1 n 0]
2
"Return time before and after N iterations of a loop.">
-
+
(silly-loop 5000000)
=> ("Mon Sep 14 15:53:43 1998"
"Mon Sep 14 15:53:49 1998") ; 6 seconds
\1f
File: lispref.info, Node: Compilation Functions, Next: Compilation Options, Prev: Speed of Byte-Code, Up: Byte Compilation
-The Compilation Functions
-=========================
+21.2 The Compilation Functions
+==============================
You can byte-compile an individual function or macro definition with
the `byte-compile' function. You can compile a whole file with
when someone _runs_ the compiled program, write `eval-when-compile'
around the `require' calls (*note Eval During Compile::).
- - Function: byte-compile symbol
+ -- Function: byte-compile symbol
This function byte-compiles the function definition of SYMBOL,
replacing the previous definition with the compiled one. The
function definition of SYMBOL must be the actual code for the
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
=> factorial
-
+
(byte-compile 'factorial)
=> #<compiled-function
(integer)
except for certain primitives that are coded as special
instructions.
- - Command: compile-defun &optional arg
+ -- Command: compile-defun &optional arg
This command reads the defun containing point, compiles it, and
evaluates the result. If you use this on a defun that is actually
a function definition, the effect is to install a compiled version
If ARG is non-`nil', the result is inserted in the current buffer
after the form; otherwise, it is printed in the minibuffer.
- - Command: byte-compile-file filename &optional load
+ -- Command: byte-compile-file filename &optional load
This function compiles a file of Lisp code named FILENAME into a
file of byte-code. The output file's name is made by appending
`c' to the end of FILENAME.
% ls -l push*
-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
-
+
(byte-compile-file "~/emacs/push.el")
=> t
-
+
% ls -l push*
-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
-rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc
- - Command: byte-recompile-directory directory &optional flag
+ -- Command: byte-recompile-directory directory &optional flag
norecursion force
This function recompiles every `.el' file in DIRECTORY that needs
recompilation. A file needs recompilation if a `.elc' file exists
The return value of this command is unpredictable.
- - Function: batch-byte-compile
+ -- Function: batch-byte-compile
This function runs `byte-compile-file' on files specified on the
command line. This function must be used only in a batch
execution of Emacs, as it kills Emacs on completion. An error in
% xemacs -batch -f batch-byte-compile *.el
- - Function: batch-byte-recompile-directory
+ -- Function: batch-byte-recompile-directory
This function is similar to `batch-byte-compile' but runs the
command `byte-recompile-directory' on the files remaining on the
command line.
- - Variable: byte-recompile-directory-ignore-errors-p
+ -- Variable: byte-recompile-directory-ignore-errors-p
When non-`nil', `byte-recompile-directory' will continue compiling
even when an error occurs in a file. Default: `nil', but bound to
`t' by `batch-byte-recompile-directory'.
- - Variable: byte-recompile-directory-recursively
+ -- Variable: byte-recompile-directory-recursively
When non-`nil', `byte-recompile-directory' will recurse on
subdirectories. Default: `t'.
- - Function: byte-code instructions constants stack-depth
+ -- Function: byte-code instructions constants stack-depth
This function actually interprets byte-code. Don't call this
function yourself. Only the byte compiler knows how to generate
valid calls to this function.
\1f
File: lispref.info, Node: Compilation Options, Next: Docs and Compilation, Prev: Compilation Functions, Up: Byte Compilation
-Options for the Byte Compiler
-=============================
+21.3 Options for the Byte Compiler
+==================================
Warning: this node is a quick draft based on docstrings. There may be
inaccuracies, as the docstrings occasionally disagree with each other.
variables. The `byte-compiler-options' macro described below provides
a convenient way to set most of them on a file-by-file basis.
- - Variable: emacs-lisp-file-regexp
+ -- Variable: emacs-lisp-file-regexp
Regexp which matches Emacs Lisp source files. You may want to
redefine `byte-compile-dest-file' if you change this. Default:
`"\\.el$"'.
- - Function: byte-compile-dest-file filename
+ -- Function: byte-compile-dest-file filename
Convert an Emacs Lisp source file name to a compiled file name.
This function may be redefined by the user, if necessary, for
compatibility with `emacs-lisp-file-regexp'.
- - Variable: byte-compile-verbose
+ -- Variable: byte-compile-verbose
When non-`nil', print messages describing progress of
byte-compiler. Default: `t' if interactive on a not-too-slow
terminal (see `search-slow-speed'), otherwise `nil'.
- - Variable: byte-optimize
+ -- Variable: byte-optimize
Level of optimization in the byte compiler.
`nil'
code) only.
Default: `t'.
- - Variable: byte-compile-delete-errors
+ -- Variable: byte-compile-delete-errors
When non-`nil', the optimizer may delete forms that may signal an
error if that is the only change in the function's behavior. This
includes variable references and calls to functions such as `car'.
Default: `t'.
- - Variable: byte-optimize-log nil
+ -- Variable: byte-optimize-log nil
When non-`nil', the byte-compiler logs optimizations into
`*Compile-Log*'.
code) only.
Default: `nil'.
- - Variable: byte-compile-error-on-warn
+ -- Variable: byte-compile-error-on-warn
When non-`nil', the byte-compiler reports warnings with `error'.
Default: `nil'.
- - Variable: byte-compile-default-warnings
+ -- Variable: byte-compile-default-warnings
The warnings used when `byte-compile-warnings' is `t'. Called
`byte-compile-warning-types' in GNU Emacs. Default: `(redefine
callargs subr-callargs free-vars unresolved unused-vars obsolete)'.
- - Variable: byte-compile-warnings
+ -- Variable: byte-compile-warnings
List of warnings that the compiler should issue (`t' for the
default set). Elements of the list may be:
The compiler can generate a call graph, which gives information about
which functions call which functions.
- - Variable: byte-compile-generate-call-tree
+ -- Variable: byte-compile-generate-call-tree
When non-`nil', the compiler generates a call graph. This records
functions that were called and from where. If the value is `t',
compilation displays the call graph when it finishes. If the
which can be invoked interactively are excluded from this list.
Default: `nil'.
- - Variable: byte-compile-call-tree nil
+ -- Variable: byte-compile-call-tree nil
Alist of functions and their call tree, used internally. Each
element takes the form
is a list of functions for which calls were generated while
compiling FUNCTION.
- - Variable: byte-compile-call-tree-sort
+ -- Variable: byte-compile-call-tree-sort
When non-`nil', sort the call tree. The values `name', `callers',
`calls', and `calls+callers' specify different fields to sort
on.") Default: `name'.
`byte-compile-overwrite-file' controls treatment of existing
compiled files.
- - Variable: byte-compile-overwrite-file
+ -- Variable: byte-compile-overwrite-file
When non-`nil', do not preserve backups of `.elc's. Precisely, if
`nil', old `.elc' files are deleted before the new one is saved,
and `.elc' files will have the same modes as the corresponding
crashes or data loss. Always recompile your Lisp when moving between
XEmacs and GNU Emacs.
- - Variable: byte-compile-single-version nil
+ -- Variable: byte-compile-single-version nil
When non-`nil', the choice of emacs version (v19 or v20) byte-codes
will be hard-coded into bytecomp when it compiles itself. If the
compiler itself is compiled with optimization, this causes a
speedup. Default: `nil'.
- - Variable: byte-compile-emacs19-compatibility
+ -- Variable: byte-compile-emacs19-compatibility
When non-`nil' generate output that can run in Emacs 19. Default:
`nil' when Emacs version is 20 or above, otherwise `t'.
- - Variable: byte-compile-print-gensym
+ -- Variable: byte-compile-print-gensym
When non-`nil', the compiler may generate code that creates unique
symbols at run-time. This is achieved by printing uninterned
symbols using the `#:' notation, so that they will be read
Default: When `byte-compile-emacs19-compatibility' is non-nil, this
variable is ignored and considered to be `nil'. Otherwise `t'.
- - Variable: byte-compile-new-bytecodes
+ -- Variable: byte-compile-new-bytecodes
This is completely ignored. For backwards compatibility.
- - Function: byte-compiler-options &rest args
+ -- Function: byte-compiler-options &rest args
Set some compilation-parameters for this file. This will affect
only the file in which it appears; this does nothing when
evaluated, or when loaded from a `.el' file.
(#### Need to check whether the newer variables are settable here.)
Keys: Values: Corresponding variable:
-
+
verbose t, nil byte-compile-verbose
optimize t, nil, source, byte byte-optimize
warnings list of warnings byte-compile-warnings
\1f
File: lispref.info, Node: Docs and Compilation, Next: Dynamic Loading, Prev: Compilation Options, Up: Byte Compilation
-Documentation Strings and Compilation
-=====================================
+21.4 Documentation Strings and Compilation
+==========================================
Functions and variables loaded from a byte-compiled file access their
documentation strings dynamically from the file whenever needed. This
-*-byte-compile-dynamic-docstrings: nil;-*-
- - Variable: byte-compile-dynamic-docstrings
+ -- Variable: byte-compile-dynamic-docstrings
If this is non-`nil', the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
Default: t.
\1f
File: lispref.info, Node: Dynamic Loading, Next: Eval During Compile, Prev: Docs and Compilation, Up: Byte Compilation
-Dynamic Loading of Individual Functions
-=======================================
+21.5 Dynamic Loading of Individual Functions
+============================================
When you compile a file, you can optionally enable the "dynamic
function loading" feature (also known as "lazy loading"). With dynamic
-*-byte-compile-dynamic: t;-*-
- - Variable: byte-compile-dynamic
+ -- Variable: byte-compile-dynamic
If this is non-`nil', the byte compiler generates compiled files
that are set up for dynamic function loading. Default: nil.
- - Function: fetch-bytecode function
+ -- Function: fetch-bytecode function
This immediately finishes loading the definition of FUNCTION from
its byte-compiled file, if it is not fully loaded already. The
argument FUNCTION may be a compiled-function object or a function
\1f
File: lispref.info, Node: Eval During Compile, Next: Compiled-Function Objects, Prev: Dynamic Loading, Up: Byte Compilation
-Evaluation During Compilation
-=============================
+21.6 Evaluation During Compilation
+==================================
These features permit you to write code to be evaluated during
compilation of a program.
- - Special Form: eval-and-compile body
+ -- Special Form: eval-and-compile body
This form marks BODY to be evaluated both when you compile the
containing code and when you run it (whether compiled or not).
preferable if there is a substantial amount of code to be executed
in this way.
- - Special Form: eval-when-compile body
+ -- Special Form: eval-when-compile body
This form marks BODY to be evaluated at compile time and not when
the compiled program is loaded. The result of evaluation by the
compiler becomes a constant which appears in the compiled program.
\1f
File: lispref.info, Node: Compiled-Function Objects, Next: Disassembly, Prev: Eval During Compile, Up: Byte Compilation
-Compiled-Function Objects
-=========================
+21.7 Compiled-Function Objects
+==============================
Byte-compiled functions have a special data type: they are
"compiled-function objects". The evaluator handles this data type
The primitive way to create a compiled-function object is with
`make-byte-code':
- - Function: make-byte-code arglist instructions constants stack-depth
+ -- Function: make-byte-code arglist instructions constants stack-depth
&optional doc-string interactive
This function constructs and returns a compiled-function object
with the specified attributes.
The following primitives are provided for accessing the elements of
a compiled-function object.
- - Function: compiled-function-arglist function
+ -- Function: compiled-function-arglist function
This function returns the argument list of compiled-function object
FUNCTION.
- - Function: compiled-function-instructions function
+ -- Function: compiled-function-instructions function
This function returns a string describing the byte-code
instructions of compiled-function object FUNCTION.
- - Function: compiled-function-constants function
+ -- Function: compiled-function-constants function
This function returns the vector of Lisp objects referenced by
compiled-function object FUNCTION.
- - Function: compiled-function-stack-depth function
+ -- Function: compiled-function-stack-depth function
This function returns the maximum stack size needed by
compiled-function object FUNCTION.
- - Function: compiled-function-doc-string function
+ -- Function: compiled-function-doc-string function
This function returns the doc string of compiled-function object
FUNCTION, if available.
- - Function: compiled-function-interactive function
+ -- Function: compiled-function-interactive function
This function returns the interactive spec of compiled-function
object FUNCTION, if any. The return value is `nil' or a
two-element list, the first element of which is the symbol
`interactive' and the second element is the interactive spec (a
string or Lisp form).
- - Function: compiled-function-domain function
+ -- Function: compiled-function-domain function
This function returns the domain of compiled-function object
FUNCTION, if any. The result will be a string or `nil'. *Note
Domain Specification::.
\1f
File: lispref.info, Node: Disassembly, Next: Different Behavior, Prev: Compiled-Function Objects, Up: Byte Compilation
-Disassembled Byte-Code
-======================
+21.8 Disassembled Byte-Code
+===========================
People do not write byte-code; that job is left to the byte compiler.
But we provide a disassembler to satisfy a cat-like curiosity. The
ordinary Lisp variables, by transferring values between variables and
the stack.
- - Command: disassemble object &optional stream
+ -- Command: disassemble object &optional stream
This function prints the disassembled code for OBJECT. If STREAM
is supplied, then output goes there. Otherwise, the disassembled
code is printed to the stream `standard-output'. The argument
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
=> factorial
-
+
(factorial 4)
=> 24
-
+
(disassemble 'factorial)
-| byte-code for factorial:
doc: Compute factorial of an integer.
args: (integer)
-
+
0 varref integer ; Get value of `integer'
; from the environment
; and push the value
; onto the stack.
-
+
1 constant 1 ; Push 1 onto stack.
-
+
2 eqlsign ; Pop top two values off stack,
; compare them,
; and push result onto stack.
-
+
3 goto-if-nil 1 ; Pop and test top of stack;
; if `nil',
; go to label 1 (which is also byte 7),
; else continue.
-
+
5 constant 1 ; Push 1 onto top of stack.
-
+
6 return ; Return the top element
; of the stack.
-
+
7:1 varref integer ; Push value of `integer' onto stack.
-
+
8 constant factorial ; Push `factorial' onto stack.
-
+
9 varref integer ; Push value of `integer' onto stack.
-
+
10 sub1 ; Pop `integer', decrement value,
; push new value onto stack.
-
+
; Stack now contains:
; - decremented value of `integer'
; - `factorial'
; - value of `integer'
-
+
15 call 1 ; Call function `factorial' using
; the first (i.e., the top) element
; of the stack as the argument;
; push returned value onto stack.
-
+
; Stack now contains:
; - result of recursive
; call to `factorial'
; - value of `integer'
-
+
12 mult ; Pop top two values off the stack,
; multiply them,
; pushing the result onto the stack.
-
+
13 return ; Return the top element
; of the stack.
=> nil
0))
(list t1 (current-time-string))))
=> silly-loop
-
+
(disassemble 'silly-loop)
-| byte-code for silly-loop:
doc: Return time before and after N iterations of a loop.
args: (n)
-
+
0 constant current-time-string ; Push
; `current-time-string'
; onto top of stack.
-
+
1 call 0 ; Call `current-time-string'
; with no argument,
; pushing result onto stack.
-
+
2 varbind t1 ; Pop stack and bind `t1'
; to popped value.
-
+
3:1 varref n ; Get value of `n' from
; the environment and push
; the value onto the stack.
-
+
4 sub1 ; Subtract 1 from top of stack.
-
+
5 dup ; Duplicate the top of the stack;
; i.e., copy the top of
; the stack and push the
; copy onto the stack.
-
+
6 varset n ; Pop the top of the stack,
; and set `n' to the value.
-
+
; In effect, the sequence `dup varset'
; copies the top of the stack
; into the value of `n'
; without popping it.
-
+
7 constant 0 ; Push 0 onto stack.
-
+
8 gtr ; Pop top two values off stack,
; test if N is greater than 0
; and push result onto stack.
-
+
9 goto-if-not-nil 1 ; Goto label 1 (byte 3) if `n' <= 0
; (this exits the while loop).
; else pop top of stack
; and continue
-
+
11 varref t1 ; Push value of `t1' onto stack.
-
+
12 constant current-time-string ; Push
; `current-time-string'
; onto top of stack.
-
+
13 call 0 ; Call `current-time-string' again.
-
+
14 unbind 1 ; Unbind `t1' in local environment.
-
+
15 list2 ; Pop top two elements off stack,
; create a list of them,
; and push list onto stack.
-
+
16 return ; Return the top element of the stack.
-
+
=> nil
\1f
File: lispref.info, Node: Different Behavior, Prev: Disassembly, Up: Byte Compilation
-Different Behavior
-==================
+21.9 Different Behavior
+=======================
The intent is that compiled byte-code and the corresponding code
executed by the Lisp interpreter produce identical results. However,
\1f
File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top
-Debugging Lisp Programs
-***********************
+22 Debugging Lisp Programs
+**************************
There are three ways to investigate a problem in an XEmacs Lisp program,
depending on what you are doing with the program when the problem
\1f
File: lispref.info, Node: Debugger, Next: Syntax Errors, Up: Debugging
-The Lisp Debugger
-=================
+22.1 The Lisp Debugger
+======================
The "Lisp debugger" provides the ability to suspend evaluation of a
form. While evaluation is suspended (a state that is commonly known as
\1f
File: lispref.info, Node: Error Debugging, Next: Infinite Loops, Up: Debugger
-Entering the Debugger on an Error
----------------------------------
+22.1.1 Entering the Debugger on an Error
+----------------------------------------
The most important time to enter the debugger is when a Lisp error
happens. This allows you to investigate the immediate causes of the
debugger each time this happens. If you want errors to enter the
debugger, set the variable `debug-on-error' to non-`nil'.
- - User Option: debug-on-error
+ -- User Option: debug-on-error
This variable determines whether the debugger is called when an
error is signaled and not handled. If `debug-on-error' is `t', all
errors call the debugger. If it is `nil', none call the debugger.
happen in process filter functions and sentinels. Therefore, these
errors also can invoke the debugger. *Note Processes::.
- - User Option: debug-on-signal
+ -- User Option: debug-on-signal
This variable is similar to `debug-on-error' but breaks whenever
an error is signalled, regardless of whether it would be handled.
- - User Option: debug-ignored-errors
+ -- User Option: debug-ignored-errors
This variable specifies certain kinds of errors that should not
enter the debugger. Its value is a list of error condition
symbols and/or regular expressions. If the error has any of those
\1f
File: lispref.info, Node: Infinite Loops, Next: Function Debugging, Prev: Error Debugging, Up: Debugger
-Debugging Infinite Loops
-------------------------
+22.1.2 Debugging Infinite Loops
+-------------------------------
When a program loops infinitely and fails to return, your first problem
is to stop the loop. On most operating systems, you can do this with
If you step through the entire loop, you will probably get enough
information to solve the problem.
- - User Option: debug-on-quit
+ -- User Option: debug-on-quit
This variable determines whether the debugger is called when `quit'
is signaled and not handled. If `debug-on-quit' is non-`nil',
then the debugger is called whenever you quit (that is, type
\1f
File: lispref.info, Node: Function Debugging, Next: Explicit Debug, Prev: Infinite Loops, Up: Debugger
-Entering the Debugger on a Function Call
-----------------------------------------
+22.1.3 Entering the Debugger on a Function Call
+-----------------------------------------------
To investigate a problem that happens in the middle of a program, one
useful technique is to enter the debugger whenever a certain function is
called shortly before the problem, step quickly over the call to that
function, and then step through its caller.
- - Command: debug-on-entry function-name
+ -- Command: debug-on-entry function-name
This function requests FUNCTION-NAME to invoke the debugger each
time it is called. It works by inserting the form `(debug
'debug)' into the function definition as the first form.
(debug-on-entry 'fact)
=> fact
(fact 3)
-
+
------ Buffer: *Backtrace* ------
Entering:
* fact(3)
eval-insert-last-sexp(nil)
* call-interactively(eval-insert-last-sexp)
------ Buffer: *Backtrace* ------
-
+
(symbol-function 'fact)
=> (lambda (n)
(debug (quote debug))
(if (zerop n) 1 (* n (fact (1- n)))))
- - Command: cancel-debug-on-entry &optional function-name
+ -- Command: cancel-debug-on-entry &optional function-name
This function undoes the effect of `debug-on-entry' on
FUNCTION-NAME. When called interactively, it prompts for
FUNCTION-NAME in the minibuffer. If FUNCTION-NAME is `nil' or the
\1f
File: lispref.info, Node: Explicit Debug, Next: Using Debugger, Prev: Function Debugging, Up: Debugger
-Explicit Entry to the Debugger
-------------------------------
+22.1.4 Explicit Entry to the Debugger
+-------------------------------------
You can cause the debugger to be called at a certain point in your
program by writing the expression `(debug)' at that point. To do this,
\1f
File: lispref.info, Node: Using Debugger, Next: Debugger Commands, Prev: Explicit Debug, Up: Debugger
-Using the Debugger
-------------------
+22.1.5 Using the Debugger
+-------------------------
When the debugger is entered, it displays the previously selected
buffer in one window and a buffer named `*Backtrace*' in another
\1f
File: lispref.info, Node: Debugger Commands, Next: Invoking the Debugger, Prev: Using Debugger, Up: Debugger
-Debugger Commands
------------------
+22.1.6 Debugger Commands
+------------------------
Inside the debugger (in Debugger mode), these special commands are
available in addition to the usual cursor motion commands. (Keep in
\1f
File: lispref.info, Node: Invoking the Debugger, Next: Internals of Debugger, Prev: Debugger Commands, Up: Debugger
-Invoking the Debugger
----------------------
+22.1.7 Invoking the Debugger
+----------------------------
Here we describe fully the function used to invoke the debugger.
- - Function: debug &rest debugger-args
+ -- Function: debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer
named `*Backtrace*' (or `*Backtrace*<2>' if it is the second
recursive entry to the debugger, etc.), and fills it with
(let ((debug-on-error t))
(/ 1 0))
-
+
------ Buffer: *Backtrace* ------
Signaling: (arith-error)
/(1 0)
\1f
File: lispref.info, Node: Internals of Debugger, Prev: Invoking the Debugger, Up: Debugger
-Internals of the Debugger
--------------------------
+22.1.8 Internals of the Debugger
+--------------------------------
This section describes functions and variables used internally by the
debugger.
- - Variable: debugger
+ -- Variable: debugger
The value of this variable is the function to call to invoke the
debugger. Its value must be a function of any number of arguments
(or, more typically, the name of a function). Presumably this
was called. The convention for arguments is detailed in the
description of `debug'.
- - Command: backtrace &optional stream detailed
+ -- Command: backtrace &optional stream detailed
This function prints a trace of Lisp function calls currently
active. This is the function used by `debug' to fill up the
`*Backtrace*' buffer. It is written in C, since it must have
(setq var (eval '(progn
(1+ var)
(list 'testing (backtrace))))))))
-
+
=> nil
-
+
----------- Buffer: backtrace-output ------------
backtrace()
(list ...computing arguments...)
The character `*' indicates a frame whose debug-on-exit flag is
set.
- - Variable: debug-on-next-call
+ -- Variable: debug-on-next-call
If this variable is non-`nil', it says to call the debugger before
the next `eval', `apply' or `funcall'. Entering the debugger sets
`debug-on-next-call' to `nil'.
The `d' command in the debugger works by setting this variable.
- - Function: backtrace-debug level flag
+ -- Function: backtrace-debug level flag
This function sets the debug-on-exit flag of the stack frame LEVEL
levels down the stack, giving it the value FLAG. If FLAG is
non-`nil', this will cause the debugger to be entered when that
This function is used only by the debugger.
- - Variable: command-debug-status
+ -- Variable: command-debug-status
This variable records the debugging status of the current
interactive command. Each time a command is called interactively,
this variable is bound to `nil'. The debugger can set this
another global variable is that the data will never carry over to a
subsequent command invocation.
- - Function: backtrace-frame frame-number
+ -- Function: backtrace-frame frame-number
The function `backtrace-frame' is intended for use in Lisp
debuggers. It returns information about what computation is
happening in the stack frame FRAME-NUMBER levels down.
\1f
File: lispref.info, Node: Syntax Errors, Next: Compilation Errors, Prev: Debugger, Up: Debugging
-Debugging Invalid Lisp Syntax
-=============================
+22.2 Debugging Invalid Lisp Syntax
+==================================
The Lisp reader reports invalid syntax, but cannot say where the real
problem is. For example, the error "End of file during parsing" in
\1f
File: lispref.info, Node: Excess Open, Next: Excess Close, Up: Syntax Errors
-Excess Open Parentheses
------------------------
+22.2.1 Excess Open Parentheses
+------------------------------
The first step is to find the defun that is unbalanced. If there is an
excess open parenthesis, the way to do this is to insert a close
\1f
File: lispref.info, Node: Excess Close, Prev: Excess Open, Up: Syntax Errors
-Excess Close Parentheses
-------------------------
+22.2.2 Excess Close Parentheses
+-------------------------------
To deal with an excess close parenthesis, first insert an open
parenthesis at the beginning of the file, back up over it, and type
\1f
File: lispref.info, Node: Compilation Errors, Next: Edebug, Prev: Syntax Errors, Up: Debugging
-Debugging Problems in Compilation
-=================================
+22.3 Debugging Problems in Compilation
+======================================
When an error happens during byte compilation, it is normally due to
invalid syntax in the program you are compiling. The compiler prints a
\1f
File: lispref.info, Node: Edebug, Prev: Compilation Errors, Up: Top
-Edebug
-======
+22.4 Edebug
+===========
Edebug is a source-level debugger for XEmacs Lisp programs that
provides the following features:
\1f
File: lispref.info, Node: Using Edebug, Next: Instrumenting, Up: Edebug
-Using Edebug
-------------
+22.4.1 Using Edebug
+-------------------
To debug an XEmacs Lisp program with Edebug, you must first
"instrument" the Lisp code that you want to debug. If you want to just
\1f
File: lispref.info, Node: Instrumenting, Next: Edebug Execution Modes, Prev: Using Edebug, Up: Edebug
-Instrumenting for Edebug
-------------------------
+22.4.2 Instrumenting for Edebug
+-------------------------------
In order to use Edebug to debug Lisp code, you must first "instrument"
the code. Instrumenting a form inserts additional code into it which
\1f
File: lispref.info, Node: Edebug Execution Modes, Next: Jumping, Prev: Instrumenting, Up: Edebug
-Edebug Execution Modes
-----------------------
+22.4.3 Edebug Execution Modes
+-----------------------------
Edebug supports several execution modes for running the program you are
debugging. We call these alternatives "Edebug execution modes"; do not
\1f
File: lispref.info, Node: Jumping, Next: Edebug Misc, Prev: Edebug Execution Modes, Up: Edebug
-Jumping
--------
+22.4.4 Jumping
+--------------
Commands described here let you jump to a specified location. All,
except `i', use temporary breakpoints to establish the stop point and
\1f
File: lispref.info, Node: Edebug Misc, Next: Breakpoints, Prev: Jumping, Up: Edebug
-Miscellaneous
--------------
+22.4.5 Miscellaneous
+--------------------
Some miscellaneous commands are described here.
\1f
File: lispref.info, Node: Breakpoints, Next: Trapping Errors, Prev: Edebug Misc, Up: Edebug
-Breakpoints
------------
+22.4.6 Breakpoints
+------------------
There are three more ways to stop execution once it has started:
breakpoints, the global break condition, and embedded breakpoints.
\1f
File: lispref.info, Node: Global Break Condition, Next: Embedded Breakpoints, Up: Breakpoints
-Global Break Condition
-......................
+22.4.6.1 Global Break Condition
+...............................
In contrast to breaking when execution reaches specified locations, you
can also cause a break when a certain event occurs. The "global break
\1f
File: lispref.info, Node: Embedded Breakpoints, Prev: Global Break Condition, Up: Breakpoints
-Embedded Breakpoints
-....................
+22.4.6.2 Embedded Breakpoints
+.............................
Since all breakpoints in a definition are cleared each time you
reinstrument it, you might rather create an "embedded breakpoint" which
\1f
File: lispref.info, Node: Trapping Errors, Next: Edebug Views, Prev: Breakpoints, Up: Edebug
-Trapping Errors
----------------
+22.4.7 Trapping Errors
+----------------------
An error may be signaled by subroutines or XEmacs Lisp code. If a
signal is not handled by a `condition-case', this indicates an
\1f
File: lispref.info, Node: Edebug Views, Next: Edebug Eval, Prev: Trapping Errors, Up: Edebug
-Edebug Views
-------------
+22.4.8 Edebug Views
+-------------------
The following Edebug commands let you view aspects of the buffer and
window status that obtained before entry to Edebug.
\1f
File: lispref.info, Node: Edebug Eval, Next: Eval List, Prev: Edebug Views, Up: Edebug
-Evaluation
-----------
+22.4.9 Evaluation
+-----------------
While within Edebug, you can evaluate expressions "as if" Edebug were
not running. Edebug tries to be invisible to the expression's
\1f
File: lispref.info, Node: Eval List, Next: Reading in Edebug, Prev: Edebug Eval, Up: Edebug
-Evaluation List Buffer
-----------------------
+22.4.10 Evaluation List Buffer
+------------------------------
You can use the "evaluation list buffer", called `*edebug*', to
evaluate expressions interactively. You can also set up the
\1f
File: lispref.info, Node: Reading in Edebug, Next: Printing in Edebug, Prev: Eval List, Up: Edebug
-Reading in Edebug
------------------
+22.4.11 Reading in Edebug
+-------------------------
To instrument a form, Edebug first reads the whole form. Edebug
replaces the standard Lisp Reader with its own reader that remembers the
\1f
File: lispref.info, Node: Printing in Edebug, Next: Tracing, Prev: Reading in Edebug, Up: Edebug
-Printing in Edebug
-------------------
+22.4.12 Printing in Edebug
+--------------------------
If the result of an expression in your program contains a circular
reference, you may get an error when Edebug attempts to print it. You
\1f
File: lispref.info, Node: Tracing, Next: Coverage Testing, Prev: Printing in Edebug, Up: Edebug
-Tracing
--------
+22.4.13 Tracing
+---------------
In addition to automatic stepping through source code, which is also
called _tracing_ (see *Note Edebug Execution Modes::), Edebug can
\1f
File: lispref.info, Node: Coverage Testing, Next: The Outside Context, Prev: Tracing, Up: Edebug
-Coverage Testing
-----------------
+22.4.14 Coverage Testing
+------------------------
Edebug provides a rudimentary coverage tester and display of execution
frequency. Frequency counts are always accumulated, both before and
expensive. Both data sets are displayed by `M-x
edebug-display-freq-count'.
- - Command: edebug-display-freq-count
+ -- Command: edebug-display-freq-count
Display the frequency count data for each line of the current
definition. The frequency counts are inserted as comment lines
after each line, and you can undo all insertions with one `undo'
\1f
File: lispref.info, Node: The Outside Context, Next: Instrumenting Macro Calls, Prev: Coverage Testing, Up: Edebug
-The Outside Context
--------------------
+22.4.15 The Outside Context
+---------------------------
Edebug tries to be transparent to the program you are debugging. In
addition, most evaluations you do within Edebug (see *Note Edebug
\1f
File: lispref.info, Node: Checking Whether to Stop, Next: Edebug Display Update, Up: The Outside Context
-Checking Whether to Stop
-........................
+22.4.15.1 Checking Whether to Stop
+..................................
Whenever Edebug is entered just to think about whether to take some
action, it needs to save and restore certain data.
\1f
File: lispref.info, Node: Edebug Display Update, Next: Edebug Recursive Edit, Prev: Checking Whether to Stop, Up: The Outside Context
-Edebug Display Update
-.....................
+22.4.15.2 Edebug Display Update
+...............................
When Edebug needs to display something (e.g., in trace mode), it saves
the current window configuration from "outside" Edebug. When you exit
\1f
File: lispref.info, Node: Edebug Recursive Edit, Prev: Edebug Display Update, Up: The Outside Context
-Edebug Recursive Edit
-.....................
+22.4.15.3 Edebug Recursive Edit
+...............................
When Edebug is entered and actually reads commands from the user, it
saves (and later restores) these additional data:
\1f
File: lispref.info, Node: Instrumenting Macro Calls, Next: Edebug Options, Prev: The Outside Context, Up: Edebug
-Instrumenting Macro Calls
--------------------------
+22.4.16 Instrumenting Macro Calls
+---------------------------------
When Edebug instruments an expression that calls a Lisp macro, it needs
additional advice to do the job properly. This is because there is no
the format of macro call arguments by using `def-edebug-spec' to define
an "Edebug specification" for each macro.
- - Macro: def-edebug-spec macro specification
+ -- Macro: def-edebug-spec macro specification
Specify which expressions of a call to macro MACRO are forms to be
evaluated. For simple macros, the SPECIFICATION often looks very
similar to the formal argument list of the macro definition, but
(def-edebug-spec for
(symbolp "from" form "to" form "do" &rest form))
-
+
(def-edebug-spec for
(symbolp ['from form] ['to form] ['do body]))
\1f
File: lispref.info, Node: Specification List, Next: Backtracking, Up: Instrumenting Macro Calls
-Specification List
-..................
+22.4.16.1 Specification List
+............................
A "specification list" is required for an Edebug specification if some
arguments of a macro call are evaluated while others are not. Some
\1f
File: lispref.info, Node: Backtracking, Next: Debugging Backquote, Prev: Specification List, Up: Instrumenting Macro Calls
-Backtracking
-............
+22.4.16.2 Backtracking
+......................
If a specification fails to match at some point, this does not
necessarily mean a syntax error will be signaled; instead,
\1f
File: lispref.info, Node: Debugging Backquote, Next: Specification Examples, Prev: Backtracking, Up: Instrumenting Macro Calls
-Debugging Backquote
-...................
+22.4.16.3 Debugging Backquote
+.............................
Backquote (``') is a macro that results in an expression that may or
may not be evaluated. It is often used to simplify the definition of a
(defmacro inc (var)
(list 'setq var (list '1+ var)))
-
+
(defmacro for (var from init to final do &rest body)
(let ((tempvar (make-symbol "max")))
(edebug-` (let (((, var) (, init))
(def-edebug-spec for
(symbolp "from" def-form "to" def-form "do" &rest def-form))
-
+
(let ((n 5))
(for i from n to (* n (+ n 1)) do
(message "%s" i)))
\1f
File: lispref.info, Node: Specification Examples, Prev: Debugging Backquote, Up: Instrumenting Macro Calls
-Specification Examples
-......................
+22.4.16.4 Specification Examples
+................................
Here we provide several examples of Edebug specifications to show many
of its capabilities.
[&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'
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])
\1f
File: lispref.info, Node: Edebug Options, Prev: Instrumenting Macro Calls, Up: Edebug
-Edebug Options
---------------
+22.4.17 Edebug Options
+----------------------
These options affect the behavior of Edebug:
- - User Option: edebug-setup-hook
+ -- 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
+ -- 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'.
by calling `(make-local-variable 'edebug-all-defs)' in your
`emacs-lisp-mode-hook'. See *Note Instrumenting::.
- - User Option: edebug-all-forms
+ -- 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
+ -- 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. This command is bound to `W' in source code buffers.
See *Note Edebug Display Update::.
- - User Option: edebug-save-displayed-buffer-points
+ -- 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
so it is best to avoid it if you can. See *Note Edebug Display
Update::.
- - User Option: edebug-initial-mode
+ -- 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',
The default value is `step'. See *Note Edebug Execution Modes::.
- - User Option: edebug-trace
+ -- 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.
Also see `edebug-tracing'. See *Note Tracing::.
- - User Option: edebug-test-coverage
+ -- 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
and coverage information for a definition. See *Note Coverage
Testing::.
- - User Option: edebug-continue-kbd-macro
+ -- 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
+ -- 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
+ -- 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
+ -- 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
+ -- 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
+ -- 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
+ -- 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
+ -- 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
-*********************************
+23 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
\1f
File: lispref.info, Node: Streams Intro, Next: Input Streams, Up: Read and Print
-Introduction to Reading and Printing
-====================================
+23.1 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
\1f
File: lispref.info, Node: Input Streams, Next: Input Functions, Prev: Streams Intro, Up: Read and Print
-Input Streams
-=============
+23.2 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
---------- 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 ----------
---------- 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)
(setq useless-list (append "XY()" nil))
=> (88 89 40 41)
-
+
(defun useless-stream (&optional unread)
(if unread
(setq useless-list (cons unread useless-list))
(read 'useless-stream)
=> XY
-
+
useless-list
=> (40 41)
\1f
File: lispref.info, Node: Input Functions, Next: Output Streams, Prev: Input Streams, Up: Read and Print
-Input Functions
-===============
+23.3 Input Functions
+====================
This section describes the Lisp functions and variables that pertain to
reading.
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
=> ((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-from-string "(list 112)" 6 8)
=> (11 . 8)
- - Variable: standard-input
+ -- 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
-==============
+23.4 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
---------- 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"
---------- 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>
(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)
\1f
File: lispref.info, Node: Output Functions, Next: Output Variables, Prev: Output Streams, Up: Read and Print
-Output Functions
-================
+23.5 Output Functions
+=====================
This section describes the Lisp functions for printing Lisp objects.
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.
\1f
File: lispref.info, Node: Output Variables, Prev: Output Functions, Up: Read and Print
-Variables Affecting Output
-==========================
+23.6 Variables Affecting Output
+===============================
- - Variable: standard-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
+ -- 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.
-| b"
=> "a
b"
-
+
(let ((print-escape-newlines t))
(prin1 "a\nb"))
-| "a\nb"
`print-escape-newlines' is in effect during the call to `prin1',
but not during the printing of the result.
- - Variable: print-readably
+ -- 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
form `(quote object)' will be written as the equivalent `'object'.
Do not _set_ this variable; bind it instead.
- - Variable: print-length
+ -- 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.
-| (1 2 ...)
=> (1 2 ...)
- - Variable: print-level
+ -- 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
This variable exists in version 19 and later versions.
- - Variable: print-string-length
+ -- 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
+ -- 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
for the printer to distinguish between symbols interned in no
obarray, and symbols interned in an alternate obarray.
- - Variable: float-output-format
+ -- 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
\1f
File: lispref.info, Node: Minibuffers, Next: Command Loop, Prev: Read and Print, Up: Top
-Minibuffers
-***********
+24 Minibuffers
+**************
A "minibuffer" is a special buffer that XEmacs commands use to read
arguments more complicated than the single numeric prefix argument.
\1f
File: lispref.info, Node: Intro to Minibuffers, Next: Text from Minibuffer, Up: Minibuffers
-Introduction to Minibuffers
-===========================
+24.1 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
\1f
File: lispref.info, Node: Text from Minibuffer, Next: Object from Minibuffer, Prev: Intro to Minibuffers, Up: Minibuffers
-Reading Text Strings with the Minibuffer
-========================================
+24.2 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
reading the arguments for a command, in the `interactive' spec. *Note
Defining Commands::.
- - Function: read-from-minibuffer prompt-string &optional
+ -- 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
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
+ -- 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'.
(read-from-minibuffer PROMPT INITIAL nil nil
HISTORY nil DEFAULT)))
- - Variable: minibuffer-local-map
+ -- Variable: minibuffer-local-map
This is the default local keymap for reading from the minibuffer.
By default, it makes the following bindings:
\1f
File: lispref.info, Node: Object from Minibuffer, Next: Minibuffer History, Prev: Text from Minibuffer, Up: Minibuffers
-Reading Lisp Objects with the Minibuffer
-========================================
+24.3 Reading Lisp Objects with the Minibuffer
+=============================================
This section describes functions for reading Lisp objects with the
minibuffer.
- - Function: read-expression prompt &optional initial history
+ -- 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
(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: read-minibuffer prompt &optional initial history
+ -- 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
+ -- 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
==
(eval (read-expression PROMPT INITIAL))
- - Function: edit-and-eval-command prompt form &optional history
+ -- 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
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 ----------
\1f
File: lispref.info, Node: Minibuffer History, Next: Completion, Prev: Object from Minibuffer, Up: Minibuffers
-Minibuffer History
-==================
+24.4 Minibuffer History
+=======================
A "minibuffer history list" records previous minibuffer inputs so the
user can reuse them conveniently. A history list is actually a symbol,
Here are some of the standard minibuffer history list variables:
- - Variable: minibuffer-history
+ -- Variable: minibuffer-history
The default history list for minibuffer history input.
- - Variable: query-replace-history
+ -- Variable: query-replace-history
A history list for arguments to `query-replace' (and similar
arguments to other commands).
- - Variable: file-name-history
+ -- Variable: file-name-history
A history list for file name arguments.
- - Variable: regexp-history
+ -- Variable: regexp-history
A history list for regular expression arguments.
- - Variable: extended-command-history
+ -- Variable: extended-command-history
A history list for arguments that are names of extended commands.
- - Variable: shell-command-history
+ -- Variable: shell-command-history
A history list for arguments that are shell commands.
- - Variable: read-expression-history
+ -- Variable: read-expression-history
A history list for arguments that are Lisp expressions to evaluate.
- - Variable: Info-minibuffer-history
+ -- Variable: Info-minibuffer-history
A history list for Info mode's minibuffer.
- - Variable: Manual-page-minibuffer-history
+ -- Variable: Manual-page-minibuffer-history
A history list for `manual-entry'.
There are many other minibuffer history lists, defined by various
\1f
File: lispref.info, Node: Completion, Next: Yes-or-No Queries, Prev: Minibuffer History, Up: Minibuffers
-Completion
-==========
+24.5 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
\1f
File: lispref.info, Node: Basic Completion, Next: Minibuffer Completion, Up: Completion
-Basic Completion Functions
---------------------------
+24.5.1 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
+ -- Function: try-completion string collection &optional predicate
This function returns the longest common prefix 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
"foo"
'(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
=> "fooba"
-
+
(try-completion "foo" '(("barfoo" 2) ("foo" 3)))
=> t
'test)
=> "foobar"
- - Function: all-completions string collection &optional predicate
+ -- Function: all-completions string collection &optional predicate
This function returns a list of all possible completions of STRING.
The arguments to this function are the same as those of
`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
+ -- 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
------------------------------
+24.5.2 Completion and the Minibuffer
+------------------------------------
This section describes the basic interface for reading from the
minibuffer with completion.
- - Function: completing-read prompt collection &optional predicate
+ -- 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
"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 ----------
\1f
File: lispref.info, Node: Completion Commands, Next: High-Level Completion, Prev: Minibuffer Completion, Up: Completion
-Minibuffer Commands That Do Completion
---------------------------------------
+24.5.3 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
+ -- 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:
with other characters bound as in `minibuffer-local-map' (*note
Text from Minibuffer::).
- - Variable: minibuffer-local-must-match-map
+ -- 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
with other characters bound as in `minibuffer-local-map'.
- - Variable: minibuffer-completion-table
+ -- 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
+ -- 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
+ -- 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
+ -- Command: minibuffer-complete
This function completes the minibuffer contents as far as possible.
- - Command: minibuffer-complete-and-exit
+ -- 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_
command is programmed to work without confirmation when run twice
in succession.
- - Variable: minibuffer-completion-confirm
+ -- 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
+ -- 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
list of completions is displayed as text in a buffer named
`*Completions*'.
- - Function: display-completion-list completions &rest cl-keys
+ -- Function: display-completion-list completions &rest cl-keys
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
(display-completion-list
(all-completions (buffer-string) my-alist)))
- - User Option: completion-auto-help
+ -- 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
\1f
File: lispref.info, Node: High-Level Completion, Next: Reading File Names, Prev: Completion Commands, Up: Completion
-High-Level Completion Functions
---------------------------------
+24.5.4 High-Level Completion Functions
+---------------------------------------
This section describes the higher-level convenient functions for
reading certain sorts of names with completion.
reading the arguments for a command, in the `interactive' spec. *Note
Defining Commands::.
- - Function: read-buffer prompt &optional default existing
+ -- Function: read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a
string. The argument DEFAULT is the default name to use, the
value to return if the user exits with an empty minibuffer. If
;; After evaluation of the preceding expression,
;; the following prompt appears,
;; with an empty minibuffer:
-
+
---------- Buffer: Minibuffer ----------
Buffer name? (default foo) -!-
---------- Buffer: Minibuffer ----------
-
+
;; The user types `minibuffer.t <RET>'.
=> "minibuffer.texi"
- - Function: read-command prompt &optional default-value
+ -- Function: read-command prompt &optional default-value
This function reads the name of a command and returns it as a Lisp
symbol. The argument PROMPT is used as in `read-from-minibuffer'.
Recall that a command is anything for which `commandp' returns
user enters null input, the return value is `nil'.
(read-command "Command name? ")
-
+
;; After evaluation of the preceding expression,
;; the following prompt appears with an empty minibuffer:
-
+
---------- Buffer: Minibuffer ----------
Command name?
---------- Buffer: Minibuffer ----------
(intern (completing-read PROMPT obarray
'commandp t nil))
- - Function: read-variable prompt &optional default-value
+ -- Function: read-variable prompt &optional default-value
This function reads the name of a user variable and returns it as a
symbol.
then if the user enters null input, the return value is `nil'.
(read-variable "Variable name? ")
-
+
;; After evaluation of the preceding expression,
;; the following prompt appears,
;; with an empty minibuffer:
-
+
---------- Buffer: Minibuffer ----------
Variable name? -!-
---------- Buffer: Minibuffer ----------
\1f
File: lispref.info, Node: Reading File Names, Next: Programmed Completion, Prev: High-Level Completion, Up: Completion
-Reading File Names
-------------------
+24.5.5 Reading File Names
+-------------------------
Here is another high-level completion function, designed for reading a
file name. It provides special features including automatic insertion
of the default directory.
- - Function: read-file-name prompt &optional directory default existing
- initial history
+ -- Function: read-file-name prompt &optional directory default
+ existing initial history
This function reads a file name in the minibuffer, prompting with
PROMPT and providing completion. If DEFAULT is non-`nil', then
the function returns DEFAULT if the user just types <RET>.
Here is an example:
(read-file-name "The file is ")
-
+
;; After evaluation of the preceding expression,
;; the following appears in the minibuffer:
-
+
---------- Buffer: Minibuffer ----------
The file is /gp/gnu/elisp/-!-
---------- Buffer: Minibuffer ----------
If the user types <RET>, `read-file-name' returns the file name as
the string `"/gp/gnu/elisp/manual.texi"'.
- - User Option: insert-default-directory
+ -- User Option: insert-default-directory
This variable is used by `read-file-name'. Its value controls
whether `read-file-name' starts by placing the name of the default
directory in the minibuffer, plus the initial file name if any.
;; Here the minibuffer starts out with the default directory.
(let ((insert-default-directory t))
(read-file-name "The file is "))
-
+
---------- Buffer: Minibuffer ----------
The file is ~lewis/manual/-!-
---------- Buffer: Minibuffer ----------
-
+
;; Here the minibuffer is empty and only the prompt
;; appears on its line.
(let ((insert-default-directory nil))
(read-file-name "The file is "))
-
+
---------- Buffer: Minibuffer ----------
The file is -!-
---------- Buffer: Minibuffer ----------
\1f
File: lispref.info, Node: Programmed Completion, Prev: Reading File Names, Up: Completion
-Programmed Completion
----------------------
+24.5.6 Programmed Completion
+----------------------------
Sometimes it is not possible to create an alist or an obarray
containing all the intended possible completions. In such a case, you
\1f
File: lispref.info, Node: Yes-or-No Queries, Next: Multiple Queries, Prev: Completion, Up: Minibuffers
-Yes-or-No Queries
-=================
+24.6 Yes-or-No Queries
+======================
This section describes functions used to ask the user a yes-or-no
question. The function `y-or-n-p' can be answered with a single
Strictly speaking, `yes-or-no-p' uses the minibuffer and `y-or-n-p'
does not; but it seems best to describe them together.
- - Function: y-or-n-p prompt
+ -- Function: y-or-n-p prompt
This function asks the user a question, expecting input in the echo
area. It returns `t' if the user types `y', `nil' if the user
types `n'. This function also accepts <SPC> to mean yes and <DEL>
invalid. At the next prompt the user types `y'.
(y-or-n-p "Do you need a lift? ")
-
+
;; After evaluation of the preceding expression,
;; the following prompt appears in the echo area:
-
+
---------- Echo area ----------
Do you need a lift? (y or n)
---------- Echo area ----------
-
+
;; If the user then types `q', the following appears:
-
+
---------- Echo area ----------
Please answer y or n. Do you need a lift? (y or n)
---------- Echo area ----------
-
+
;; When the user types a valid answer,
;; it is displayed after the question:
-
+
---------- Echo area ----------
Do you need a lift? (y or n) y
---------- Echo area ----------
We show successive lines of echo area messages, but only one
actually appears on the screen at a time.
- - Function: yes-or-no-p prompt
+ -- Function: yes-or-no-p prompt
This function asks the user a question, expecting input in the
minibuffer. It returns `t' if the user enters `yes', `nil' if the
user types `no'. The user must type <RET> to finalize the
Here is an example:
(yes-or-no-p "Do you really want to remove everything? ")
-
+
;; After evaluation of the preceding expression,
;; the following prompt appears,
;; with an empty minibuffer:
-
+
---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
Do you really want to remove everything? (yes or no)
---------- Buffer: minibuffer ----------
- - Function: yes-or-no-p-dialog-box prompt
+ -- Function: yes-or-no-p-dialog-box prompt
This function asks the user a "y or n" question with a popup dialog
box. It returns `t' if the answer is "yes". PROMPT is the string
to display to ask the question.
are replaced with the following functions, so that menu items bring up
dialog boxes instead of minibuffer questions.
- - Function: y-or-n-p-maybe-dialog-box prompt
+ -- Function: y-or-n-p-maybe-dialog-box prompt
This function asks user a "y or n" question, using either a dialog
box or the minibuffer, as appropriate.
- - Function: yes-or-no-p-maybe-dialog-box prompt
+ -- Function: yes-or-no-p-maybe-dialog-box prompt
This function asks user a "yes or no" question, using either a
dialog box or the minibuffer, as appropriate.
\1f
File: lispref.info, Node: Multiple Queries, Next: Reading a Password, Prev: Yes-or-No Queries, Up: Minibuffers
-Asking Multiple Y-or-N Questions
-================================
+24.7 Asking Multiple Y-or-N Questions
+=====================================
When you have a series of similar questions to ask, such as "Do you
want to save this buffer" for each buffer in turn, you should use
each question individually. This gives the user certain convenient
facilities such as the ability to answer the whole series at once.
- - Function: map-y-or-n-p prompter actor list &optional help
+ -- Function: map-y-or-n-p prompter actor list &optional help
action-alist
This function, new in Emacs 19, asks the user a series of
questions, reading a single-character answer in the echo area for
\1f
File: lispref.info, Node: Reading a Password, Next: Minibuffer Misc, Prev: Multiple Queries, Up: Minibuffers
-Reading a Password
-==================
+24.8 Reading a Password
+=======================
To read a password to pass to another program, you can use the function
`read-passwd'.
- - Function: read-passwd prompt &optional confirm default
+ -- Function: read-passwd prompt &optional confirm default
This function reads a password, prompting with PROMPT. It does
not echo the password as the user types it; instead, it echoes `.'
for each character in the password.
and inserted in the minibuffer. If DEFAULT is `nil', then
`read-passwd' returns the null string in that case.
- - User Option: passwd-invert-frame-when-keyboard-grabbed
+ -- User Option: passwd-invert-frame-when-keyboard-grabbed
If non-`nil', swap the foreground and background colors of all
faces while reading a password. Default values is `t', unless
feature `infodock' is provided.
- - User Option: passwd-echo
+ -- User Option: passwd-echo
This specifies the character echoed when typing a password. When
`nil', nothing is echoed.
\1f
File: lispref.info, Node: Minibuffer Misc, Prev: Reading a Password, Up: Minibuffers
-Minibuffer Miscellany
-=====================
+24.9 Minibuffer Miscellany
+==========================
This section describes some basic functions and variables related to
minibuffers.
- - Command: exit-minibuffer
+ -- Command: exit-minibuffer
This command exits the active minibuffer. It is normally bound to
keys in minibuffer local keymaps.
- - Command: self-insert-and-exit
+ -- Command: self-insert-and-exit
This command exits the active minibuffer after inserting the last
character typed on the keyboard (found in `last-command-char';
*note Command Loop Info::).
- - Command: previous-history-element n
+ -- Command: previous-history-element n
This command replaces the minibuffer contents with the value of the
Nth previous (older) history element.
- - Command: next-history-element n
+ -- Command: next-history-element n
This command replaces the minibuffer contents with the value of the
Nth more recent history element.
- - Command: previous-matching-history-element pattern
+ -- Command: previous-matching-history-element pattern
This command replaces the minibuffer contents with the value of the
previous (older) history element that matches PATTERN (a regular
expression).
- - Command: next-matching-history-element pattern
+ -- Command: next-matching-history-element pattern
This command replaces the minibuffer contents with the value of
the next (newer) history element that matches PATTERN (a regular
expression).
- - Function: minibuffer-prompt
+ -- Function: minibuffer-prompt
This function returns the prompt string of the currently active
minibuffer. If no minibuffer is active, it returns `nil'.
- - Function: minibuffer-prompt-width
+ -- Function: minibuffer-prompt-width
This function returns the display width of the prompt string of the
currently active minibuffer. If no minibuffer is active, it
returns 0.
- - Variable: minibuffer-setup-hook
+ -- Variable: minibuffer-setup-hook
This is a normal hook that is run whenever the minibuffer is
entered. *Note Hooks::.
- - Variable: minibuffer-exit-hook
+ -- Variable: minibuffer-exit-hook
This is a normal hook that is run whenever the minibuffer is
exited. *Note Hooks::.
- - Variable: minibuffer-help-form
+ -- Variable: minibuffer-help-form
The current value of this variable is used to rebind `help-form'
locally inside the minibuffer (*note Help Functions::).
- - Function: active-minibuffer-window
+ -- Function: active-minibuffer-window
This function returns the currently active minibuffer window, or
`nil' if none is currently active.
- - Function: minibuffer-window &optional frame
+ -- Function: minibuffer-window &optional frame
This function returns the minibuffer window used for frame FRAME.
If FRAME is `nil', that stands for the current frame. Note that
the minibuffer window used by a frame need not be part of that
frame--a frame that has no minibuffer of its own necessarily uses
some other frame's minibuffer window.
- - Function: window-minibuffer-p &optional window
+ -- Function: window-minibuffer-p &optional window
This function returns non-`nil' if WINDOW is a minibuffer window.
It is not correct to determine whether a given window is a
because there can be more than one minibuffer window if there is more
than one frame.
- - Function: minibuffer-window-active-p window
+ -- Function: minibuffer-window-active-p window
This function returns non-`nil' if WINDOW, assumed to be a
minibuffer window, is currently active.
- - Variable: minibuffer-scroll-window
+ -- Variable: minibuffer-scroll-window
If the value of this variable is non-`nil', it should be a window
object. When the function `scroll-other-window' is called in the
minibuffer, it scrolls this window.
Finally, some functions and variables deal with recursive minibuffers
(*note Recursive Editing::):
- - Function: minibuffer-depth
+ -- Function: minibuffer-depth
This function returns the current depth of activations of the
minibuffer, a nonnegative integer. If no minibuffers are active,
it returns zero.
- - User Option: enable-recursive-minibuffers
+ -- User Option: enable-recursive-minibuffers
If this variable is non-`nil', you can invoke commands (such as
`find-file') that use minibuffers even while the minibuffer window
is active. Such invocation produces a recursive editing level for
\1f
File: lispref.info, Node: Command Loop, Next: Keymaps, Prev: Minibuffers, Up: Top
-Command Loop
-************
+25 Command Loop
+***************
When you run XEmacs, it enters the "editor command loop" almost
immediately. This loop reads events, executes their definitions, and
\1f
File: lispref.info, Node: Command Overview, Next: Defining Commands, Up: Command Loop
-Command Loop Overview
-=====================
+25.1 Command Loop Overview
+==========================
The command loop in XEmacs is a standard event loop, reading events one
at a time with `next-event' and handling them with `dispatch-event'.
To terminate the execution of a running command, type `C-g'. This
character causes "quitting" (*note Quitting::).
- - Variable: pre-command-hook
+ -- Variable: pre-command-hook
The editor command loop runs this normal hook before each command.
At that time, `this-command' contains the command that is about to
run, and `last-command' describes the previous command. *Note
Hooks::.
- - Variable: post-command-hook
+ -- Variable: post-command-hook
The editor command loop runs this normal hook after each command.
(In FSF Emacs, it is also run when the command loop is entered, or
reentered after an error or quit.) At that time, `this-command'
\1f
File: lispref.info, Node: Defining Commands, Next: Interactive Call, Prev: Command Overview, Up: Command Loop
-Defining Commands
-=================
+25.2 Defining Commands
+======================
A Lisp function becomes a command when its body contains, at top level,
a form that calls the special form `interactive'. This form does
\1f
File: lispref.info, Node: Using Interactive, Next: Interactive Codes, Up: Defining Commands
-Using `interactive'
--------------------
+25.2.1 Using `interactive'
+--------------------------
This section describes how to write the `interactive' form that makes a
Lisp function an interactively-callable command.
- - Special Form: interactive arg-descriptor
+ -- Special Form: interactive arg-descriptor
This special form declares that the function in which it appears
is a command, and that it may therefore be called interactively
(via `M-x' or by entering a key sequence bound to it). The
* It may be a Lisp expression that is not a string; then it should
be a form that is evaluated to get a list of arguments to pass to
- the command.
+ the command.
If this expression reads keyboard input (this includes using the
minibuffer), keep in mind that the integer value of point or the
prompt string (starting with the first character that is not `*',
`@', or `_').
- - Function: function-interactive function
+ -- Function: function-interactive function
This function retrieves the interactive specification of FUNCTION,
which may be any funcallable object. The specification will be
returned as the list of the symbol `interactive' and the specs. If
\1f
File: lispref.info, Node: Interactive Codes, Next: Interactive Examples, Prev: Using Interactive, Up: Defining Commands
-Code Characters for `interactive'
----------------------------------
+25.2.2 Code Characters for `interactive'
+----------------------------------------
The code character descriptions below contain a number of key words,
defined here as follows:
\1f
File: lispref.info, Node: Interactive Examples, Prev: Interactive Codes, Up: Defining Commands
-Examples of Using `interactive'
--------------------------------
+25.2.3 Examples of Using `interactive'
+--------------------------------------
Here are some examples of `interactive':
(interactive) ; just moves forward two words.
(forward-word 2))
=> foo1
-
+
(defun foo2 (n) ; `foo2' takes one argument,
(interactive "p") ; which is the numeric prefix.
(forward-word (* 2 n)))
=> foo2
-
+
(defun foo3 (n) ; `foo3' takes one argument,
(interactive "nCount:") ; which is read with the Minibuffer.
(forward-word (* 2 n)))
=> foo3
-
+
(defun three-b (b1 b2 b3)
"Select three existing buffers.
Put them into three windows, selecting the last one."
\1f
File: lispref.info, Node: Interactive Call, Next: Command Loop Info, Prev: Defining Commands, Up: Command Loop
-Interactive Call
-================
+25.3 Interactive Call
+=====================
After the command loop has translated a key sequence into a definition,
it invokes that definition using the function `command-execute'. If
`call-interactively', which reads the arguments and calls the command.
You can also call these functions yourself.
- - Function: commandp function
+ -- Function: commandp function
Returns `t' if FUNCTION is suitable for calling interactively;
that is, if FUNCTION is a command. Otherwise, returns `nil'.
See `documentation' in *Note Accessing Documentation::, for a
realistic example of using `commandp'.
- - Function: call-interactively command &optional record-flag keys
+ -- Function: call-interactively command &optional record-flag keys
This function calls the interactively callable function COMMAND,
reading arguments according to its interactive calling
specifications. An error is signaled if COMMAND is not a function
the command is added only if it uses the minibuffer to read an
argument. *Note Command History::.
- - Function: command-execute command &optional record-flag keys
+ -- Function: command-execute command &optional record-flag keys
This function executes COMMAND as an editing command. The
argument COMMAND must satisfy the `commandp' predicate; i.e., it
must be an interactively callable function or a keyboard macro.
Such a definition is handled by loading the specified library and
then rechecking the definition of the symbol.
- - Command: execute-extended-command prefix-argument
+ -- Command: execute-extended-command prefix-argument
This function reads a command name from the minibuffer using
`completing-read' (*note Completion::). Then it uses
`command-execute' to call the specified command. Whatever that
---------- Buffer: Minibuffer ----------
=> t
- - Function: interactive-p
+ -- Function: interactive-p
This function returns `t' if the containing function (the one that
called `interactive-p') was called interactively, with the function
`call-interactively'. (It makes no difference whether
(and (interactive-p)
(message "foo")))
=> foo
-
+
(defun bar ()
(interactive)
(setq foobar (list (foo) (interactive-p))))
=> bar
-
+
;; Type `M-x foo'.
-| foo
-
+
;; Type `M-x bar'.
;; This does not print anything.
-
+
foobar
=> (nil t)
\1f
File: lispref.info, Node: Command Loop Info, Next: Events, Prev: Interactive Call, Up: Command Loop
-Information from the Command Loop
-=================================
+25.4 Information from the Command Loop
+======================================
The editor command loop sets several Lisp variables to keep status
records for itself and for commands that are run.
- - Variable: last-command
+ -- Variable: last-command
This variable records the name of the previous command executed by
the command loop (the one before the current command). Normally
the value is a symbol with a function definition, but this is not
the command loop, except when the command specifies a prefix
argument for the following command.
- - Variable: this-command
+ -- Variable: this-command
This variable records the name of the command now being executed by
the editor command loop. Like `last-command', it is normally a
symbol with a function definition.
...do the work...
(setq this-command old-this-command)))
- - Function: this-command-keys
+ -- Function: this-command-keys
This function returns a vector containing the key and mouse events
that invoked the present command, plus any previous commands that
generated the prefix argument for this command. (Note: this is not
;; Now use `C-u C-x C-e' to evaluate that.
=> [#<keypress-event control-U> #<keypress-event control-X> #<keypress-event control-E>]
- - Variable: last-command-event
+ -- Variable: last-command-event
This variable is set to the last input event that was read by the
command loop as part of a command. The principal use of this
variable is in `self-insert-command', which uses it to decide which
;; Now type `C-u C-x C-e'.
=> #<keypress-event control-E>
- - Variable: last-command-char
+ -- Variable: last-command-char
If the value of `last-command-event' is a keyboard event, then this
is the nearest character equivalent to it (or `nil' if there is no
character equivalent). `last-command-char' is the character that
=> ?\^E
- - Variable: current-mouse-event
+ -- Variable: current-mouse-event
This variable holds the mouse-button event which invoked this
command, or `nil'. This is what `(interactive "e")' returns.
- - Variable: echo-keystrokes
+ -- Variable: echo-keystrokes
This variable determines how much time should elapse before command
characters echo. Its value must be an integer, which specifies the
number of seconds to wait before echoing. If the user types a
\1f
File: lispref.info, Node: Events, Next: Reading Input, Prev: Command Loop Info, Up: Command Loop
-Events
-======
+25.5 Events
+===========
The XEmacs command loop reads a sequence of "events" that represent
keyboard or mouse activity. Unlike in Emacs 18 and in FSF Emacs,
For information about how exactly the XEmacs command loop works,
*Note Reading Input::.
- - Function: eventp object
+ -- Function: eventp object
This function returns non-`nil' if OBJECT is an input event.
* Menu:
\1f
File: lispref.info, Node: Event Types, Next: Event Contents, Up: Events
-Event Types
------------
+25.5.1 Event Types
+------------------
Events represent keyboard or mouse activity or status changes of various
sorts, such as process input being available or a timeout being
\1f
File: lispref.info, Node: Event Contents, Next: Event Predicates, Prev: Event Types, Up: Events
-Contents of the Different Types of Events
------------------------------------------
+25.5.2 Contents of the Different Types of Events
+------------------------------------------------
Every event, no matter what type it is, contains a timestamp (which is
typically an offset in milliseconds from when the X server was started)
The object to pass to the function. The function and object
are set when the event is created.
- - Function: event-type event
+ -- Function: event-type event
Return the type of EVENT.
This will be a symbol; one of
\1f
File: lispref.info, Node: Event Predicates, Next: Accessing Mouse Event Positions, Prev: Event Contents, Up: Events
-Event Predicates
-----------------
+25.5.3 Event Predicates
+-----------------------
The following predicates return whether an object is an event of a
particular type.
- - Function: key-press-event-p object
+ -- Function: key-press-event-p object
This is true if OBJECT is a key-press event.
- - Function: button-event-p object
+ -- Function: button-event-p object
This is true if OBJECT is a mouse button-press or button-release
event.
- - Function: button-press-event-p object
+ -- Function: button-press-event-p object
This is true if OBJECT is a mouse button-press event.
- - Function: button-release-event-p object
+ -- Function: button-release-event-p object
This is true if OBJECT is a mouse button-release event.
- - Function: motion-event-p object
+ -- Function: motion-event-p object
This is true if OBJECT is a mouse motion event.
- - Function: mouse-event-p object
+ -- Function: mouse-event-p object
This is true if OBJECT is a mouse button-press, button-release or
motion event.
- - Function: eval-event-p object
+ -- Function: eval-event-p object
This is true if OBJECT is an eval event.
- - Function: misc-user-event-p object
+ -- Function: misc-user-event-p object
This is true if OBJECT is a misc-user event.
- - Function: process-event-p object
+ -- Function: process-event-p object
This is true if OBJECT is a process event.
- - Function: timeout-event-p object
+ -- Function: timeout-event-p object
This is true if OBJECT is a timeout event.
- - Function: event-live-p object
+ -- Function: event-live-p object
This is true if OBJECT is any event that has not been deallocated.
\1f
File: lispref.info, Node: Accessing Mouse Event Positions, Next: Accessing Other Event Info, Prev: Event Predicates, Up: Events
-Accessing the Position of a Mouse Event
----------------------------------------
+25.5.4 Accessing the Position of a Mouse Event
+----------------------------------------------
Unlike other events, mouse events (i.e. motion, button-press,
button-release, and drag or drop type misc-user events) occur in a
\1f
File: lispref.info, Node: Frame-Level Event Position Info, Next: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
-Frame-Level Event Position Info
-...............................
+25.5.4.1 Frame-Level Event Position Info
+........................................
The following functions return frame-level information about where a
mouse event occurred.
- - Function: event-frame event
+ -- Function: event-frame event
This function returns the "channel" or frame that the given mouse
motion, button press, button release, or misc-user event occurred
in. This will be `nil' for non-mouse events.
- - Function: event-x-pixel event
+ -- Function: event-x-pixel event
This function returns the X position in pixels of the given mouse
event. The value returned is relative to the frame the event
occurred in. This will signal an error if the event is not a
mouse event.
- - Function: event-y-pixel event
+ -- Function: event-y-pixel event
This function returns the Y position in pixels of the given mouse
event. The value returned is relative to the frame the event
occurred in. This will signal an error if the event is not a
\1f
File: lispref.info, Node: Window-Level Event Position Info, Next: Event Text Position Info, Prev: Frame-Level Event Position Info, Up: Accessing Mouse Event Positions
-Window-Level Event Position Info
-................................
+25.5.4.2 Window-Level Event Position Info
+.........................................
The following functions return window-level information about where a
mouse event occurred.
- - Function: event-window event
+ -- Function: event-window event
Given a mouse motion, button press, button release, or misc-user
event, compute and return the window on which that event occurred.
This may be `nil' if the event occurred in the border or over a
toolbar. The modeline is considered to be within the window it
describes.
- - Function: event-buffer event
+ -- Function: event-buffer event
Given a mouse motion, button press, button release, or misc-user
event, compute and return the buffer of the window on which that
event occurred. This may be `nil' if the event occurred in the
`event-window' and then calling `window-buffer' on the result if
it is a window.
- - Function: event-window-x-pixel event
+ -- Function: event-window-x-pixel event
This function returns the X position in pixels of the given mouse
event. The value returned is relative to the window the event
occurred in. This will signal an error if the event is not a
mouse-motion, button-press, button-release, or misc-user event.
- - Function: event-window-y-pixel event
+ -- Function: event-window-y-pixel event
This function returns the Y position in pixels of the given mouse
event. The value returned is relative to the window the event
occurred in. This will signal an error if the event is not a
\1f
File: lispref.info, Node: Event Text Position Info, Next: Event Glyph Position Info, Prev: Window-Level Event Position Info, Up: Accessing Mouse Event Positions
-Event Text Position Info
-........................
+25.5.4.3 Event Text Position Info
+.................................
The following functions return information about the text (including the
modeline) that a mouse event occurred over or near.
- - Function: event-over-text-area-p event
+ -- Function: event-over-text-area-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over the text
area of a window. Otherwise, `nil' is returned. The modeline is
not considered to be part of the text area.
- - Function: event-over-modeline-p event
+ -- Function: event-over-modeline-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over the modeline
of a window. Otherwise, `nil' is returned.
- - Function: event-x event
+ -- Function: event-x event
This function returns the X position of the given mouse-motion,
button-press, button-release, or misc-user event in characters.
This is relative to the window the event occurred over.
- - Function: event-y event
+ -- Function: event-y event
This function returns the Y position of the given mouse-motion,
button-press, button-release, or misc-user event in characters.
This is relative to the window the event occurred over.
- - Function: event-point event
+ -- Function: event-point event
This function returns the character position of the given
mouse-motion, button-press, button-release, or misc-user event.
If the event did not occur over a window, or did not occur over
text, then this returns `nil'. Otherwise, it returns an index
into the buffer visible in the event's window.
- - Function: event-closest-point event
+ -- Function: event-closest-point event
This function returns the character position of the given
mouse-motion, button-press, button-release, or misc-user event.
If the event did not occur over a window or over text, it returns
\1f
File: lispref.info, Node: Event Glyph Position Info, Next: Event Toolbar Position Info, Prev: Event Text Position Info, Up: Accessing Mouse Event Positions
-Event Glyph Position Info
-.........................
+25.5.4.4 Event Glyph Position Info
+..................................
The following functions return information about the glyph (if any) that
a mouse event occurred over.
- - Function: event-over-glyph-p event
+ -- Function: event-over-glyph-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over a glyph.
Otherwise, `nil' is returned.
- - Function: event-glyph-extent event
+ -- Function: event-glyph-extent event
If the given mouse-motion, button-press, button-release, or
misc-user event happened on top of a glyph, this returns its
extent; else `nil' is returned.
- - Function: event-glyph-x-pixel event
+ -- Function: event-glyph-x-pixel event
Given a mouse-motion, button-press, button-release, or misc-user
event over a glyph, this function returns the X position of the
pointer relative to the upper left of the glyph. If the event is
not over a glyph, it returns `nil'.
- - Function: event-glyph-y-pixel event
+ -- Function: event-glyph-y-pixel event
Given a mouse-motion, button-press, button-release, or misc-user
event over a glyph, this function returns the Y position of the
pointer relative to the upper left of the glyph. If the event is
\1f
File: lispref.info, Node: Event Toolbar Position Info, Next: Other Event Position Info, Prev: Event Glyph Position Info, Up: Accessing Mouse Event Positions
-Event Toolbar Position Info
-...........................
+25.5.4.5 Event Toolbar Position Info
+....................................
- - Function: event-over-toolbar-p event
+ -- Function: event-over-toolbar-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over a toolbar.
Otherwise, `nil' is returned.
- - Function: event-toolbar-button event
+ -- Function: event-toolbar-button event
If the given mouse-motion, button-press, button-release, or
misc-user event happened on top of a toolbar button, this function
returns the button. Otherwise, `nil' is returned.
\1f
File: lispref.info, Node: Other Event Position Info, Prev: Event Toolbar Position Info, Up: Accessing Mouse Event Positions
-Other Event Position Info
-.........................
+25.5.4.6 Other Event Position Info
+..................................
- - Function: event-over-border-p event
+ -- Function: event-over-border-p event
Given a mouse-motion, button-press, button-release, or misc-user
event, this function returns `t' if the event is over an internal
toolbar. Otherwise, `nil' is returned.
\1f
File: lispref.info, Node: Accessing Other Event Info, Next: Working With Events, Prev: Accessing Mouse Event Positions, Up: Events
-Accessing the Other Contents of Events
---------------------------------------
+25.5.5 Accessing the Other Contents of Events
+---------------------------------------------
The following functions allow access to the contents of events other
than the position info described in the previous section.
- - Function: event-timestamp event
+ -- Function: event-timestamp event
This function returns the timestamp of the given event object.
- - Function: event-device event
+ -- Function: event-device event
This function returns the device that the given event occurred on.
- - Function: event-key event
+ -- Function: event-key event
This function returns the Keysym of the given key-press event.
This will be the ASCII code of a printing character, or a symbol.
- - Function: event-button event
+ -- Function: event-button event
This function returns the button-number of the given button-press
or button-release event.
- - Function: event-modifiers event
+ -- Function: event-modifiers event
This function returns a list of symbols, the names of the modifier
keys which were down when the given mouse or keyboard event was
produced.
- - Function: event-modifier-bits event
+ -- Function: event-modifier-bits event
This function returns a number representing the modifier keys
which were down when the given mouse or keyboard event was
produced.
- - Function: event-function event
+ -- Function: event-function event
This function returns the callback function of the given timeout,
misc-user, or eval event.
- - Function: event-object event
+ -- Function: event-object event
This function returns the callback function argument of the given
timeout, misc-user, or eval event.
- - Function: event-process event
+ -- Function: event-process event
This function returns the process of the given process event.
\1f
File: lispref.info, Node: Working With Events, Next: Converting Events, Prev: Accessing Other Event Info, Up: Events
-Working With Events
--------------------
+25.5.6 Working With Events
+--------------------------
XEmacs provides primitives for creating, copying, and destroying event
objects. Many functions that return events take an event object as an
either an event object or `nil', creating the event object first in the
latter case.
- - Function: make-event &optional type plist
+ -- Function: make-event &optional type plist
This function creates a new event structure. If no arguments are
specified, the created event will be empty. To specify the event
type, use the TYPE argument. The allowed types are `empty',
;; Create an empty event.
(make-event)
=> #<empty-event>
-
+
;; Try creating a key-press event.
(make-event 'key-press)
error--> Undefined key for keypress event
-
+
;; Creating a key-press event, try 2
(make-event 'key-press '(key home))
=> #<keypress-event home>
-
+
;; Create a key-press event of dubious fame.
(make-event 'key-press '(key escape modifiers (meta alt control shift)))
=> #<keypress-event control-meta-alt-shift-escape>
-
+
;; Create a M-button1 event at coordinates defined by variables
;; X and Y.
(make-event 'button-press `(button 1 modifiers (meta) x ,x y ,y))
=> #<buttondown-event meta-button1>
-
+
;; Create a similar button-release event.
(make-event 'button-release `(button 1 modifiers (meta) x ,x y ,x))
=> #<buttonup-event meta-button1up>
-
+
;; Create a mouse-motion event.
(make-event 'motion '(x 20 y 30))
=> #<motion-event 20, 30>
-
+
(event-properties (make-event 'motion '(x 20 y 30)))
=> (channel #<x-frame "emacs" 0x8e2> x 20 y 30
modifiers nil timestamp 0)
(append '(modifiers nil)
(event-properties EVENT)))
- - Function: copy-event event1 &optional event2
+ -- Function: copy-event event1 &optional event2
This function makes a copy of the event object EVENT1. If a
second event argument EVENT2 is given, EVENT1 is copied into
EVENT2 and EVENT2 is returned. If EVENT2 is not supplied (or is
`nil') then a new event will be made, as with `make-event'.
- - Function: deallocate-event event
+ -- Function: deallocate-event event
This function allows the given event structure to be reused. You
*MUST NOT* use this event object after calling this function with
it. You will lose. It is not necessary to call this function, as
\1f
File: lispref.info, Node: Converting Events, Prev: Working With Events, Up: Events
-Converting Events
------------------
+25.5.7 Converting Events
+------------------------
XEmacs provides some auxiliary functions for converting between events
and other ways of representing keys. These are useful when working with
ASCII strings and with keymaps.
- - Function: character-to-event key-description &optional event console
- use-console-meta-flag
+ -- Function: character-to-event key-description &optional event
+ console use-console-meta-flag
This function converts a keystroke description to an event
structure. KEY-DESCRIPTION is the specification of a key stroke,
and EVENT is the event object to fill in. This function contains
strictly inverse functions, since events contain much more
information than the ASCII character set can encode.
- - Function: event-to-character event &optional allow-extra-modifiers
+ -- Function: event-to-character event &optional allow-extra-modifiers
allow-meta allow-non-ascii
This function returns the closest ASCII approximation to EVENT.
If the event isn't a keypress, this returns `nil'.
ambiguous, as both use the high bit; <M-x> and <oslash> will be
indistinguishable.
- - Function: events-to-keys events &optional no-mice
+ -- Function: events-to-keys events &optional no-mice
Given a vector of event objects, this function returns a vector of
key descriptors, or a string (if they all fit in the ASCII range).
Optional arg NO-MICE means that button events are not allowed.
\1f
File: lispref.info, Node: Reading Input, Next: Waiting, Prev: Events, Up: Command Loop
-Reading Input
-=============
+25.6 Reading Input
+==================
The editor command loop reads keyboard input using the function
`next-event' and constructs key sequences out of the events using
\1f
File: lispref.info, Node: Key Sequence Input, Next: Reading One Event, Up: Reading Input
-Key Sequence Input
-------------------
+25.6.1 Key Sequence Input
+-------------------------
Lisp programs can read input a key sequence at a time by calling
`read-key-sequence'; for example, `describe-key' uses it to read the
key to describe.
- - Function: read-key-sequence prompt &optional continue-echo
+ -- Function: read-key-sequence prompt &optional continue-echo
dont-downcase-last
This function reads a sequence of keystrokes or mouse clicks and
returns it as a vector of event objects read. It keeps reading
and the user types `C-x C-f'.
(read-key-sequence "?")
-
+
---------- Echo Area ----------
?C-x C-f
---------- Echo Area ----------
-
+
=> [#<keypress-event control-X> #<keypress-event control-F>]
If an input character is an upper-case letter and has no key binding,
\1f
File: lispref.info, Node: Reading One Event, Next: Dispatching an Event, Prev: Key Sequence Input, Up: Reading Input
-Reading One Event
------------------
+25.6.2 Reading One Event
+------------------------
The lowest level functions for command input are those which read a
single event. These functions often make a distinction between
actions), and other events, which serve as communication between XEmacs
and the window system.
- - Function: next-event &optional event prompt
+ -- Function: next-event &optional event prompt
This function reads and returns the next available event from the
window system or terminal driver, waiting if necessary until an
event is available. Pass this object to `dispatch-event' to
In most cases, the function `next-command-event' is more
appropriate.
- - Function: next-command-event &optional event prompt
+ -- Function: next-command-event &optional event prompt
This function returns the next available "user" event from the
window system or terminal driver. Pass this object to
`dispatch-event' to handle it. If an event object is supplied, it
(next-command-event)
=> #<keypress-event right>
- - Function: read-char
+ -- Function: read-char
This function reads and returns a character of command input. If a
mouse click is detected, an error is signalled. The character
typed is returned as an ASCII value. This function is retained for
compatibility with Emacs 18, and is most likely the wrong thing
for you to be using: consider using `next-command-event' instead.
- - Function: enqueue-eval-event function object
+ -- Function: enqueue-eval-event function object
This function adds an eval event to the back of the queue. The
eval event will be the next event read after all pending events.
\1f
File: lispref.info, Node: Dispatching an Event, Next: Quoted Character Input, Prev: Reading One Event, Up: Reading Input
-Dispatching an Event
---------------------
+25.6.3 Dispatching an Event
+---------------------------
- - Function: dispatch-event event
+ -- Function: dispatch-event event
Given an event object returned by `next-event', this function
executes it. This is the basic function that makes XEmacs respond
to user input; it also deals with notifications from the window
\1f
File: lispref.info, Node: Quoted Character Input, Next: Peeking and Discarding, Prev: Dispatching an Event, Up: Reading Input
-Quoted Character Input
-----------------------
+25.6.4 Quoted Character Input
+-----------------------------
You can use the function `read-quoted-char' to ask the user to specify
a character, and allow the user to specify a control or meta character
conveniently, either literally or as an octal character code. The
command `quoted-insert' uses this function.
- - Function: read-quoted-char &optional prompt
+ -- Function: read-quoted-char &optional prompt
This function is like `read-char', except that if the first
character read is an octal digit (0-7), it reads up to two more
octal digits (but stopping if a non-octal digit is found) and
(which is 127 in decimal).
(read-quoted-char "What character")
-
+
---------- Echo Area ----------
What character-177
---------- Echo Area ----------
-
+
=> 127
projects / chise / xemacs-chise.git / blobdiff