Sync with r21_2_36.
[chise/xemacs-chise.git] / info / lispref.info-16
index b61a7d9..5e63304 100644 (file)
@@ -1,5 +1,5 @@
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
 
 INFO-DIR-SECTION XEmacs Editor
 START-INFO-DIR-ENTRY
@@ -50,6 +50,124 @@ may be included in a translation approved by the Free Software
 Foundation instead of in the original English.
 
 \1f
+File: lispref.info,  Node: Completion Commands,  Next: High-Level Completion,  Prev: Minibuffer Completion,  Up: Completion
+
+Minibuffer Commands That Do Completion
+--------------------------------------
+
+   This section describes the keymaps, commands and user options used in
+the minibuffer to do completion.
+
+ - Variable: minibuffer-local-completion-map
+     `completing-read' uses this value as the local keymap when an
+     exact match of one of the completions is not required.  By
+     default, this keymap makes the following bindings:
+
+    `?'
+          `minibuffer-completion-help'
+
+    <SPC>
+          `minibuffer-complete-word'
+
+    <TAB>
+          `minibuffer-complete'
+
+     with other characters bound as in `minibuffer-local-map' (*note
+     Text from Minibuffer::).
+
+ - Variable: minibuffer-local-must-match-map
+     `completing-read' uses this value as the local keymap when an
+     exact match of one of the completions is required.  Therefore, no
+     keys are bound to `exit-minibuffer', the command that exits the
+     minibuffer unconditionally.  By default, this keymap makes the
+     following bindings:
+
+    `?'
+          `minibuffer-completion-help'
+
+    <SPC>
+          `minibuffer-complete-word'
+
+    <TAB>
+          `minibuffer-complete'
+
+    `C-j'
+          `minibuffer-complete-and-exit'
+
+    <RET>
+          `minibuffer-complete-and-exit'
+
+     with other characters bound as in `minibuffer-local-map'.
+
+ - Variable: minibuffer-completion-table
+     The value of this variable is the alist or obarray used for
+     completion in the minibuffer.  This is the global variable that
+     contains what `completing-read' passes to `try-completion'.  It is
+     used by minibuffer completion commands such as
+     `minibuffer-complete-word'.
+
+ - Variable: minibuffer-completion-predicate
+     This variable's value is the predicate that `completing-read'
+     passes to `try-completion'.  The variable is also used by the other
+     minibuffer completion functions.
+
+ - Command: minibuffer-complete-word
+     This function completes the minibuffer contents by at most a single
+     word.  Even if the minibuffer contents have only one completion,
+     `minibuffer-complete-word' does not add any characters beyond the
+     first character that is not a word constituent.  *Note Syntax
+     Tables::.
+
+ - Command: minibuffer-complete
+     This function completes the minibuffer contents as far as possible.
+
+ - Command: minibuffer-complete-and-exit
+     This function completes the minibuffer contents, and exits if
+     confirmation is not required, i.e., if
+     `minibuffer-completion-confirm' is `nil'.  If confirmation _is_
+     required, it is given by repeating this command immediately--the
+     command is programmed to work without confirmation when run twice
+     in succession.
+
+ - Variable: minibuffer-completion-confirm
+     When the value of this variable is non-`nil', XEmacs asks for
+     confirmation of a completion before exiting the minibuffer.  The
+     function `minibuffer-complete-and-exit' checks the value of this
+     variable before it exits.
+
+ - Command: minibuffer-completion-help
+     This function creates a list of the possible completions of the
+     current minibuffer contents.  It works by calling `all-completions'
+     using the value of the variable `minibuffer-completion-table' as
+     the COLLECTION argument, and the value of
+     `minibuffer-completion-predicate' as the PREDICATE argument.  The
+     list of completions is displayed as text in a buffer named
+     `*Completions*'.
+
+ - Function: display-completion-list completions &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
+     normally a list of completions just returned by `all-completions',
+     but it does not have to be.  Each element may be a symbol or a
+     string, either of which is simply printed, or a list of two
+     strings, which is printed as if the strings were concatenated.
+
+     This function is called by `minibuffer-completion-help'.  The most
+     common way to use it is together with
+     `with-output-to-temp-buffer', like this:
+
+          (with-output-to-temp-buffer "*Completions*"
+            (display-completion-list
+              (all-completions (buffer-string) my-alist)))
+
+ - User Option: completion-auto-help
+     If this variable is non-`nil', the completion commands
+     automatically display a list of possible completions whenever
+     nothing can be completed because the next character is not
+     uniquely determined.
+
+\1f
 File: lispref.info,  Node: High-Level Completion,  Next: Reading File Names,  Prev: Completion Commands,  Up: Completion
 
 High-Level Completion  Functions
