[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[elpa] externals/dash ffe72fb 08/14: Update documentation.
From: |
Phillip Lord |
Subject: |
[elpa] externals/dash ffe72fb 08/14: Update documentation. |
Date: |
Sun, 04 Oct 2015 12:01:02 +0000 |
branch: externals/dash
commit ffe72fbee0854657423ca6d9fc0fd86324069bfc
Author: Matus Goljer <address@hidden>
Commit: Matus Goljer <address@hidden>
Update documentation.
---
README.md | 26 +++++++++++++-----
dash.texi | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
2 files changed, 100 insertions(+), 13 deletions(-)
diff --git a/README.md b/README.md
index 232d6bb..d66447b 100644
--- a/README.md
+++ b/README.md
@@ -598,6 +598,14 @@ Return a new list with the concatenation of the elements
in the supplied `lists`
Take a nested list `l` and return its contents as a single, flat list.
+Note that because `nil` represents a list of zero elements (an
+empty list), any mention of nil in `l` will disappear after
+flattening. If you need to preserve nils, consider
[`-flatten-n`](#-flatten-n-num-list)
+or map them to some unique symbol and then map them back.
+
+Conses of two atoms are considered "terminals", that is, they
+aren't flattened further.
+
See also: [`-flatten-n`](#-flatten-n-num-list)
```el
@@ -1787,7 +1795,7 @@ and when that result is non-nil, through the next form,
etc.
```el
(-some-> '(2 3 5)) ;; => '(2 3 5)
(-some-> 5 square) ;; => 25
-(-some-> nil square) ;; => nil
+(-some-> 5 even? square) ;; => nil
```
#### -some->> `(x &optional form &rest more)`
@@ -1837,7 +1845,9 @@ If all `vals` evaluate to true, bind them to their
corresponding
`vars` and execute body. `vars-vals` should be a list of (`var` `val`)
pairs.
-Note: binding is done according to [`-let*`](#-let-varlist-rest-body).
+Note: binding is done according to [`-let*`](#-let-varlist-rest-body). `vals`
are evaluated
+sequentially, and evaluation stops after the first nil `val` is
+encountered.
```el
(-when-let* ((x 5) (y 3) (z (+ y 4))) (+ x y z)) ;; => 15
@@ -1862,7 +1872,9 @@ If all `vals` evaluate to true, bind them to their
corresponding
`vars` and do `then`, otherwise do `else`. `vars-vals` should be a list
of (`var` `val`) pairs.
-Note: binding is done according to [`-let*`](#-let-varlist-rest-body).
+Note: binding is done according to [`-let*`](#-let-varlist-rest-body). `vals`
are evaluated
+sequentially, and evaluation stops after the first nil `val` is
+encountered.
```el
(-if-let* ((x 5) (y 3) (z 7)) (+ x y z) "foo") ;; => 15
@@ -1932,10 +1944,10 @@ Vectors:
If the `pattern` is longer than `source`, an `error` is
thrown.
- [a1 a2 a3 ... &rest rest] ) - as above, but bind the rest of
- the sequence to `rest`. This is
- conceptually the same as improper list
- matching (a1 a2 ... aN . rest)
+ [a1 a2 a3 ... &rest rest] - as above, but bind the rest of
+ the sequence to `rest`. This is
+ conceptually the same as improper list
+ matching (a1 a2 ... aN . rest)
Key/value stores:
diff --git a/dash.texi b/dash.texi
index f566483..4e59866 100644
--- a/dash.texi
+++ b/dash.texi
@@ -727,6 +727,14 @@ Return a new list with the concatenation of the elements
in the supplied @var{li
@defun -flatten (l)
Take a nested list @var{l} and return its contents as a single, flat list.
+Note that because @code{nil} represents a list of zero elements (an
+empty list), any mention of nil in @var{l} will disappear after
+flattening. If you need to preserve nils, consider @code{-flatten-n}
(@pxref{-flatten-n})
+or map them to some unique symbol and then map them back.
+
+Conses of two atoms are considered "terminals", that is, they
+aren't flattened further.
+
See also: @code{-flatten-n} (@pxref{-flatten-n})
@example
@@ -2759,6 +2767,69 @@ in second form, etc.
@end example
@end defun
address@hidden>}
address@hidden -some-> (x &optional form &rest more)
+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.
+
address@hidden
address@hidden
+(-some-> '(2 3 5))
+ @result{} '(2 3 5)
address@hidden group
address@hidden
+(-some-> 5 square)
+ @result{} 25
address@hidden group
address@hidden
+(-some-> 5 even? square)
+ @result{} nil
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden>>}
address@hidden -some->> (x &optional form &rest more)
+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.
+
address@hidden
address@hidden
+(-some->> '(1 2 3) (-map 'square))
+ @result{} '(1 4 9)
address@hidden group
address@hidden
+(-some->> '(1 3 5) (-last 'even?) (+ 100))
+ @result{} nil
address@hidden group
address@hidden
+(-some->> '(2 4 6) (-last 'even?) (+ 100))
+ @result{} 106
address@hidden group
address@hidden example
address@hidden defun
+
address@hidden>}
address@hidden -some--> (x &optional form &rest more)
+When expr in non-nil, thread it through the first form (via @code{-->}
(@pxref{-->})),
+and when that result is non-nil, through the next form, etc.
+
address@hidden
address@hidden
+(-some--> "def" (concat "abc" it "ghi"))
+ @result{} "abcdefghi"
address@hidden group
address@hidden
+(-some--> nil (concat "abc" it "ghi"))
+ @result{} nil
address@hidden group
address@hidden
+(-some--> '(1 3 5) (-filter 'even? it) (append it it) (-map 'square it))
+ @result{} nil
address@hidden group
address@hidden example
address@hidden defun
+
@node Binding
@section Binding
@@ -2796,7 +2867,9 @@ If all @var{vals} evaluate to true, bind them to their
corresponding
@var{vars} and execute body. @var{vars-vals} should be a list of (@var{var}
@var{val})
pairs.
-Note: binding is done according to @code{-let*} (@pxref{-let*}).
+Note: binding is done according to @code{-let*} (@pxref{-let*}). @var{vals}
are evaluated
+sequentially, and evaluation stops after the first nil @var{val} is
+encountered.
@example
@group
@@ -2835,7 +2908,9 @@ If all @var{vals} evaluate to true, bind them to their
corresponding
@var{vars} and do @var{then}, otherwise do @var{else}. @var{vars-vals} should
be a list
of (@var{var} @var{val}) pairs.
-Note: binding is done according to @code{-let*} (@pxref{-let*}).
+Note: binding is done according to @code{-let*} (@pxref{-let*}). @var{vals}
are evaluated
+sequentially, and evaluation stops after the first nil @var{val} is
+encountered.
@example
@group
@@ -2915,10 +2990,10 @@ Vectors:
If the @var{pattern} is longer than @var{source}, an
@code{error} is
thrown.
- [a1 a2 a3 ... &rest rest] ) - as above, but bind the rest of
- the sequence to @var{rest}. This is
- conceptually the same as improper list
- matching (a1 a2 ... aN . rest)
+ [a1 a2 a3 ... &rest rest] - as above, but bind the rest of
+ the sequence to @var{rest}. This is
+ conceptually the same as improper list
+ matching (a1 a2 ... aN . rest)
Key/value stores:
- [elpa] externals/dash updated (eadb265 -> fa90644), Phillip Lord, 2015/10/08
- [elpa] externals/dash ce3c2fe 01/14: Errant paren removed from -let documentation., Phillip Lord, 2015/10/08
- [elpa] externals/dash ffe72fb 08/14: Update documentation.,
Phillip Lord <=
- [elpa] externals/dash c8c6ea4 05/14: [Fix #154] Clarify that -flatten destroys all nils., Phillip Lord, 2015/10/08
- [elpa] externals/dash dbe2bf2 10/14: Merge pull request #160 from phillord/feature/gnu-elpa-support, Phillip Lord, 2015/10/08
- [elpa] externals/dash 3e2e0b5 03/14: Merge pull request #131 from phillord/fix/documentation-for-let, Phillip Lord, 2015/10/08
- [elpa] externals/dash fa90644 14/14: Release 2.12.0, Phillip Lord, 2015/10/08
- [elpa] externals/dash 8fa70c5 12/14: [Fix #101] Use faster hashtable implementation for -union., Phillip Lord, 2015/10/08
- [elpa] externals/dash 66cb6f5 09/14: Merge pull request #146 from holomorph/info-macros, Phillip Lord, 2015/10/08
- [elpa] externals/dash 5d2a73c 07/14: [Fix #155] -is-suffix? no longer destroys input list., Phillip Lord, 2015/10/08
- [elpa] externals/dash 91a2b14 13/14: [Fix #101] Fix reversed condition for hashtable -union., Phillip Lord, 2015/10/08
- [elpa] externals/dash 3ae7335 02/14: Indicate macros in generated info manual, Phillip Lord, 2015/10/08
- [elpa] externals/dash c6c2105 04/14: Add support for GNU ELPA., Phillip Lord, 2015/10/08