[elpa] externals/dash 47f8b2b 214/316: Clean up -doto

[ELPA Syncer]

branch: externals/dash
commit 47f8b2b7239637638b99051842ea124bc6596987
Author: Basil L. Contovounesios <contovob@tcd.ie>
Commit: Basil L. Contovounesios <contovob@tcd.ie>

    Clean up -doto
    
    * dash.el (-doto): Fix docstring and simplify slightly.
    (--doto): Clarify docstring.
    * dev/examples.el (--doto): Move from here...
    (-doto): ...to here, simplifying in the process.  Fix tests to avoid
    destructive modification of immutable literals.
    
    * README.md:
    * dash.texi: Regenerate docs.
---
 README.md       | 26 ++++++++------------------
 dash.el         | 17 ++++++++---------
 dash.texi       | 26 ++++++++------------------
 dev/examples.el | 11 ++++-------
 4 files changed, 28 insertions(+), 52 deletions(-)

diff --git a/README.md b/README.md
index 78e3b68..1b50586 100644
--- a/README.md
+++ b/README.md
@@ -325,8 +325,7 @@ Functions iterating over lists for side-effect only.
 * [-each-r](#-each-r-list-fn) `(list fn)`
 * [-each-r-while](#-each-r-while-list-pred-fn) `(list pred fn)`
 * [-dotimes](#-dotimes-num-fn) `(num fn)`
-* [-doto](#-doto-eval-initial-value-rest-forms) `(eval-initial-value &rest 
forms)`
-* [--doto](#--doto-eval-initial-value-rest-forms) `(eval-initial-value &rest 
forms)`
+* [-doto](#-doto-init-rest-forms) `(init &rest forms)`
 
 ### Destructive operations
 
@@ -2649,25 +2648,16 @@ if `num` is less than 1.
 (let (s) (--dotimes 5 (push it s)) s) ;; => '(4 3 2 1 0)
 ```
 
-#### -doto `(eval-initial-value &rest forms)`
+#### -doto `(init &rest forms)`
 
-Eval a form, then insert that form as the 2nd argument to other forms.
-The `eval-initial-value` form is evaluated once. Its result is
-passed to `forms`, which are then evaluated sequentially. Returns
-the target form.
+Evaluate `init` and thread the result as the 2nd argument to other forms.
+`init` is evaluated once.  Its result is passed to `forms`, which are
+then evaluated sequentially.  Returns the target form.
 
 ```el
-(-doto '(1 2 3) (!cdr) (!cdr)) ;; => '(3)
-(-doto '(1 . 2) (setcar 3) (setcdr 4)) ;; => '(3 . 4)
-```
-
-#### --doto `(eval-initial-value &rest forms)`
-
-Anaphoric form of [`-doto`](#-doto-eval-initial-value-rest-forms).
-Note: `it` is not required in each form.
-
-```el
-(gethash "key" (--doto (make-hash-table :test 'equal) (puthash "key" "value" 
it))) ;; => "value"
+(-doto (list 1 2 3) (pop) (pop)) ;; => '(3)
+(-doto (cons 1 2) (setcar 3) (setcdr 4)) ;; => '(3 . 4)
+(gethash 'k (--doto (make-hash-table) (puthash 'k 'v it))) ;; => 'v
 ```
 
 
diff --git a/dash.el b/dash.el
index 06e01b0..7e8d39e 100644
--- a/dash.el
+++ b/dash.el
@@ -62,24 +62,23 @@
          (setq it-index (1+ it-index))
          (!cdr ,l)))))
 
-(defmacro -doto (eval-initial-value &rest forms)
-  "Eval a form, then insert that form as the 2nd argument to other forms.
-The EVAL-INITIAL-VALUE form is evaluated once. Its result is
-passed to FORMS, which are then evaluated sequentially. Returns
-the target form."
+(defmacro -doto (init &rest forms)
+  "Evaluate INIT and thread the result as the 2nd argument to other forms.
+INIT is evaluated once.  Its result is passed to FORMS, which are
+then evaluated sequentially.  Returns the target form."
   (declare (indent 1))
   (let ((retval (make-symbol "value")))
-    `(let ((,retval ,eval-initial-value))
+    `(let ((,retval ,init))
        ,@(mapcar (lambda (form)
-                   (if (sequencep form)
-                       `(,(-first-item form) ,retval ,@(cdr form))
+                   (if (listp form)
+                       `(,(car form) ,retval ,@(cdr form))
                      `(funcall form ,retval)))
                  forms)
        ,retval)))
 
 (defmacro --doto (eval-initial-value &rest forms)
   "Anaphoric form of `-doto'.
-Note: `it' is not required in each form."
+Note: `it' need not be used in each form."
   (declare (indent 1))
   `(let ((it ,eval-initial-value))
      ,@forms
diff --git a/dash.texi b/dash.texi
index e847455..f70a68d 100644
--- a/dash.texi
+++ b/dash.texi
@@ -4025,33 +4025,23 @@ if @var{num} is less than 1.
 @end defun
 
 @anchor{-doto}
-@defmac -doto (eval-initial-value &rest forms)
-Eval a form, then insert that form as the 2nd argument to other forms.
-The @var{eval-initial-value} form is evaluated once. Its result is
-passed to @var{forms}, which are then evaluated sequentially. Returns
-the target form.
+@defmac -doto (init &rest forms)
+Evaluate @var{init} and thread the result as the 2nd argument to other forms.
+@var{init} is evaluated once.  Its result is passed to @var{forms}, which are
+then evaluated sequentially.  Returns the target form.
 
 @example
 @group
-(-doto '(1 2 3) (!cdr) (!cdr))
+(-doto (list 1 2 3) (pop) (pop))
     @result{} '(3)
 @end group
 @group
-(-doto '(1 . 2) (setcar 3) (setcdr 4))
+(-doto (cons 1 2) (setcar 3) (setcdr 4))
     @result{} '(3 . 4)
 @end group
-@end example
-@end defmac
-
-@anchor{--doto}
-@defmac --doto (eval-initial-value &rest forms)
-Anaphoric form of @code{-doto} (@pxref{-doto}).
-Note: @code{it} is not required in each form.
-
-@example
 @group
-(gethash "key" (--doto (make-hash-table :test 'equal) (puthash "key" "value" 
it)))
-    @result{} "value"
+(gethash 'k (--doto (make-hash-table) (puthash 'k 'v it)))
+    @result{} 'v
 @end group
 @end example
 @end defmac
diff --git a/dev/examples.el b/dev/examples.el
index d16e504..01a7ce1 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -1365,13 +1365,10 @@ consuming a list to produce a single value."
     (let (s) (--dotimes 3 (push it s) (setq it -1)) s) => '(2 1 0))
 
   (defexamples -doto
-    (-doto '(1 2 3) (!cdr) (!cdr)) => '(3)
-    (-doto '(1 . 2) (setcar 3) (setcdr 4)) => '(3 . 4))
-
-  (defexamples --doto
-    (gethash "key"
-             (--doto (make-hash-table :test 'equal)
-               (puthash "key" "value" it))) => "value"))
+    (-doto (list 1 2 3) (pop) (pop)) => '(3)
+    (-doto (cons 1 2) (setcar 3) (setcdr 4)) => '(3 . 4)
+    (gethash 'k (--doto (make-hash-table) (puthash 'k 'v it))) => 'v
+    (-doto (cons 1 2)) => '(1 . 2)))
 
 (def-example-group "Destructive operations" nil
   (defexamples !cons