diff --git a/dash.texi b/dash.texi index 1ae123a..f6149b5 100644 --- a/dash.texi +++ b/dash.texi @@ -1639,7 +1639,7 @@ Return a list of iterated applications of @var{fun} to @var{init}. This means a list of the form: - (@var{init} (@var{fun} @var{init}) (@var{fun} (@var{fun} @var{init})) @dots{}) + (@var{init} (@var{fun} @var{init}) (@var{fun} (@var{fun} @var{init})) @dots{}) @var{n} is the length of the returned list. @@ -2820,7 +2820,7 @@ Unzip @var{lists}. This works just like @code{-zip} (@pxref{-zip}) but takes a list of lists instead of a variable number of arguments, such that - (-unzip (-zip @var{l1} @var{l2} @var{l3} @dots{})) + (-unzip (-zip @var{l1} @var{l2} @var{l3} @dots{})) is identity (given that the lists are the same length). @@ -2929,7 +2929,7 @@ combinations created by taking one element from each list in order. The results are flattened, ignoring the tensor structure of the result. This is equivalent to calling: - (-flatten-n (1- (length lists)) (apply '-table fn lists)) + (-flatten-n (1- (length lists)) (apply '-table fn lists)) but the implementation here is much more efficient. @@ -3711,11 +3711,11 @@ If @var{varlist} only contains one (@var{pattern} @var{source}) element, you can optionally specify it using a vector and discarding the outer-most parens. Thus - (-let ((@var{pattern} @var{source})) @dots{}) + (-let ((@var{pattern} @var{source})) @dots{}) becomes - (-let [@var{pattern} @var{source}] @dots{}). + (-let [@var{pattern} @var{source}] @dots{}). @code{-let} (@pxref{-let}) uses a convention of not binding places (symbols) starting with _ whenever it's possible. You can use this to skip over @@ -3730,59 +3730,59 @@ symbol/variable. Symbol: - a - bind the @var{source} to @var{a}. This is just like regular @code{let}. + a - bind the @var{source} to @var{a}. This is just like regular @code{let}. Conses and lists: - (a) - bind @code{car} of cons/list to @var{a} + (a) - bind @code{car} of cons/list to @var{a} - (a . b) - bind car of cons to @var{a} and @code{cdr} to @var{b} + (a . b) - bind car of cons to @var{a} and @code{cdr} to @var{b} - (a b) - bind car of list to @var{a} and @code{cadr} to @var{b} + (a b) - bind car of list to @var{a} and @code{cadr} to @var{b} - (a1 a2 a3 @dots{}) - bind 0th car of list to @var{a1}, 1st to @var{a2}, 2nd to @var{a3}@enddots{} + (a1 a2 a3 @dots{}) - bind 0th car of list to @var{a1}, 1st to @var{a2}, 2nd to @var{a3}@enddots{} - (a1 a2 a3 @dots{} aN . rest) - as above, but bind the Nth cdr to @var{rest}. + (a1 a2 a3 @dots{} aN . rest) - as above, but bind the Nth cdr to @var{rest}. Vectors: - [a] - bind 0th element of a non-list sequence to @var{a} (works with - vectors, strings, bit arrays@dots{}) + [a] - bind 0th element of a non-list sequence to @var{a} (works with + vectors, strings, bit arrays@dots{}) - [a1 a2 a3 @dots{}] - bind 0th element of non-list sequence to @var{a0}, 1st to - @var{a1}, 2nd to @var{a2}, @enddots{} - If the @var{pattern} is shorter than @var{source}, the values at - places not in @var{pattern} are ignored. - If the @var{pattern} is longer than @var{source}, an @code{error} is - thrown. + [a1 a2 a3 @dots{}] - bind 0th element of non-list sequence to @var{a0}, 1st to + @var{a1}, 2nd to @var{a2}, @enddots{} + If the @var{pattern} is shorter than @var{source}, the values at + places not in @var{pattern} are ignored. + If the @var{pattern} is longer than @var{source}, an @code{error} is + thrown. - [a1 a2 a3 @dots{} &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 @dots{} aN . rest) + [a1 a2 a3 @dots{} &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 @dots{} aN . rest) Key/value stores: - (&plist key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the - @var{source} plist to aK. If the - value is not found, aK is nil. - Uses @code{plist-get} to fetch values. + (&plist key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the + @var{source} plist to aK. If the + value is not found, aK is nil. + Uses @code{plist-get} to fetch values. - (&alist key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the - @var{source} alist to aK. If the - value is not found, aK is nil. - Uses @code{assoc} to fetch values. + (&alist key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the + @var{source} alist to aK. If the + value is not found, aK is nil. + Uses @code{assoc} to fetch values. - (&hash key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the - @var{source} hash table to aK. If the - value is not found, aK is nil. - Uses @code{gethash} to fetch values. + (&hash key0 a0 @dots{} keyN aN) - bind value mapped by keyK in the + @var{source} hash table to aK. If the + value is not found, aK is nil. + Uses @code{gethash} to fetch values. Further, special keyword &keys supports "inline" matching of plist-like key-value pairs, similarly to &keys keyword of @code{cl-defun}. - (a1 a2 @dots{} aN &keys key1 b1 @dots{} keyN bK) + (a1 a2 @dots{} aN &keys key1 b1 @dots{} keyN bK) This binds @var{n} values from the list to a1 @dots{} aN, then interprets the cdr as a plist (see key/value matching above). @@ -3805,41 +3805,41 @@ invalid spec fails with an error. Thus the patterns are normalized as follows: - ;; derive all the missing patterns - (&plist :foo 'bar "baz") => (&plist :foo foo 'bar bar "baz" baz) + ;; derive all the missing patterns + (&plist :foo 'bar "baz") => (&plist :foo foo 'bar bar "baz" baz) - ;; we can specify some but not others - (&plist :foo 'bar explicit-bar) => (&plist :foo foo 'bar explicit-bar) + ;; we can specify some but not others + (&plist :foo 'bar explicit-bar) => (&plist :foo foo 'bar explicit-bar) - ;; nothing happens, we store :foo in x - (&plist :foo x) => (&plist :foo x) + ;; nothing happens, we store :foo in x + (&plist :foo x) => (&plist :foo x) - ;; nothing happens, we match recursively - (&plist :foo (a b c)) => (&plist :foo (a b c)) + ;; nothing happens, we match recursively + (&plist :foo (a b c)) => (&plist :foo (a b c)) You can name the source using the syntax @var{symbol} &as @var{pattern}. This syntax works with lists (proper or improper), vectors and all types of maps. - (list &as a b c) (list 1 2 3) + (list &as a b c) (list 1 2 3) binds @var{a} to 1, @var{b} to 2, @var{c} to 3 and @var{list} to (1 2 3). Similarly: - (bounds &as beg . end) (cons 1 2) + (bounds &as beg . end) (cons 1 2) binds @var{beg} to 1, @var{end} to 2 and @var{bounds} to (1 . 2). - (items &as first . rest) (list 1 2 3) + (items &as first . rest) (list 1 2 3) binds @var{first} to 1, @var{rest} to (2 3) and @var{items} to (1 2 3) - [vect &as _ b c] [1 2 3] + [vect &as _ b c] [1 2 3] binds @var{b} to 2, @var{c} to 3 and @var{vect} to [1 2 3] (_ avoids binding as usual). - (plist &as &plist :b b) (list :a 1 :b 2 :c 3) + (plist &as &plist :b b) (list :a 1 :b 2 :c 3) binds @var{b} to 2 and @var{plist} to (:a 1 :b 2 :c 3). Same for &alist and &hash. @@ -3851,7 +3851,7 @@ result and pass it to another computation, but at the same time we want to get the second item from each vector. We can achieve it with pattern - (result &as [_ a] [_ b]) (function-returning-complex-structure) + (result &as [_ a] [_ b]) (function-returning-complex-structure) Note: Clojure programmers may know this feature as the ":as binding". The difference is that we put the &as at the front @@ -3910,8 +3910,8 @@ Return a lambda which destructures its input as @var{match-form} and executes @v Note that you have to enclose the @var{match-form} in a pair of parens, such that: - (-lambda (x) body) - (-lambda (x y @dots{}) body) + (-lambda (x) body) + (-lambda (x y @dots{}) body) has the usual semantics of @code{lambda}. Furthermore, these get translated into normal @code{lambda}, so there is no performance @@ -3944,14 +3944,14 @@ Bind each @var{match-form} to the value of its @var{val}. This macro allows you to bind multiple variables by destructuring the value, so for example: - (-setq (a b) x - (&plist :c c) plist) + (-setq (a b) x + (&plist :c c) plist) expands roughly speaking to the following code - (setq a (car x) - b (cadr x) - c (plist-get plist :c)) + (setq a (car x) + b (cadr x) + c (plist-get plist :c)) Care is taken to only evaluate each @var{val} once so that in case of multiple assignments it does not cause unexpected side effects. @@ -4425,7 +4425,7 @@ In types: (a -> a) -> Int -> a -> a. This function satisfies the following law: - (funcall (-iteratefn fn n) init) = (-last-item (-iterate fn init (1+ n))). + (funcall (-iteratefn fn n) init) = (-last-item (-iterate fn init (1+ n))). @example @group @@ -4452,18 +4452,18 @@ argument, @var{x}, the initial value for the fixpoint iteration. The iteration halts when either of the following conditions is satisfied: 1. Iteration converges to the fixpoint, with equality being - tested using @var{equal-test}. If @var{equal-test} is not specified, - @code{equal} is used. For functions over the floating point - numbers, it may be necessary to provide an appropriate - approximate comparison test. + tested using @var{equal-test}. If @var{equal-test} is not specified, + @code{equal} is used. For functions over the floating point + numbers, it may be necessary to provide an appropriate + approximate comparison test. 2. @var{halt-test} returns a non-nil value. @var{halt-test} defaults to a - simple counter that returns t after @code{-fixfn-max-iterations}, - to guard against infinite iteration. Otherwise, @var{halt-test} - must be a function that accepts a single argument, the - current value of @var{x}, and returns non-nil as long as iteration - should continue. In this way, a more sophisticated - convergence test may be supplied by the caller. + simple counter that returns t after @code{-fixfn-max-iterations}, + to guard against infinite iteration. Otherwise, @var{halt-test} + must be a function that accepts a single argument, the + current value of @var{x}, and returns non-nil as long as iteration + should continue. In this way, a more sophisticated + convergence test may be supplied by the caller. The return value of the lambda is either the fixpoint or, if iteration halted before converging, a cons with car @code{halted} and @@ -4497,10 +4497,10 @@ In types (for n=2): ((a -> b), (c -> d)) -> (a, c) -> (b, d) This function satisfies the following laws: - (-compose (-prodfn f g @dots{}) (-prodfn f' g' @dots{})) = (-prodfn (-compose f f') (-compose g g') @dots{}) - (-prodfn f g @dots{}) = (-juxt (-compose f (-partial 'nth 0)) (-compose g (-partial 'nth 1)) @dots{}) - (-compose (-prodfn f g @dots{}) (-juxt f' g' @dots{})) = (-juxt (-compose f f') (-compose g g') @dots{}) - (-compose (-partial 'nth n) (-prod f1 f2 @dots{})) = (-compose fn (-partial 'nth n)) + (-compose (-prodfn f g @dots{}) (-prodfn f' g' @dots{})) = (-prodfn (-compose f f') (-compose g g') @dots{}) + (-prodfn f g @dots{}) = (-juxt (-compose f (-partial 'nth 0)) (-compose g (-partial 'nth 1)) @dots{}) + (-compose (-prodfn f g @dots{}) (-juxt f' g' @dots{})) = (-juxt (-compose f f') (-compose g g') @dots{}) + (-compose (-partial 'nth n) (-prod f1 f2 @dots{})) = (-compose fn (-partial 'nth n)) @example @group diff --git a/dev/examples-to-info.el b/dev/examples-to-info.el index 646f50d..ce445ad 100644 --- a/dev/examples-to-info.el +++ b/dev/examples-to-info.el @@ -102,7 +102,6 @@ Based on `describe-function-1'." (while (re-search-forward (rx (| (group bow (in "A-Z") (* (in "A-Z" ?-)) (* num) eow) (: ?` (group (+ (not (in ?\s)))) ?\') - (group bol " ") (: "..." (? (group eol))))) nil t) (cond ((match-beginning 1) @@ -115,11 +114,8 @@ Based on `describe-function-1'." "@code{\\2} (@pxref{\\2})" "@code{\\2}") t)) - ;; Indent examples within docstrings. - ;; FIXME: This has no effect in Texinfo. - ((match-beginning 3) (insert " ")) ;; Ellipses. - ((match-beginning 4) (replace-match "@enddots{}" t t)) + ((match-beginning 3) (replace-match "@enddots{}" t t)) ((replace-match "@dots{}" t t)))))))) (defun function-to-node (function)