[elpa] externals/dash d983d4f 217/316: Fix -doto

[ELPA Syncer]

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

    Fix -doto
    
    The macro was broken until now for anything other than list forms,
    due to a mistake in quoting.  Use this as an opportunity to rethink
    the macro's behavior in this case.  Instead of using funcall, which
    is unusual for a macro, thread the value using ->.  Suggested by
    Zach Shaftel <zshaftel@gmail.com>.
    
    * dash.el (-doto): Rewrite in terms of ->.  Fix docstring.  Add
    Edebug spec.
    (--doto): Rename argument for consistency with -doto.  Expand
    docstring.  Add Edebug spec.
    * dev/examples.el (-doto): Test fixed behavior of -doto.
    
    * README.md:
    * dash.texi: Regenerate docs.
    
    Fixes #333.
---
 README.md       |  9 +++++----
 dash.el         | 25 ++++++++++++-------------
 dash.texi       |  9 +++++----
 dev/examples.el |  2 +-
 4 files changed, 23 insertions(+), 22 deletions(-)

diff --git a/README.md b/README.md
index 85d7d44..929860c 100644
--- a/README.md
+++ b/README.md
@@ -2650,12 +2650,13 @@ if `num` is less than 1.
 
 #### -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.
+Evaluate `init` and pass it as argument to `forms` with 
[`->`](#--x-optional-form-rest-more).
+The `result` of evaluating `init` is threaded through each of `forms`
+individually using [`->`](#--x-optional-form-rest-more), which see.  The 
return value is `result`,
+which `forms` may have modified by side effect.
 
 ```el
-(-doto (list 1 2 3) (pop) (pop)) ;; => '(3)
+(-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 6548f8d..be4fd4b 100644
--- a/dash.el
+++ b/dash.el
@@ -63,24 +63,23 @@
          (!cdr ,l)))))
 
 (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")))
+  "Evaluate INIT and pass it as argument to FORMS with `->'.
+The RESULT of evaluating INIT is threaded through each of FORMS
+individually using `->', which see.  The return value is RESULT,
+which FORMS may have modified by side effect."
+  (declare (debug (form body)) (indent 1))
+  (let ((retval (make-symbol "result")))
     `(let ((,retval ,init))
-       ,@(mapcar (lambda (form)
-                   (if (listp form)
-                       `(,(car form) ,retval ,@(cdr form))
-                     `(funcall form ,retval)))
-                 forms)
+       ,@(mapcar (lambda (form) `(-> ,retval ,form)) forms)
        ,retval)))
 
-(defmacro --doto (eval-initial-value &rest forms)
+(defmacro --doto (init &rest forms)
   "Anaphoric form of `-doto'.
+This just evaluates INIT, binds the result to `it', evaluates
+FORMS, and returns the final value of `it'.
 Note: `it' need not be used in each form."
-  (declare (indent 1))
-  `(let ((it ,eval-initial-value))
+  (declare (debug (form body)) (indent 1))
+  `(let ((it ,init))
      ,@forms
      it))
 
diff --git a/dash.texi b/dash.texi
index 899fbb8..0e5aa86 100644
--- a/dash.texi
+++ b/dash.texi
@@ -4026,13 +4026,14 @@ if @var{num} is less than 1.
 
 @anchor{-doto}
 @defmac -doto (init &rest forms)
-Evaluate @var{init} and thread the result as the 2nd argument to other 
@var{forms}.
-@var{init} is evaluated once.  Its result is passed to @var{forms}, which are
-then evaluated sequentially.  Returns the target form.
+Evaluate @var{init} and pass it as argument to @var{forms} with @code{->} 
(@pxref{->}).
+The @var{result} of evaluating @var{init} is threaded through each of 
@var{forms}
+individually using @code{->} (@pxref{->}), which see.  The return value is 
@var{result},
+which @var{forms} may have modified by side effect.
 
 @example
 @group
-(-doto (list 1 2 3) (pop) (pop))
+(-doto (list 1 2 3) pop pop)
     @result{} '(3)
 @end group
 @group
diff --git a/dev/examples.el b/dev/examples.el
index 01a7ce1..067ef47 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -1365,7 +1365,7 @@ 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 (list 1 2 3) (pop) (pop)) => '(3)
+    (-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)))