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

@@ -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)
 ```
 

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.

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))

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))