GNU Info

(elisp)Text from Minibuffer

---

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

---

Enter node , (file) or (file)node

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

   Most often, the minibuffer is used to read text as a string.  It can
also be used to read a Lisp object in textual form.  The most basic
primitive for minibuffer input is `read-from-minibuffer'; it can do
either one.

   In most cases, you should not call minibuffer input functions in the
middle of a Lisp function.  Instead, do all minibuffer input as part of
reading the arguments for a command, in the `interactive'
specification.  Note: Defining Commands.

 - Function: read-from-minibuffer prompt-string &optional
          initial-contents keymap read hist default inherit-input-method
     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 the user can edit text in the minibuffer.

     When the user types a command to exit the minibuffer,
     `read-from-minibuffer' constructs the return value from the text in
     the minibuffer.  Normally it returns a string containing that text.
     However, if READ is non-`nil', `read-from-minibuffer' reads the
     text and returns the resulting Lisp object, unevaluated.  (Note:
     Input Functions, for information about reading.)

     The argument DEFAULT specifies a default value to make available
     through the history commands.  It should be a string, or `nil'.  If
     READ is non-`nil', then DEFAULT is also used as the input to
     `read', if the user enters empty input.  However, in the usual
     case (where READ is `nil'), `read-from-minibuffer' does not return
     DEFAULT when the user enters empty input; it returns an empty
     string, `""'.  In this respect, it is different from all the other
     minibuffer input functions in this chapter.

     If KEYMAP is non-`nil', that keymap is the local keymap to use in
     the minibuffer.  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 the minibuffer for various
     applications such as 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.

     If the variable `minibuffer-allow-text-properties' is non-`nil',
     then the string which is returned includes whatever text
     properties were present in the minibuffer.  Otherwise all the text
     properties are stripped when the value is returned.

     If the argument INHERIT-INPUT-METHOD is non-`nil', then the
     minibuffer inherits the current input method (Note: Input
     Methods) and the setting of `enable-multibyte-characters' (Note:
     Text Representations) from whichever buffer was current before
     entering the minibuffer.

     If INITIAL-CONTENTS is a string, `read-from-minibuffer' inserts it
     into the minibuffer, leaving point at the end, before the user
     starts to edit the text.  The minibuffer appears with this text as
     its initial contents.

     Alternatively, INITIAL-CONTENTS can be a cons cell of the form
     `(STRING . POSITION)'.  This means to insert STRING in the
     minibuffer but put point POSITION characters from the beginning,
     rather than at the end.

     *Usage note:* The INITIAL-CONTENTS argument and the DEFAULT
     argument are two alternative features for more or less the same
     job.  It does not make sense to use both features in a single call
     to `read-from-minibuffer'.  In general, we recommend using
     DEFAULT, since this permits the user to insert the default value
     when it is wanted, but does not burden the user with deleting it
     from the minibuffer on other occasions.

 - Function: read-string prompt &optional initial history default
          inherit-input-method
     This function reads a string from the minibuffer and returns it.
     The arguments PROMPT and INITIAL are used as in
     `read-from-minibuffer'.  The keymap used is `minibuffer-local-map'.

     The optional argument HISTORY, if non-nil, specifies a history
     list and optionally the initial position in the list.  The optional
     argument DEFAULT specifies a default value to return if the user
     enters null input; it should be a string.  The optional argument
     INHERIT-INPUT-METHOD specifies whether to inherit the current
     buffer's input method.

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

          (read-string PROMPT INITIAL HISTORY DEFAULT INHERIT)
          ==
          (let ((value
                 (read-from-minibuffer PROMPT INITIAL nil nil
                                       HISTORY DEFAULT INHERIT)))
            (if (equal value "")
                DEFAULT
              value))

 - Variable: minibuffer-allow-text-properties
     If this variable is `nil', then `read-from-minibuffer' strips all
     text properties from the minibuffer input before returning it.
     Since all minibuffer input uses `read-from-minibuffer', this
     variable applies to all minibuffer input.

     Note that the completion functions discard text properties
     unconditionally, regardless of the value of this variable.

 - Variable: minibuffer-local-map
     This is the default local keymap for reading from the minibuffer.
     By default, it makes the following bindings:

    `C-j'
          `exit-minibuffer'

    <RET>
          `exit-minibuffer'

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

    `M-n'
          `next-history-element'

    `M-p'
          `previous-history-element'

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

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

 - Function: read-no-blanks-input prompt &optional initial
          inherit-input-method
     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, INITIAL, and
     INHERIT-INPUT-METHOD 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, in addition to those of
     `minibuffer-local-map':

    <SPC>
          `exit-minibuffer'

    <TAB>
          `exit-minibuffer'

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