⟦a9d5a09d6⟧

TextFile

Info file: lispref,    -*-Text-*-
produced by texinfo-format-buffer
from file: lispref.texinfo









This file documents GNU Emacs Lisp.

This is Edition 0.1 Beta of the GNU Emacs Lisp Reference Manual, for
Emacs Version 18, with some references to Emacs Version 19.

Please read this document for review purposes.

Published by the Free Software Foundation, 675 Massachusetts Avenue,
Cambridge, MA 02139 USA

Copyright (C) 1989 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the
entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions,
except that this permission notice may be stated in a translation
approved by the Foundation.



▶1f◀
File: lispref  Node: Input Functions, Prev: Input Streams, Up: Streams, Next: Output Streams

Input Functions
===============

  This section describes the Lisp functions and variables that pertain
to reading.

  In the functions below, STREAM stands for an input stream.  See the
previous section for a description of input streams.  If STREAM is `nil'
or omitted, it defaults to the value of `standard-input'.

* Variable: standard-input

     This global variable is the stream that `read' reads from when the
     STREAM argument is `nil'.

* Function: read &optional STREAM

     This function reads one Lisp expression from STREAM, returning it
     as a Lisp object.  This is the basic Lisp input function.

* Function: read-from-string STRING &optional START END

     This function reads the first Lisp-expression from the text in
     STRING.  It then returns a cons cell whose CAR is that expression
     and and whose CDR is an integer, giving the position of the next
     character in the string (the first one not read).

     If START is supplied, then reading begins at that index in the
     string (where the first character is at index 0).  If END is also
     supplied, then reading ends at that index, as if the rest of the
     string were not there.

     An `end-of-file' error will result if an unterminated list or
     vector is found.

          (read-from-string "(setq x 55) (setq y 5)")
          => ((setq x 55) . 11)
          (read-from-string "\"A short string\"")
          ("A short string" . 16)

          ;; Read starting at the first character.
          (read-from-string "(list 112)" 0)
          ((list 112) . 10)
          ;; Read starting at the second character.
          (read-from-string "(list 112)" 1)
          (list . 6)
          ;; Read starting at the seventh character, and ending at the ninth.
          (read-from-string "(list 112)" 6 8)
          (11 . 8)

▶1f◀
File: lispref  Node: Output Streams, Prev: Input Functions, Up: Streams, Next: Output Functions

Output Streams
==============

  An output stream specifies what to do with the characters produced by
printing.  Most print functions accept an output stream as an optional
argument.  Here are the possible types of output stream:

BUFFER
     The output characters are inserted into BUFFER at the point.  Point
     advances as characters are inserted.

MARKER
     The output characters are inserted into the buffer that MARKER is
     in at the marker position.  The position advances as characters are
     inserted.  The value of point in the buffer has no effect when the
     stream is a marker.

FUNCTION
     FUNCTION is called with one output character as the argument.  It
     is called as many times as there are characters to be output.  The
     function is free to do anything at all with the characters.

`t'
     `t' as an output stream means that the output characters should be
     printed in the echo area.

`nil'
     `nil' specified as an output stream means that the value of
     `standard-output' should be used as the output stream; that value
     must be a non-`nil' output stream.

  Here is an example of a buffer as output stream.  At the end, the
point is located directly before that same `h'.

     ---------- Buffer: foo ----------
     This is t-!-he contents of foo.
     ---------- Buffer: foo ----------

     (print "This is the output" (get-buffer "foo"))
     => "This is the output"

     ---------- Buffer: foo ----------
     This is t
     "This is the output"
     -!-he contents of foo.
     ---------- Buffer: foo ----------

  Now we show a use of a marker as an output stream.  Initially, the
marker points in buffer `foo', between the `t' and the `h' in the word
`the'.  At the end, the marker has been advanced over the inserted text
so that it still points before the same `h'.

     ---------- Buffer: foo ----------
     "This is t-!-he output"
     ---------- Buffer: foo ----------

     m
     => #<marker at 11 in foo>

     (print "More output for foo." marker)
     => "More output for foo."

     ---------- Buffer: foo ----------
     "This is t
     "More output for foo."
     -!-he output"
     ---------- Buffer: foo ----------

     m
     => #<marker at 35 in foo>

  This example shows output to the echo area.

     (print "Echo Area output" t)
     => "Echo Area output"
     ---------- Echo Area ----------
     "Echo Area output"
     ---------- Echo Area ----------

  Finally, we show an output stream which is a function.  The function