@@ -63,7 +181,7 @@ Lisp function.  When possible, do all minibuffer input as part of
 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
@@ -94,13 +212,19 @@ Defining Commands::.
           ;; The user types `minibuffer.t <RET>'.
                => "minibuffer.texi"
 
- - Function: read-command PROMPT
+ - 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
      `t', and a command name is a symbol for which `commandp' returns
      `t'.  *Note Interactive Call::.
 
+     The argument DEFAULT-VALUE specifies what to return if the user
+     enters null input.  It can be a symbol or a string; if it is a
+     string, `read-command' interns it before returning it.  If DEFAULT
+     is `nil', that means no default has been specified; then if the
+     user enters null input, the return value is `nil'.
+
           (read-command "Command name? ")
           
           ;; After evaluation of the preceding expression,
@@ -123,10 +247,16 @@ Defining Commands::.
           (intern (completing-read PROMPT obarray
                                    'commandp t nil))
 
- - Function: read-variable PROMPT
+ - Function: read-variable prompt &optional default-value
      This function reads the name of a user variable and returns it as a
      symbol.
 
+     The argument DEFAULT-VALUE specifies what to return if the user
+     enters null input.  It can be a symbol or a string; if it is a
+     string, `read-variable' interns it before returning it.  If DEFAULT
+     is `nil', that means no default has been specified; then if the
+     user enters null input, the return value is `nil'.
+
           (read-variable "Variable name? ")
           
           ;; After evaluation of the preceding expression,
@@ -159,8 +289,8 @@ Reading File Names
 a file name.  It provides special features including automatic insertion
 of the default directory.
 
- - Function: read-file-name PROMPT &optional DIRECTORY DEFAULT EXISTING
-          INITIAL
+ - 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>.
@@ -181,10 +311,10 @@ of the default directory.
      `default-directory'.
 
      If you specify INITIAL, that is an initial file name to insert in
-     the buffer (after with DIRECTORY, if that is inserted).  In this
-     case, point goes at the beginning of INITIAL.  The default for
-     INITIAL is `nil'--don't insert any file name.  To see what INITIAL
-     does, try the command `C-x C-v'.
+     the buffer (after DIRECTORY, if that is inserted).  In this case,
+     point goes at the beginning of INITIAL.  The default for INITIAL
+     is `nil'--don't insert any file name.  To see what INITIAL does,
+     try the command `C-x C-v'.
 
      Here is an example:
 
@@ -267,8 +397,12 @@ function do all the work.
 
    * `nil' specifies `try-completion'.  The completion function should
      return the completion of the specified string, or `t' if the
-     string is an exact match already, or `nil' if the string matches no
-     possibility.
+     string is a unique and exact match already, or `nil' if the string
+     matches no possibility.
+
+     If the string is an exact match for one possibility, but also
+     matches other longer possibilities, the function should return the
+     string, not `t'.
 
    * `t' specifies `all-completions'.  The completion function should
      return a list of all possible completions of the specified string.
@@ -309,7 +443,7 @@ question.  Otherwise, it uses keyboard input.
    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>
@@ -327,7 +461,7 @@ does not; but it seems best to describe them together.
 
      This function does not actually use the minibuffer, since it does
      not allow editing of the answer.  It actually uses the echo area
-     (*note The Echo Area::.), which uses the same screen space as the
+     (*note The Echo Area::), which uses the same screen space as the
      minibuffer.  The cursor moves to the echo area while the question
      is being asked.
 
@@ -342,18 +476,20 @@ does not; but it seems best to describe them together.
           
           ;; 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 ----------
@@ -361,7 +497,7 @@ does not; but it seems best to describe them together.
      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
@@ -382,7 +518,7 @@ does not; but it seems best to describe them together.
           ;; 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 ----------
@@ -396,7 +532,7 @@ does not; but it seems best to describe them together.
           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.
@@ -408,16 +544,16 @@ running on a window system, the functions `y-or-n-p' and `yes-or-no-p'
 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: Minibuffer Misc,  Prev: Yes-or-No Queries,  Up: Minibuffers
+File: lispref.info,  Node: Multiple Queries,  Next: Reading a Password,  Prev: Yes-or-No Queries,  Up: Minibuffers
 
 Asking Multiple Y-or-N Questions
 ================================
@@ -428,8 +564,8 @@ 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
-          ACTION-ALIST
+ - 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
      each one.
@@ -494,7 +630,7 @@ facilities such as the ability to answer the whole series at once.
 
      If `map-y-or-n-p' is called in a command that was invoked using the
      mouse--more precisely, if `last-nonmenu-event' (*note Command Loop
-     Info::.) is either `nil' or a list--then it uses a dialog box or
+     Info::) is either `nil' or a list--then it uses a dialog box or
      pop-up menu to ask the question.  In this case, it does not use
      keyboard input or the echo area.  You can force use of the mouse
      or use of keyboard input by binding `last-nonmenu-event' to a
@@ -504,7 +640,40 @@ facilities such as the ability to answer the whole series at once.
      on.
 
 \1f
-File: lispref.info,  Node: Minibuffer Misc,  Prev: Multiple Queries,  Up: Minibuffers
+File: lispref.info,  Node: Reading a Password,  Next: Minibuffer Misc,  Prev: Multiple Queries,  Up: Minibuffers
+
+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
+     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.
+
+     The optional argument CONFIRM, if non-`nil', says to read the
+     password twice and insist it must be the same both times.  If it
+     isn't the same, the user has to type it over and over until the
+     last two times match.
+
+     The optional argument DEFAULT specifies the default password to
+     return if the user enters empty input.  It is translated to `.'
+     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
+     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
+     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
 =====================
@@ -519,22 +688,22 @@ minibuffers.
  - 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::.).
+     *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).
@@ -558,20 +727,20 @@ minibuffers.
 
  - Variable: minibuffer-help-form
      The current value of this variable is used to rebind `help-form'
-     locally inside the minibuffer (*note Help Functions::.).
+     locally inside the minibuffer (*note Help Functions::).
 
  - 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 WINDOW
+ - Function: window-minibuffer-p window
      This function returns non-`nil' if WINDOW is a minibuffer window.
 
    It is not correct to determine whether a given window is a
@@ -579,7 +748,7 @@ minibuffer by comparing it with the result of `(minibuffer-window)',
 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.
 
@@ -589,7 +758,7 @@ than one frame.
      minibuffer, it scrolls this window.
 
    Finally, some functions and variables deal with recursive minibuffers
-(*note Recursive Editing::.):
+(*note Recursive Editing::):
 
  - Function: minibuffer-depth
      This function returns the current depth of activations of the
@@ -598,10 +767,10 @@ than one frame.
 
  - User Option: enable-recursive-minibuffers
      If this variable is non-`nil', you can invoke commands (such as
-     `find-file') that use minibuffers even while in the minibuffer
-     window.  Such invocation produces a recursive editing level for a
-     new minibuffer.  The outer-level minibuffer is invisible while you
-     are editing the inner one.
+     `find-file') that use minibuffers even while the minibuffer window
+     is active.  Such invocation produces a recursive editing level for
+     a new minibuffer.  The outer-level minibuffer is invisible while
+     you are editing the inner one.
 
      This variable only affects invoking the minibuffer while the
      minibuffer window is selected.   If you switch windows while in the
@@ -618,8 +787,7 @@ minibuffer.  The minibuffer command `next-matching-history-element'
 want to explicitly set the value of `enable-recursive-minibuffers' in
 this fashion, just use an evaluated interactive spec and bind
 `enable-recursive-minibuffers' while reading from the minibuffer.  See
-the definition of `next-matching-history-element' in
-`lisp/prim/minibuf.el'.
+the definition of `next-matching-history-element' in `lisp/minibuf.el'.
 
 \1f
 File: lispref.info,  Node: Command Loop,  Next: Keymaps,  Prev: Minibuffers,  Up: Top
@@ -641,7 +809,7 @@ are done, and the subroutines that allow Lisp programs to do them.
 * Events::             What input looks like when you read it.
 * Reading Input::       How to read input events from the keyboard or mouse.
 * Waiting::             Waiting for user input or elapsed time.
-* Quitting::            How `C-g' works.  How to catch or defer quitting.
+* Quitting::            How C-g works.  How to catch or defer quitting.
 * Prefix Command Arguments::    How the commands to set prefix args work.
 * Recursive Editing::   Entering a recursive edit,
                           and why you usually shouldn't.
@@ -675,14 +843,14 @@ Key Lookup::, for information on how this is done.  The result of the
 translation should be a keyboard macro or an interactively callable
 function.  If the key is `M-x', then it reads the name of another
 command, which it then calls.  This is done by the command
-`execute-extended-command' (*note Interactive Call::.).
+`execute-extended-command' (*note Interactive Call::).
 
    To execute a command requires first reading the arguments for it.
-This is done by calling `command-execute' (*note Interactive Call::.).
+This is done by calling `command-execute' (*note Interactive Call::).
 For commands written in Lisp, the `interactive' specification says how
 to read the arguments.  This may use the prefix argument (*note Prefix
-Command Arguments::.) or may read with prompting in the minibuffer
-(*note Minibuffers::.).  For example, the command `find-file' has an
+Command Arguments::) or may read with prompting in the minibuffer
+(*note Minibuffers::).  For example, the command `find-file' has an
 `interactive' specification which says to read a file name using the
 minibuffer.  The command's function body does not use the minibuffer;
 if you call this command from Lisp code as a function, you must supply
