From: Eli Zaretskii Date: Mon, 10 Sep 2018 09:46:22 +0000 (+0300) Subject: Clarify documentation of functions reading character events X-Git-Tag: emacs-26.1.90~166 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=5cf282d65f10f59f7efa63359dfd2b2e124943da;p=emacs.git Clarify documentation of functions reading character events * doc/lispref/help.texi (Describing Characters): * doc/lispref/commands.texi (Keyboard Events) (Reading One Event, Classifying Events): Make the distinction between characters and character events more explicit. * src/keymap.c (Ftext_char_description) (Fsingle_key_description): * src/lread.c (Fread_char, Fread_char_exclusive): Doc fixes, to make a clear distinction between a character input event and a character code. (Bug#32562) --- diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi index 0753d6fb67c..3e74f05e4c8 100644 --- a/doc/lispref/commands.texi +++ b/doc/lispref/commands.texi @@ -1076,9 +1076,10 @@ the current Emacs session. If a symbol has not yet been so used, @cindex keyboard events There are two kinds of input you can get from the keyboard: ordinary -keys, and function keys. Ordinary keys correspond to characters; the -events they generate are represented in Lisp as characters. The event -type of a character event is the character itself (an integer); see +keys, and function keys. Ordinary keys correspond to (possibly +modified) characters; the events they generate are represented in Lisp +as characters. The event type of a character event is the character +itself (an integer), which might have some modifier bits set; see @ref{Classifying Events}. @cindex modifier bits (of input character) @@ -1123,7 +1124,7 @@ for @kbd{%} plus 2**26 @end ifnottex (assuming the terminal supports non-@acronym{ASCII} -control characters). +control characters), i.e.@: with the 27th bit set. @item shift The @@ -1133,8 +1134,8 @@ The @ifnottex 2**25 @end ifnottex -bit in the character code indicates an @acronym{ASCII} control -character typed with the shift key held down. +bit (the 26th bit) in the character event code indicates an +@acronym{ASCII} control character typed with the shift key held down. For letters, the basic code itself indicates upper versus lower case; for digits and punctuation, the shift key selects an entirely different @@ -1146,7 +1147,7 @@ character with a different basic code. In order to keep within the @ifnottex 2**25 @end ifnottex -bit for those characters. +bit for those character events. However, @acronym{ASCII} provides no way to distinguish @kbd{C-A} from @kbd{C-a}, so Emacs uses the @@ -1167,7 +1168,7 @@ The @ifnottex 2**24 @end ifnottex -bit in the character code indicates a character +bit in the character event code indicates a character typed with the hyper key held down. @item super @@ -1178,7 +1179,7 @@ The @ifnottex 2**23 @end ifnottex -bit in the character code indicates a character +bit in the character event code indicates a character typed with the super key held down. @item alt @@ -1189,9 +1190,9 @@ The @ifnottex 2**22 @end ifnottex -bit in the character code indicates a character typed with the alt key -held down. (The key labeled @key{Alt} on most keyboards is actually -treated as the meta key, not this.) +bit in the character event code indicates a character typed with the +alt key held down. (The key labeled @key{Alt} on most keyboards is +actually treated as the meta key, not this.) @end table It is best to avoid mentioning specific bit numbers in your program. @@ -1949,6 +1950,10 @@ Here are some examples: The modifiers list for a click event explicitly contains @code{click}, but the event symbol name itself does not contain @samp{click}. +Similarly, the modifiers list for an @acronym{ASCII} control +character, such as @samp{C-a}, contains @code{control}, even though +reading such an event via @code{read-char} will return the value 1 +with the control modifier bit removed. @end defun @defun event-basic-type event @@ -2545,17 +2550,31 @@ right-arrow function key: @end defun @defun read-char &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the +This function reads and returns a character input event. If the user generates an event which is not a character (i.e., a mouse click or function key event), @code{read-char} signals an error. The arguments work as in @code{read-event}. -In the first example, the user types the character @kbd{1} (@acronym{ASCII} -code 49). The second example shows a keyboard macro definition that -calls @code{read-char} from the minibuffer using @code{eval-expression}. -@code{read-char} reads the keyboard macro's very next character, which -is @kbd{1}. Then @code{eval-expression} displays its return value in -the echo area. +If the event has modifiers, Emacs attempts to resolve them and return +the code of the corresponding character. For example, if the user +types @kbd{C-a}, the function returns 1, which is the @acronym{ASCII} +code of the @samp{C-a} character. If some of the modifiers cannot be +reflected in the character code, @code{read-char} leaves the +unresolved modifier bits set in the returned event. For example, if +the user types @kbd{C-M-a}, the function returns 134217729, 8000001 in +hex, i.e.@: @samp{C-a} with the Meta modifier bit set. This value is +not a valid character code: it fails the @code{characterp} test +(@pxref{Character Codes}). Use @code{event-basic-type} +(@pxref{Classifying Events}) to recover the character code with the +modifier bits removed; use @code{event-modifiers} to test for +modifiers in the character event returned by @code{read-char}. + +In the first example below, the user types the character @kbd{1} +(@acronym{ASCII} code 49). The second example shows a keyboard macro +definition that calls @code{read-char} from the minibuffer using +@code{eval-expression}. @code{read-char} reads the keyboard macro's +very next character, which is @kbd{1}. Then @code{eval-expression} +displays its return value in the echo area. @example @group @@ -2577,10 +2596,11 @@ the echo area. @end defun @defun read-char-exclusive &optional prompt inherit-input-method seconds -This function reads and returns a character of command input. If the -user generates an event which is not a character, +This function reads and returns a character input event. If the +user generates an event which is not a character event, @code{read-char-exclusive} ignores it and reads another event, until it -gets a character. The arguments work as in @code{read-event}. +gets a character. The arguments work as in @code{read-event}. The +returned value may include modifier bits, as with @code{read-char}. @end defun None of the above functions suppress quitting. diff --git a/doc/lispref/help.texi b/doc/lispref/help.texi index 6dd55d0b256..a23bc413d25 100644 --- a/doc/lispref/help.texi +++ b/doc/lispref/help.texi @@ -556,13 +556,13 @@ brackets. @defun text-char-description character This function returns a string describing @var{character} in the -standard Emacs notation for characters that appear in text---like -@code{single-key-description}, except that control characters are -represented with a leading caret (which is how control characters in -Emacs buffers are usually displayed). Another difference is that -@code{text-char-description} recognizes the 2**7 bit as the Meta -character, whereas @code{single-key-description} uses the 2**27 bit -for Meta. +standard Emacs notation for characters that can appear in text---like +@code{single-key-description}, except that the argument must be a +valid character code that passes a @code{characterp} test +(@pxref{Character Codes}), control characters are represented with a +leading caret (which is how control characters in Emacs buffers are +usually displayed), and the 2**7 bit is treated as the Meta bit, +whereas @code{single-key-description} uses the 2**27 bit for Meta. @smallexample @group diff --git a/src/keymap.c b/src/keymap.c index c8cc933e782..ec483c7a632 100644 --- a/src/keymap.c +++ b/src/keymap.c @@ -2205,10 +2205,12 @@ push_key_description (EMACS_INT ch, char *p) DEFUN ("single-key-description", Fsingle_key_description, Ssingle_key_description, 1, 2, 0, - doc: /* Return a pretty description of command character KEY. + doc: /* Return a pretty description of a character event KEY. Control characters turn into C-whatever, etc. Optional argument NO-ANGLES non-nil means don't put angle brackets -around function keys and event symbols. */) +around function keys and event symbols. + +See `text-char-description' for describing character codes. */) (Lisp_Object key, Lisp_Object no_angles) { USE_SAFE_ALLOCA; @@ -2282,11 +2284,12 @@ push_text_char_description (register unsigned int c, register char *p) /* This function cannot GC. */ DEFUN ("text-char-description", Ftext_char_description, Stext_char_description, 1, 1, 0, - doc: /* Return a pretty description of file-character CHARACTER. -Control characters turn into "^char", etc. This differs from -`single-key-description' which turns them into "C-char". -Also, this function recognizes the 2**7 bit as the Meta character, -whereas `single-key-description' uses the 2**27 bit for Meta. + doc: /* Return the description of CHARACTER in standard Emacs notation. +CHARACTER must be a valid character code that passes the `characterp' test. +Control characters turn into "^char", the 2**7 bit is treated as Meta, etc. +This differs from `single-key-description' which accepts character events, +and thus doesn't enforce the `characterp' condition, turns control +characters into "C-char", and uses the 2**27 bit for Meta. See Info node `(elisp)Describing Characters' for examples. */) (Lisp_Object character) { diff --git a/src/lread.c b/src/lread.c index d5ba48a170d..2e5cba510c5 100644 --- a/src/lread.c +++ b/src/lread.c @@ -735,10 +735,14 @@ read_filtered_event (bool no_switch_frame, bool ascii_required, } DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0, - doc: /* Read a character from the command input (keyboard or macro). + doc: /* Read a character event from the command input (keyboard or macro). It is returned as a number. -If the character has modifiers, they are resolved and reflected to the -character code if possible (e.g. C-SPC -> 0). +If the event has modifiers, they are resolved and reflected in the +returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97). +If some of the modifiers cannot be reflected in the character code, the +returned value will include those modifiers, and will not be a valid +character code: it will fail the `characterp' test. Use `event-basic-type' +to recover the character code with the modifiers removed. If the user generates an event which is not a character (i.e. a mouse click or function key event), `read-char' signals an error. As an @@ -785,10 +789,14 @@ floating-point value. */) } DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0, - doc: /* Read a character from the command input (keyboard or macro). + doc: /* Read a character event from the command input (keyboard or macro). It is returned as a number. Non-character events are ignored. -If the character has modifiers, they are resolved and reflected to the -character code if possible (e.g. C-SPC -> 0). +If the event has modifiers, they are resolved and reflected in the +returned character code if possible (e.g. C-SPC yields 0 and C-a yields 97). +If some of the modifiers cannot be reflected in the character code, the +returned value will include those modifiers, and will not be a valid +character code: it will fail the `characterp' test. Use `event-basic-type' +to recover the character code with the modifiers removed. If the optional argument PROMPT is non-nil, display that as a prompt. If the optional argument INHERIT-INPUT-METHOD is non-nil and some