diff options
Diffstat (limited to 'lisp/subr.el')
| -rw-r--r-- | lisp/subr.el | 156 |
1 files changed, 83 insertions, 73 deletions
diff --git a/lisp/subr.el b/lisp/subr.el index 99ddd813867..427014cedc3 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -45,7 +45,8 @@ declaration. A FILE with an \"ext:\" prefix is an external file. `check-declare' will check such files if they are found, and skip them without error if they are not. -Optional ARGLIST specifies FN's arguments, or is t to not specify +Optional ARGLIST specifies FN's arguments, in the same form as +in `defun' (including the parentheses); or it is t to not specify FN's arguments. An omitted ARGLIST defaults to t, not nil: a nil ARGLIST specifies an empty argument list, and an explicit t ARGLIST is a placeholder that allows supplying a later arg. @@ -828,7 +829,7 @@ of course, also replace TO with a slightly larger value If TREE is a cons cell, this recursively copies both its car and its cdr. Contrast to `copy-sequence', which copies only along the cdrs. With second argument VECP, this copies vectors as well as conses." - (declare (side-effect-free t)) + (declare (side-effect-free error-free)) (if (consp tree) (let (result) (while (consp tree) @@ -1554,31 +1555,32 @@ EVENT may be an event or an event type. If EVENT is a symbol that has never been used in an event that has been read as input in the current Emacs session, then this function may fail to include the `click' modifier." - (let ((type event)) - (if (listp type) - (setq type (car type))) - (if (symbolp type) - ;; Don't read event-symbol-elements directly since we're not - ;; sure the symbol has already been parsed. - (cdr (internal-event-symbol-parse-modifiers type)) - (let ((list nil) - (char (logand type (lognot (logior ?\M-\0 ?\C-\0 ?\S-\0 - ?\H-\0 ?\s-\0 ?\A-\0))))) - (if (not (zerop (logand type ?\M-\0))) - (push 'meta list)) - (if (or (not (zerop (logand type ?\C-\0))) - (< char 32)) - (push 'control list)) - (if (or (not (zerop (logand type ?\S-\0))) - (/= char (downcase char))) - (push 'shift list)) - (or (zerop (logand type ?\H-\0)) - (push 'hyper list)) - (or (zerop (logand type ?\s-\0)) - (push 'super list)) - (or (zerop (logand type ?\A-\0)) - (push 'alt list)) - list)))) + (unless (stringp event) + (let ((type event)) + (if (listp type) + (setq type (car type))) + (if (symbolp type) + ;; Don't read event-symbol-elements directly since we're not + ;; sure the symbol has already been parsed. + (cdr (internal-event-symbol-parse-modifiers type)) + (let ((list nil) + (char (logand type (lognot (logior ?\M-\0 ?\C-\0 ?\S-\0 + ?\H-\0 ?\s-\0 ?\A-\0))))) + (if (not (zerop (logand type ?\M-\0))) + (push 'meta list)) + (if (or (not (zerop (logand type ?\C-\0))) + (< char 32)) + (push 'control list)) + (if (or (not (zerop (logand type ?\S-\0))) + (/= char (downcase char))) + (push 'shift list)) + (or (zerop (logand type ?\H-\0)) + (push 'hyper list)) + (or (zerop (logand type ?\s-\0)) + (push 'super list)) + (or (zerop (logand type ?\A-\0)) + (push 'alt list)) + list))))) (defun event-basic-type (event) "Return the basic type of the given event (all modifiers removed). @@ -1586,17 +1588,18 @@ The value is a printing character (not upper case) or a symbol. EVENT may be an event or an event type. If EVENT is a symbol that has never been used in an event that has been read as input in the current Emacs session, then this function may return nil." - (if (consp event) - (setq event (car event))) - (if (symbolp event) - (car (get event 'event-symbol-elements)) - (let* ((base (logand event (1- ?\A-\0))) - (uncontrolled (if (< base 32) (logior base 64) base))) - ;; There are some numbers that are invalid characters and - ;; cause `downcase' to get an error. - (condition-case () - (downcase uncontrolled) - (error uncontrolled))))) + (unless (stringp event) + (if (consp event) + (setq event (car event))) + (if (symbolp event) + (car (get event 'event-symbol-elements)) + (let* ((base (logand event (1- ?\A-\0))) + (uncontrolled (if (< base 32) (logior base 64) base))) + ;; There are some numbers that are invalid characters and + ;; cause `downcase' to get an error. + (condition-case () + (downcase uncontrolled) + (error uncontrolled)))))) (defsubst mouse-movement-p (object) "Return non-nil if OBJECT is a mouse movement event." @@ -3233,34 +3236,40 @@ This function is used by the `interactive' code letter \"n\"." n)) (defvar read-char-choice-use-read-key nil - "Prefer `read-key' when reading a character by `read-char-choice'. -Otherwise, use the minibuffer. + "If non-nil, use `read-key' when reading a character by `read-char-choice'. +Otherwise, use the minibuffer (this is the default). -When using the minibuffer, the user is less constrained, and can -use the normal commands available in the minibuffer, and can, for -instance, switch to another buffer, do things there, and then -switch back again to the minibuffer before entering the -character. This is not possible when using `read-key', but using -`read-key' may be less confusing to some users.") +When reading via the minibuffer, you can use the normal commands +available in the minibuffer, and can, for instance, temporarily +switch to another buffer, do things there, and then switch back +to the minibuffer before entering the character. This is not +possible when using `read-key', but using `read-key' may be less +confusing to some users.") (defun read-char-choice (prompt chars &optional inhibit-keyboard-quit) - "Read and return one of CHARS, prompting for PROMPT. -Any input that is not one of CHARS is ignored. - -By default, the minibuffer is used to read the key -non-modally (see `read-char-from-minibuffer'). If + "Read and return one of the characters in CHARS, prompting with PROMPT. +CHARS should be a list of single characters. +The function discards any input character that is not one of CHARS, +and by default shows a message to the effect that it is not one of +the expected characters. + +By default, this function uses the minibuffer to read the key +non-modally (see `read-char-from-minibuffer'), and the optional +argument INHIBIT-KEYBOARD-QUIT is ignored. However, if `read-char-choice-use-read-key' is non-nil, the modal `read-key' -function is used instead (see `read-char-choice-with-read-key')." +function is used instead (see `read-char-choice-with-read-key'), +and INHIBIT-KEYBOARD-QUIT is passed to it." (if (not read-char-choice-use-read-key) (read-char-from-minibuffer prompt chars) (read-char-choice-with-read-key prompt chars inhibit-keyboard-quit))) (defun read-char-choice-with-read-key (prompt chars &optional inhibit-keyboard-quit) - "Read and return one of CHARS, prompting for PROMPT. + "Read and return one of the characters in CHARS, prompting with PROMPT. +CHARS should be a list of single characters. Any input that is not one of CHARS is ignored. If optional argument INHIBIT-KEYBOARD-QUIT is non-nil, ignore -`keyboard-quit' events while waiting for a valid input. +`keyboard-quit' events while waiting for valid input. If you bind the variable `help-form' to a non-nil value while calling this function, then pressing `help-char' @@ -3556,22 +3565,22 @@ Also discard all previous input in the minibuffer." (sit-for 2))) (defvar y-or-n-p-use-read-key nil - "Prefer `read-key' when answering a \"y or n\" question by `y-or-n-p'. -Otherwise, use the minibuffer. + "Use `read-key' when reading answers to \"y or n\" questions by `y-or-n-p'. +Otherwise, use the `read-from-minibuffer' to read the answers. -When using the minibuffer, the user is less constrained, and can -use the normal commands available in the minibuffer, and can, for -instance, switch to another buffer, do things there, and then -switch back again to the minibuffer before entering the -character. This is not possible when using `read-key', but using -`read-key' may be less confusing to some users.") +When reading via the minibuffer, you can use the normal commands +available in the minibuffer, and can, for instance, temporarily +switch to another buffer, do things there, and then switch back +to the minibuffer before entering the character. This is not +possible when using `read-key', but using `read-key' may be less +confusing to some users.") (defvar from--tty-menu-p nil "Non-nil means the current command was invoked from a TTY menu.") (defun use-dialog-box-p () - "Say whether the current command should prompt the user via a dialog box." + "Return non-nil if the current command should prompt the user via a dialog box." (and last-input-event ; not during startup - (or (listp last-nonmenu-event) ; invoked by a mouse event + (or (consp last-nonmenu-event) ; invoked by a mouse event from--tty-menu-p) ; invoked via TTY menu use-dialog-box)) @@ -7114,7 +7123,7 @@ CONDITION is either: - the symbol t, to always match, - the symbol nil, which never matches, - a regular expression, to match a buffer name, -- a predicate function that takes a buffer object and ARG as +- a predicate function that takes BUFFER-OR-NAME and ARG as arguments, and returns non-nil if the buffer matches, - a cons-cell, where the car describes how to interpret the cdr. The car can be one of the following: @@ -7140,8 +7149,8 @@ CONDITION is either: (string-match-p condition (buffer-name buffer))) ((pred functionp) (if (eq 1 (cdr (func-arity condition))) - (funcall condition buffer) - (funcall condition buffer arg))) + (funcall condition buffer-or-name) + (funcall condition buffer-or-name arg))) (`(major-mode . ,mode) (eq (buffer-local-value 'major-mode buffer) @@ -7164,12 +7173,13 @@ CONDITION is either: (funcall match (list condition)))) (defun match-buffers (condition &optional buffers arg) - "Return a list of buffers that match CONDITION. -See `buffer-match-p' for details on CONDITION. By default all -buffers are checked, this can be restricted by passing an -optional argument BUFFERS, set to a list of buffers to check. -ARG is passed to `buffer-match', for predicate conditions in -CONDITION." + "Return a list of buffers that match CONDITION, or nil if none match. +See `buffer-match-p' for various supported CONDITIONs. +By default all buffers are checked, but the optional +argument BUFFERS can restrict that: its value should be +an explicit list of buffers to check. +Optional argument ARG is passed to `buffer-match-p', for +predicate conditions in CONDITION." (let (bufs) (dolist (buf (or buffers (buffer-list))) (when (buffer-match-p condition (get-buffer buf) arg) |