home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / prgramer / unix / info / elisp.i11 < prev    next >
Encoding:
GNU Info File  |  1993-06-14  |  50.4 KB  |  1,199 lines
  1. This is Info file elisp, produced by Makeinfo-1.47 from the input file
  2. elisp.texi.
  3.  
  4.    This file documents GNU Emacs Lisp.
  5.  
  6.    This is edition 1.03 of the GNU Emacs Lisp Reference Manual, for
  7. Emacs Version 18.
  8.  
  9.    Published by the Free Software Foundation, 675 Massachusetts Avenue,
  10. Cambridge, MA 02139 USA
  11.  
  12.    Copyright (C) 1990 Free Software Foundation, Inc.
  13.  
  14.    Permission is granted to make and distribute verbatim copies of this
  15. manual provided the copyright notice and this permission notice are
  16. preserved on all copies.
  17.  
  18.    Permission is granted to copy and distribute modified versions of
  19. this manual under the conditions for verbatim copying, provided that
  20. the entire resulting derived work is distributed under the terms of a
  21. permission notice identical to this one.
  22.  
  23.    Permission is granted to copy and distribute translations of this
  24. manual into another language, under the above conditions for modified
  25. versions, except that this permission notice may be stated in a
  26. translation approved by the Foundation.
  27.  
  28. 
  29. File: elisp,  Node: Using Interactive,  Next: Interactive Codes,  Prev: Defining Commands,  Up: Defining Commands
  30.  
  31. Using `interactive'
  32. -------------------
  33.  
  34.    This section describes how to write the `interactive' form that
  35. makes a Lisp function an interactively-callable command.
  36.  
  37.  -- Special Form: interactive ARG-DESCRIPTOR
  38.      This special form declares that the function in which it appears
  39.      is a command, and that it may therefore be called interactively
  40.      (via `M-x' or by entering a key sequence bound to it).  The
  41.      argument ARG-DESCRIPTOR declares the way the arguments to the
  42.      command are to be computed when the command is called
  43.      interactively.
  44.  
  45.      A command may be called from Lisp programs like any other
  46.      function, but then the arguments are supplied by the caller and
  47.      ARG-DESCRIPTOR has no effect.
  48.  
  49.      The `interactive' form has its effect because the command loop
  50.      (actually, its subroutine `call-interactively') scans through the
  51.      function definition looking for it, before calling the function. 
  52.      Once the function is called, all its body forms including the
  53.      `interactive' form are executed, but at this time `interactive'
  54.      simply returns `nil' without even evaluating its argument.
  55.  
  56.    There are three possibilities for the argument ARG-DESCRIPTOR:
  57.  
  58.    * It may be omitted or `nil'; then the command is called with no
  59.      arguments.  This leads quickly to an error if the command requires
  60.      one or more arguments.
  61.  
  62.    * It may be a Lisp expression that is not a string; then it should
  63.      be a form that is evaluated to get a list of arguments to pass to
  64.      the command.
  65.  
  66.    * It may be a string; then its contents should consist of a code
  67.      character followed by a prompt (if required for that code
  68.      character).  The prompt ends either with the end of the string or
  69.      with a newline.  Here is a simple example:
  70.  
  71.           (interactive "bFrobnicate buffer: ")
  72.  
  73.      The code letter `b' says to read the name of an existing buffer,
  74.      with completion.  The buffer name will be the sole argument passed
  75.      to the command.  The rest of the string is a prompt.
  76.  
  77.      If there is a newline character in the string, it terminates the
  78.      prompt. If the string does not end there, then the rest of the
  79.      string should contain another code character and prompt,
  80.      specifying another argument. Any number of arguments may be
  81.      specified in this way.
  82.  
  83.      If the first character in the string is `*', then an error is
  84.      signaled if the buffer is read-only.  Otherwise, the following
  85.      character is the first code character.
  86.  
  87. 
  88. File: elisp,  Node: Interactive Codes,  Next: Interactive Examples,  Prev: Using Interactive,  Up: Defining Commands
  89.  
  90. Code Characters for `interactive'
  91. ---------------------------------
  92.  
  93.    The code character descriptions below contain a number of key words,
  94. defined here as follows:
  95.  
  96. Completion
  97.      Provide completion.  TAB, SPC, and RET perform name completion
  98.      because the argument is read using `completing-read' (*note
  99.      Completion::.).  `?' displays a list of possible completions.
  100.  
  101. Existing
  102.      Require the name of an existing object.  An invalid name is not
  103.      accepted; the commands to exit the minibuffer do not exit if the
  104.      current input is not valid.
  105.  
  106. Default
  107.      A default value of some sort is used if the user enters no text in
  108.      the minibuffer.  The default depends on the code character.
  109.  
  110. Prompt
  111.      A prompt immediately follows the code character.  The prompt ends
  112.      either with the end of the string or with a newline.
  113.  
  114. No I/O
  115.      This code letter computes an argument without reading any input.
  116.      Therefore, it does not use a prompt string, and any prompt string
  117.      you supply is ignored.
  118.  
  119.    Here are the code character descriptions for use with `interactive':
  120.  
  121. `a'
  122.      A function name (i.e., a symbol which is `fboundp').  Existing,
  123.      Completion, Prompt.
  124.  
  125. `b'
  126.      The name of an existing buffer.  By default, uses the name of the
  127.      current buffer (*note Buffers::.).  Existing, Completion, Default,
  128.      Prompt.
  129.  
  130. `B'
  131.      A buffer name.  The buffer need not exist.  By default, uses the
  132.      name of a recently used buffer other than the current buffer. 
  133.      Completion, Prompt.
  134.  
  135. `c'
  136.      A character.  The cursor does not move into the echo area.  Prompt.
  137.  
  138. `C'
  139.      A command name (i.e., a symbol satisfying `commandp').  Existing,
  140.      Completion, Prompt.
  141.  
  142. `d'
  143.      The position of point as a number (*note Point::.).  No I/O.
  144.  
  145. `D'
  146.      A directory name.  The default is the current default directory of
  147.      the current buffer, `default-directory' (*note System
  148.      Environment::.). Existing, Completion, Default, Prompt.
  149.  
  150. `f'
  151.      A file name of an existing file (*note File Names::.).  The default
  152.      directory is `default-directory'.  Existing, Completion, Default,
  153.      Prompt.
  154.  
  155. `F'
  156.      A file name.  The file need not exist.  Completion, Default,
  157.      Prompt.
  158.  
  159. `k'
  160.      A key sequence (*note Keymap Terms::.).  This keeps reading
  161.      characters until a command (or undefined command) is found in the
  162.      current key maps. The key sequence argument is represented as a
  163.      string.  The cursor does not move into the echo area.  Prompt.
  164.  
  165.      This kind of input is used by commands such as `describe-key' and
  166.      `global-set-key'.
  167.  
  168. `m'
  169.      The position of the mark as a number.  No I/O.
  170.  
  171. `n'
  172.      A number read with the minibuffer.  If the input is not a number,
  173.      the user is asked to try again.  The prefix argument, if any, is
  174.      not used. Prompt.
  175.  
  176. `N'
  177.      The raw prefix argument.  If the prefix argument is `nil', then a
  178.      number is read as with `n'.  Requires a number.  Prompt.
  179.  
  180. `p'
  181.      The numeric prefix argument.  (Note that this `p' is lower case.)
  182.      No I/O.
  183.  
  184. `P'
  185.      The raw prefix argument.  (Note that this `P' is upper case.)
  186.      *Note Prefix Command Arguments::.  No I/O.
  187.  
  188. `r'
  189.      Point and the mark, as two numeric arguments, smallest first. 
  190.      This is the only code letter that specifies two successive
  191.      arguments rather than one.  No I/O.
  192.  
  193. `s'
  194.      Arbitrary text, read in the minibuffer and returned as a string
  195.      (*note Text from Minibuffer::.).  Terminate the input with either
  196.      LFD or RET.  (`C-q' may be used to include either of these
  197.      characters in the input.)  Prompt.
  198.  
  199. `S'
  200.      An interned symbol whose name is read in the minibuffer.  Any
  201.      whitespace character terminates the input.  (Use `C-q' to include
  202.      whitespace in the string.)  Other characters that normally
  203.      terminate a symbol (e.g., parentheses and brackets) do not do so
  204.      here.  Prompt.
  205.  
  206. `v'
  207.      A variable declared to be a user option (i.e., satisfying
  208.      `user-variable-p').  *Note High-Level Completion::.  Existing,
  209.      Completion, Prompt.
  210.  
  211. `x'
  212.      A Lisp object specified in printed representation, terminated with
  213.      a LFD or RET.  The object is not evaluated.  *Note Object from
  214.      Minibuffer::.  Prompt.
  215.  
  216. `X'
  217.      A Lisp form is read as with `x', but then evaluated so that its
  218.      value becomes the argument for the command.  Prompt.
  219.  
  220. 
  221. File: elisp,  Node: Interactive Examples,  Prev: Interactive Codes,  Up: Defining Commands
  222.  
  223. Examples of Using `interactive'
  224. -------------------------------
  225.  
  226.    Here are some examples of `interactive':
  227.  
  228.      (defun foo1 ()                ; `foo1' takes no arguments,
  229.          (interactive)             ; just moves forward two words.
  230.          (forward-word 2))
  231.           => foo1
  232.      
  233.      (defun foo2 (n)               ; `foo2' takes one argument,
  234.          (interactive "p")         ; which is the numeric prefix.
  235.          (forward-word (* 2 n)))
  236.           => foo2
  237.      
  238.      (defun foo3 (n)               ; `foo3' takes one argument,
  239.          (interactive "nCount:")   ; which is read with the Minibuffer.
  240.          (forward-word (* 2 n)))
  241.           => foo3
  242.      
  243.      (defun three-b (b1 b2 b3)
  244.        "Select three existing buffers (prompting for them in
  245.      the Minibuffer).  Put them into three windows, selecting the
  246.      last one."
  247.          (interactive "bBuffer1:\nbBuffer2:\nbBuffer3:")
  248.          (delete-other-windows)
  249.          (split-window (selected-window) 8)
  250.          (switch-to-buffer b1)
  251.          (other-window 1)
  252.          (split-window (selected-window) 8)
  253.          (switch-to-buffer b2)
  254.          (other-window 1)
  255.          (switch-to-buffer b3))
  256.           => three-b
  257.      (three-b "*scratch*" "declarations.texi" "*mail*")
  258.           => nil
  259.  
  260. 
  261. File: elisp,  Node: Interactive Call,  Next: Command Loop Info,  Prev: Defining Commands,  Up: Command Loop
  262.  
  263. Interactive Call
  264. ================
  265.  
  266.    After the command loop has translated a key sequence into a
  267. definition, it invokes that definition using the function
  268. `command-execute'.  If the definition is a function that is a command,
  269. `command-execute' calls `call-interactively', which reads the arguments
  270. and calls the command.  You can also call these functions yourself.
  271.  
  272.  -- Function: commandp OBJECT
  273.      Returns `t' if OBJECT is suitable for calling interactively; that
  274.      is, if OBJECT is a command.  Otherwise, returns `nil'.
  275.  
  276.      The interactively callable objects include strings (treated as
  277.      keyboard macros), lambda expressions that contain a top-level call
  278.      to `interactive', autoload objects that are declared as interactive
  279.      (non-`nil' fourth argument to `autoload'), and some of the
  280.      primitive functions.
  281.  
  282.      A symbol is `commandp' if its function definition is `commandp'.
  283.  
  284.      Keys and keymaps are not commands.  Rather, they are used to look
  285.      up commands (*note Keymaps::.).
  286.  
  287.      See `documentation' in *Note Accessing Documentation::, for a
  288.      realistic example of using `commandp'.
  289.  
  290.  -- Function: call-interactively COMMAND &optional RECORD-FLAG
  291.      This function calls the interactively callable function COMMAND,
  292.      reading arguments according to its interactive calling
  293.      specifications. An error is signaled if COMMAND cannot be called
  294.      interactively (i.e., it is not a command).  Note that strings are
  295.      not accepted, even though they are considered commands.
  296.  
  297.      If RECORD-FLAG is non-`nil', then this command and its arguments
  298.      are unconditionally added to the list `command-history'.
  299.      Otherwise, the command is added only if it uses the minibuffer to
  300.      read an argument.  *Note Command History::.
  301.  
  302.  -- Function: command-execute COMMAND &optional RECORD-FLAG
  303.      This function executes COMMAND as an editing command.  The
  304.      argument COMMAND must satisfy the `commandp' predicate; i.e., it
  305.      must be an interactively callable function or a string.
  306.  
  307.      A string as COMMAND is executed with `execute-kbd-macro'.  A
  308.      function is passed to `call-interactively', along with the optional
  309.      RECORD-FLAG.
  310.  
  311.      A symbol is handled by using its function definition in its place.
  312.       A symbol with an `autoload' definition counts as a command if it
  313.      was declared to stand for an interactively callable function. 
  314.      Such a definition is handled by loading the specified library and
  315.      then rechecking the definition of the symbol.
  316.  
  317.  -- Command: execute-extended-command PREFIX-ARGUMENT
  318.      This primitive function reads a command name from the minibuffer
  319.      using `completing-read' (*note Completion::.).  Then it uses
  320.      `command-execute' to call the specified command.  Whatever that
  321.      command returns becomes the value of `execute-extended-command'.
  322.  
  323.      If the command asks for a prefix argument, the value
  324.      PREFIX-ARGUMENT is supplied.  If `execute-extended-command' is
  325.      called interactively, the current raw prefix argument is used for
  326.      PREFIX-ARGUMENT, and thus passed on to whatever command is run.
  327.  
  328.      `execute-extended-command' is the normal definition of `M-x', so
  329.      it uses the string `M-x ' as a prompt.  (It would be better to
  330.      take the prompt from the characters used to invoke
  331.      `execute-extended-command', but that is painful to implement.)  A
  332.      description of the value of the prefix argument, if any, also
  333.      becomes part of the prompt.
  334.  
  335.           (execute-extended-command 1)
  336.           ---------- Buffer: Minibuffer ----------
  337.           M-x forward-word RET
  338.           ---------- Buffer: Minibuffer ----------
  339.                => t
  340.  
  341.  -- Function: interactive-p
  342.      This function returns `t' if the containing function (the one that
  343.      called `interactive-p') was called interactively, with
  344.      `call-interactively'.  (It makes no difference whether
  345.      `call-interactively' was called from Lisp or directly from the
  346.      editor command loop.)  Note that if the containing function was
  347.      called by Lisp evaluation (or with `apply' or `funcall'), then it
  348.      was not called interactively.
  349.  
  350.      The usual application of `interactive-p' is for deciding whether to
  351.      print an informative message.  As a special exception,
  352.      `interactive-p' returns `nil' whenever a keyboard macro is being
  353.      run.  This is to suppress the informative messages and speed
  354.      execution of the macro.
  355.  
  356.      For example:
  357.  
  358.           (defun foo ()
  359.             (interactive)
  360.             (and (interactive-p)
  361.                  (message "foo")))
  362.                => foo
  363.           
  364.           (defun bar ()
  365.             (interactive)
  366.             (setq foobar (list (foo) (interactive-p))))
  367.                => bar
  368.           
  369.           ;; Type `M-x foo'.
  370.                -| foo
  371.           
  372.           ;; Type `M-x bar'.
  373.           ;; This does not print anything.
  374.           
  375.           foobar
  376.                => (nil t)
  377.  
  378. 
  379. File: elisp,  Node: Command Loop Info,  Next: Keyboard Input,  Prev: Interactive Call,  Up: Command Loop
  380.  
  381. Information from the Command Loop
  382. =================================
  383.  
  384.    The editor command loop sets several Lisp variables to keep status
  385. records for itself and for commands that are run.
  386.  
  387.  -- Variable: last-command
  388.      This variable records the name of the previous command executed by
  389.      the command loop (the one before the current command).  Normally
  390.      the value is a symbol with a function definition, but this is not
  391.      guaranteed.
  392.  
  393.      The value is set by copying the value of `this-command' when a
  394.      command returns to the command loop, except when the command
  395.      specifies a prefix argument for the following command.
  396.  
  397.  -- Variable: this-command
  398.      This variable records the name of the command now being executed by
  399.      editor command loop.  Like `last-command', it is normally a symbol
  400.      with a function definition.
  401.  
  402.      This variable is set by the command loop just before the command
  403.      is run, and its value is copied into `last-command' when the
  404.      command finishes (unless the command specifies a prefix argument
  405.      for the following command).
  406.  
  407.      Some commands change the value of this variable during their
  408.      execution, simply as a flag for whatever command runs next.  In
  409.      particular, the functions that kill text set `this-command' to
  410.      `kill-region' so that any kill commands immediately following will
  411.      know to append the killed text to the previous kill.
  412.  
  413.  -- Function: this-command-keys
  414.      This function returns a string containing the key sequence that
  415.      invoked the present command, plus any previous commands that
  416.      generated the prefix argument for this command.
  417.  
  418.           (this-command-keys) ;; Now type `C-u C-x C-e'.
  419.                => "^U^X^E"
  420.  
  421.  -- Variable: last-command-char
  422.      This variable is set to the last character that was typed on the
  423.      terminal and was part of a command.  The principal use of this
  424.      variable is in `self-insert-command', which uses it to decide which
  425.      character to insert.
  426.  
  427.           last-command-char ;; Now type `C-u C-x C-e'.
  428.                => 5
  429.  
  430.      The value is 5 because that is the ASCII code for `C-e'.
  431.  
  432.  -- Variable: echo-keystrokes
  433.      This variable determines how much time should elapse before command
  434.      characters are echoed.  Its value must be an integer, which
  435.      specifies the number of seconds to wait before echoing.  If the
  436.      user types a prefix key (say `C-x') and then delays this many
  437.      seconds before continuing, the key `C-x' is echoed in the echo
  438.      area.  Any subsequent characters in the same command will be
  439.      echoed as well.
  440.  
  441.      If the value is zero, then command input is not echoed.
  442.  
  443. 
  444. File: elisp,  Node: Keyboard Input,  Next: Quitting,  Prev: Command Loop Info,  Up: Command Loop
  445.  
  446. Keyboard Input
  447. ==============
  448.  
  449.    The editor command loop reads keyboard input using
  450. `read-key-sequence', which uses `read-char'.  These and other functions
  451. for keyboard input are also available for use in Lisp programs.  See
  452. also `momentary-string-display' in *Note Temporary Displays::, and
  453. `sit-for' in *Note Waiting::.  *Note Terminal Input::, for functions
  454. and variables for controlling terminal input modes and debugging
  455. terminal input.
  456.  
  457.  -- Function: read-char
  458.      This function reads a character from the command input (either from
  459.      direct keyboard input or from an executing keyboard macro), and
  460.      returns it.
  461.  
  462.      No message is displayed to indicate that keyboard input is
  463.      expected.  If you want to display a message, call `message' first.
  464.       If `cursor-in-echo-area' is non-`nil', then the cursor moves to
  465.      the echo area, to the end of any message displayed there. 
  466.      Otherwise the cursor does not move.  *Note The Echo Area::.
  467.  
  468.      In the first example, the user types `1' (which is ASCII code 49).
  469.       The second example shows a keyboard macro definition that calls
  470.      `read-char' from the minibuffer.  `read-char' reads the keyboard
  471.      macro's very next character, which is `1'.  The value of this
  472.      function is displayed in the echo area by the command
  473.      `eval-expression'.
  474.  
  475.           (read-char)
  476.                => 49
  477.           
  478.           (symbol-function 'foo)
  479.                => "^[^[(read-char)^M1"
  480.           (execute-kbd-macro foo)
  481.                -| 49
  482.                => nil
  483.  
  484.  -- Function: read-quoted-char &optional PROMPT
  485.      This function is like `read-char', except that if the first
  486.      character read is an octal digit (0-7), it reads up to two more
  487.      octal digits (but stopping if a non-octal digit is found) and
  488.      returns the character represented by those digits as an octal
  489.      number.
  490.  
  491.      Quitting is suppressed when the first character is read, so that
  492.      the user can enter a `C-g'.  *Note Quitting::.
  493.  
  494.      If PROMPT is supplied, it specifies a string for prompting the
  495.      user.  The prompt string is always printed in the echo area and
  496.      followed by a single `-'.
  497.  
  498.      In the following example, the user types in the octal number 177
  499.      (which is 127 in decimal).
  500.  
  501.           (read-quoted-char "What character")
  502.           
  503.           ---------- Echo Area ----------
  504.           What character-`177'
  505.           ---------- Echo Area ----------
  506.           
  507.                => 127
  508.  
  509.  -- Function: read-key-sequence PROMPT
  510.      This function reads a key sequence and returns it as a string.  It
  511.      keeps reading characters until it has accumulated a full key
  512.      sequence; that is, enough characters to specify a non-prefix
  513.      command using the current local and global keymaps. 
  514.      `read-key-sequence' is used by the command loop to read command
  515.      input.
  516.  
  517.      If an input character is an upper case letter and has no
  518.      definition, but the lower case equivalent is defined, then the
  519.      character is converted to lower case.  Note that `lookup-key' does
  520.      not perform case conversion in this way.
  521.  
  522.      Quitting is suppressed inside `read-key-sequence'.  In other words,
  523.      a `C-g' typed while reading with this function is treated like any
  524.      other character, and `quit-flag' is not set.  *Note Quitting::.
  525.  
  526.      The argument PROMPT is either a string to be displayed in the echo
  527.      area as a prompt, or `nil', meaning that no prompt is displayed.
  528.  
  529.      In the example below, the prompt `?' is displayed in the echo area,
  530.      and the user types `C-x C-f'.
  531.  
  532.           (read-key-sequence "?")
  533.           
  534.           ---------- Echo Area ----------
  535.           ?`C-x C-f'
  536.           ---------- Echo Area ----------
  537.           
  538.                => "^X^F"
  539.  
  540.  -- Variable: unread-command-char
  541.      This variable holds a character waiting to be read as the next
  542.      input from the command input stream, or to the integer -1 if no
  543.      character is waiting.  The variable is used because in some cases
  544.      an input function reads a character and then decides not to use it.
  545.      Storing the character in this variable causes it to be processed
  546.      normally by the command loop or when `read-char' is next called.
  547.  
  548.      For example, the function that governs prefix arguments reads any
  549.      number of digits.  When it finds a non-digit character, it must
  550.      unread the character so that it becomes input for the next
  551.      command.  Likewise, incremental search uses this feature to unread
  552.      a control character used to terminate the search.
  553.  
  554.  -- Function: input-pending-p
  555.      This function determines whether command input is currently
  556.      available. It returns immediately, with value `t' if there is
  557.      input, `nil' otherwise.  On rare occasions it may return `t' when
  558.      no input is available.
  559.  
  560.  -- Variable: last-input-char
  561.      This variable records the last terminal input character read,
  562.      whether as part of a command or explicitly by a Lisp program.
  563.  
  564.      In the example below, a character is read (the character `1',
  565.      ASCII code 49).  It becomes the value of `last-input-char', while
  566.      `C-e' (from the `C-x C-e' command used to evaluate this
  567.      expression) remains the value of `last-command-char'.
  568.  
  569.           (progn (print (read-char))
  570.                  (print last-command-char)
  571.                  last-input-char)
  572.                -| 49
  573.                -| 5
  574.                => 49
  575.  
  576.  -- Function: discard-input
  577.      This function discards the contents of the terminal input buffer
  578.      and cancels any keyboard macro that might be in the process of
  579.      definition. It returns `nil'.
  580.  
  581.      In the following example, the user may type a number of characters
  582.      right after starting the evaluation of the form.  After the
  583.      `sleep-for' finishes sleeping, any characters that have been typed
  584.      are discarded.
  585.  
  586.           (progn (sleep-for 2)
  587.             (discard-input))
  588.                => nil
  589.  
  590. 
  591. File: elisp,  Node: Quitting,  Next: Prefix Command Arguments,  Prev: Keyboard Input,  Up: Command Loop
  592.  
  593. Quitting
  594. ========
  595.  
  596.    Typing `C-g' while the command loop has run a Lisp function causes
  597. Emacs to "quit" whatever it is doing.  This means that control returns
  598. to the innermost active command loop.
  599.  
  600.    Typing `C-g' while the command loop is waiting for keyboard input
  601. does not cause a quit; it acts as an ordinary input character.  In the
  602. simplest case, you cannot tell the difference, because `C-g' normally
  603. runs the command `keyboard-quit', whose effect is to quit. However,
  604. when `C-g' follows a prefix key, the result is an undefined key.  The
  605. effect is to cancel the prefix key as well as any prefix argument.
  606.  
  607.    In the minibuffer, `C-g' has a different definition: it aborts out
  608. of the minibuffer.  This means, in effect, that it exits the minibuffer
  609. and then quits.  (Simply quitting would return to the command loop
  610. *within* the minibuffer.)  The reason why `C-g' does not quit directly
  611. when the command reader is reading input is so that its meaning can be
  612. redefined in the minibuffer in this way.  `C-g' following a prefix key
  613. is not redefined in the minibuffer, and it has its normal effect of
  614. canceling the prefix key and prefix argument.  This too would not be
  615. possible if `C-g' quit directly.
  616.  
  617.    `C-g' causes a quit by setting the variable `quit-flag' to a
  618. non-`nil' value.  Emacs checks this variable at appropriate times and
  619. quits if it is not `nil'.  Setting `quit-flag' non-`nil' in any way
  620. thus causes a quit.
  621.  
  622.    At the level of C code, quits cannot happen just anywhere; only at
  623. the special places which check `quit-flag'.  The reason for this is
  624. that quitting at other places might leave an inconsistency in Emacs's
  625. internal state.  Because quitting is delayed until a safe place,
  626. quitting cannot make Emacs crash.
  627.  
  628.    Certain functions such as `read-key-sequence' or `read-quoted-char'
  629. prevent quitting entirely even though they wait for input.  Instead of
  630. quitting, `C-g' serves as the requested input.  In the case of
  631. `read-key-sequence', this serves to bring about the special behavior of
  632. `C-g' in the command loop.  In the case of `read-quoted-char', this is
  633. so that `C-q' can be used to quote a `C-g'.
  634.  
  635.    You can prevent quitting for a portion of a Lisp function by binding
  636. the variable `inhibit-quit' to a non-`nil' value.  Then, although `C-g'
  637. still sets `quit-flag' to `t' as usual, the usual result of this--a
  638. quit--is prevented.  Eventually, `inhibit-quit' will become `nil'
  639. again, such as when its binding is unwound at the end of a `let' form. 
  640. At that time, if `quit-flag' is still non-`nil', the requested quit
  641. happens immediately.  This behavior is ideal for a "critical section",
  642. where you wish to make sure that quitting does not happen within that
  643. part of the program.
  644.  
  645.    In some functions (such as `read-quoted-char'), `C-g' is handled in
  646. a special way which does not involve quitting.  This is done by reading
  647. the input with `inhibit-quit' bound to `t' and setting `quit-flag' to
  648. `nil' before `inhibit-quit' becomes `nil' again.  This excerpt from the
  649. definition of `read-quoted-char' shows how this is done; it also shows
  650. that normal quitting is permitted after the first character of input.
  651.  
  652.      (defun read-quoted-char (&optional prompt)
  653.        "...DOCUMENTATION..."
  654.        (let ((count 0) (code 0) char)
  655.          (while (< count 3)
  656.            (let ((inhibit-quit (zerop count))
  657.                  (help-form nil))
  658.              (and prompt (message "%s-" prompt))
  659.              (setq char (read-char))
  660.              (if inhibit-quit (setq quit-flag nil)))
  661.            ...)
  662.          (logand 255 code)))
  663.  
  664.  -- Variable: quit-flag
  665.      If this variable is non-`nil', then Emacs quits immediately,
  666.      unless `inhibit-quit' is non-`nil'.  Typing `C-g' sets `quit-flag'
  667.      non-`nil', regardless of `inhibit-quit'.
  668.  
  669.  -- Variable: inhibit-quit
  670.      This variable determines whether Emacs should quit when `quit-flag'
  671.      is set to a value other than `nil'.  If `inhibit-quit' is
  672.      non-`nil', then `quit-flag' has no special effect.
  673.  
  674.  -- Command: keyboard-quit
  675.      This function signals the `quit' condition with `(signal 'quit
  676.      nil)'.  This is the same thing that quitting does.  (See `signal'
  677.      in *Note Errors::.)
  678.  
  679.    You can specify a character other than `C-g' to use for quitting.
  680. See the function `set-input-mode' in *Note Terminal Input::.
  681.  
  682. 
  683. File: elisp,  Node: Prefix Command Arguments,  Next: Recursive Editing,  Prev: Quitting,  Up: Command Loop
  684.  
  685. Prefix Command Arguments
  686. ========================
  687.  
  688.    Most Emacs commands can use a "prefix argument", a number specified
  689. before the command itself.  (Don't confuse prefix arguments with prefix
  690. keys.)  The prefix argument is represented by a value that is always
  691. available (though it may be `nil', meaning there is no prefix
  692. argument).  Each command may use the prefix argument or ignore it.
  693.  
  694.    There are two representations of the prefix argument: "raw" and
  695. "numeric".  The editor command loop uses the raw representation
  696. internally, and so do the Lisp variables that store the information, but
  697. commands can request either representation.
  698.  
  699.    Here are the possible values of a raw prefix argument:
  700.  
  701.    * `nil', meaning there is no prefix argument.  Its numeric value is
  702.      1, but numerous commands make a distinction between `nil' and the
  703.      integer 1.
  704.  
  705.    * An integer, which stands for itself.
  706.  
  707.    * A list of one element, which is an integer.  This form of prefix
  708.      argument results from one or a succession of `C-u''s with no
  709.      digits.  The numeric value is the integer in the list, but some
  710.      commands make a distinction between such a list and an integer
  711.      alone.
  712.  
  713.    * The symbol `-'.  This indicates that `M--' or `C-u -' was typed,
  714.      without following digits.  The equivalent numeric value is -1, but
  715.      some commands make a distinction between the integer -1 and the
  716.      symbol `-'.
  717.  
  718.    The various possibilities may be illustrated by calling the following
  719. function with various prefixes:
  720.  
  721.      (defun print-prefix (arg)
  722.        "Print the value of the raw prefix arg at point."
  723.        (interactive "P")
  724.        (message "%s" arg))
  725.  
  726. Here are the results of calling `print-prefix' with various raw prefix
  727. arguments:
  728.  
  729.              M-x print-prefix  -| nil
  730.      
  731.      C-u     M-x print-prefix  -| (4)
  732.      
  733.      C-u C-u M-x print-prefix  -| (16)
  734.      
  735.      C-u 3   M-x print-prefix  -| 3
  736.      
  737.      M-3     M-x print-prefix  -| 3      ; (Same as `C-u 3'.)
  738.      
  739.      C-u -   M-x print-prefix  -| -
  740.      
  741.      M- -    M-x print-prefix  -| -      ; (Same as `C-u -'.)
  742.      
  743.      C-u -7  M-x print-prefix  -| -7
  744.      
  745.      M- -7   M-x print-prefix  -| -7     ; (Same as `C-u -7'.)
  746.  
  747.    There are two variables used to store the prefix argument:
  748. `prefix-arg' and `current-prefix-arg'.  Commands such as
  749. `universal-argument' that set up prefix arguments for other commands
  750. store them in `prefix-arg'.  In contrast, `current-prefix-arg' conveys
  751. the prefix argument to the current command, so setting it has no effect
  752. on the prefix arguments for future commands.
  753.  
  754.    Normally, commands specify which representation to use for the prefix
  755. argument, either numeric or raw, in the `interactive' declaration.
  756. (*Note Interactive Call::.)  Alternatively, functions may look at the
  757. value of the prefix argument directly in the variable
  758. `current-prefix-arg', but this is less clean.
  759.  
  760.    Don't call `universal-argument', `digit-argument', or
  761. `negative-argument' unless you intend to let the user enter the prefix
  762. argument for the *next* command.
  763.  
  764.  -- Command: universal-argument
  765.      This command reads input and specifies a prefix argument for the
  766.      following command.  Don't call this command yourself unless you
  767.      know what you are doing.
  768.  
  769.  -- Command: digit-argument ARG
  770.      This command adds to the prefix argument for the following
  771.      command.  The argument ARG is the raw prefix argument as it was
  772.      before this command; it is used to compute the updated prefix
  773.      argument.  Don't call this command yourself unless you know what
  774.      you are doing.
  775.  
  776.  -- Command: negative-argument ARG
  777.      This command adds to the numeric argument for the next command. 
  778.      The argument ARG is the raw prefix argument as it was before this
  779.      command; its value is negated to form the new prefix argument. 
  780.      Don't call this command yourself unless you know what you are
  781.      doing.
  782.  
  783.  -- Function: prefix-numeric-value ARG
  784.      This function returns the numeric meaning of a valid raw prefix
  785.      argument value, ARG.  The argument may be a symbol, a number, or a
  786.      list. If it is `nil', the value 1 is returned; if it is any other
  787.      symbol, the value -1 is returned.  If it is a number, that number
  788.      is returned; if it is a list, the CAR of that list (which should
  789.      be a number) is returned.
  790.  
  791.  -- Variable: current-prefix-arg
  792.      This variable is the value of the raw prefix argument for the
  793.      *current* command.  Commands may examine it directly, but the usual
  794.      way to access it is with `(interactive "P")'.
  795.  
  796.  -- Variable: prefix-arg
  797.      The value of this variable is the raw prefix argument for the
  798.      *next* editing command.  Commands that specify prefix arguments for
  799.      the following command work by setting this variable.
  800.  
  801. 
  802. File: elisp,  Node: Recursive Editing,  Next: Disabling Commands,  Prev: Prefix Command Arguments,  Up: Command Loop
  803.  
  804. Recursive Editing
  805. =================
  806.  
  807.    The Emacs command loop is entered automatically when Emacs starts up.
  808. This top-level invocation of the command loop is never exited until the
  809. Emacs is killed.  Lisp programs can also invoke the command loop.  Since
  810. this makes more than one activation of the command loop, we call it
  811. "recursive editing".  A recursive editing level has the effect of
  812. suspending whatever command invoked it and permitting the user to do
  813. arbitrary editing before resuming that command.
  814.  
  815.    The commands available during recursive editing are the same ones
  816. available in the top-level editing loop and defined in the keymaps.
  817. Only a few special commands exit the recursive editing level; the others
  818. return to the recursive editing level when finished.  (The special
  819. commands for exiting are always available, but do nothing when recursive
  820. editing is not in progress.)
  821.  
  822.    All command loops, including recursive ones, set up all-purpose error
  823. handlers so that an error in a command run from the command loop will
  824. not exit the loop.
  825.  
  826.    Minibuffer input is a special kind of recursive editing.  It has a
  827. few special wrinkles, such as enabling display of the minibuffer and the
  828. minibuffer window, but fewer than you might suppose.  Certain keys
  829. behave differently in the minibuffer, but that is only because of the
  830. minibuffer's local map; if you switch windows, you get the usual Emacs
  831. commands.
  832.  
  833.    To invoke a recursive editing level, call the function
  834. `recursive-edit'.  This function contains the command loop; it also
  835. contains a call to `catch' with tag `exit', which makes it possible to
  836. exit the recursive editing level by throwing to `exit' (*note Catch and
  837. Throw::.).  If you throw a value other than `t', then `recursive-edit'
  838. returns normally to the function that called it.  The command `C-M-c'
  839. (`exit-recursive-edit') does this. Throwing a `t' value causes
  840. `recursive-edit' to quit, so that control returns to the command loop
  841. one level up.  This is called "aborting", and is done by `C-]'
  842. (`abort-recursive-edit').
  843.  
  844.    Most applications should not use recursive editing, except as part of
  845. using the minibuffer.  Usually it is more convenient for the user if you
  846. change the major mode of the current buffer temporarily to a special
  847. major mode, which has a command to go back to the previous mode.  (This
  848. technique is used by the `w' command in Rmail.)  Or, if you wish to
  849. give the user different text to edit "recursively", create and select a
  850. new buffer in a special mode.  In this mode, define a command to
  851. complete the processing and go back to the previous buffer.  (The `m'
  852. command in Rmail does this.)
  853.  
  854.    Recursive edits are useful in debugging.  You can insert a call to
  855. `debug' into a function definition as a sort of breakpoint, so that you
  856. can look around when the function gets there.  `debug' invokes a
  857. recursive edit but also provides the other features of the debugger.
  858.  
  859.    Recursive editing levels are also used when you type `C-r' in
  860. `query-replace' or use `C-x q' (`kbd-macro-query').
  861.  
  862.  -- Function: recursive-edit
  863.      This function invokes the editor command loop.  It is called
  864.      automatically by the initialization of Emacs, to let the user begin
  865.      editing.  When called from a Lisp program, it enters a recursive
  866.      editing level.
  867.  
  868.      In the following example, the function `simple-rec' first advances
  869.      point one word, then enters a recursive edit, printing out a
  870.      message in the echo area.  The user can then do any editing
  871.      desired, and then type `C-M-c' to exit and continue executing
  872.      `simple-rec'.
  873.  
  874.           (defun simple-rec ()
  875.             (forward-word 1)
  876.             (message "Recursive edit in progress.")
  877.             (recursive-edit)
  878.             (forward-word 1))
  879.                => simple-rec
  880.           (simple-rec)
  881.                => nil
  882.  
  883.  -- Command: exit-recursive-edit
  884.      This function exits from the innermost recursive edit (including
  885.      minibuffer input).  Its definition is effectively `(throw 'exit
  886.      nil)'.
  887.  
  888.  -- Command: abort-recursive-edit
  889.      This function aborts the command that requested the innermost
  890.      recursive edit (including minibuffer input), by signaling `quit'
  891.      after exiting the recursive edit.  Its definition is effectively
  892.      `(throw 'exit t)'.  *Note Quitting::.
  893.  
  894.  -- Command: top-level
  895.      This function exits all recursive editing levels; it does not
  896.      return a value, as it jumps completely out of any computation
  897.      directly back to the main command loop.
  898.  
  899.  -- Function: recursion-depth
  900.      This function returns the current depth of recursive edits.  When
  901.      no recursive edit is active, it returns 0.
  902.  
  903. 
  904. File: elisp,  Node: Disabling Commands,  Next: Command History,  Prev: Recursive Editing,  Up: Command Loop
  905.  
  906. Disabling Commands
  907. ==================
  908.  
  909.    "Disabling a command" marks the command as requiring user
  910. confirmation before it can be executed.  Disabling is used for commands
  911. which might be confusing to beginning users, to prevent them from using
  912. the commands by accident.
  913.  
  914.    The low-level mechanism for disabling a command is to put a
  915. non-`nil' `disabled' property on the Lisp symbol for the command. 
  916. These properties are normally set up by the user's `.emacs' file with
  917. Lisp expressions such as this:
  918.  
  919.      (put 'upcase-region 'disabled t)
  920.  
  921. For a few commands, these properties are present by default and may be
  922. removed by the `.emacs' file.
  923.  
  924.    If the value of the `disabled' property is a string, that string is
  925. included in the message printed when the command is used:
  926.  
  927.      (put 'delete-region 'disabled
  928.           "Text deleted this way cannot be yanked back!\n")
  929.  
  930.    *Note Disabling: (emacs)Disabling, for the details on what happens
  931. when a disabled command is invoked interactively. Disabling a command
  932. has no effect on calling it as a function from Lisp programs.
  933.  
  934.  -- Command: enable-command COMMAND
  935.      Allow COMMAND to be executed without special confirmation from now
  936.      on.  The user's `.emacs' file is optionally altered so that this
  937.      will apply to future sessions.
  938.  
  939.  -- Command: disable-command COMMAND
  940.      Require special confirmation to execute COMMAND from now on.  The
  941.      user's `.emacs' file is optionally altered so that this will apply
  942.      to future sessions.
  943.  
  944.  -- Variable: disabled-command-hook
  945.      The value of this variable is a function to be called instead of
  946.      any command that is disabled (i.e., that has a non-`nil' disabled
  947.      property).  By default, the value of `disabled-command-hook' is a
  948.      function defined to ask the user whether to proceed.
  949.  
  950. 
  951. File: elisp,  Node: Command History,  Next: Keyboard Macros,  Prev: Disabling Commands,  Up: Command Loop
  952.  
  953. Command History
  954. ===============
  955.  
  956.    The command loop keeps a history of the complex commands that have
  957. been executed, to make it convenient to repeat these commands.  A
  958. "complex command" is one for which the interactive argument reading
  959. uses the minibuffer.  This includes any `M-x' command, any `M-ESC'
  960. command, and any command whose `interactive' specification reads an
  961. argument from the minibuffer.  Explicit use of the minibuffer during
  962. the execution of the command itself does not cause the command to be
  963. considered complex.
  964.  
  965.  -- Variable: command-history
  966.      This variable's value is a list of recent complex commands, each
  967.      represented as a form to evaluate.  It continues to accumulate all
  968.      complex commands for the duration of the editing session, but all
  969.      but the first (most recent) thirty elements are deleted when a
  970.      garbage collection takes place (*note Garbage Collection::.).
  971.  
  972.           command-history
  973.           => ((switch-to-buffer "chistory.texi")
  974.               (describe-key "^X^[")
  975.               (visit-tags-table "~/emacs/src/")
  976.               (find-tag "repeat-complex-command"))
  977.  
  978.    There are a number of commands and even two entire modes devoted to
  979. facilitating the editing and recall of previous commands.  The commands
  980. `repeat-complex-command', and `list-command-history' are described in
  981. the user manual (*note Repetition: (emacs)Repetition.).
  982.  
  983.  -- Variable: repeat-complex-command-map
  984.      The value of this variable is a sparse keymap used by the
  985.      minibuffer inside of `read-complex-command'.
  986.  
  987. 
  988. File: elisp,  Node: Keyboard Macros,  Prev: Command History,  Up: Command Loop
  989.  
  990. Keyboard Macros
  991. ===============
  992.  
  993.    A "keyboard macro" is a canned sequence of keystrokes that can be
  994. considered a command and made the definition of a key.  Don't confuse
  995. keyboard macros with Lisp macros (*note Macros::.).
  996.  
  997.  -- Function: execute-kbd-macro MACRO &optional COUNT
  998.      This function executes MACRO as a string of editor commands.  If
  999.      MACRO is a string, then the characters in that string are executed
  1000.      exactly as if they had been typed as command input.
  1001.  
  1002.      If MACRO is a symbol, then its function definition is used in
  1003.      place of MACRO.  If that is another symbol, this process repeats.
  1004.      Eventually the result should be a string.  If the result is
  1005.      neither a symbol nor a string, an error is signaled.
  1006.  
  1007.      The argument COUNT is a repeat count; MACRO is executed that many
  1008.      times.  If COUNT is omitted or `nil', MACRO is executed once.  If
  1009.      it is 0, MACRO is executed over and over until it encounters an
  1010.      error or a failing search.
  1011.  
  1012.  -- Variable: last-kbd-macro
  1013.      This variable is the definition of the most recently defined
  1014.      keyboard macro.  Its value is a string or `nil'.
  1015.  
  1016.  -- Variable: executing-macro
  1017.      This variable contains the string that defines the keyboard macro
  1018.      that is currently executing.  It is `nil' if no macro is currently
  1019.      executing.
  1020.  
  1021.  -- Variable: defining-kbd-macro
  1022.      This variable indicates whether a keyboard macro is being defined.
  1023.       It is set to `t' by `start-kbd-macro', and `nil' by
  1024.      `end-kbd-macro'.  It is not hard to use this variable to make a
  1025.      command behave differently when run from a keyboard macro (perhaps
  1026.      indirectly by calling `interactive-p').  However, do not set this
  1027.      variable yourself.
  1028.  
  1029.    The user-level commands for defining, running and editing keyboard
  1030. macros include `call-last-kbd-macro', `insert-kbd-macro',
  1031. `start-kbd-macro', `end-kbd-macro', `kbd-macro-query', and
  1032. `name-last-kbd-macro'.  They are described in the user's manual (*note
  1033. Keyboard Macros: (emacs)Keyboard Macros.).
  1034.  
  1035. 
  1036. File: elisp,  Node: Keymaps,  Next: Modes,  Prev: Command Loop,  Up: Top
  1037.  
  1038. Keymaps
  1039. *******
  1040.  
  1041.    The bindings between keyboard input and commands are recorded in data
  1042. structures called "keymaps".  Each binding in a keymap associates (or
  1043. "binds") an individual character either with another keymap or with a
  1044. command.  When a character is bound to a keymap, that keymap is used to
  1045. look up the next character typed; this continues until a command is
  1046. found.  This process is called "key lookup".
  1047.  
  1048. * Menu:
  1049.  
  1050. * Keymap Terms::        Definitions of terms pertaining to keymaps.
  1051. * Creating Keymaps::    Functions to create and copy keymaps.
  1052. * Key Lookup::                  How extracting elements from keymaps works.
  1053. * Functions for Key Lookup::    How to request key lookup.
  1054. * Prefix Keys::                 Defining a key with a keymap as its definition.
  1055. * Global and Local Keymaps::    Each buffer has a local keymap
  1056.                                    to override the standard (global) bindings.
  1057. * Changing Key Bindings::       Redefining a key in a keymap.
  1058. * Key Binding Commands::        Interactive interfaces for redefining keys.
  1059. * Scanning Keymaps::            Looking through all keymaps, for printing help.
  1060.  
  1061. 
  1062. File: elisp,  Node: Keymap Terms,  Next: Creating Keymaps,  Prev: Keymaps,  Up: Keymaps
  1063.  
  1064. Keymaps: Terminology
  1065. ====================
  1066.  
  1067.    A "keymap" is a table mapping characters to definitions (which can
  1068. be any Lisp objects, though only certain types are meaningful for
  1069. execution by the command loop).  Given a character and a keymap, Emacs
  1070. can get the character's definition.
  1071.  
  1072.    A sequence of keyboard input characters that form a unit is called a
  1073. "key sequence", or "key" for short.  A sequence of one character is
  1074. always a key sequence, and so are some multicharacter sequences.
  1075.  
  1076.    A keymap determines a binding or definition for any key sequence.  If
  1077. the key sequence is a single character, its binding is the definition of
  1078. the character in the keymap.  The binding of a multicharacter key
  1079. sequence is found by an iterative process: the binding of the first
  1080. character is found, and must be a keymap; then the second character's
  1081. binding is found in that keymap, and so on until all the characters in
  1082. the key sequence are used up.
  1083.  
  1084.    If the binding of a key sequence is a keymap, we call the key
  1085. sequence a "prefix key".  Otherwise, we call it a "complete key"
  1086. (because no more characters can be added to it).  If the binding is
  1087. `nil', we call the key "undefined".  Examples of prefix keys are `C-c',
  1088. `C-x', and `C-x 4'.  Examples of defined complete keys are `X', RET,
  1089. and `C-x 4 C-f'.  Examples of undefined complete keys are `C-x C-g',
  1090. and `C-c 3'.  *Note Prefix Keys::, for more details.
  1091.  
  1092.    The rule for finding the binding of a key sequence assumes that the
  1093. intermediate bindings (found for the characters before the last) are all
  1094. keymaps; if this is not so, the sequence of characters does not form a
  1095. unit--it is not really a key sequence.  In other words, removing one or
  1096. more characters from the end of any key must always yield a prefix key.
  1097. For example, `C-f C-f' is not a key; `C-f' is not a prefix key, so a
  1098. longer sequence starting with `C-f' cannot be a key.  Note that the set
  1099. of possible multicharacter key sequences depends on the bindings for
  1100. prefix keys; therefore, it can be different for different keymaps, and
  1101. can change when bindings are changed.  However, a one-character
  1102. sequence is always a key sequence, because it does not depend on any
  1103. prefix keys for its validity.
  1104.  
  1105.    At any time, two primary keymaps are in use for finding key bindings:
  1106. the "global map", which is shared by all buffers, and the "local
  1107. keymap", which is usually associated with a specific major mode.  The
  1108. local keymap bindings shadow (i.e., take precedence over) the
  1109. corresponding global bindings.  *Note Global and Local Keymaps::, for
  1110. details.
  1111.  
  1112. 
  1113. File: elisp,  Node: Creating Keymaps,  Next: Key Lookup,  Prev: Keymap Terms,  Up: Keymaps
  1114.  
  1115. Creating Keymaps
  1116. ================
  1117.  
  1118.    A keymap can be represented as one of two kinds of Lisp object: a
  1119. vector or a list.  A "full keymap" is a vector of length 128.  The
  1120. binding for a character in such a keymap is found by indexing into the
  1121. vector with the character as the index.
  1122.  
  1123.    A "sparse keymap" is a list whose CAR is the symbol `keymap', and
  1124. whose remaining elements are cons cells of the form `(CHAR . BINDING)'.
  1125.  It is called a sparse keymap because it stores only the entries which
  1126. are significant.  Use a sparse keymap when you expect only a few
  1127. entries.  (`define-key' automatically creates sparse keymaps for
  1128. intermediate keymaps.)
  1129.  
  1130.    Keymaps record directly only character codes less than 128; they are
  1131. unable to handle directly the META characters, whose codes are from 128
  1132. to 255.  Instead, META characters are regarded for purposes of key
  1133. lookup as sequences of two characters, the first of which is ESC (the
  1134. usual value of `meta-prefix-char').  Thus, the key `M-a' is really
  1135. represented as `ESC a', and its global binding is found at the slot for
  1136. `a' in `esc-map'.
  1137.  
  1138.    Here as an example is the local keymap for Lisp mode, a sparse
  1139. keymap. It defines `C-c C-l' as the `run-lisp' command, `M-C-q' as
  1140. `indent-sexp', and `M-C-x' as `lisp-send-defun'.
  1141.  
  1142.      lisp-mode-map
  1143.      =>
  1144.      (keymap
  1145.       (9 . lisp-indent-line)                 ; TAB
  1146.       (127 . backward-delete-char-untabify)  ; DEL
  1147.       (3 keymap
  1148.          (12 . run-lisp))                    ; `C-c C-l'
  1149.       (27 keymap
  1150.           (17 . indent-sexp)                 ; `M-C-q', treated as `ESC C-q'
  1151.           (24 . lisp-send-defun)))           ; `M-C-x', treated as `ESC C-x'
  1152.  
  1153.  -- Function: keymapp OBJECT
  1154.      This function returns `t' if OBJECT is a keymap, `nil' otherwise. 
  1155.      A keymap is either a vector of length 128, or a list with the form
  1156.      `(keymap PAIRS...)', where PAIRS stands for a series of
  1157.      associations, cons cells of the form `(CHAR . BINDING)'.
  1158.  
  1159.           (keymapp '(keymap))
  1160.               => t
  1161.           (keymapp (current-global-map))
  1162.               => t
  1163.  
  1164.  -- Function: make-keymap
  1165.      This function creates and returns a new full keymap (i.e., a vector
  1166.      of length 128).  All entries in the keymap are `nil', which means
  1167.      that no characters are defined.
  1168.  
  1169.           (make-keymap)
  1170.               => [nil nil nil ... nil nil]
  1171.  
  1172.  -- Function: make-sparse-keymap
  1173.      This function creates and returns a new sparse keymap with no
  1174.      entries. In this keymap, no characters are defined.
  1175.  
  1176.           (make-sparse-keymap)
  1177.               => (keymap)
  1178.  
  1179.  -- Function: copy-keymap KEYMAP
  1180.      This function returns a copy of KEYMAP.  Any keymaps which appear
  1181.      directly as bindings in KEYMAP are also copied recursively, and so
  1182.      on to any number of levels.  However, recursive copying does not
  1183.      take place when the definition of a character is a symbol whose
  1184.      function definition is a keymap; the same symbol appears in the
  1185.      new copy.
  1186.  
  1187.           (setq map (copy-keymap (current-local-map)))
  1188.           => (keymap
  1189.                (27 keymap         ; (This implements META characters.)
  1190.                  (83 . center-paragraph)
  1191.                  (115 . center-line))
  1192.                (9 . tab-to-tab-stop))
  1193.           
  1194.           (eq map (current-local-map))
  1195.               => nil
  1196.           (equal map (current-local-map))
  1197.               => t
  1198.  
  1199.