`eat-output' takes each character that it is given and conses it onto
the front of the list `last-output'.  At the end, the list contains all
the characters output, but in reverse order.

     (setq last-output nil)
     => nil

     (defun eat-output (c)
       (setq last-output (cons c last-output)))
     => eat-output

     (print "This is the output" 'eat-output)
     => "This is the output"

     last-output
     => (10 34 116 117 112 116 117 111 32 101 104 116 32 115 105
         32 115 105 104 84 34 10)

Now we can put the output in the proper order by reversing the list:

     (concat (nreverse last-output))
     => "
     \"This is the output\"
     "

▶1f◀
File: lispref  Node: Output Functions, Prev: Output Streams, Up: Streams

Output Functions
----------------

  This section describes the Lisp functions and variables that pertain
to printing.

  There are actually two different ways of printing a Lisp object,
depending on the purpose of printing: with or without quoting
characters.  You specify quoting or no quoting by the choice of printing
function.

  If the text is to be read back into Lisp, then it is best to print
with quoting characters to avoid ambiguity.  (The quoting characters
used are `\' and `"'.)  *Note Print Representation and Read Syntax::,
for the details of how quoting characters are used.

  However, if the purpose of the output is to look nice for humans, then
it is better print without quoting.

  In the functions below, STREAM stands for an output stream.  See the
previous section for a description of output streams.  If STREAM is
`nil' or omitted, it defaults to the value of `standard-output'.

* Variable: standard-output

     The value of this variable is default output stream, used when the
     STREAM argument is omitted.

* Function: print OBJECT &optional STREAM

     This function is the most convenient and simple interface to
     printing.  It outputs the printed representation of OBJECT to
     STREAM.  It also prints one newline before OBJECT and another after
     it.  It returns OBJECT.

     The output of `print' includes any escape and quoting characters
     (`\' and `"') required to allow the object to be read back in.

          (progn (print 'The\ cat\ in)
                 (print "the hat")
                 (print " came back"))
          -| 
          -| The\ cat\ in
          -| 
          -| "the hat"
          -| 
          -| " came back"
          -| 
          => " came back"

* Function: prin1 OBJECT &optional STREAM

     This function outputs the printed representation of OBJECT to
     STREAM.  It does not print any spaces or newlines to separate
     output as `print' does, but it does use quoting characters just
     like `print'.  It returns OBJECT.

          (progn (prin1 'The\ cat\ in) 
                 (prin1 "the hat") 
                 (prin1 " came back"))
          -| The\ cat\ in"the hat"" came back"
          => " came back"

* Function: prin1-to-string OBJECT

     This function returns a string which is what the function `prin1'
     would have printed.  See `format', in *Note Conversion of
     Characters and Strings::, for other ways to convert objects to
     string representation.

          (prin1-to-string 'foo)
          => "foo"
          (prin1-to-string (mark-marker))
          => "#<marker at 2773 in strings.texinfo>"

* Function: princ OBJECT &optional STREAM

     This function outputs the printed representation of OBJECT to
     STREAM.  It returns OBJECT.

     This function is intended to produce output that is readable by
     people, not `read', so no quoting characters are used, and double
     quotes are not printed around the contents of strings.  It does not
     add any spacing between calls.

          (progn
            (princ 'The\ cat)
            (princ " in the \"hat\""))
          -| The cat in the "hat"
          => " in the \"hat\""

* Function: terpri &optional STREAM

     This function outputs a newline to STREAM.  The name stands for
     ``terminate print''.

* Variable: print-escape-newlines

     Non-`nil' means print newlines in strings as `\n'.  Normally they
     are printed as actual newlines.

     This variable affects all the print functions.  Here is an example
     using `princ':

          (princ "a\nb")
          -| a
          -| b
          => "a
          => b"

          (let ((print-escape-newlines t))
            (princ "a\nb"))
          -| a\nb
          => "a
          => b"

     In the second expression, the local binding of
     `print-escape-newlines' is in effect during the call to `princ' but
     not during the printing of the result.

* Variable: print-length

     The value of this variable is the maximum number of elements of a
     list that will be printed.  If the list being printed is longer
     than this, then it is abbreviated with an ellipsis.

     If the value is `nil' (the default), then there is no limit.

          (setq print-length 2)
          => 2
          (print '(1 2 3 4 5))
          => (1 2 ...)
          => (1 2 ...)

* Function: write-char CHARACTER &optional STREAM

     This function outputs CHARACTER to STREAM.  It returns CHARACTER.


▶1f◀
File: lispref  Node: Minibuffers, Prev: Streams, Up: Top, Next: Command Loop

Minibuffers
***********

  A "minibuffer" is a special buffer used by Emacs commands to read
arguments more complicated than the single numeric prefix argument.

  In most ways, a minibuffer is a normal Emacs buffer.  Although some
operations for managing buffers do not apply to minibuffers, most
operations *within* a buffer, such as editing commands, work normally in
the minibuffer.  But minibuffers cannot be deleted or renamed.  (In
fact, a minibuffer, once created, is never deleted by Emacs, even after
the user exits from the minibuffer.)

  The minibuffer has its own window, from which it cannot be separated.
The window is the single line at the bottom of the screen; it can be
temporarily resized with the window sizing commands.

  A "recursive minibuffer" may be created when there is an active
minibuffer and a command is invoked that requires input from a
minibuffer.  Recursive minibuffers may be allowed or disallowed by
setting the variable `enable-recursive-minibuffers'.  Of several
recursive minibuffers, the innermost, or most recently entered, one is
the active minibuffer.  It is the only one that is displayed in a
window.

  The first minibuffer is named ` *Minibuf-0*'.  Recursive minibuffers
are named by incrementing the number at the end of the name.  All
minibuffer names begin with a space so that they won't show up in normal
buffer lists.

  The minibuffer may use one of several local keymaps; they contain
various completion and exit commands.

   * `minibuffer-local-map' is used for ordinary input (no completion).

   * `minibuffer-local-ns-map' is similar, except that SPC exits just
     like RET.  This is used mainly for MockLisp compatibility.

   * `minibuffer-local-completion-map' is for permissive completion.

   * `minibuffer-local-must-match-map' is for strict completion and for
     cautious completion.

   * `repeat-complex-command-map' is for use in `C-x ESC'.

* Menu:

* Reading Text or Objects::     
* Completion::  
* Yes or No Queries::   
* Minibuffer Odds and Ends::    

▶1f◀
File: lispref  Node: Reading Text or Objects, Prev: Minibuffers, Up: Minibuffers, Next: Completion

Reading Text or Objects
=======================

  The main use of the minibuffer is to read text.  One extension of that
is to treat the text as a Lisp object, and return that.

* Menu:

* Reading Lisp Objects in the Minibuffer::      

* Function: read-from-minibuffer PROMPT-STRING &optional INITIAL KEYMAP READ

       This function is perhaps the most general way to get input in the
     minibuffer: it reads an arbitrary string and returns it.

       First, PROMPT-STRING is printed in the minibuffer.  PROMPT-STRING
     must be a string.

       Then, if INITIAL is non-`nil', the value of INITIAL is inserted
     into the minibuffer.  INITIAL is considered to be part of the
     user's input, at least to begin with, and so it can be edited
     normally.

       If KEYMAP is non-`nil', that keymap is the local keymap to use
     while reading.  If KEYMAP is omitted or `nil', the value of
     `minibuffer-local-map' is used as the keymap.

       Finally, if READ is non-`nil', Emacs interprets the result as a
     Lisp object and `read-from-minibuffer' returns that object,
     unevaluated.  Otherwise, it returns the minibuffer contents as a
     string.

       For example, suppose you save the last string the user searched
     for in the variable `last-search-string', and offer it for editing
     the next time.  To get a search string, you might want to call
     `read-from-minibuffer' as follows.

          (read-from-minibuffer "Find string: " last-search-string)

       Assuming the value of `last-search-string' is `No', and the user
     wants to search for `Nope', the interaction looks like this:

          (setq last-search-string "No")

          (read-from-minibuffer "Find string: " last-search-string)
               => "Nope"

     Here is the minibuffer after evaluating the call to
     `read-from-minibuffer' but before typing in the characters `pe' and
     RET

          ---------- Buffer: Minibuffer ----------
          Find string: No-!-
          ---------- Buffer: Minibuffer ----------


* Function: read-string PROMPT &optional INITIAL

       This function reads a string from the minibuffer, and returns it.
     PROMPT and INITIAL are the same as in `read-from-minibuffer'.

       This function is a simplified call to `read-from-minibuffer'.

          (read-string PROMPT INITIAL)
          ==
          (read-from-minibuffer PROMPT INITIAL nil nil)

* Function: read-no-blanks-input PROMPT &optional INITIAL

       This function reads a string from the minibuffer, but does not
     allow the user to type blanks.  PROMPT and INITIAL are the same as
     in `read-from-minibuffer'.  Typing a blank *exits* the minibuffer.

       This function is a simplified call to `read-from-minibuffer'.
     The `read-no-blanks-input' function uses the
     `minibuffer-local-ns-map' keymap.  Since `read-no-blanks-input'
     does not redefine `quoted-insert', it *is* possible to put a space
     into the string, by quoting it.  Also, of course, you may rebind
     the keys in `minibuffer-local-ns-map'.

          (read-no-blanks-input PROMPT INITIAL)
          ==
          (read-from-minibuffer PROMPT INITIAL minibuffer-local-ns-map)

* Variable: minibuffer-local-ns-map

       This built-in variable is the keymap passed by the function
     `read-no-blanks-input' to `read-from-minibuffer'.  By default, it
     makes the following bindings:

     LFD
          `exit-minibuffer'

     SPC
          `exit-minibuffer'

     TAB
          `exit-minibuffer'

     RET
          `exit-minibuffer'

     C-g
          `abort-recursive-edit'

     ?
          `self-insert-and-exit'

* Variable: minibuffer-local-map

       This is the default keymap for reading from the minibuffer.  It
     is the keymap used by the minibuf for local bindings when spaces
     are allowed in the minibuffer.

     By default, it makes the following bindings:

     LFD
          `exit-minibuffer'

     RET
          `exit-minibuffer'

     C-g
          `abort-recursive-edit'

▶1f◀
File: lispref  Node: Reading Lisp Objects in the Minibuffer, Prev: Reading Text or Objects, Up: Reading Text or Objects

Reading Lisp Objects in the Minibuffer
--------------------------------------

  This section describes functions for reading Lisp objects from the
minibuffer.

* Function: read-minibuffer PROMPT &optional INITIAL

       This function reads a Lisp object in the minibuffer and returns
     it, unevaluated.  PROMPT and INITIAL are the same as in
     `read-from-minibuffer'.

       This function is a simplified call to `read-from-minibuffer'.

          (read-minibuffer PROMPT INITIAL)
          ==
          (read-from-minibuffer PROMPT INITIAL nil t)

     Here is an example:

          (read-minibuffer "Enter an expression: " (format "%s" '(testing)))

          ;;  After the preceding expression is evaluated,
          ;;  the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          Enter an expression: (testing)
          ---------- Buffer: Minibuffer ----------

     In this example, `(testing)' is inserted initially, and may be
     edited by the user.

* Function: eval-minibuffer PROMPT &optional INITIAL

       This function reads a Lisp expression in the minibuffer, then
     evaluates it, returning the result.  PROMPT and INITIAL are the
     same as in `read-from-minibuffer'.

       This function simply evaluates the result of a call to
     `read-minibuffer'.

          (eval-minibuffer PROMPT INITIAL)
          ==
          (eval (read-minibuffer PROMPT INITIAL))

* Function: edit-and-eval-command PROMPT FORM

       This function reads a Lisp expression in the minibuffer, and then
     evaluates it.  The difference from `eval-minibuffer' is that the
     initial FORM is not optional and it is not expected to be a string.
     FORM is printed with `prin1', so if it is a string, double quotes
     characters, `"', will appear in the initial text.

       First, PROMPT is printed in the minibuffer.  Then FORM is
     converted to its print representation and inserted into the
     minibuffer as input, like INITIAL in `read-from-minibuffer'.  When
     the user exits the minibuffer, the new form is evaluated.  The
     resulting value is the value of `edit-and-eval-command'.

       In the following example, the user is offered an expression with
     an incomplete name for a function call within it:

          (edit-and-eval-command "Please edit: " '(forward-))

          ;; After evaluating the preceding expression, 
          ;; the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          Please edit: (forward-)-!-
          ---------- Buffer: Minibuffer ----------

     The user may edit the minibuffer, for example, by typing: `DEL
     `word 1)''.  This action edits the form to create a complete
     expression: `(forward-word 1)'.  Typing RET then causes Emacs to
     evaluate the expression, which will move point forward one word.
     `edit-and-eval-command' returns `nil' in this example.

▶1f◀
File: lispref  Node: Completion, Prev: Reading Text or Objects, Up: Minibuffers, Next: Yes or No Queries

Completion
==========

  Emacs will attempt to complete the name of a symbol, file, or buffer
if you type a part of it.  This saves typing and makes life easier.  For
example, when you type `C-x b' (`switch-to-buffer') and then type the
first few letters of the name of the buffer to which you wish to switch,
and then type TAB (`minibuffer-complete'), Emacs will try to extend the
name as far as it can.

  Completion works for functions such as `switch-to-buffer' or
`describe-function' because Emacs keeps track of the names of all the
buffers and the names of all the functions and is able to search through
those names to locate those that begin with the letters you type.

  The functions described in this section handle completion in a fairly
general way.  The `try-completion' function is at the heart of the
completion routines.  It returns the longest possible substring for a
given initial string, and set of strings to match against.  Other
functions perform completion for various other specifications.

  The function `completing-read' provides a higher-level interface for
completion.  A call to `completing-read' specifies what should be
completed, and how.  The function then switches to the minibuffer where
the local keymap binds a few keys to functions useful for completion.

  For information about functions that complete filenames, *Note
Filename Completion::; for functions that complete symbols, *Note Lisp
Symbol Completion::.

* Menu:

* Basic Completion::
* Completion Reading::
* High-level Completion::

▶1f◀
File: lispref  Node: Basic Completion, Prev: Completion, Up: Completion, Next: Completion Reading

Basic Completion Functions
--------------------------

* Function: try-completion STRING ALIST-OR-OBARRAY &optional PREDICATE

       This function returns the longest common substring of all
     possible completions of STRING in ALIST-OR-OBARRAY.

       If ALIST-OR-OBARRAY is an alist (*Note Association Lists::), the
     first element of each pair in the association list is tested to see
     whether it begins with STRING.  All elements that match are then
     compared.  The longest initial sequence common to all matches is
     returned as a string.  If none is matched, `try-completion' returns
     `nil'.  If only one element is matched, and the match is exact,
     then `try-completion' returns `t'.

       If ALIST-OR-OBARRAY is an obarray (*Note Creating and Interning
     Symbols::), the print names of all symbols in the obarray are
     tested for matches.  (The global variable `obarray' holds an
     obarray containing the names of all interned Lisp symbols.)

       If PREDICATE is passed to `try-completion', then it must be a
     function of one argument.  It is used to test each possible match,
     and the match is a candidate only if PREDICATE returns non-`nil'.
     The argument given to PREDICATE is either the alist element (which
     is a pair, the CAR of which is a string) or else it is the symbol
     (*not* the symbol name) from the obarray.

       In the first of the following examples, the string `foo' is
     matched by three of the alist pairs.  All of the matches begin with
     the characters `fooba', so that is the result.  In the second
     example, there is only one possible match, and it is exact, so `t'
     is returned.

          (try-completion "foo"
               '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)))
               => "fooba"

          (try-completion "foo" '(("barfoo" 2) ("foo" 3)))
               => t

       In the following example, numerous symbols begin with the
     characters `forw', and all of them begin with the word `forward',
     but only one does not contain the additional character `-'.

          (try-completion "forw" obarray)
               => "forward"

       Finally, in the following example, only two of the three possible
     matches pass the predicate `test' (the string `foobaz' is too
     short).  Both of those begin with the string `foobar'.

          (defun test (s) 
            (> (length (car s)) 6))
          => test
          (try-completion "foo"
               '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4)) 
               'test)
          => "foobar"

* Function: all-completions STRING ALIST-OR-OBARRAY &optional PREDICATE

       This function returns a list of all possible completions, instead
     of the longest substring they share.  The parameters to this
     function are the same as to `try-completion'.

       In the following example, `test' is defined as in the example for
     `try-completion'.

          (defun test (s) 
            (> (length (car s)) 6))
          => test

          (all-completions  "foo"
               '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
               (function test))
          => ("foobar1" "foobar2")

The two functions, `try-completion' and `all-completions' have nothing
in themselves to do with minibuffers.  However, completion is most often
used there, which is why it is described in this chapter.

▶1f◀
File: lispref  Node: Completion Reading, Prev: Basic Completion, Up: Completion, Next: High-level Completion

Functions and Variables for Reading with Completion
---------------------------------------------------

Here are the functions and variables for dealing with completion while
reading from the minibuffer.

* Function: completing-read PROMPT ALIST-OR-OBARRAY &optional PREDICATE REQUIRE-MATCH INITIAL

       This function reads a string in the minibuffer, assisting the
     user by providing completion.  First, it prints PROMPT, which must
     be a string.  If INITIAL is non-`nil', `completing-read' inserts it
     into the minibuffer as part of the input.  Then it allows the user
     to edit the input, providing several commands to attempt
     completion.

       The function performs completion using ALIST-OR-OBARRAY and
     PREDICATE in the same way that `try-completion' does.

       If REQUIRE-MATCH is `t', the user will not be allowed to exit
     unless the input completes to an element of ALIST-OR-OBARRAY.  If
     REQUIRE-MATCH is neither `nil' nor `t', then `completing-read' does
     not exit unless the input typed is itself an element of
     ALIST-OR-OBARRAY.  To accomplish this, `completing-read' calls
     `read-minibuffer' with the keymap `minibuffer-local-completion-map'
     if REQUIRE-MATCH is `nil', or else with the keymap
     `minibuffer-local-must-match-map', if REQUIRE-MATCH is non-`nil'.

       Case is ignored if the built-in variable `completion-ignore-case'
     is non-`nil'.

       The `completing-read' function also binds three special
     variables, the first two of which are passed to the
     `read-minibuffer' function, the last of which is checked by the
     `minibuffer-complete-and-exit' function.

     `minibuffer-completion-table'
          The value of this variable is bound to ALIST-OR-OBARRAY
          argument.

     `minibuffer-completion-predicate'
          The PREDICATE argument is bound to the value of this variable.

     `minibuffer-completion-confirm'
          The REQUIRE-MATCH argument is bound to the value of this
          variable.

     For example:

          (completing-read "Complete a foo: "
               '(("foobar1" 1) ("barfoo" 2) ("foobaz" 3) ("foobar2" 4))
               nil t "fo")

          ;; After evaluating the preceding expression, 
          ;; the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          Complete a foo: fo
          ---------- Buffer: Minibuffer ----------

     If in this case, the user types `DEL DEL b RET', Emacs will return
     `barfoo'.

* Variable: minibuffer-local-completion-map

       `completing-read' uses this value as the local map 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'

     `LFD'
          `exit-minibuffer'

     `RET'
          `exit-minibuffer'

     `C-g'
          `abort-recursive-edit'


* Variable: minibuffer-local-must-match-map

       `completing-read' uses the value of this variableas the local map
     when an exact match of one of the completions is required.
     Therefore, no keys are bound to `exit-minibuffer'.

     By default, this variable makes the following bindings:

     `?'
          `minibuffer-completion-help'

     `SPC'
          `minibuffer-complete-word'

     `TAB'
          `minibuffer-complete'

     `LFD'
          `minibuffer-complete-and-exit'

     `RET'
          `minibuffer-complete-and-exit'

     `C-g'
          `abort-recursive-edit'

* 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 `read-minibuffer'.  It is
     used by all the minibuffer completion functions, such as
     `minibuffer-complete-word'.

* Variable: minibuffer-completion-predicate

         The value of this variable is the predicate that that
     `completing-read' passes to `read-minibuffer'.  The variable also
     used by the other minibuffer completion functions.

  Here are the interactive commands and user options that are people use
directly for completion in the minibuffer.

* Command: minibuffer-complete-word

       This function completes the minibuffer contents by at most a
     single word.  Even if the minibuffer contents has only one
     completion, `minibuffer-complete-word' will not add any characters
     beyond the first character that is not a word constituent.  *Note
     Syntax Tables::.

* Command: minibuffer-complete

       This function completes the minibuffer contents as far as
     possible.

* Command: minibuffer-complete-and-exit

       This function completes the minibuffer contents, and exits if
     confirmation is not required, i.e., if
     `minibuffer-completion-confirm' is non-`nil'.  If a confirmation
     *is* required, and is given, repeating this command will exit.

* Variable: minibuffer-completion-confirm

       When the value of this variable is non-`nil', Emacs 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 using `all-completions' passed the
     values of `minibuffer-completion-table' and
     `minibuffer-completion-predicate'.  Emacs displays the list in the
     buffer named `*Completions*'.

* Function: display-completion-list COMPLETIONS

       This function displays COMPLETIONS to the stream
     `standard-output' (usually a buffer).  (*Note Streams::, for more
     information about streams.)  COMPLETIONS is normally the list of
     completions just made.  Each element may be a symbol or a string,
     either of which is simply printed, or a list of two strings, which
     are printed as if concatenated.

       This function is called by `minibuffer-completion-help'.

* Variable: completion-ignore-case

       If the value of this variable is non-`nil', Emacs does not
     consider case significant in completion.

▶1f◀
File: lispref  Node: High-level Completion, Prev: Completion Reading, Up: Completion

High-level Completion  Functions
--------------------------------

Here are functions for reading from the minibuffer with completion.

* Function: read-buffer PROMPT &optional DEFAULT EXISTING

       This function reads the name of a buffer and returns it as a
     string.  DEFAULT (which must be a string if it is supplied) is
     printed along with the prompt and is the value to return if the
     user simply exits.  DEFAULT is therefore not an initial value in
     the sense of `read-from-minibuffer'.

       If EXISTING is non-`nil', then any name the user types must be
     the name of an existing buffer.  (However, even if EXISTING is
     non-`nil', DEFAULT need not be the name of an existing buffer.)

       In the following example, the user enters `minibuffer.t', and
     then types RET.  The only buffer name starting with that string is
     `minibuffer.texinfo', so that name is returned.

          (read-buffer "Buffer name? " "foo" t)

          ;; After evaluating the preceding expression, 
          ;; the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          Buffer name? (default foo) 
          ---------- Buffer: Minibuffer ----------

     The user types `minibuffer.t RET' and the result is
     `minibuffer.texinfo'.

* Function: read-file-name PROMPT DIRECTORY &optional DEFAULT MUSTMATCH

       This function reads a file name in the minibuffer, prompting with
     PROMPT.  The function provides completion for the name.  If DEFAULT
     is non-`nil', then the value of DEFAULT will be returned by the
     function if the user just types RET.


       If MUSTMATCH is non-`nil', then the name must refer to an
     existing file.  If the value of MUSTMATCH is neither non-`nil' nor
     non-`t', then Emacs also requires confirmation after completion.

     DIRECTORY defaults to the current buffer's default directory.

     For example, after evaluating the following expression,

          (read-file-name "The file is ")

     the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          The file is /gp/gnu/elisp/-!-
          ---------- Buffer: Minibuffer ----------

     Typing `manual TAB' results in the following:

          ---------- Buffer: Minibuffer ----------
          The file is /gp/gnu/elisp/manual.texinfo
          ---------- Buffer: Minibuffer ----------

     Then, after typing RET, Emacs will return
     `"/gp/gnu/elisp/manual.texinfo"'.

* User Option: insert-default-directory

       This variable is used by `read-file-name'.  The value of the
     variable determines if, when reading a filename in the minibuffer,
     Emacs should start by placing the name of the default directory in
     the minibuffer.  If the value of this variable is `nil', then Emacs
     will not place anything into the minibuffer.  In that case, the
     default directory will still be used, but it will not be displayed.

          (let ((insert-default-directory t))
            (read-file-name "The file is "))

          ---------- Buffer: Minibuffer ----------
          The file is ~lewis/manual/ 
          ---------- Buffer: Minibuffer ----------

          (let ((insert-default-directory nil))
            (read-file-name "The file is "))

          ---------- Buffer: Minibuffer ----------
          The file is
          ---------- Buffer: Minibuffer ----------

* Function: read-command PROMPT

       This function reads the name of a command and returns it as a
     Lisp symbol.  PROMPT is the same as in `read-from-minibuffer'.
     Recall that a command is merely a function with an interactive
     calling specification.

          (read-command "Command name? ")

          ;; After evaluating the preceding expression, 
          ;; the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ---------- 
          Command name?  
          ---------- Buffer: Minibuffer ----------

     If in this case, the user types `forward-c RET', then Emacs will
     return `forward-char'.

       The `read-command' function is a simplified call to
     `completing-read'.  The `read-command' function uses the `commandp'
     predicate to allow only commands to be entered; and it uses the
     `obarray' global variable so as to be able to complete all extant
     Lisp symbols.

          (read-command PROMPT)
          ==
          (intern (completing-read PROMPT obarray 'commandp t nil))

* Function: read-variable PROMPT

       This function reads the name of a user variable and returns it as
     a symbol.  This function is analogous to `read-command'; it uses
     the predicate `user-variable-p' instead of `commandp'.

          (read-variable PROMPT)
          ==
          (intern (completing-read PROMPT obarray 'user-variable-p t nil))

          (read-variable "Variable name? ")

          ;; After evaluating the preceding expression, 
          ;; the following appears in the minibuffer:

          ---------- Buffer: Minibuffer ----------
          Variable name? -!-
          ---------- Buffer: Minibuffer ----------

     If in this case, the user types `fill-p RET', then Emacs will
     return `fill-prefix'.



The functions described in this chapter deal with general completion in
the minibuffer.  Emacs Lisp also provides functions for filename
completion (*Note Filename Completion::) and Lisp symbol completion
(*Note Lisp Symbol Completion::).

▶1f◀
File: lispref  Node: Yes or No Queries, Prev: Completion, Up: Minibuffers, Next: Minibuffer Odds and Ends

Yes or No Queries
=================

* 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'.  Only a single character is needed to answer, with no
     RET to end the input.  The function also accepts SPC to mean yes
     and DEL to mean no.  Upper and lowercase are not equivalent.

       Asking the question means print PROMPT in the echo area, followed
     by the string `(y or n) '.  If the input is not one of the expected
     answers (`y', `n', `SPC', or `DEL'), the function responds `Please
     answer y or n.', and repeats the request.

       In the following example, the user first types `q', which is
     invalid.  At the next prompt the user types `n'.  Note that we show
     successive lines of minibuffer prompts here.  In fact, only one
     will appear at any time.

          (y-or-n-p "Do you need a lift? ")

          ;; After evaluating the preceding expression, 
          ;; the following appears in the minibuffer:

          ---------- 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 ----------

* Function: yes-or-no-p PROMPT

       This function asks the user a question, expecting input in
     minibuffer.  It returns `t' if the user types `yes', `nil' if the
     user types `no'.  A return must be typed to end the response.
     Upper and lowercase are not equivalent.

       `yes-or-no-p' requires more work from the user than `y-or-n-p'
     and is used for correspondingly more critical actions.

       `yes-or-no-p' prints PROMPT in the echo area, followed by the
     string `(yes or no) '.  The user must type one of the expected
     responses; otherwise, the function responds `Please answer yes or
     no.', waits about two seconds and repeats the request.

     For example:
          (yes-or-no-p 
            "Do you really want to remove your entire directory? ")

          ;; After evaluating the preceding expression, 
          ;; the following appears in the minibuffer:

          ---------- Buffer: minibuffer ----------
          Do you really want to remove your entire directory? (yes or no) 
          ---------- Buffer: minibuffer ----------

     If the user first enters `y', which is invalid because it must be
     the entire word `yes', Emacs responds by erasing the `y' and
     displaying:

          ---------- Buffer: minibuffer ----------
          Please answer yes or no.
          Do you really want to remove your entire directory? (yes or no)
          ---------- Buffer: minibuffer ----------

▶1f◀
File: lispref  Node: Minibuffer Odds and Ends, Prev: Yes or No Queries, Up: Minibuffers

Minibuffer Odds and Ends
========================

Some basic operations and functions are defined here.

* Command: exit-minibuffer

       This function terminates the present minibuffer read.  It is only
     useful if bound to a key.

* Command: self-insert-and-exit

       This function terminates minibuffer input after inserting
     `last-command-char' (*Note Command Loop Info::).

Some objects are special to the minibuffer:

* Variable: minibuffer-help-form

       The global or ambient value of this variable is used to rebind
     `help-form' locally inside the minibuffer (*Note Help Functions::).

* Function: minibuffer-window

       This function returns the window that is used for the minibuffer.
     This is always the same window.  It cannot be deleted.

* Variable: minibuffer-scroll-window

       If the value of this built-in variable is non-`nil', it should be
     a window object.  When the function `scroll-other-window' is called
     in the minibuffer, Emacs will scroll the `minibuffer-scroll-window'
     window.

* Variable: minibuffer-local-map

       This variable is the default keymap Emacs uses as the local map
     when reading from the minibuffer.  By default, it makes the
     following bindings:


     LFD
          `exit-minibuffer'

     RET
          `exit-minibuffer'

     `C-g'
          `abort-recursive-edit'

     Almost all the examples in this chapter assume RET is bound to
     `exit-minibuffer'.  Some examples also assume DEL deletes the
     character before point.

Finally, some functions and variables deal with recursive minibuffers:

* Function: minibuffer-depth

       This function returns the current depth of activations of the
     minibuffer, a nonnegative integer.  If no minibuffers are active,
     it returns zero.

* User Option: enable-recursive-minibuffers

       If this variable is non-`nil', you can invoke commands, such as
     `find-file', which use minibuffers, while in the minbuffer window.
     This produces a recursive editing level for a new minbuffer.  The
     outer-level minibuffer is invisible while you are editing the inner
     one.

     This variable only affects invoking the minibuffer while in the
     minibuffer itself, since it is always possible to invoke a
     minibuffer from a different window, even if the minibuffer is
     active.

▶1f◀
File: lispref  Node: Command Loop, Prev: Minibuffers, Up: Top, Next: Keymaps

Command Loop
************

  When you run Emacs, it enters the "editing command loop" almost
immediately.  This loop reads key sequences, executes their definitions,
and displays the results.  In this chapter, we describe how these things
are done, and the subroutines which allow Lisp programs to do them.

* Menu:

* Command Overview::    
* Defining Commands::   
* Interactive Call::    
* Command Loop Info::   
* Keyboard Input::      
* Quitting::    
* Prefix Command Arguments::    
* Recursive Editing::   
* Disabling Commands::  
* Command History::     
* Keyboard Macros::     

▶1f◀
File: lispref  Node: Command Overview, Prev: Command Loop, Up: Command Loop, Next: Defining Commands

Command Loop Overview
=====================

  The first thing the command loop must do is read a key sequence, which
is a sequence of characters that translates into a command.  It does
this by calling the function `read-key-sequence'.  Your Lisp code can
call this function, too (*Note Keyboard Input::).  Lisp programs can
also do input at a lower level with `read-char' or discard the input
with `discard-input'.

  The key sequence is translated into a command through the keymaps.
*Note Keymaps::, for information on how this is done.  The result is a
keyboard macro or an interactively callable function, or a symbol which
leads to one of them.  If the key is `M-x', then it reads the name of
another command which is used instead.  This is done by the command
`execute-extended-command' (*Note Interactive Call::).

  Now it is time to execute the command, which includes reading
arguments to be given to it.  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 `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 the file name
string as an ordinary Lisp function argument.

  If the command is a string (i.e., a keyboard macro) then the function
`execute-keyboard-macro' is used to execute it.  You can call this
function yourself.  *Note Keyboard Macros::.

  If a command runs away, typing `C-g' will terminate its execution
immediately.  This is called "quitting" (*Note Quitting::).

▶1f◀
File: lispref  Node: Defining Commands, Prev: Command Overview, Up: Command Loop, Next: Interactive Call

Defining Commands
=================

  A Lisp function becomes a command when its body contains, at top
level, a form which calls the special form `interactive'.  This form
does nothing when actually executed, but its mere presence is a flag
noticed by the command loop, and its argument controls the reading of
arguments, with the minibuffer or otherwise.

* Menu:

* Using interactive::
* Interactive Codes::
* interactive Examples::        

▶1f◀
File: lispref  Node: Using interactive, Prev: Defining Commands, Up: Defining Commands, Next: Interactive Codes

Using `interactive'
-------------------

* Special form: interactive ARG-DESCRIPTOR

     This special form declares that the function in which it appears is
     a command, and therefore it may be called interactively (via `M-x'
     or by entering a key sequence bound to it).  ARG-DESCRIPTOR
     declares how the arguments to the command are to be computed when
     the command is called interactively.  The command may also be
     called from Lisp programs like any other function, but then the
     arguments are supplied by the caller, and ARG-DESCRIPTOR has no
     effect.

     The `interactive' form has its effect because the command loop
     (actually, its subroutine `call-interactively') scans through the
     function definition looking for it, before calling the function.
     Once the function is called, all its body forms including the
     `interactive' form are executed, but at this time `interactive'
     simply returns `nil' without even evaluating its argument.

There are three possibilities for the argument ARG-DESCRIPTOR:

   * It may be omitted or `nil'.  Then the command is called with no
     arguments.  This leads quickly to an error if the command requires
     one or more arguments.

   * It may be a Lisp expression which is not a string.  Then it must be
     a form which is evaluated to get a list of arguments to pass to the
     command.

   * It may be a string.  The string should consist of a code character,
     followed by a prompt (if required for that code character).  The
     prompt ends either with the end of the string or with a newline.
     Here is a simple example:

          (interactive "bFrobnicate buffer: ")

     The code letter `b' says to read the name of an existing buffer,
     with completion.  The buffer will be the sole argument passed to
     the command.  The rest of the string is a prompt.

     If the prompt ends with a newline, a second code character and
     prompt may follow, specifying a second argument.  Any number of
     arguments may be specified in this way.

     If the first character in the string is `*', then an error is
     signaled if the buffer is read-only.  Otherwise, the following
     character is the first code character.

▶1f◀
File: lispref  Node: Interactive Codes, Prev: Using interactive, Up: Defining Commands, Next: interactive Examples

Code Characters for `interactive'
---------------------------------

The code character descriptions below contain a number of key words with
the following meanings.

Completion
     Do completion.  TAB, SPC, and RET will perform name completion
     according to the function `completing-read' (*Note Completion::).

Existing
     Require the name of an existing object.  An incorrect name will not
     be accepted (Emacs will complain `[No Match]' and continue to
     prompt for a name).

Default
     A default string is supplied by Emacs, which depends on the code
     character.

Prompt
     A prompt immediatly follows the code character.  The prompt ends
     either with the end of the string or with a newline.

No I/O
     This code letter computes an argument without reading any input.
     Therefore, it does not use a prompt string, and any prompt string
     you supply is ignored.

Here are the code character descriptions for use with `interactive':

`a'
     A function name (i.e., a symbol which is `fboundp').  Existing,
     Completion, Prompt.

`b'
     The name of a buffer.  By default, its directory is the current
     buffer (*Note Buffers::).  Existing, Completion, Default, Prompt.

`B'
     The name of a buffer.  Completion, Prompt.

`c'
     A character.  The cursor does not move into the echo area.  Prompt.

`C'
     A command name (i.e., an interactive function).  Existing,
     Completion, Prompt.

`d'
     Use the position of the point as a number.  No I/O.

`D'
     A directory name.  Default is current directory associated with the
     current buffer (*Note Operating System Environment::).  Existing,
     Completion, Default, Prompt.

`f'
     A file name.  Default is the `default-directory'.  Existing,
     Completion, Default, Prompt.

`F'
     A file name.  The file need not exist.  Completion, Default,
     Prompt.

`k'
     A key sequence.  This keeps reading characters until a command (or
     undefined command) is found in the current key maps.  The key
     sequence is handed to the function as a string.  The cursor does
     not move into the echo area.  Prompt.

`m'
     The position of the mark as a number.  No I/O.

`n'
     The minibuffer is used to read a number.  If the input is not a
     number, the user is asked to try again.  The prefix argument, if
     any, is not used.  Prompt.

`N'
     The unprocessed prefix argument is passed to the function.  If the
     prefix argument is `nil', then a number is read as with `n'.
     Requires a number.  Prompt.

`p'
     (lower case) The processed prefix argument is passed to the
     function.  No I/O.

`P'
     (upper case) The unprocessed prefix argument is passed to the
     function.  No I/O.  *Note Prefix Command Arguments::

`r'
     The point and the mark are passed to the function as two numeric
     arguments, smallest first.  No I/O.

`s'
     A string is read, without quotes, terminated with either LFD or
     RET.  `C-q' may be used to include either into the string.  Prompt.

`S'
     A string is read, without quotes, terminated with any whitespace
     character, and it is interned as a symbol.  `C-q' may be used to
     include whitespace into the string.  Other characters which
     normally terminate a symbol (e.g., `()[]') do not do so here.
     Prompt.

`v'
     A variable declared to be a user option (i.e., satisfying
     `user-variable-p').  Existing, Completion, Prompt.

`x'
     A Lisp form is read and terminated with a LFD or RET.  The form is
     not evaluated.  Prompt.

`X'
     A Lisp form is read as with `x', but it is then evaluated and the
     result is passed to the function.  Prompt.

▶1f◀
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦a9d5a09d6⟧ TextFile

Derivation

TextFile
