From e879070d8c329e4e7ccbd6687ef577589faedcf1 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 12 Jan 2016 21:00:19 +0200 Subject: [PATCH] Document changes in 'read-buffer' and 'read-buffer-function' * doc/lispref/minibuf.texi (High-Level Completion): Document the 4th argument to 'read-buffer' and 'read-buffer-function'. --- doc/lispref/minibuf.texi | 22 ++++++++++++++-------- etc/NEWS | 4 +++- 2 files changed, 17 insertions(+), 9 deletions(-) diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index bf9564627d6..ead4fe982dc 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -1236,14 +1236,14 @@ Lisp function. When possible, do all minibuffer input as part of reading the arguments for a command, in the @code{interactive} specification. @xref{Defining Commands}. -@defun read-buffer prompt &optional default require-match +@defun read-buffer prompt &optional default require-match predicate This function reads the name of a buffer and returns it as a string. -The argument @var{default} is the default name to use, the value to -return if the user exits with an empty minibuffer. If non-@code{nil}, -it should be a string, a list of strings, or a buffer. If it is -a list, the default value is the first element of this list. It is -mentioned in the prompt, but is not inserted in the minibuffer as -initial input. +It prompts with @var{prompt}. The argument @var{default} is the +default name to use, the value to return if the user exits with an +empty minibuffer. If non-@code{nil}, it should be a string, a list of +strings, or a buffer. If it is a list, the default value is the first +element of this list. It is mentioned in the prompt, but is not +inserted in the minibuffer as initial input. The argument @var{prompt} should be a string ending with a colon and a space. If @var{default} is non-@code{nil}, the function inserts it in @@ -1253,6 +1253,12 @@ the minibuffer with a default value (@pxref{Programming Tips}). The optional argument @var{require-match} has the same meaning as in @code{completing-read}. @xref{Minibuffer Completion}. +The optional argument @var{predicate}, if non-@code{nil}, specifies a +function to filter the buffers that should be considered: the function +will be called with every potential candidate as its argument, and +should return @code{nil} to reject the candidate, non-@code{nil} to +accept it. + In the following example, the user enters @samp{minibuffer.t}, and then types @key{RET}. The argument @var{require-match} is @code{t}, and the only buffer name starting with the given input is @@ -1287,7 +1293,7 @@ its usual work, with the same arguments passed to @code{read-buffer}. @defopt read-buffer-completion-ignore-case If this variable is non-@code{nil}, @code{read-buffer} ignores case -when performing completion. +when performing completion while reading the buffer name. @end defopt @defun read-command prompt &optional default diff --git a/etc/NEWS b/etc/NEWS index 9c416ae7070..029e9d8392f 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1221,7 +1221,9 @@ Use the INSIDE_EMACS environment variable instead. ** `save-excursion' does not save&restore the mark any more. Use `save-mark-and-excursion' if you want the old behavior. -** read-buffer-function can now be called with a 4th argument (`predicate'). ++++ +** `read-buffer' and `read-buffer-function' can now be called with a 4th +argument (`predicate'). ** completion-table-dynamic stays in the minibuffer. If you want the old behavior of calling the function in the buffer -- 2.39.5