comparison src/minibuf.c @ 94528:ea7a33f062ae

(Fread_from_minibuffer, Fread_string, Fread_command) (Fread_variable, Fread_buffer, Fcompleting_read): Document the DEFAULT argument as a list of default values in docstrings.

94527:207661f84875

  (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.
Sixth arg DEFAULT-VALUE is the default value.  If non-nil, it is available
  for history commands; but, unless READ is non-nil, `read-from-minibuffer'
  does NOT return DEFAULT-VALUE if the user enters empty input!  It returns
  the empty string.
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,
 then the string which is returned includes whatever text properties
 were present in the minibuffer.  Otherwise the value has no text properties.

  be nil in new code.  It behaves as in `read-from-minibuffer'.  See the
  documentation string of that function for details.
The third arg HISTORY, if non-nil, specifies a history list
  and optionally the initial position in the list.
See `read-from-minibuffer' for details of HISTORY argument.
Fourth arg DEFAULT-VALUE is the default value.  If non-nil, it is used
 for history commands, and as the value to return if the user enters
 the empty string.
Fifth arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits
 the current input method and the setting of `enable-multibyte-characters'.  */)
     (prompt, initial_input, history, default_value, inherit_input_method)
     Lisp_Object prompt, initial_input, history, default_value;
     Lisp_Object inherit_input_method;

		       !NILP (inherit_input_method));
}

DEFUN ("read-command", Fread_command, Sread_command, 1, 2, 0,
       doc: /* Read the name of a command and return as a symbol.
Prompt with PROMPT.  By default, return DEFAULT-VALUE.  */)
     (prompt, default_value)
     Lisp_Object prompt, default_value;
{
  Lisp_Object name, default_string;

}
#endif /* NOTDEF */

DEFUN ("read-variable", Fread_variable, Sread_variable, 1, 2, 0,
       doc: /* Read the name of a user variable and return it as a symbol.
Prompt with PROMPT.  By default, return DEFAULT-VALUE.
A user variable is one for which `user-variable-p' returns non-nil.  */)
     (prompt, default_value)
     Lisp_Object prompt, default_value;
{
  Lisp_Object name, default_string;

DEFUN ("read-buffer", Fread_buffer, Sread_buffer, 1, 3, 0,
       doc: /* Read the name of a buffer and return as a string.
Prompt with PROMPT.
Optional second arg DEF is value to return if user enters an empty line.
If optional third arg REQUIRE-MATCH is non-nil,
 only existing buffer names are allowed.
The argument PROMPT should be a string ending with a colon and a space.  */)
     (prompt, def, require_match)
     Lisp_Object prompt, def, require_match;

- `confirm-only' means that the user can exit with any input, but she will
  need to confirm her choice if the input is not an element of COLLECTION.
- anything else behaves like t except that typing RET does not exit if it
  does non-null completion.

If the input is null, `completing-read' returns DEF, or an empty string
 if DEF is nil, regardless of the value of REQUIRE-MATCH.

If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
  with point positioned at the end.
  If it is (STRING . POSITION), the initial input is STRING, but point
  is placed at _zero-indexed_ position POSITION in STRING.  (*Note*

  INITIAL-INPUT.  (This is the only case in which you should use
  INITIAL-INPUT instead of DEF.)  Positions are counted starting from
  1 at the beginning of the list.  The variable `history-length'
  controls the maximum length of a history list.

DEF, if non-nil, is the default value.

If INHERIT-INPUT-METHOD is non-nil, the minibuffer inherits
  the current input method and the setting of `enable-multibyte-characters'.

Completion ignores case if the ambient value of

94528:ea7a33f062ae

  (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.
Sixth arg DEFAULT-VALUE is the default value or the list of default values.
  If non-nil, it is available for history commands, and as the value
  (or the first element of the list of default values) to return
  if the user enters the empty string.  But, unless READ is non-nil,
  `read-from-minibuffer' does NOT return DEFAULT-VALUE if the user enters
  empty input!  It returns the empty string.
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,
 then the string which is returned includes whatever text properties
 were present in the minibuffer.  Otherwise the value has no text properties.

  be nil in new code.  It behaves as in `read-from-minibuffer'.  See the
  documentation string of that function for details.
The third arg HISTORY, if non-nil, specifies a history list
  and optionally the initial position in the list.
See `read-from-minibuffer' for details of HISTORY argument.
Fourth arg DEFAULT-VALUE is the default value or the list of default values.
 If non-nil, it is used for history commands, and as the value (or the first
 element of the list of default values) to return if the user enters the
 empty string.
Fifth arg INHERIT-INPUT-METHOD, if non-nil, means the minibuffer inherits
 the current input method and the setting of `enable-multibyte-characters'.  */)
     (prompt, initial_input, history, default_value, inherit_input_method)
     Lisp_Object prompt, initial_input, history, default_value;
     Lisp_Object inherit_input_method;

		       !NILP (inherit_input_method));
}

DEFUN ("read-command", Fread_command, Sread_command, 1, 2, 0,
       doc: /* Read the name of a command and return as a symbol.
Prompt with PROMPT.  By default, return DEFAULT-VALUE or its first element
if it is a list.  */)
     (prompt, default_value)
     Lisp_Object prompt, default_value;
{
  Lisp_Object name, default_string;

}
#endif /* NOTDEF */

DEFUN ("read-variable", Fread_variable, Sread_variable, 1, 2, 0,
       doc: /* Read the name of a user variable and return it as a symbol.
Prompt with PROMPT.  By default, return DEFAULT-VALUE or its first element
if it is a list.
A user variable is one for which `user-variable-p' returns non-nil.  */)
     (prompt, default_value)
     Lisp_Object prompt, default_value;
{
  Lisp_Object name, default_string;

DEFUN ("read-buffer", Fread_buffer, Sread_buffer, 1, 3, 0,
       doc: /* Read the name of a buffer and return as a string.
Prompt with PROMPT.
Optional second arg DEF is value to return if user enters an empty line.
 If DEF is a list of default values, return its first element.
If optional third arg REQUIRE-MATCH is non-nil,
 only existing buffer names are allowed.
The argument PROMPT should be a string ending with a colon and a space.  */)
     (prompt, def, require_match)
     Lisp_Object prompt, def, require_match;

- `confirm-only' means that the user can exit with any input, but she will
  need to confirm her choice if the input is not an element of COLLECTION.
- anything else behaves like t except that typing RET does not exit if it
  does non-null completion.

If the input is null, `completing-read' returns DEF, or the first element
of the list of default values, or an empty string if DEF is nil,
regardless of the value of REQUIRE-MATCH.

If INITIAL-INPUT is non-nil, insert it in the minibuffer initially,
  with point positioned at the end.
  If it is (STRING . POSITION), the initial input is STRING, but point
  is placed at _zero-indexed_ position POSITION in STRING.  (*Note*

  INITIAL-INPUT.  (This is the only case in which you should use
  INITIAL-INPUT instead of DEF.)  Positions are counted starting from
  1 at the beginning of the list.  The variable `history-length'
  controls the maximum length of a history list.

DEF, if non-nil, is the default value or the list of default values.

If INHERIT-INPUT-METHOD is non-nil, the minibuffer inherits
  the current input method and the setting of `enable-multibyte-characters'.

Completion ignores case if the ambient value of