From 0789fd068c27685fb306e4850322a949f388375e Mon Sep 17 00:00:00 2001
From: "Basil L. Contovounesios" <contovob@tcd.ie>
Date: Sun, 24 Jan 2021 15:21:47 +0000
Subject: [PATCH] Fix -some--> docstring and Edebug spec

* dash.el (-some-->): Use a valid Edebug spec, not ->.  Fix
docstring.
* dev/examples.el (-some-->): Improve tests.

* README.md:
* dev/examples.el: Regenerate docs.
---
 README.md       | 12 +++++++-----
 dash.el         | 15 ++++++++-------
 dash.texi       | 12 +++++++-----
 dev/examples.el | 10 +++++++---
 4 files changed, 29 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index f5c116c..bb8b0fa 100644
--- a/README.md
+++ b/README.md
@@ -316,7 +316,7 @@ Functions pretending lists are trees.
 * [-as->](#-as--value-variable-rest-forms) `(value variable &rest forms)`
 * [-some->](#-some--x-optional-form-rest-more) `(x &optional form &rest more)`
 * [-some->>](#-some--x-optional-form-rest-more) `(x &optional form &rest more)`
-* [-some-->](#-some---x-rest-forms) `(x &rest forms)`
+* [-some-->](#-some---expr-rest-forms) `(expr &rest forms)`
 * [-doto](#-doto-init-rest-forms) `(init &rest forms)`
 
 ### Binding
@@ -2321,15 +2321,17 @@ and when that result is non-nil, through the next form, etc.
 (-some->> '(2 4 6) (-last 'even?) (+ 100)) ;; => 106
 ```
 
-#### -some--> `(x &rest forms)`
+#### -some--> `(expr &rest forms)`
 
-When expr is non-nil, thread it through the first form (via [`-->`](#---x-rest-forms)),
-and when that result is non-nil, through the next form, etc.
+Thread `expr` through `forms` via [`-->`](#---x-rest-forms), while the result is non-nil.
+When `expr` evaluates to non-nil, thread the result through the
+first of `forms`, and when that result is non-nil, thread it
+through the next form, etc.
 
 ```el
 (-some--> "def" (concat "abc" it "ghi")) ;; => "abcdefghi"
 (-some--> nil (concat "abc" it "ghi")) ;; => nil
-(-some--> '(1 3 5) (-filter 'even? it) (append it it) (-map 'square it)) ;; => nil
+(-some--> '(0 1) (-remove #'natnump it) (append it it) (-map #'1+ it)) ;; => '()
 ```
 
 #### -doto `(init &rest forms)`
diff --git a/dash.el b/dash.el
index 7f23a71..8033fd2 100644
--- a/dash.el
+++ b/dash.el
@@ -1751,14 +1751,15 @@ and when that result is non-nil, through the next form, etc."
                    (->> ,result ,form))
                  ,@more))))
 
-(defmacro -some--> (x &rest forms)
-  "When expr is non-nil, thread it through the first form (via `-->'),
-and when that result is non-nil, through the next form, etc."
-  (declare (debug ->)
-           (indent 1))
-  (if (null forms) x
+(defmacro -some--> (expr &rest forms)
+  "Thread EXPR through FORMS via `-->', while the result is non-nil.
+When EXPR evaluates to non-nil, thread the result through the
+first of FORMS, and when that result is non-nil, thread it
+through the next form, etc."
+  (declare (debug (form &rest &or symbolp consp)) (indent 1))
+  (if (null forms) expr
     (let ((result (make-symbol "result")))
-      `(-some--> (-when-let (,result ,x)
+      `(-some--> (-when-let (,result ,expr)
                    (--> ,result ,(car forms)))
          ,@(cdr forms)))))
 
diff --git a/dash.texi b/dash.texi
index ab5469f..9a05cb8 100644
--- a/dash.texi
+++ b/dash.texi
@@ -3601,9 +3601,11 @@ and when that result is non-nil, through the next form, etc.
 @end defmac
 
 @anchor{-some-->}
-@defmac -some--> (x &rest forms)
-When expr is non-nil, thread it through the first form (via @code{-->} (@pxref{-->})),
-and when that result is non-nil, through the next form, etc.
+@defmac -some--> (expr &rest forms)
+Thread @var{expr} through @var{forms} via @code{-->} (@pxref{-->}), while the result is non-nil.
+When @var{expr} evaluates to non-nil, thread the result through the
+first of @var{forms}, and when that result is non-nil, thread it
+through the next form, etc.
 
 @example
 @group
@@ -3615,8 +3617,8 @@ and when that result is non-nil, through the next form, etc.
     @result{} nil
 @end group
 @group
-(-some--> '(1 3 5) (-filter 'even? it) (append it it) (-map 'square it))
-    @result{} nil
+(-some--> '(0 1) (-remove #'natnump it) (append it it) (-map #'1+ it))
+    @result{} '()
 @end group
 @end example
 @end defmac
diff --git a/dev/examples.el b/dev/examples.el
index 3d3dd5f..e31460c 100644
--- a/dev/examples.el
+++ b/dev/examples.el
@@ -1283,9 +1283,13 @@ value rather than consuming a list to produce a single value."
   (defexamples -some-->
     (-some--> "def" (concat "abc" it "ghi")) => "abcdefghi"
     (-some--> nil (concat "abc" it "ghi")) => nil
-    (-some--> '(1 3 5) (-filter 'even? it) (append it it) (-map 'square it)) => nil
-    (-some--> '(2 4 6) (-filter 'even? it) (append it it) (-map 'square it)) => '(4 16 36 4 16 36)
-    (-some--> 1 nil) !!> (void-function nil))
+    (-some--> '(0 1) (-remove #'natnump it) (append it it) (-map #'1+ it))
+    => '()
+    (-some--> '(0 1) (-filter #'natnump it) (append it it) (-map #'1+ it))
+    => '(1 2 1 2)
+    (-some--> 1 nil) !!> (void-function nil)
+    (-some--> nil) => nil
+    (-some--> t) => t)
 
   (defexamples -doto
     (-doto (list 1 2 3) pop pop) => '(3)