-let is a macro defined in dash.el.
Signature
(-let VARLIST &rest BODY)
Documentation
Bind variables according to VARLIST then eval BODY.
VARLIST is a list of lists of the form (PATTERN SOURCE). Each
PATTERN is matched against the SOURCE "structurally". SOURCE
is only evaluated once for each PATTERN. Each PATTERN is matched
recursively, and can therefore contain sub-patterns which are
matched against corresponding sub-expressions of SOURCE.
All the SOURCEs are evalled before any symbols are
bound (i.e. "in parallel").
If VARLIST only contains one (PATTERN SOURCE) element, you can
optionally specify it using a vector and discarding the
outer-most parens. Thus
(-let ((PATTERN SOURCE)) ...)
becomes
(-let [PATTERN SOURCE] ...).
-let uses a convention of not binding places (symbols) starting
with _ whenever it's possible. You can use this to skip over
entries you don't care about. However, this is not *always*
possible (as a result of implementation) and these symbols might
get bound to undefined values.
Following is the overview of supported patterns. Remember that
patterns can be matched recursively, so every a, b, aK in the
following can be a matching construct and not necessarily a
symbol/variable.
Symbol:
a - bind the SOURCE to A. This is just like regular let.
Conses and lists:
(a) - bind car of cons/list to A
(a . b) - bind car of cons to A and cdr to B
(a b) - bind car of list to A and cadr to B
(a1 a2 a3 ...) - bind 0th car of list to A1, 1st to A2, 2nd to A3...
(a1 a2 a3 ... aN . rest) - as above, but bind the Nth cdr to REST.
Vectors:
[a] - bind 0th element of a non-list sequence to A (works with
vectors, strings, bit arrays...)
[a1 a2 a3 ...] - bind 0th element of non-list sequence to A0, 1st to
A1, 2nd to A2, ...
If the PATTERN is shorter than SOURCE, the values at
places not in PATTERN are ignored.
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)
Key/value stores:
(&plist key0 a0 ... keyN aN) - bind value mapped by keyK in the
SOURCE plist to aK. If the
value is not found, aK is nil.
Uses plist-get to fetch values.
(&alist key0 a0 ... keyN aN) - bind value mapped by keyK in the
SOURCE alist to aK. If the
value is not found, aK is nil.
Uses assoc to fetch values.
(&hash key0 a0 ... keyN aN) - bind value mapped by keyK in the
SOURCE hash table to aK. If the
value is not found, aK is nil.
Uses gethash to fetch values.
Further, special keyword &keys supports "inline" matching of
plist-like key-value pairs, similarly to &keys keyword of
cl-defun.
(a1 a2 ... aN &keys key1 b1 ... keyN bK)
This binds N values from the list to a1 ... aN, then interprets
the cdr as a plist (see key/value matching above).
A shorthand notation for kv-destructuring exists which allows the
patterns be optionally left out and derived from the key name in
the following fashion:
- a key :foo is converted into foo pattern,
- a key 'bar is converted into bar pattern,
- a key "baz" is converted into baz pattern.
That is, the entire value under the key is bound to the derived
variable without any further destructuring.
This is possible only when the form following the key is not a
valid pattern (i.e. not a symbol, a cons cell or a vector).
Otherwise the matching proceeds as usual and in case of an
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)
;; 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 match recursively
(&plist :foo (a b c)) => (&plist :foo (a b c))
You can name the source using the syntax SYMBOL &as PATTERN.
This syntax works with lists (proper or improper), vectors and
all types of maps.
(list &as a b c) (list 1 2 3)
binds A to 1, B to 2, C to 3 and LIST to (1 2 3).
Similarly:
(bounds &as beg . end) (cons 1 2)
binds BEG to 1, END to 2 and BOUNDS to (1 . 2).
(items &as first . rest) (list 1 2 3)
binds FIRST to 1, REST to (2 3) and ITEMS to (1 2 3)
[vect &as _ b c] [1 2 3]
binds B to 2, C to 3 and VECT to [1 2 3] (_ avoids binding as usual).
(plist &as &plist :b b) (list :a 1 :b 2 :c 3)
binds B to 2 and PLIST to (:a 1 :b 2 :c 3). Same for &alist and &hash.
This is especially useful when we want to capture the result of a
computation and destructure at the same time. Consider the
form (function-returning-complex-structure) returning a list of
two vectors with two items each. We want to capture this entire
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)
Note: Clojure programmers may know this feature as the ":as
binding". The difference is that we put the &as at the front
because we need to support improper list binding.
References
-let is unused in dash.el.
Find all references Functions used by -let
Debugging
Enable edebug Enable tracing
Disassemble Forget
Source Code
~/.config/emacs/elpaca-test/builds/dash/dash.el
(defmacro -let (varlist &rest body)
"Bind variables according to VARLIST then eval BODY.
VARLIST is a list of lists of the form (PATTERN SOURCE). Each
PATTERN is matched against the SOURCE \"structurally\". SOURCE
is only evaluated once for each PATTERN. Each PATTERN is matched
recursively, and can therefore contain sub-patterns which are
matched against corresponding sub-expressions of SOURCE.
All the SOURCEs are evalled before any symbols are
bound (i.e. \"in parallel\").
If VARLIST only contains one (PATTERN SOURCE) element, you can
optionally specify it using a vector and discarding the
outer-most parens. Thus
(-let ((PATTERN SOURCE)) ...)
becomes
(-let [PATTERN SOURCE] ...).
`-let' uses a convention of not binding places (symbols) starting
with _ whenever it's possible. You can use this to skip over
entries you don't care about. However, this is not *always*
possible (as a result of implementation) and these symbols might
get bound to undefined values.
Following is the overview of supported patterns. Remember that
patterns can be matched recursively, so every a, b, aK in the
following can be a matching construct and not necessarily a
symbol/variable.
Symbol:
a - bind the SOURCE to A. This is just like regular `let'.
Conses and lists:
(a) - bind `car' of cons/list to A
(a . b) - bind car of cons to A and `cdr' to B
(a b) - bind car of list to A and `cadr' to B
(a1 a2 a3 ...) - bind 0th car of list to A1, 1st to A2, 2nd to A3...
(a1 a2 a3 ... aN . rest) - as above, but bind the Nth cdr to REST.
Vectors:
[a] - bind 0th element of a non-list sequence to A (works with
vectors, strings, bit arrays...)
[a1 a2 a3 ...] - bind 0th element of non-list sequence to A0, 1st to
A1, 2nd to A2, ...
If the PATTERN is shorter than SOURCE, the values at
places not in PATTERN are ignored.
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)
Key/value stores:
(&plist key0 a0 ... keyN aN) - bind value mapped by keyK in the
SOURCE plist to aK. If the
value is not found, aK is nil.
Uses `plist-get' to fetch values.
(&alist key0 a0 ... keyN aN) - bind value mapped by keyK in the
SOURCE alist to aK. If the
value is not found, aK is nil.
Uses `assoc' to fetch values.
(&hash key0 a0 ... keyN aN) - bind value mapped by keyK in the
SOURCE hash table to aK. If the
value is not found, aK is nil.
Uses `gethash' to fetch values.
Further, special keyword &keys supports \"inline\" matching of
plist-like key-value pairs, similarly to &keys keyword of
`cl-defun'.
(a1 a2 ... aN &keys key1 b1 ... keyN bK)
This binds N values from the list to a1 ... aN, then interprets
the cdr as a plist (see key/value matching above).
A shorthand notation for kv-destructuring exists which allows the
patterns be optionally left out and derived from the key name in
the following fashion:
- a key :foo is converted into `foo' pattern,
- a key \\='bar is converted into `bar' pattern,
- a key \"baz\" is converted into `baz' pattern.
That is, the entire value under the key is bound to the derived
variable without any further destructuring.
This is possible only when the form following the key is not a
valid pattern (i.e. not a symbol, a cons cell or a vector).
Otherwise the matching proceeds as usual and in case of an
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)
;; 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 match recursively
(&plist :foo (a b c)) => (&plist :foo (a b c))
You can name the source using the syntax SYMBOL &as PATTERN.
This syntax works with lists (proper or improper), vectors and
all types of maps.
(list &as a b c) (list 1 2 3)
binds A to 1, B to 2, C to 3 and LIST to (1 2 3).
Similarly:
(bounds &as beg . end) (cons 1 2)
binds BEG to 1, END to 2 and BOUNDS to (1 . 2).
(items &as first . rest) (list 1 2 3)
binds FIRST to 1, REST to (2 3) and ITEMS to (1 2 3)
[vect &as _ b c] [1 2 3]
binds B to 2, C to 3 and VECT to [1 2 3] (_ avoids binding as usual).
(plist &as &plist :b b) (list :a 1 :b 2 :c 3)
binds B to 2 and PLIST to (:a 1 :b 2 :c 3). Same for &alist and &hash.
This is especially useful when we want to capture the result of a
computation and destructure at the same time. Consider the
form (function-returning-complex-structure) returning a list of
two vectors with two items each. We want to capture this entire
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)
Note: Clojure programmers may know this feature as the \":as
binding\". The difference is that we put the &as at the front
because we need to support improper list binding."
(declare (debug ([&or (&rest [&or (sexp form) sexp])
(vector [&rest [sexp form]])]
body))
(indent 1))
(if (vectorp varlist)
`(let* ,(dash--match (aref varlist 0) (aref varlist 1))
,@body)
(let* ((varlist (dash--normalize-let-varlist varlist))
(inputs (--map-indexed (list (make-symbol (format "input%d" it-index)) (cadr it)) varlist))
(new-varlist (--zip-with (list (car it) (car other))
varlist inputs)))
`(let ,inputs
(-let* ,new-varlist ,@body)))))
Symbol Properties
edebug-form-spec
([&or
(&rest
[&or
(sexp form)
sexp])
(vector
[&rest
[sexp form]])]
body)
lisp-indent-function
1