Function: read-from-minibuffer

read-from-minibuffer is a function defined in minibuf.c.

Signature

(read-from-minibuffer PROMPT &optional INITIAL-CONTENTS KEYMAP READ HIST DEFAULT-VALUE INHERIT-INPUT-METHOD)

Documentation

Read and return a string from the minibuffer, prompting with string PROMPT.

The optional second arg INITIAL-CONTENTS is an obsolete alternative to
  DEFAULT-VALUE. It normally should be nil in new code, except when
  HIST is a cons. It is discussed in more detail below.

Third arg KEYMAP is a keymap to use whilst reading;
  if omitted or nil, the default is minibuffer-local-map.

If fourth arg READ is non-nil, interpret the result as a Lisp object
  and return that object:
  in other words, do (car (read-from-string INPUT-STRING))

Fifth arg HIST, if non-nil, specifies a history list and optionally
  the initial position in the list. It can be a symbol, which is the
  history list variable to use, or a cons cell (HISTVAR . HISTPOS).
  In that case, HISTVAR is the history list variable to use, and
  HISTPOS is the initial position for use by the minibuffer history
  commands. For consistency, you should also specify that element of
  the history as the value of INITIAL-CONTENTS. Positions are counted
  starting from 1 at the beginning of the list. If HIST is nil, the
  default history list minibuffer-history is used. If HIST is t,
  history is not recorded.

  If history-add-new-input is non-nil (the default), the result will
  be added to the history list using add-to-history.

Sixth arg DEFAULT-VALUE, if non-nil, should be a string, which is used
  as the default to read if READ is non-nil and the user enters
  empty input. But if READ is nil, this function does _not_ return
  DEFAULT-VALUE for empty input! Instead, it returns the empty string.

  Whatever the value of READ, DEFAULT-VALUE is made available via the
  minibuffer history commands. DEFAULT-VALUE can also be a list of
  strings, in which case all the strings are available in the history,
  and the first string is the default to read if READ is non-nil.

Seventh arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits
 the current input method and the setting of enable-multibyte-characters.

If the variable minibuffer-allow-text-properties is non-nil
 (either let-bound or buffer-local in the minibuffer),
 then the string which is returned includes whatever text properties
 were present in the minibuffer. Otherwise the value has no text properties.

If inhibit-interaction is non-nil, this function will signal an
  inhibited-interaction error.

The remainder of this documentation string describes the INITIAL-CONTENTS argument in more detail. It is only relevant when studying existing code, or when HIST is a cons. If non-nil, INITIAL-CONTENTS is a string to be inserted into the minibuffer before reading input. Normally, point is put at the end of that string. However, if INITIAL-CONTENTS is (STRING . POSITION), the initial input is STRING, but point is placed at _one-indexed_ position POSITION in the minibuffer. Any integer value less than or equal to one puts point at the beginning of the string. *Note* that this behavior differs from the way such arguments are used in completing-read and some related functions, which use zero-indexing for POSITION.

View in manual

Probably introduced at or before Emacs version 16.

Source Code

// Defined in /usr/src/emacs/src/minibuf.c
{
  Lisp_Object histvar, histpos, val;

  barf_if_interaction_inhibited ();

  CHECK_STRING (prompt);
  if (NILP (keymap))
    keymap = Vminibuffer_local_map;
  else
    keymap = get_keymap (keymap, 1, 0);

  if (SYMBOLP (hist))
    {
      histvar = hist;
      histpos = Qnil;
    }
  else
    {
      histvar = Fcar_safe (hist);
      histpos = Fcdr_safe (hist);
    }
  if (NILP (histvar))
    histvar = Qminibuffer_history;
  if (NILP (histpos))
    XSETFASTINT (histpos, 0);

#ifdef HAVE_TEXT_CONVERSION
  /* If overriding-text-conversion-style is set, assume that it was
     changed prior to this call and force text conversion to be reset,
     since redisplay might conclude that the value was retained
     unmodified from a previous call to Fread_from_minibuffer as the
     selected window will not have changed.  */
  if (!EQ (Voverriding_text_conversion_style, Qlambda)
      /* Separate minibuffer frames are not material here, since they
         will already be selected if the situation that this is meant to
         prevent is possible.  */
      && FRAME_WINDOW_P (SELECTED_FRAME ()))
    reset_frame_conversion (SELECTED_FRAME ());
#endif /* HAVE_TEXT_CONVERSION */

  val = read_minibuf (keymap, initial_contents, prompt,
		      !NILP (read),
		      histvar, histpos, default_value,
		      minibuffer_allow_text_properties,
		      !NILP (inherit_input_method));
  return val;
}