(lispref.info)Text from Minibuffer


Next: Object from Minibuffer Prev: Intro to Minibuffers Up: Minibuffers

Reading Text Strings with the Minibuffer
========================================

   The minibuffer is usually used to read text which is returned as a
string, but can also be used to read a Lisp object in textual form.  The
most basic primitive for minibuffer input is `read-from-minibuffer'.

 - Function: read-from-minibuffer PROMPT-STRING &optional INITIAL
          KEYMAP READ HIST
     This function is the most general way to get input through the
     minibuffer.  By default, it accepts arbitrary text and returns it
     as a string; however, if READ is non-`nil', then it uses `read' to
     convert the text into a Lisp object (Note: Input Functions.).

     The first thing this function does is to activate a minibuffer and
     display it with PROMPT-STRING as the prompt.  This value must be a
     string.

     Then, if INITIAL is a string; its contents are inserted into the
     minibuffer as initial contents.  The text thus inserted is treated
     as if the user had inserted it; the user can alter it with Emacs
     editing commands.

     The value of INITIAL may also be a cons cell of the form `(STRING
     . POSITION)'.  This means to insert STRING in the minibuffer but
     put the cursor POSITION characters from the beginning, rather than
     at the end.

     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.  Specifying a keymap
     is the most important way to customize minibuffer input for
     various applications including completion.

     The argument HIST specifies which history list variable to use for
     saving the input and for history commands used in the minibuffer.
     It defaults to `minibuffer-history'.  Note: Minibuffer History.

     When the user types a command to exit the minibuffer, the current
     minibuffer contents are usually made into a string which becomes
     the value of `read-from-minibuffer'.  However, if READ is
     non-`nil', `read-from-minibuffer' converts the result to a Lisp
     object, and returns that object, unevaluated.

     Suppose, for example, you are writing a search command and want to
     record the last search string and provide it as a default for the
     next search.  Suppose that the previous search string is stored in
     the variable `last-search-string'.  Here is how you can read a
     search string while providing the previous string as initial input
     to be edited:

          (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)
          ---------- Buffer: Minibuffer ----------
          Find string: No-!-
          ---------- Buffer: Minibuffer ----------
          ;; The user now types `pe RET':
               => "Nope"

     This technique is no longer preferred for most applications; it is
     usually better to use a history list.

 - Function: read-string PROMPT &optional INITIAL
     This function reads a string from the minibuffer and returns it.
     The arguments PROMPT and INITIAL are used as in
     `read-from-minibuffer'.

     This is a simplified interface to the `read-from-minibuffer'
     function:

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

 - Variable: minibuffer-local-map
     This is the default local keymap for reading from the minibuffer.
     It is the keymap used by the minibuffer for local bindings in the
     function `read-string'.  By default, it makes the following
     bindings:

    LFD
          `exit-minibuffer'

    RET
          `exit-minibuffer'

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

    `M-n' and `M-p'
          `next-history-element' and `previous-history-element'

    `M-r'
          `next-matching-history-element'

    `M-s'
          `previous-matching-history-element'

 - Function: read-no-blanks-input PROMPT &optional INITIAL
     This function reads a string from the minibuffer, but does not
     allow whitespace characters as part of the input: instead, those
     characters terminate the input.  The arguments PROMPT and INITIAL
     are used as in `read-from-minibuffer'.

     This is a simplified interface to the `read-from-minibuffer'
     function, and passes the value of the `minibuffer-local-ns-map'
     keymap as the KEYMAP argument for that function.  Since the keymap
     `minibuffer-local-ns-map' does not rebind `C-q', it *is* possible
     to put a space into the string, by quoting it.

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

 - Variable: minibuffer-local-ns-map
     This built-in variable is the keymap used as the minibuffer local
     keymap in the function `read-no-blanks-input'.  By default, it
     makes the following bindings:

    LFD
          `exit-minibuffer'

    SPC
          `exit-minibuffer'

    TAB
          `exit-minibuffer'

    RET
          `exit-minibuffer'

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

    `?'
          `self-insert-and-exit'

    `M-n' and `M-p'
          `next-history-element' and `previous-history-element'

    `M-r'
          `next-matching-history-element'

    `M-s'
          `previous-matching-history-element'


automatically generated by info2www