Function: read-buffer

read-buffer is a function defined in minibuf.c.

Signature

(read-buffer PROMPT &optional DEF REQUIRE-MATCH PREDICATE)

Documentation

Read the name of a buffer and return it as a string.

Prompt with PROMPT, which should be a string ending with a colon and a space. Provides completion on buffer names the user types. Optional second arg DEF is value to return if user enters an empty line,
 instead of that empty string.
 If DEF is a list of default values, return its first element.
Optional third arg REQUIRE-MATCH has the same meaning as the
 REQUIRE-MATCH argument of completing-read.
Optional arg PREDICATE, if non-nil, is a function limiting the buffers that can be considered. It will be called with each potential candidate, in the form of either a string or a cons cell whose car is a string, and should return non-nil to accept the candidate for completion, nil otherwise. If read-buffer-completion-ignore-case is non-nil, completion ignores case while reading the buffer name. If read-buffer-function is non-nil, this works by calling it as a function, instead of the usual behavior.

Probably introduced at or before Emacs version 20.1.

Source Code

// Defined in /usr/src/emacs/src/minibuf.c
{
  Lisp_Object result;
  char *s;
  ptrdiff_t len;
  ptrdiff_t count = SPECPDL_INDEX ();

  if (BUFFERP (def))
    def = BVAR (XBUFFER (def), name);

  specbind (Qcompletion_ignore_case,
	    read_buffer_completion_ignore_case ? Qt : Qnil);

  if (NILP (Vread_buffer_function))
    {
      if (!NILP (def))
	{
	  /* A default value was provided: we must change PROMPT,
	     editing the default value in before the colon.  To achieve
	     this, we replace PROMPT with a substring that doesn't
	     contain the terminal space and colon (if present).  They
	     are then added back using Fformat.  */

	  if (STRINGP (prompt))
	    {
	      s = SSDATA (prompt);
	      len = SBYTES (prompt);
	      if (len >= 2 && s[len - 2] == ':' && s[len - 1] == ' ')
		len = len - 2;
	      else if (len >= 1 && (s[len - 1] == ':' || s[len - 1] == ' '))
		len--;

	      prompt = make_specified_string (s, -1, len,
					      STRING_MULTIBYTE (prompt));
	    }

	  prompt = CALLN (Ffuncall, intern("format-prompt"),
			  prompt,
			  CONSP (def) ? XCAR (def) : def);
	}

      result = Fcompleting_read (prompt, intern ("internal-complete-buffer"),
				 predicate, require_match, Qnil,
				 Qbuffer_name_history, def, Qnil);
    }
  else
    result = (NILP (predicate)
	      /* Partial backward compatibility for older read_buffer_functions
		 which don't expect a `predicate' argument.  */
	      ? call3 (Vread_buffer_function, prompt, def, require_match)
	      : call4 (Vread_buffer_function, prompt, def, require_match,
		       predicate));
  return unbind_to (count, result);
}