@@ -690,10 +858,10 @@ the file name string as an ordinary Lisp function argument.
 
    If the command is a string or vector (i.e., a keyboard macro) then
 `execute-kbd-macro' is used to execute it.  You can call this function
-yourself (*note Keyboard Macros::.).
+yourself (*note Keyboard Macros::).
 
    To terminate the execution of a running command, type `C-g'.  This
-character causes "quitting" (*note Quitting::.).
+character causes "quitting" (*note Quitting::).
 
  - Variable: pre-command-hook
      The editor command loop runs this normal hook before each command.
@@ -740,7 +908,7 @@ 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
@@ -775,7 +943,7 @@ makes a Lisp function an interactively-callable command.
      output; if subprocess output arrives while the command is waiting
      for input, it could relocate point and the mark.
 
-     Here's an example of what *not* to do:
+     Here's an example of what _not_ to do:
 
           (interactive
            (list (region-beginning) (region-end)
@@ -807,8 +975,8 @@ makes a Lisp function an interactively-callable command.
 
      The prompt string can use `%' to include previous argument values
      (starting with the first argument) in the prompt.  This is done
-     using `format' (*note Formatting Strings::.).  For example, here
-     is how you could read the name of an existing buffer followed by a
+     using `format' (*note Formatting Strings::).  For example, here is
+     how you could read the name of an existing buffer followed by a
      new name to give to that buffer:
 
           (interactive "bBuffer to rename: \nsRename buffer %s to: ")
@@ -831,7 +999,7 @@ makes a Lisp function an interactively-callable command.
      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
@@ -849,8 +1017,7 @@ defined here as follows:
 Completion
      Provide completion.  <TAB>, <SPC>, and <RET> perform name
      completion because the argument is read using `completing-read'
-     (*note Completion::.).  `?' displays a list of possible
-     completions.
+     (*note Completion::).  `?' displays a list of possible completions.
 
 Existing
      Require the name of an existing object.  An invalid name is not
@@ -898,7 +1065,7 @@ Special
 
 `b'
      The name of an existing buffer.  By default, uses the name of the
-     current buffer (*note Buffers::.).  Existing, Completion, Default,
+     current buffer (*note Buffers::).  Existing, Completion, Default,
      Prompt.
 
 `B'
@@ -914,12 +1081,12 @@ Special
      Completion, Prompt.
 
 `d'
-     The position of point, as an integer (*note Point::.).  No I/O.
+     The position of point, as an integer (*note Point::).  No I/O.
 
 `D'
      A directory name.  The default is the current default directory of
      the current buffer, `default-directory' (*note System
-     Environment::.).  Existing, Completion, Default, Prompt.
+     Environment::).  Existing, Completion, Default, Prompt.
 
 `e'
      The last mouse-button or misc-user event in the key sequence that
@@ -931,7 +1098,7 @@ Special
      such event.
 
 `f'
-     A file name of an existing file (*note File Names::.).  The default
+     A file name of an existing file (*note File Names::).  The default
      directory is `default-directory'.  Existing, Completion, Default,
      Prompt.
 
@@ -940,7 +1107,7 @@ Special
      Prompt.
 
 `k'
-     A key sequence (*note Keymap Terminology::.).  This keeps reading
+     A key sequence (*note Keymap Terminology::).  This keeps reading
      events until a command (or undefined command) is found in the
      current key maps.  The key sequence argument is represented as a
      vector of events.  The cursor does not move into the echo area.
@@ -983,7 +1150,7 @@ Special
 
 `s'
      Arbitrary text, read in the minibuffer and returned as a string
-     (*note Text from Minibuffer::.).  Terminate the input with either
+     (*note Text from Minibuffer::).  Terminate the input with either
      <LFD> or <RET>.  (`C-q' may be used to include either of these
      characters in the input.)  Prompt.
 
@@ -1047,128 +1214,3 @@ Examples of Using `interactive'
      (three-b "*scratch*" "declarations.texi" "*mail*")
           => nil
 
-\1f
-File: lispref.info,  Node: Interactive Call,  Next: Command Loop Info,  Prev: Defining Commands,  Up: Command Loop
-
-Interactive Call
-================
-
-   After the command loop has translated a key sequence into a
-definition, it invokes that definition using the function
-`command-execute'.  If the definition is a function that is a command,
-`command-execute' calls `call-interactively', which reads the arguments
-and calls the command.  You can also call these functions yourself.
-
- - Function: commandp OBJECT
-     Returns `t' if OBJECT is suitable for calling interactively; that
-     is, if OBJECT is a command.  Otherwise, returns `nil'.
-
-     The interactively callable objects include strings and vectors
-     (treated as keyboard macros), lambda expressions that contain a
-     top-level call to `interactive', compiled-function objects made
-     from such lambda expressions, autoload objects that are declared
-     as interactive (non-`nil' fourth argument to `autoload'), and some
-     of the primitive functions.
-
-     A symbol is `commandp' if its function definition is `commandp'.
-
-     Keys and keymaps are not commands.  Rather, they are used to look
-     up commands (*note Keymaps::.).
-
-     See `documentation' in *Note Accessing Documentation::, for a
-     realistic example of using `commandp'.
-
- - Function: call-interactively COMMAND &optional RECORD-FLAG
-     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
-     or if it cannot be called interactively (i.e., is not a command).
-     Note that keyboard macros (strings and vectors) are not accepted,
-     even though they are considered commands, because they are not
-     functions.
-
-     If RECORD-FLAG is the symbol `lambda', the interactive calling
-     arguments for `command' are read and returned as a list, but the
-     function is not called on them.
-
-     If RECORD-FLAG is `t', then this command and its arguments are
-     unconditionally added to the list `command-history'.  Otherwise,
-     the command is added only if it uses the minibuffer to read an
-     argument.  *Note Command History::.
-
- - Function: command-execute COMMAND &optional RECORD-FLAG
-     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.
-
-     A string or vector as COMMAND is executed with
-     `execute-kbd-macro'.  A function is passed to
-     `call-interactively', along with the optional RECORD-FLAG.
-
-     A symbol is handled by using its function definition in its place.
-     A symbol with an `autoload' definition counts as a command if it
-     was declared to stand for an interactively callable function.
-     Such a definition is handled by loading the specified library and
-     then rechecking the definition of the symbol.
-
- - 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
-     command returns becomes the value of `execute-extended-command'.
-
-     If the command asks for a prefix argument, it receives the value
-     PREFIX-ARGUMENT.  If `execute-extended-command' is called
-     interactively, the current raw prefix argument is used for
-     PREFIX-ARGUMENT, and thus passed on to whatever command is run.
-
-     `execute-extended-command' is the normal definition of `M-x', so
-     it uses the string `M-x ' as a prompt.  (It would be better to
-     take the prompt from the events used to invoke
-     `execute-extended-command', but that is painful to implement.)  A
-     description of the value of the prefix argument, if any, also
-     becomes part of the prompt.
-
-          (execute-extended-command 1)
-          ---------- Buffer: Minibuffer ----------
-          1 M-x forward-word RET
-          ---------- Buffer: Minibuffer ----------
-               => t
-
- - 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
-     `call-interactively' was called from Lisp or directly from the
-     editor command loop.)  If the containing function was called by
-     Lisp evaluation (or with `apply' or `funcall'), then it was not
-     called interactively.
-
-     The most common use of `interactive-p' is for deciding whether to
-     print an informative message.  As a special exception,
-     `interactive-p' returns `nil' whenever a keyboard macro is being
-     run.  This is to suppress the informative messages and speed
-     execution of the macro.
-
-     For example:
-
-          (defun foo ()
-            (interactive)
-            (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)
-