[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 99852fb867e 1/3: Merge from origin/emacs-30
|
From: |
Sean Whitton |
|
Subject: |
master 99852fb867e 1/3: Merge from origin/emacs-30 |
|
Date: |
Tue, 11 Mar 2025 22:10:05 -0400 (EDT) |
branch: master
commit 99852fb867e4d7d2090cbb82ff12d86d2a6ed9cc
Merge: 85b147d3210 894b0e3a2fe
Author: Sean Whitton <spwhitton@spwhitton.name>
Commit: Sean Whitton <spwhitton@spwhitton.name>
Merge from origin/emacs-30
894b0e3a2fe ; Adapt comment in tramp.el
cc87717fa07 Add keyword placeholder to tramp.el
7d0d61d8549 Rewrite ERT manual introduction
b2f124f2a88 ; cperl-mode.el: Don't misinterpret exec_fcn as keyword exec
59d1aac49df Document return values of the various read-* functions
---
doc/misc/ert.texi | 20 +++++++++++---------
lisp/auth-source.el | 2 +-
lisp/emacs-lisp/map-ynp.el | 3 +--
lisp/env.el | 2 +-
lisp/faces.el | 6 +++---
lisp/files-x.el | 10 +++++++---
lisp/files.el | 1 +
lisp/international/mule-cmds.el | 1 +
lisp/international/mule-diag.el | 1 +
lisp/language/japan-util.el | 3 ++-
lisp/minibuffer.el | 5 +++--
lisp/net/tramp.el | 8 +++++++-
lisp/progmodes/cperl-mode.el | 2 +-
lisp/replace.el | 2 +-
lisp/simple.el | 11 +++++++----
lisp/subr.el | 4 ++--
lisp/textmodes/string-edit.el | 3 +++
src/coding.c | 5 ++++-
src/lread.c | 6 +++---
src/minibuf.c | 4 ++--
.../cperl-mode-resources/cperl-indents.erts | 19 +++++++++++++++++++
21 files changed, 81 insertions(+), 37 deletions(-)
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.
-
-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.
+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 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 <michael.albinus@gmx.de>
;; 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
\\<minibuffer-local-must-match-map>\\[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;
+=-=-=