[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/compat eea73e19ce 5/5: Rename :explicit to :extended
|
From: |
ELPA Syncer |
|
Subject: |
[elpa] externals/compat eea73e19ce 5/5: Rename :explicit to :extended |
|
Date: |
Sat, 21 Jan 2023 15:57:25 -0500 (EST) |
branch: externals/compat
commit eea73e19cea65b4d309724c13920ba7c184f1ab7
Author: Daniel Mendler <mail@daniel-mendler.de>
Commit: Daniel Mendler <mail@daniel-mendler.de>
Rename :explicit to :extended
---
compat-25.el | 2 +-
compat-26.el | 12 ++++++------
compat-27.el | 22 +++++++++++-----------
compat-28.el | 8 ++++----
compat-29.el | 10 +++++-----
compat-macs.el | 30 +++++++++++++++---------------
compat.el | 17 +++++++++--------
compat.texi | 44 ++++++++++++++++++++++----------------------
8 files changed, 73 insertions(+), 72 deletions(-)
diff --git a/compat-25.el b/compat-25.el
index 4fa47b6898..e710f86452 100644
--- a/compat-25.el
+++ b/compat-25.el
@@ -43,7 +43,7 @@ usage: (bool-vector &rest OBJECTS)"
(compat-defun sort (seq predicate) ;; <compat-tests:sort>
"Handle vector SEQ."
- :explicit t
+ :extended t
(cond
((listp seq)
(sort seq predicate))
diff --git a/compat-26.el b/compat-26.el
index ce23d9ca80..1a370c20cc 100644
--- a/compat-26.el
+++ b/compat-26.el
@@ -51,7 +51,7 @@ SEQUENCE may be a list, a vector, a boolean vector, or a
string."
(compat-defun line-number-at-pos (&optional position absolute) ;;
<compat-tests:line-number-at-pos>
"Handle optional argument ABSOLUTE."
- :explicit t
+ :extended t
(if absolute
(save-restriction
(widen)
@@ -91,7 +91,7 @@ If you just want to check `major-mode', use `derived-mode-p'."
(compat-defun assoc (key alist &optional testfn) ;; <compat-tests:assoc>
"Handle the optional TESTFN."
- :explicit t
+ :extended t
(if testfn
(catch 'found
(dolist (ent alist)
@@ -101,7 +101,7 @@ If you just want to check `major-mode', use
`derived-mode-p'."
(compat-defun alist-get (key alist &optional default remove testfn) ;;
<compat-tests:alist-get>
"Handle optional argument TESTFN."
- :explicit "25.1"
+ :extended "25.1"
(ignore remove)
(let ((x (if (not testfn)
(assq key alist)
@@ -142,14 +142,14 @@ If you just want to check `major-mode', use
`derived-mode-p'."
(compat-defun string-trim-left (string &optional regexp) ;;
<compat-tests:string-trim-left>
"Handle optional argument REGEXP."
- :explicit t
+ :extended t
(if (string-match (concat "\\`\\(?:" (or regexp "[ \t\n\r]+") "\\)") string)
(substring string (match-end 0))
string))
(compat-defun string-trim-right (string &optional regexp) ;;
<compat-tests:string-trim-right>
"Handle optional argument REGEXP."
- :explicit t
+ :extended t
(let ((i (string-match-p
(concat "\\(?:" (or regexp "[ \t\n\r]+") "\\)\\'")
string)))
@@ -157,7 +157,7 @@ If you just want to check `major-mode', use
`derived-mode-p'."
(compat-defun string-trim (string &optional trim-left trim-right) ;;
<compat-tests:string-trim>
"Handle optional arguments TRIM-LEFT and TRIM-RIGHT."
- :explicit t
+ :extended t
(compat--string-trim-left
(compat--string-trim-right
string
diff --git a/compat-27.el b/compat-27.el
index 6c88f424ab..233577877d 100644
--- a/compat-27.el
+++ b/compat-27.el
@@ -85,7 +85,7 @@ Letter-case is significant, but text properties are ignored."
(compat-defun recenter (&optional arg redisplay) ;; <compat-tests:recenter>
"Handle optional argument REDISPLAY."
- :explicit t
+ :extended t
(recenter arg)
(when (and redisplay recenter-redisplay)
(redisplay)))
@@ -94,7 +94,7 @@ Letter-case is significant, but text properties are ignored."
(compat-defun lookup-key (keymap key &optional accept-default) ;;
<compat-tests:lookup-key>
"Allow for KEYMAP to be a list of keymaps."
- :explicit t
+ :extended t
(cond
((keymapp keymap)
(lookup-key keymap key accept-default))
@@ -130,7 +130,7 @@ NOTE: This function is not as accurate as the actual
`time-equal-p'."
(compat-defmacro setq-local (&rest pairs) ;; <compat-tests:setq-local>
"Handle multiple assignments."
- :explicit t
+ :extended t
(unless (zerop (mod (length pairs) 2))
(error "PAIRS must have an even number of variable/value members"))
(let (body)
@@ -211,7 +211,7 @@ return nil."
(compat-defun assoc-delete-all (key alist &optional test) ;;
<compat-tests:assoc-delete-all>
"Handle optional argument TEST."
- :explicit "26.2"
+ :extended "26.2"
(unless test (setq test #'equal))
(while (and (consp (car alist))
(funcall test (caar alist) key))
@@ -305,7 +305,7 @@ the minibuffer was activated, and execute the forms."
(compat-defun image--set-property (image property value) ;;
<compat-tests:image-property>
"Set PROPERTY in IMAGE to VALUE, internal use only."
- :explicit "26.1"
+ :extended "26.1"
:feature image
(if (null value)
(while (cdr image)
@@ -328,13 +328,13 @@ the minibuffer was activated, and execute the forms."
(compat-defun file-name-quoted-p (name &optional top) ;;
<compat-tests:file-name-quoted-p>
"Handle optional argument TOP."
- :explicit "26.1"
+ :extended "26.1"
(let ((file-name-handler-alist (unless top file-name-handler-alist)))
(string-prefix-p "/:" (file-local-name name))))
(compat-defun file-name-quote (name &optional top) ;;
<compat-tests:file-name-quote>
"Handle optional argument TOP."
- :explicit "26.1"
+ :extended "26.1"
(let ((file-name-handler-alist (unless top file-name-handler-alist)))
(if (string-prefix-p "/:" (file-local-name name))
name
@@ -342,7 +342,7 @@ the minibuffer was activated, and execute the forms."
(compat-defun file-size-human-readable (file-size &optional flavor space unit)
;; <compat-tests:file-size-human-readable>
"Handle the optional arguments SPACE and UNIT."
- :explicit t
+ :extended t
(let ((power (if (or (null flavor) (eq flavor 'iec))
1024.0
1000.0))
@@ -385,7 +385,7 @@ the value of the variable `exec-path'."
(compat-defun executable-find (command &optional remote) ;;
<compat-tests:executable-find>
"Handle optional argument REMOTE."
- :explicit t
+ :extended t
(if (and remote (file-remote-p default-directory))
(let ((res (locate-file
command
@@ -411,7 +411,7 @@ Optional arg PARENTS, if non-nil then creates parent dirs
as needed."
(compat-defun regexp-opt (strings &optional paren) ;; <compat-tests:regexp-opt>
"Handle an empty list of STRINGS."
- :explicit t
+ :extended t
(if (null strings)
(let ((re "\\`a\\`"))
(cond ((null paren)
@@ -468,7 +468,7 @@ The return value is a string (or nil in case we can’t find
it)."
(&optional localp arg filter distinguish-one-marked error)
"Handle optional argument ERROR."
:feature dired
- :explicit t
+ :extended t
(let ((result (dired-get-marked-files localp arg filter
distinguish-one-marked)))
(if (and (null result) error)
(user-error (if (stringp error) error "No files specified"))
diff --git a/compat-28.el b/compat-28.el
index 13685fdc7b..76dfe37e3d 100644
--- a/compat-28.el
+++ b/compat-28.el
@@ -112,7 +112,7 @@ inserted before contatenating."
(compat-defun string-width (string &optional from to) ;;
<compat-tests:string-width>
"Handle optional arguments FROM and TO."
- :explicit t
+ :extended t
(let* ((len (length string))
(from (or from 0))
(to (or to len)))
@@ -124,7 +124,7 @@ inserted before contatenating."
(compat-defun directory-files (directory &optional full match nosort count) ;;
<compat-tests:directory-files>
"Handle additional optional argument COUNT."
- :explicit t
+ :extended t
(let ((files (directory-files directory full match nosort)))
(when (natnump count)
(setf (nthcdr count files) nil))
@@ -132,7 +132,7 @@ inserted before contatenating."
(compat-defun directory-files-and-attributes (directory &optional full match
nosort id-format count) ;; <compat-tests:directory-files-and-attributs>
"Handle additional optional argument COUNT."
- :explicit t
+ :extended t
(let ((files (directory-files-and-attributes directory full match nosort
id-format)))
(when (natnump count)
(setf (nthcdr count files) nil))
@@ -686,7 +686,7 @@ the last form in BODY."
(compat-defun count-windows (&optional minibuf all-frames) ;;
<compat-tests:count-windows>
"Handle optional argument ALL-FRAMES."
- :explicit t
+ :extended t
(if all-frames
(let ((sum 0))
(dolist (frame (frame-list))
diff --git a/compat-29.el b/compat-29.el
index 6e5b93f223..6612612ea3 100644
--- a/compat-29.el
+++ b/compat-29.el
@@ -85,7 +85,7 @@ Unibyte strings are converted to multibyte for comparison."
(compat-defun plist-get (plist prop &optional predicate) ;;
<compat-tests:plist-get>
"Handle optional argument PREDICATE."
- :explicit t
+ :extended t
(if (or (null predicate) (eq predicate 'eq))
(plist-get plist prop)
(catch 'found
@@ -96,7 +96,7 @@ Unibyte strings are converted to multibyte for comparison."
(compat-defun plist-put (plist prop val &optional predicate) ;;
<compat-tests:plist-get>
"Handle optional argument PREDICATE."
- :explicit t
+ :extended t
(if (or (null predicate) (eq predicate 'eq))
(plist-put plist prop val)
(catch 'found
@@ -110,7 +110,7 @@ Unibyte strings are converted to multibyte for comparison."
(compat-defun plist-member (plist prop &optional predicate) ;;
<compat-tests:plist-get>
"Handle optional argument PREDICATE."
- :explicit t
+ :extended t
(if (or (null predicate) (eq predicate 'eq))
(plist-member plist prop)
(catch 'found
@@ -1108,7 +1108,7 @@ command exists in this specific map, but it doesn't have
the
(compat-defun define-key (keymap key def &optional remove) ;;
<compat-tests:define-key>
"Handle optional argument REMOVE."
- :explicit t
+ :extended t
(if (not remove)
(define-key keymap key def)
;; Canonicalize key
@@ -1193,7 +1193,7 @@ Also see `buttonize'."
(compat-defun read-multiple-choice ;; <compat-tests:read-multiple-choice>
(prompt choices &optional _help-str _show-help long-form)
"Handle LONG-FORM argument."
- :explicit t
+ :extended t
(if (not long-form)
(read-multiple-choice prompt choices)
(let ((answer
diff --git a/compat-macs.el b/compat-macs.el
index bfdc5da705..f8bf80b2a9 100644
--- a/compat-macs.el
+++ b/compat-macs.el
@@ -97,14 +97,14 @@ a plist of predicates for arguments which are passed to
FUN."
(defun compat--guard-defun (type name arglist docstring rest)
"Define function NAME of TYPE with ARGLIST and DOCSTRING.
REST are attributes and the function BODY."
- (compat--guard rest `(:explicit ,(lambda (x) (or (booleanp x)
(version-to-list x)))
+ (compat--guard rest `(:extended ,(lambda (x) (or (booleanp x)
(version-to-list x)))
:obsolete ,(lambda (x) (or (booleanp x) (stringp x)))
:body t)
- (lambda (explicit obsolete body)
- (when (stringp explicit)
- (setq explicit (version<= explicit emacs-version)))
- (compat--strict (eq explicit (fboundp name))
- "Wrong :explicit flag for %s %s" type name)
+ (lambda (extended obsolete body)
+ (when (stringp extended)
+ (setq extended (version<= extended emacs-version)))
+ (compat--strict (eq extended (fboundp name))
+ "Wrong :extended flag for %s %s" type name)
;; Remove unsupported declares. It might be possible to set these
;; properties otherwise. That should be looked into and implemented
;; if it is the case.
@@ -112,8 +112,8 @@ REST are attributes and the function BODY."
(when (<= emacs-major-version 25)
(delq (assq 'side-effect-free (car body)) (car body))
(delq (assq 'pure (car body)) (car body))))
- ;; Use `:explicit' name if the function is already defined.
- (let* ((defname (if (and explicit (fboundp name))
+ ;; Use `:extended' name if the function is already defined.
+ (let* ((defname (if (and extended (fboundp name))
(intern (format "compat--%s" name))
name))
(def `(,(if (memq '&key arglist)
@@ -188,13 +188,13 @@ The function must be documented in DOCSTRING. REST is an
attribute plist followed by the function body. The attributes
specify the conditions under which the definition is generated.
-- :explicit :: Make the definition available for explicit
- invocation via `compat-call'. :explicit should be used for
- functions which extend already existing functions, e.g.,
- functions which changed their calling convention or their
- behavior. The value can also be a version string, which
- specifies for which Emacs version and newer an explicit
- definition will be created.
+- :extended :: Mark the function as extended if t. The function
+ must be called explicitly via `compat-call'. This attribute
+ should be used for functions which extend already existing
+ functions, e.g., functions which changed their calling
+ convention or their behavior. The value can also be a version
+ string, which specifies the Emacs version when the original
+ version of the function was introduced.
- :obsolete :: Mark the function as obsolete if t, can be a
string describing the obsoletion.
diff --git a/compat.el b/compat.el
index bc573b5ebf..ffdd379650 100644
--- a/compat.el
+++ b/compat.el
@@ -46,7 +46,7 @@
(when (eval-when-compile (< emacs-major-version 29))
(require 'compat-29))
-;;;; Macros for explicit compatibility function calls
+;;;; Macros for extended compatibility function calls
(defmacro compat-function (fun)
"Return compatibility function symbol for FUN.
@@ -59,15 +59,16 @@ version. For example Compat 29.1 will provide compatibility
functions which implement the behavior and calling convention of
Emacs 29.1.
-An example is the function `plist-get' which got an additional
-predicate argument in Emacs 29. The compatibility function,
-which supports this additional argument can be obtained
+An example is the function `plist-get' which was extended with an
+additional predicate argument in Emacs 29. The compatibility
+function, which supports this additional argument can be obtained
via (compat-function plist-get) and called with the additional
predicate argument via (compat-call plist-get plist prop
-predicate). It is not possible to directly call (plist-get plist
-prop predicate), since the function does not yet support the
-predicate argument on older Emacs versions and the Compat library
-does not override existing functions."
+predicate). It is not possible to directly evaluate (plist-get
+plist prop predicate), since the original `plist-get' function
+does not yet support the predicate argument on older Emacs
+versions. Note that Compat library never overrides existing
+functions."
(let ((compat (intern (format "compat--%s" fun))))
`#',(if (fboundp compat) compat fun)))
diff --git a/compat.texi b/compat.texi
index 33876d7e62..fd03115ee8 100644
--- a/compat.texi
+++ b/compat.texi
@@ -127,10 +127,10 @@ the noerror flag should be specified.
(require 'compat nil 'noerror)
@end example
-This will load all implicit and explicit Compat definitions. Note
-that if Compat is installed on a recent version of Emacs, all of the
-definitions are disabled at compile time, such that no negative
-performance impact is incurred.
+This will load all necessary Compat definitions. Note that if Compat
+is installed on a recent version of Emacs, all of the definitions are
+disabled at compile time, such that no negative performance impact is
+incurred.
Note that Compat provides replacement functions with extended
functionality for functions that are already defined (@code{sort},
@@ -138,12 +138,12 @@ functionality for functions that are already defined
(@code{sort},
calling convention (additional optional arguments) or may have changed
their behavior. These functions must be looked up explicitly with
@code{compat-function} or called explicitly with @code{compat-call}.
-We call them ``Explicit Definitions''. In contrast, ``Implicit
+We call them ``Extended Definitions''. In contrast, newly ``Added
Definitions'' can be called as usual.
@example
-(compat-call assoc KEY ALIST TESTFN) ;; Explicit
-(mapcan FUNCTION SEQUENCE) ;; Implicit
+(compat-call assoc KEY ALIST TESTFN) ;; Call extended `assoc'
+(mapcan FUNCTION SEQUENCE) ;; Call newly added `mapcan'
@end example
@defmac compat-call fun &rest args
@@ -263,7 +263,7 @@ manage to provide for each Emacs version.
@node Emacs 25.1
@section Emacs 25.1
-@subsection Implicit Definitions
+@subsection Added Definitions
The following functions and macros are implemented in Emacs
25.1. These functions are made available by Compat on Emacs versions
older than 25.1.
@@ -481,9 +481,9 @@ arguments, @var{objects}.
@xref{Bool-Vectors,,,elisp}.
@end defun
-@subsection Explicit Definitions
+@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention or behavior changed:
+since their calling convention or behavior was extended:
@defun compat-call@ sort sequence predicate
This function sorts @var{sequence} stably. Note that this function
@@ -550,7 +550,7 @@ The functions @code{bufferpos-to-filepos} and
@node Emacs 26.1
@section Emacs 26.1
-@subsection Implicit Definitions
+@subsection Added Definitions
The following functions and macros are implemented in Emacs
26.1. These functions are made available by Compat on Emacs versions
older than 26.1.
@@ -882,9 +882,9 @@ size, modes, inode-number and device-number.
@end example
@end defun
-@subsection Explicit Definitions
+@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention or behavior changed:
+since their calling convention or behavior was extended:
@defun compat-call@ assoc key alist &optional testfn
This function returns the first association for @var{key} in
@@ -1007,7 +1007,7 @@ The function @code{string-version-lessp}.
@node Emacs 27.1
@section Emacs 27.1
-@subsection Implicit Definitions
+@subsection Added Definitions
The following functions and macros are implemented in Emacs
27.1. These functions are made available by Compat on Emacs versions
older than 27.1.
@@ -1301,9 +1301,9 @@ This function creates an empty file named @var{filename}.
As
function signals an error.
@end defun
-@subsection Explicit Definitions
+@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention or behavior changed:
+since their calling convention or behavior was extended:
@c based on lispref/windows.texi
@defun compat-call@ recenter &optional count redisplay
@@ -1562,7 +1562,7 @@ functionality.
@node Emacs 28.1
@section Emacs 28.1
-@subsection Implicit Definitions
+@subsection Added Definitions
The following functions and macros are implemented in Emacs
28.1. These functions are made available by Compat on Emacs versions
older than 28.1.
@@ -2010,9 +2010,9 @@ If native compilation is not available, this function
always returns
@code{nil}.
@end defun
-@subsection Explicit Definitions
+@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention or behavior changed:
+since their calling convention or behavior was extended:
@defun compat-call@ string-width string &optional from to
This function returns the width in columns of the string @var{string},
@@ -2126,7 +2126,7 @@ Any @code{multisession} functionality.
@node Emacs 29.1
@section Emacs 29.1
-@subsection Implicit Definitions
+@subsection Added Definitions
The following functions and macros are implemented in Emacs
29.1. These functions are made available by Compat on Emacs versions
older than 29.1. Note that due to upstream changes, it might happen
@@ -2796,9 +2796,9 @@ Like @code{when-let}, but repeat until a binding in
@var{spec} is
This is comparable to @code{and-let*}.
@end defmac
-@subsection Explicit Definitions
+@subsection Extended Definitions
These functions must be called explicitly via @code{compat-call},
-since their calling convention or behavior changed:
+since their calling convention or behavior was extended:
@c copied from lispref/keymaps.texi
@defun compat-call@ define-key