[elpa] externals/dash 6d8abc7 022/316: Add -doto macro (like Clojure's doto) (#177)

[ELPA Syncer]

branch: externals/dash
commit 6d8abc7322ab4509f5836c05b8145090d725fb19
Author: Mika Vilpas <mika.vilpas@gmail.com>
Commit: Matus Goljer <dota.keys@gmail.com>

    Add -doto macro (like Clojure's doto) (#177)
    
    * Add -doto macro (like Clojure's doto)
    
    Here is its documentation in clojuredocs:
    
      (doto x & forms)
    
      Evaluates x then calls all of the methods and functions with the
      value of x supplied at the front of the given arguments.  The forms
      are evaluated in order.  Returns x.
      (doto (new java.util.HashMap) (.put "a" 1) (.put "b" 2))
    
    Documentation:
    https://clojuredocs.org/clojure.core/doto
    
    Source (clojure):
    
https://github.com/clojure/clojure/blob/clojure-1.7.0/src/clj/clojure/core.clj#L3700
    
    * Use make-symbol instead of gensym to stay consistent
    
    Consistent with other code in dash.el
    
    * Fix referring to rest from cl.el in -doto
    
    * Add doto example with setcar and setcdr
    
    * Clarify -doto docstring: eval-initial-value evalled only once
    
    Also mention all arguments in the docstring to please checkdoc
    
    * Make -doto documentation more in line with Emacs standards
---
 dash.el         | 15 +++++++++++++++
 dev/examples.el |  6 +++++-
 2 files changed, 20 insertions(+), 1 deletion(-)

diff --git a/dash.el b/dash.el
index 41651a1..8938674 100644
--- a/dash.el
+++ b/dash.el
@@ -71,6 +71,21 @@ special values."
          (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."
+  (declare (indent 1))
+  (let ((retval (make-symbol "value")))
+    `(let ((,retval ,eval-initial-value))
+       ,@(mapcar (lambda (form)
+                   (if (sequencep form)
+                       `(,(-first-item form) ,retval ,@(cdr form))
+                     `(funcall form ,retval)))
+                 forms)
+       ,retval)))
+
 (defun -each (list fn)
   "Call FN with every item in LIST. Return nil, used for side-effects only."
   (--each list (funcall fn it)))
diff --git a/dev/examples.el b/dev/examples.el
index 92f8861..ade7eab 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -1020,7 +1020,11 @@ new list."
 
   (defexamples -dotimes
     (let (s) (-dotimes 3 (lambda (n) (!cons n s))) s) => '(2 1 0)
-    (let (s) (--dotimes 5 (!cons it s)) s) => '(4 3 2 1 0)))
+    (let (s) (--dotimes 5 (!cons it s)) s) => '(4 3 2 1 0))
+
+  (defexamples -doto
+    (-doto '(1 2 3) (!cdr) (!cdr)) => '(3)
+    (-doto '(1 . 2) (setcar 3) (setcdr 4)) => '(3 . 4)))
 
 (def-example-group "Destructive operations" nil
   (defexamples !cons