[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/dash 1152feb 237/316: Deprecate variadic -list
From: |
ELPA Syncer |
Subject: |
[elpa] externals/dash 1152feb 237/316: Deprecate variadic -list |
Date: |
Mon, 15 Feb 2021 15:58:08 -0500 (EST) |
branch: externals/dash
commit 1152febb1479c77fc544c0fe8acb59ebf92d1c2d
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>
Deprecate variadic -list
* dash.el (-list): Change preferred calling convention to a single
required argument.
* dev/examples.el (-list) Rearrange and expand tests accordingly.
* README.md:
* dash.texi: Regenerate docs.
Fixes #225.
---
README.md | 17 +++++++++++------
dash.el | 18 ++++++++++++------
dash.texi | 17 +++++++++++------
dev/examples.el | 9 +++++++--
4 files changed, 41 insertions(+), 20 deletions(-)
diff --git a/README.md b/README.md
index 74d8c55..e4b262b 100644
--- a/README.md
+++ b/README.md
@@ -291,7 +291,7 @@ Other list functions not fit to be classified elsewhere.
* [-last-item](#-last-item-list) `(list)`
* [-butlast](#-butlast-list) `(list)`
* [-sort](#-sort-comparator-list) `(comparator list)`
-* [-list](#-list-rest-args) `(&rest args)`
+* [-list](#-list-optional-arg-rest-args) `(&optional arg &rest args)`
* [-fix](#-fix-fn-list) `(fn list)`
### Tree operations
@@ -2094,15 +2094,20 @@ if the first element should sort before the second.
(--sort (< it other) '(3 1 2)) ;; => '(1 2 3)
```
-#### -list `(&rest args)`
+#### -list `(&optional arg &rest args)`
-Return a list based on `args`.
-If the first item of `args` is already a list, simply return it.
-Otherwise, return a list with `args` as elements.
+Ensure `arg` is a list.
+If `arg` is already a list, return it as is (not a copy).
+Otherwise, return a new list with `arg` as its only element.
+
+Another supported calling convention is (-list &rest `args`).
+In this case, if `arg` is not a list, a new list with all of
+`args` as elements is returned. This use is supported for
+backward compatibility and is otherwise deprecated.
```el
(-list 1) ;; => '(1)
-(-list 1 2 3) ;; => '(1 2 3)
+(-list nil) ;; => nil
(-list '(1 2 3)) ;; => '(1 2 3)
```
diff --git a/dash.el b/dash.el
index b12588c..6903b42 100644
--- a/dash.el
+++ b/dash.el
@@ -2618,12 +2618,18 @@ if the first element should sort before the second."
(declare (debug (form form)))
`(-sort (lambda (it other) ,form) ,list))
-(defun -list (&rest args)
- "Return a list based on ARGS.
-If the first item of ARGS is already a list, simply return it.
-Otherwise, return a list with ARGS as elements."
- (declare (pure t) (side-effect-free t))
- (if (listp (car args)) (car args) args))
+(defun -list (&optional arg &rest args)
+ "Ensure ARG is a list.
+If ARG is already a list, return it as is (not a copy).
+Otherwise, return a new list with ARG as its only element.
+
+Another supported calling convention is (-list &rest ARGS).
+In this case, if ARG is not a list, a new list with all of
+ARGS as elements is returned. This use is supported for
+backward compatibility and is otherwise deprecated."
+ (declare (advertised-calling-convention (arg) "2.18.0")
+ (pure t) (side-effect-free t))
+ (if (listp arg) arg (cons arg args)))
(defun -repeat (n x)
"Return a new list of length N with each element being X.
diff --git a/dash.texi b/dash.texi
index ee38333..1ec69fb 100644
--- a/dash.texi
+++ b/dash.texi
@@ -3202,10 +3202,15 @@ if the first element should sort before the second.
@end defun
@anchor{-list}
-@defun -list (&rest args)
-Return a list based on @var{args}.
-If the first item of @var{args} is already a list, simply return it.
-Otherwise, return a list with @var{args} as elements.
+@defun -list (&optional arg &rest args)
+Ensure @var{arg} is a list.
+If @var{arg} is already a list, return it as is (not a copy).
+Otherwise, return a new list with @var{arg} as its only element.
+
+Another supported calling convention is (-list &rest @var{args}).
+In this case, if @var{arg} is not a list, a new list with all of
+@var{args} as elements is returned. This use is supported for
+backward compatibility and is otherwise deprecated.
@example
@group
@@ -3213,8 +3218,8 @@ Otherwise, return a list with @var{args} as elements.
@result{} '(1)
@end group
@group
-(-list 1 2 3)
- @result{} '(1 2 3)
+(-list nil)
+ @result{} nil
@end group
@group
(-list '(1 2 3))
diff --git a/dev/examples.el b/dev/examples.el
index 2ab60a7..4dbc38c 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -1009,12 +1009,17 @@ value rather than consuming a list to produce a single
value."
(defexamples -list
(-list 1) => '(1)
- (-list 1 2 3) => '(1 2 3)
+ (-list ()) => ()
(-list '(1 2 3)) => '(1 2 3)
+ (-list 1 2 3) => '(1 2 3)
+ (let ((l (list 1 2))) (setcar (-list l) 3) l) => '(3 2)
+ (let ((l (list 1 2))) (setcar (apply #'-list l) 3) l) => '(1 2)
(-list '((1) (2))) => '((1) (2))
(-list) => ()
- (-list ()) => ()
(-list () 1) => ()
+ (-list () ()) => ()
+ (-list 1 ()) => '(1 ())
+ (-list 1 '(2)) => '(1 (2))
(-list '(())) => '(())
(-list '(() 1)) => '(() 1))
- [elpa] externals/dash 4f3238b 300/316: Strip leading zeros from octal escapes in Emacs 26, (continued)
- [elpa] externals/dash 4f3238b 300/316: Strip leading zeros from octal escapes in Emacs 26, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 2028805 302/316: Don't quote error messages in Texinfo examples, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 6c41b32 301/316: Move case-fold-search binding to where it's used, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 1c711f1 303/316: Unquote results in Texinfo examples, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 1bf9ddb 304/316: Makefile aesthetics, ELPA Syncer, 2021/02/15
- [elpa] externals/dash da0415b 312/316: * NEWS.md (2.18): Start news for upcoming release., ELPA Syncer, 2021/02/15
- [elpa] externals/dash 5eea156 315/316: Absorb dash-functional into dash, ELPA Syncer, 2021/02/15
- [elpa] externals/dash eaf33b3 226/316: Add info-lookup-symbol support, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 565055e 229/316: * dash.el (---truthy?): Simplify., ELPA Syncer, 2021/02/15
- [elpa] externals/dash 97bd233 231/316: Use lexical binding for -grade-up/down, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 1152feb 237/316: Deprecate variadic -list,
ELPA Syncer <=
- [elpa] externals/dash 609ac28 245/316: Improve Texinfo markup when documenting errors, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 999cae9 253/316: Fix short-circuiting of --first, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 3726eb1 254/316: Improve the examples of -some, ELPA Syncer, 2021/02/15
- [elpa] externals/dash b0bef0f 276/316: Don't set text-quoting-style globally, ELPA Syncer, 2021/02/15
- [elpa] externals/dash bedc804 282/316: Improve function-to-info, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 9727f7c 288/316: Simplify Lisp -> Texinfo printing, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 7b2584c 294/316: Simplify GitHub link creation, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 7048e68 296/316: Restore some newlines in docstrings, ELPA Syncer, 2021/02/15
- [elpa] externals/dash f6554c3 298/316: Unquote results in README examples, ELPA Syncer, 2021/02/15
- [elpa] externals/dash 39e5b12 306/316: Merge pull request #370 from blc/news, ELPA Syncer, 2021/02/15