diff --git a/doc/misc/ert.texi b/doc/misc/ert.texi index 3fa3019f266..0e3aecdf313 100644 --- a/doc/misc/ert.texi +++ b/doc/misc/ert.texi @@ -46,15 +46,17 @@ modify this GNU manual.'' @insertcopying ERT is a tool for automated testing in Emacs Lisp. Its main features -are facilities for defining tests, running them and reporting the -results, and for debugging test failures interactively. +are facilities for defining and running tests, reporting results, and +debugging test failures interactively. Tests are written in Emacs Lisp, +just like the code under test, making it easy to write expressive and +concise test cases. -ERT is similar to tools for other environments such as JUnit, but has -unique features that take advantage of the dynamic and interactive -nature of Emacs. Despite its name, it works well both for test-driven -development (see -@url{https://en.wikipedia.org/wiki/Test-driven_development}) and for -traditional software development methods. +ERT has unique features that take advantage of the dynamic and +interactive nature of Emacs. It is unopinionated about when or how +tests are written: you can use it to verify newly written code, +reproduce known bugs, prevent regressions, or explore the behavior of +complex systems. It can be used for both unit tests and larger +integration tests. @menu * Introduction:: A simple example of an ERT test. diff --git a/lisp/auth-source.el b/lisp/auth-source.el index 6d53960e9a0..06f23af5b11 100644 --- a/lisp/auth-source.el +++ b/lisp/auth-source.el @@ -2547,7 +2547,7 @@ Adapt also mode line." ;;;###autoload (defun read-passwd (prompt &optional confirm default) - "Read a password, prompting with PROMPT, and return it. + "Read a password, prompting with PROMPT, and return password as a string. If optional CONFIRM is non-nil, read the password twice to make sure. Optional DEFAULT is a default password to use instead of empty input. diff --git a/lisp/emacs-lisp/map-ynp.el b/lisp/emacs-lisp/map-ynp.el index 18277b60fb8..952497032a2 100644 --- a/lisp/emacs-lisp/map-ynp.el +++ b/lisp/emacs-lisp/map-ynp.el @@ -326,6 +326,7 @@ variable." (defun read-answer (question answers) "Read an answer either as a complete word or its character abbreviation. Ask user a question and accept an answer from the list of possible answers. +Return the long answer even when accepting short ones. QUESTION should end in a space; this function adds a list of answers to it. @@ -349,8 +350,6 @@ Example: When `read-answer-short' is non-nil, accept short answers. -Return a long answer even in case of accepting short ones. - When `use-dialog-box' is t, pop up a dialog window to get user input." (let* ((short (if (eq read-answer-short 'auto) (or use-short-answers diff --git a/lisp/env.el b/lisp/env.el index 288f7e224d7..9e8b7f53a11 100644 --- a/lisp/env.el +++ b/lisp/env.el @@ -38,7 +38,7 @@ (defvar read-envvar-name-history nil) (defun read-envvar-name (prompt &optional mustmatch) - "Read environment variable name, prompting with PROMPT. + "Read and return an environment variable name string, prompting with PROMPT. Optional second arg MUSTMATCH, if non-nil, means require existing envvar name. If it is also not t, RET does not exit if it does non-null completion." (completing-read prompt diff --git a/lisp/faces.el b/lisp/faces.el index dd8c24f5001..e699e9f243b 100644 --- a/lisp/faces.el +++ b/lisp/faces.el @@ -1095,7 +1095,7 @@ of the default face. Value is FACE." "Text string to display as the sample text for `read-face-name'.") (defun read-face-name (prompt &optional default multiple) - "Read one or more face names, prompting with PROMPT. + "Read and return one or more face names, strings, prompting with PROMPT. PROMPT should not end in a space or a colon. If DEFAULT is non-nil, it should be a face (a symbol) or a face @@ -1373,7 +1373,7 @@ of a global face. Value is the new attribute value." (pattern &optional face frame maximum width)) (defun read-face-font (face &optional frame) - "Read the name of a font for FACE on FRAME. + "Read and return the string name of the font for FACE on FRAME. If optional argument FRAME is nil or omitted, use the selected frame." (let ((completion-ignore-case t)) (completing-read (format-message @@ -1981,7 +1981,7 @@ If omitted or nil, that stands for the selected frame's display." (defun read-color (&optional prompt convert-to-RGB allow-empty-name msg foreground face) - "Read a color name or RGB triplet. + "Read a color name or RGB triplet, return a string, the color name or RGB. Completion is available for color names, but not for RGB triplets. RGB triplets have the form \"#RRGGBB\". Each of the R, G, and B diff --git a/lisp/files-x.el b/lisp/files-x.el index 3f57321eb53..ee15993978b 100644 --- a/lisp/files-x.el +++ b/lisp/files-x.el @@ -38,7 +38,9 @@ ;;; Commands to add/delete file-local/directory-local variables. (defun read-file-local-variable (prompt) - "Read file-local variable using PROMPT and completion. + "Read the name of a file-local variable using PROMPT and completion. +Return the symbol of the variable, or nil if the user entered empty or +null name. Intended to be used in the `interactive' spec of `add-file-local-variable', `delete-file-local-variable', `add-dir-local-variable', `delete-dir-local-variable'." @@ -57,7 +59,7 @@ Intended to be used in the `interactive' spec of (and (stringp variable) (intern variable)))) (defun read-file-local-variable-value (variable) - "Read value of file-local VARIABLE using completion. + "Read and return the value of a file-local VARIABLE using completion. Intended to be used in the `interactive' spec of `add-file-local-variable' and `add-dir-local-variable'." (cond @@ -90,7 +92,9 @@ Intended to be used in the `interactive' spec of default))))) (defun read-file-local-variable-mode () - "Read per-directory file-local variable's mode using completion. + "Read the name of a per-directory file-local variable's mode using completion. +Return the symbol of the variable, or nil if the user entered empty or +null name. Intended to be used in the `interactive' spec of `add-dir-local-variable', `delete-dir-local-variable'." (let* ((default (and (symbolp major-mode) (symbol-name major-mode))) diff --git a/lisp/files.el b/lisp/files.el index aa4da83bfe0..cc1efdf836c 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -888,6 +888,7 @@ DEFAULT-DIRNAME specifies the default directory name to return if user exits with the same non-empty string that was inserted by this function. (If DEFAULT-DIRNAME is omitted, DIR combined with INITIAL is used, or just DIR if INITIAL is nil.) +Return the directory as a string. If the user exits with an empty minibuffer, return an empty string. (This can happen only if the user erased the pre-inserted diff --git a/lisp/international/mule-cmds.el b/lisp/international/mule-cmds.el index 6a4bc590922..f23ea4c5ed7 100644 --- a/lisp/international/mule-cmds.el +++ b/lisp/international/mule-cmds.el @@ -1673,6 +1673,7 @@ This is a subroutine for `describe-input-method'." (defun read-multilingual-string (prompt &optional initial-input input-method) "Read a multilingual string from minibuffer, prompting with string PROMPT. +Return the string thus read. The input method selected last time is activated in minibuffer. If optional second argument INITIAL-INPUT is non-nil, insert it in the minibuffer initially. diff --git a/lisp/international/mule-diag.el b/lisp/international/mule-diag.el index 2a21d969572..c12956112cd 100644 --- a/lisp/international/mule-diag.el +++ b/lisp/international/mule-diag.el @@ -206,6 +206,7 @@ Character sets for defining other charsets, or for backward compatibility (defun read-charset (prompt &optional default-value initial-input) "Read a character set from the minibuffer, prompting with string PROMPT. It must be an Emacs character set listed in the variable `charset-list'. +Return the charset as a symbol. Optional arguments are DEFAULT-VALUE and INITIAL-INPUT. DEFAULT-VALUE, if non-nil, is the default value. diff --git a/lisp/language/japan-util.el b/lisp/language/japan-util.el index c61e98c8fca..718c469d562 100644 --- a/lisp/language/japan-util.el +++ b/lisp/language/japan-util.el @@ -317,7 +317,8 @@ Optional argument KATAKANA-ONLY non-nil means to convert only KATAKANA char." ;;;###autoload (defun read-hiragana-string (prompt &optional initial-input) "Read a Hiragana string from the minibuffer, prompting with string PROMPT. -If non-nil, second arg INITIAL-INPUT is a string to insert before reading." +If non-nil, second arg INITIAL-INPUT is a string to insert before reading. +Return the string read from the minibuffer." (read-multilingual-string prompt initial-input "japanese-hiragana")) ;; diff --git a/lisp/minibuffer.el b/lisp/minibuffer.el index 01aae53ece5..66b5e6b4d19 100644 --- a/lisp/minibuffer.el +++ b/lisp/minibuffer.el @@ -3174,7 +3174,7 @@ with `minibuffer-local-must-match-map'." "?" #'self-insert-and-exit) (defun read-no-blanks-input (prompt &optional initial inherit-input-method) - "Read a string from the terminal, not allowing blanks. + "Read and return a string from the terminal, not allowing blanks. Prompt with PROMPT. Whitespace terminates the input. If INITIAL is non-nil, it should be a string, which is used as initial input, with point positioned at the end, so that SPACE will accept the input. @@ -3556,7 +3556,8 @@ like the `beginning-of-buffer' command." (if (listp default) default (list default))))) (defun read-file-name (prompt &optional dir default-filename mustmatch initial predicate) - "Read file name, prompting with PROMPT and completing in directory DIR. + "Read a file name, prompting with PROMPT and completing in directory DIR. +Retrun the file name as a string. The return value is not expanded---you must call `expand-file-name' yourself. diff --git a/lisp/net/tramp.el b/lisp/net/tramp.el index e66693d51f6..190e1871234 100644 --- a/lisp/net/tramp.el +++ b/lisp/net/tramp.el @@ -7,9 +7,15 @@ ;; Maintainer: Michael Albinus ;; Keywords: comm, processes ;; Package: tramp +;; Version: 0 +;; Package-Requires: () +;; Package-Type: multi +;; URL: https://www.gnu.org/software/tramp/ -;; This is a GNU ELPA :core package. Avoid functionality that is not +;; This is also a GNU ELPA package. Avoid functionality that is not ;; compatible with the version of Emacs recorded in trampver.el. +;; Version and Package-Requires are place holders. They are updated +;; when the GNU ELPA package is released. ;; This file is part of GNU Emacs. diff --git a/lisp/progmodes/cperl-mode.el b/lisp/progmodes/cperl-mode.el index 388c47d2158..7052ac75817 100644 --- a/lisp/progmodes/cperl-mode.el +++ b/lisp/progmodes/cperl-mode.el @@ -5607,7 +5607,7 @@ Do not look before LIM." (forward-sexp -1) (not (looking-at - "\\(map\\|grep\\|say\\|printf?\\|system\\|exec\\|tr\\|s\\)\\>"))))))) + "\\(map\\|grep\\|say\\|printf?\\|system\\|exec\\|tr\\|s\\)\\_>"))))))) (defun cperl-indent-exp () diff --git a/lisp/replace.el b/lisp/replace.el index acb0e340266..2d64612f0fc 100644 --- a/lisp/replace.el +++ b/lisp/replace.el @@ -929,7 +929,7 @@ regexp from the user." (or result input)))) (defun read-regexp-case-fold-search (regexp) - "Return a value for `case-fold-search' based on REGEXP and current settings. + "Return the value for `case-fold-search' based on REGEXP and current settings. REGEXP is a string as returned by `read-regexp'." (let ((fold (get-text-property 0 'case-fold regexp))) (cond diff --git a/lisp/simple.el b/lisp/simple.el index 7fc9f149718..df8f8276812 100644 --- a/lisp/simple.el +++ b/lisp/simple.el @@ -2276,7 +2276,7 @@ This is used by the \\\\[execute-extended-comma "Minor mode used for completion in `read-extended-command'.") (defun read-extended-command (&optional prompt) - "Read command name to invoke via `execute-extended-command'. + "Read and return name of command to invoke via `execute-extended-command'. Use `read-extended-command-predicate' to determine which commands to include among completion candidates. @@ -4311,7 +4311,7 @@ after the default value." "Keymap used for completing shell commands in minibuffer.") (defun read-shell-command (prompt &optional initial-contents hist &rest args) - "Read a shell command from the minibuffer. + "Read a shell command from the minibuffer, and return it as a string. The arguments are the same as the ones of `read-from-minibuffer', except READ and KEYMAP are missing and HIST defaults to `shell-command-history'." @@ -6461,7 +6461,8 @@ variable to determine how strings should be escaped." (defvar read-from-kill-ring-history) (defun read-from-kill-ring (prompt) "Read a `kill-ring' entry using completion and minibuffer history. -PROMPT is a string to prompt with." +PROMPT is a string to prompt with. +Return the entry as a string." ;; `current-kill' updates `kill-ring' with a possible interprogram-paste (current-kill 0) (let* ((history-add-new-input nil) @@ -11298,7 +11299,9 @@ killed." (string= string "")) (defun read-signal-name () - "Read a signal number or name." + "Read a signal number or name. +Return the signal number, if the user entered a number, otherwise +the signal symbol." (let ((value (completing-read "Signal code or name: " (signal-names) diff --git a/lisp/subr.el b/lisp/subr.el index 932a22d3250..c027fea5caa 100644 --- a/lisp/subr.el +++ b/lisp/subr.el @@ -3409,7 +3409,7 @@ miscellaneous values associated with the process." (defvar read-key-delay 0.01) ;Fast enough for 100Hz repeat rate, hopefully. (defun read-key (&optional prompt disable-fallbacks) - "Read a key from the keyboard. + "Read a key from the keyboard, return the event thus read. Contrary to `read-event' this will not return a raw event but instead will obey the input decoding and translations usually done by `read-key-sequence'. So escape sequences and keyboard encoding are taken into account. @@ -3531,7 +3531,7 @@ with Emacs. Do not call it directly in your own packages." "The default history for the `read-number' function.") (defun read-number (prompt &optional default hist) - "Read a numeric value in the minibuffer, prompting with PROMPT. + "Read from the minibuffer and return a numeric value, prompting with PROMPT. DEFAULT specifies a default value to return if the user just types RET. For historical reasons, the value of DEFAULT is always inserted into PROMPT, so it's recommended to use `format' instead of `format-prompt' diff --git a/lisp/textmodes/string-edit.el b/lisp/textmodes/string-edit.el index 1188a965f6f..3c76db202c7 100644 --- a/lisp/textmodes/string-edit.el +++ b/lisp/textmodes/string-edit.el @@ -92,6 +92,9 @@ PROMPT will be inserted at the start of the buffer, but won't be included in the resulting string. If nil, no prompt will be inserted in the buffer. +When the user exits recursive edit, this function returns the +edited STRING. + Also see `string-edit'." (string-edit prompt diff --git a/src/coding.c b/src/coding.c index 4f7cf23e96e..b0bd5d3a9ab 100644 --- a/src/coding.c +++ b/src/coding.c @@ -8625,7 +8625,8 @@ about coding-system objects. */) DEFUN ("read-non-nil-coding-system", Fread_non_nil_coding_system, Sread_non_nil_coding_system, 1, 1, 0, - doc: /* Read a coding system from the minibuffer, prompting with string PROMPT. */) + doc: /* Read a coding system from the minibuffer, prompting with string PROMPT. +Return the symbol of the coding-system. */) (Lisp_Object prompt) { Lisp_Object val; @@ -8641,6 +8642,8 @@ DEFUN ("read-non-nil-coding-system", Fread_non_nil_coding_system, DEFUN ("read-coding-system", Fread_coding_system, Sread_coding_system, 1, 2, 0, doc: /* Read a coding system from the minibuffer, prompting with string PROMPT. If the user enters null input, return second argument DEFAULT-CODING-SYSTEM. +Return the coding-system's symbol, or nil if both the user input and +DEFAULT-CODING-SYSTEM are empty or null. Ignores case when completing coding systems (all Emacs coding systems are lower-case). */) (Lisp_Object prompt, Lisp_Object default_coding_system) diff --git a/src/lread.c b/src/lread.c index d45860fd470..add8deb3954 100644 --- a/src/lread.c +++ b/src/lread.c @@ -855,7 +855,7 @@ read_filtered_event (bool no_switch_frame, bool ascii_required, DEFUN ("read-char", Fread_char, Sread_char, 0, 3, 0, doc: /* Read a character event from the command input (keyboard or macro). -It is returned as a number. +Return the character as a number. 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 @@ -903,7 +903,7 @@ If `inhibit-interaction' is non-nil, this function will signal an } DEFUN ("read-event", Fread_event, Sread_event, 0, 3, 0, - doc: /* Read an event object from the input stream. + doc: /* Read and return an event object from the input stream. If you want to read non-character events, consider calling `read-key' instead. `read-key' will decode events via `input-decode-map' that @@ -939,7 +939,7 @@ If `inhibit-interaction' is non-nil, this function will signal an DEFUN ("read-char-exclusive", Fread_char_exclusive, Sread_char_exclusive, 0, 3, 0, doc: /* Read a character event from the command input (keyboard or macro). -It is returned as a number. Non-character events are ignored. +Return the character as a number. Non-character events are ignored. 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 diff --git a/src/minibuf.c b/src/minibuf.c index 720172a3aa4..b0d54bd51f0 100644 --- a/src/minibuf.c +++ b/src/minibuf.c @@ -1296,7 +1296,7 @@ barf_if_interaction_inhibited (void) DEFUN ("read-from-minibuffer", Fread_from_minibuffer, Sread_from_minibuffer, 1, 7, 0, - doc: /* Read a string from the minibuffer, prompting with string PROMPT. + doc: /* Read and return a string from the minibuffer, prompting with string PROMPT. The optional second arg INITIAL-CONTENTS is an obsolete alternative to DEFAULT-VALUE. It normally should be nil in new code, except when HIST is a cons. It is discussed in more detail below. @@ -1448,7 +1448,7 @@ inherits the current input method and the setting of } DEFUN ("read-command", Fread_command, Sread_command, 1, 2, 0, - doc: /* Read the name of a command and return as a symbol. + doc: /* Read the name of a command and return it as a symbol. Prompt with PROMPT. By default, return DEFAULT-VALUE or its first element if it is a list. If DEFAULT-VALUE is omitted or nil, and the user enters null input, return a symbol whose name is an empty string. */) diff --git a/test/lisp/progmodes/cperl-mode-resources/cperl-indents.erts b/test/lisp/progmodes/cperl-mode-resources/cperl-indents.erts index ba35b1d0690..ab00e9ce6d4 100644 --- a/test/lisp/progmodes/cperl-mode-resources/cperl-indents.erts +++ b/test/lisp/progmodes/cperl-mode-resources/cperl-indents.erts @@ -79,3 +79,22 @@ class C say "done!"; =-=-= + +Name: cperl-keyword-in-subname + +=-= +# Bug#76851 +sub exec_fcn { +} + +sub other { +} +=-=-= + +Name: cperl-keyword-without-space + +=-= +# Bug#76851, message #13 +my %h = map{$_=>1} + @ARGV; +=-=-=