Copyright (C) 2000-2012 |
GNU Info (elisp)High-Level CompletionHigh-Level Completion Functions -------------------------------- This section describes the higher-level convenient functions for reading certain sorts of names with completion. In most cases, you should not call these functions in the middle of a Lisp function. When possible, do all minibuffer input as part of reading the arguments for a command, in the `interactive' specification. Note: Defining Commands. - Function: read-buffer prompt &optional default existing This function reads the name of a buffer and returns it as a string. The argument DEFAULT is the default name to use, the value to return if the user exits with an empty minibuffer. If non-`nil', it should be a string or a buffer. It is mentioned in the prompt, but is not inserted in the minibuffer as initial input. If EXISTING is non-`nil', then the name specified must be that of an existing buffer. The usual commands to exit the minibuffer do not exit if the text is not valid, and <RET> does completion to attempt to find a valid name. (However, DEFAULT is not checked for validity; it is returned, whatever it is, if the user exits with the minibuffer empty.) In the following example, the user enters `minibuffer.t', and then types <RET>. The argument EXISTING is `t', and the only buffer name starting with the given input is `minibuffer.texi', so that name is the value. (read-buffer "Buffer name? " "foo" t) ;; After evaluation of the preceding expression, ;; the following prompt appears, ;; with an empty minibuffer: ---------- Buffer: Minibuffer ---------- Buffer name? (default foo) -!- ---------- Buffer: Minibuffer ---------- ;; The user types `minibuffer.t <RET>'. => "minibuffer.texi" - Variable: read-buffer-function This variable specifies how to read buffer names. For example, if you set this variable to `iswitchb-read-buffer', all Emacs commands that call `read-buffer' to read a buffer name will actually use the `iswitchb' package to read it. - Function: read-command prompt &optional default This function reads the name of a command and returns it as a Lisp symbol. The argument PROMPT is used as in `read-from-minibuffer'. Recall that a command is anything for which `commandp' returns `t', and a command name is a symbol for which `commandp' returns `t'. Note: Interactive Call. The argument DEFAULT specifies what to return if the user enters null input. It can be a symbol or a string; if it is a string, `read-command' interns it before returning it. If DEFAULT is `nil', that means no default has been specified; then if the user enters null input, the return value is `nil'. (read-command "Command name? ") ;; After evaluation of the preceding expression, ;; the following prompt appears with an empty minibuffer: ---------- Buffer: Minibuffer ---------- Command name? ---------- Buffer: Minibuffer ---------- If the user types `forward-c <RET>', then this function returns `forward-char'. The `read-command' function is a simplified interface to `completing-read'. It uses the variable `obarray' so as to complete in the set of extant Lisp symbols, and it uses the `commandp' predicate so as to accept only command names: (read-command PROMPT) == (intern (completing-read PROMPT obarray 'commandp t nil)) - Function: read-variable prompt &optional default This function reads the name of a user variable and returns it as a symbol. The argument DEFAULT specifies what to return if the user enters null input. It can be a symbol or a string; if it is a string, `read-variable' interns it before returning it. If DEFAULT is `nil', that means no default has been specified; then if the user enters null input, the return value is `nil'. (read-variable "Variable name? ") ;; After evaluation of the preceding expression, ;; the following prompt appears, ;; with an empty minibuffer: ---------- Buffer: Minibuffer ---------- Variable name? -!- ---------- Buffer: Minibuffer ---------- If the user then types `fill-p <RET>', `read-variable' returns `fill-prefix'. This function is similar to `read-command', but uses the predicate `user-variable-p' instead of `commandp': (read-variable PROMPT) == (intern (completing-read PROMPT obarray 'user-variable-p t nil)) See also the functions `read-coding-system' and `read-non-nil-coding-system', in Note: User-Chosen Coding Systems. automatically generated by info2www version 1.2.2.9 |