A modern list api for Emacs. No 'cl required.
It's available on marmalade and Melpa:
M-x package-install dash
Or you
ED4F
can just dump dash.el in your load path somewhere.
- -map
(fn list) - -reduce-from
(fn initial-value list) - -reduce
(fn list) - -filter
(pred list) - -remove
(pred list) - -keep
(fn list) - -map-when
(pred rep list) - -flatten
(l) - -concat
(&rest lists) - -mapcat
(fn list) - -any?
(pred list) - -all?
(pred list) - -none?
(pred list) - -only-some?
(pred list) - -each
(list fn) - -each-while
(list pred fn) - -dotimes
(num fn) - -take
(n list) - -drop
(n list) - -take-while
(pred list) - -drop-while
(pred list) - -split-at
(n list) - -split-with
(pred list) - -separate
(pred list) - -partition
(n list) - -partition-all
(n list) - -partition-by
(fn list) - -interpose
(sep list) - -interleave
(&rest lists) - -first
(pred list) - -union
(list list2) - -difference
(list list2) - -intersection
(list list2) - -distinct
(list) - -contains?
(list element) - -partial
(fn &rest args) - -rpartial
(fn &rest args) - ->
(x &optional form &rest more) - ->>
(x form &rest more) - -->
(x form &rest more) - !cons
(car cdr) - !cdr
(list)
There are also anaphoric versions of these functions where that makes sense, prefixed with two dashes instead of one.
While -map takes a function to map over the list, you can also use
the anaphoric form with double dashes - which will then be executed
with it exposed as the list item. Here's an example:
(-map (lambda (n) (* n n)) '(1 2 3 4)) ;; normal version
(--map (* it it) '(1 2 3 4)) ;; anaphoric versionof course the original can also be written like
(defun square (n) (* n n))
(-map 'square '(1 2 3 4))which demonstrates the usefulness of both versions.
Returns a new list consisting of the result of applying fn to the items in list.
(-map (lambda (num) (* num num)) '(1 2 3 4)) ;; => '(1 4 9 16)
(-map 'square '(1 2 3 4)) ;; => '(1 4 9 16)
(--map (* it it) '(1 2 3 4)) ;; => '(1 4 9 16)Returns the result of applying fn to initial-value and the
first item in list, then applying fn to that result and the 2nd
item, etc. If list contains no items, returns initial-value and
fn is not called.
In the anaphoric form --reduce-from, the accumulated value is
exposed as acc.
(-reduce-from '+ 7 '(1 2)) ;; => 10
(-reduce-from (lambda (memo item) (+ memo item)) 7 '(1 2)) ;; => 10
(--reduce-from (+ acc it) 7 '(1 2 3)) ;; => 13Returns the result of applying fn to the first 2 items in list,
then applying fn to that result and the 3rd item, etc. If list
contains no items, fn must accept no arguments as well, and
reduce returns the result of calling fn with no arguments. If
list has only 1 item, it is returned and fn is not called.
In the anaphoric form --reduce, the accumulated value is
exposed as acc.
(-reduce '+ '(1 2)) ;; => 3
(-reduce (lambda (memo item) (format "%s-%s" memo item)) '(1 2 3)) ;; => "1-2-3"
(--reduce (format "%s-%s" acc it) '(1 2 3)) ;; => "1-2-3"Returns a new list of the items in list for which pred returns a non-nil value.
Alias: -select
(-filter (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(2 4)
(-filter 'even? '(1 2 3 4)) ;; => '(2 4)
(--filter (= 0 (% it 2)) '(1 2 3 4)) ;; => '(2 4)Returns a new list of the items in list for which pred returns nil.
Alias: -reject
(-remove (lambda (num) (= 0 (% num 2))) '(1 2 3 4)) ;; => '(1 3)
(-remove 'even? '(1 2 3 4)) ;; => '(1 3)
(--remove (= 0 (% it 2)) '(1 2 3 4)) ;; => '(1 3)Returns a new list of the non-nil results of applying fn to the items in list.
(-keep 'cdr '((1 2 3) (4 5) (6))) ;; => '((2 3) (5))
(-keep (lambda (num) (when (> num 3) (* 10 num))) '(1 2 3 4 5 6)) ;; => '(40 50 60)
(--keep (when (> it 3) (* 10 it)) '(1 2 3 4 5 6)) ;; => '(40 50 60)Returns a new list where the elements in list that does not match the pred function
are unchanged, and where the elements in list that do match the pred function are mapped
through the rep function.
(-map-when 'even? 'square '(1 2 3 4)) ;; => '(1 4 3 16)
(--map-when (> it 2) (* it it) '(1 2 3 4)) ;; => '(1 2 9 16)
(--map-when (= it 2) 17 '(1 2 3 4)) ;; => '(1 17 3 4)Takes a nested list l and returns its contents as a single, flat list.
(-flatten '((1))) ;; => '(1)
(-flatten '((1 (2 3) (((4 (5))))))) ;; => '(1 2 3 4 5)Returns a new list with the concatenation of the elements in the supplied lists.
(-concat '(1)) ;; => '(1)
(-concat '(1) '(2)) ;; => '(1 2)
(-concat '(1) '(2 3) '(4)) ;; => '(1 2 3 4)Returns the result of applying concat to the result of applying map to fn and list.
Thus function fn should return a collection.
(-mapcat 'list '(1 2 3)) ;; => '(1 2 3)
(-mapcat (lambda (item) (list 0 item)) '(1 2 3)) ;; => '(0 1 0 2 0 3)
(--mapcat (list 0 it) '(1 2 3)) ;; => '(0 1 0 2 0 3)Returns t if (pred x) is non-nil for any x in list, else nil.
Alias: -some?
(-any? 'even? '(1 2 3)) ;; => t
(-any? 'even? '(1 3 5)) ;; => nil
(--any? (= 0 (% it 2)) '(1 2 3)) ;; => tReturns t if (pred x) is non-nil for all x in list, else nil.
Alias: -every?
(-all? 'even? '(1 2 3)) ;; => nil
(-all? 'even? '(2 4 6)) ;; => t
(--all? (= 0 (% it 2)) '(2 4 6)) ;; => tReturns t if (pred x) is nil for all x in list, else nil.
(-none? 'even? '(1 2 3)) ;; => nil
(-none? 'even? '(1 3 5)) ;; => t
(--none? (= 0 (% it 2)) '(1 2 3)) ;; => nilReturns t if there is a mix of items in list that matches and does not match pred.
Returns nil both if all items match the predicate, and if none of the items match the predicate.
(-only-some? 'even? '(1 2 3)) ;; => t
(-only-some? 'even? '(1 3 5)) ;; => nil
(-only-some? 'even? '(2 4 6)) ;; => nilCalls fn with every item in list. Returns nil, used for side-effects only.
(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s))))) ;; => nil
(let (s) (-each '(1 2 3) (lambda (item) (setq s (cons item s)))) s) ;; => '(3 2 1)
(let (s) (--each '(1 2 3) (setq s (cons it s))) s) ;; => '(3 2 1)Calls fn with every item in list while (pred item) is non-nil.
Returns nil, used for side-effects only.
(let (s) (-each-while '(2 4 5 6) 'even? (lambda (item) (!cons item s))) s) ;; => '(4 2)
(let (s) (--each-while '(1 2 3 4) (< it 3) (!cons it s)) s) ;; => '(2 1)Repeatedly calls fn (presumably for side-effects) passing in integers from 0 through n-1.
(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)Returns a new list of the first n items in list, or all items if there are fewer than n.
(-take 3 '(1 2 3 4 5)) ;; => '(1 2 3)
(-take 17 '(1 2 3 4 5)) ;; => '(1 2 3 4 5)Returns the tail of list without the first n items.
(-drop 3 '(1 2 3 4 5)) ;; => '(4 5)
(-drop 17 '(1 2 3 4 5)) ;; => '()Returns a new list of successive items from list while (pred item) returns a non-nil value.
(-take-while 'even? '(1 2 3 4)) ;; => '()
(-take-while 'even? '(2 4 5 6)) ;; => '(2 4)
(--take-while (< it 4) '(1 2 3 4 3 2 1)) ;; => '(1 2 3)Returns the tail of list starting from the first item for which (pred item) returns nil.
(-drop-while 'even? '(1 2 3 4)) ;; => '(1 2 3 4)
(-drop-while 'even? '(2 4 5 6)) ;; => '(5 6)
(--drop-while (< it 4) '(1 2 3 4 3 2 1)) ;; => '(4 3 2 1)Returns a list of ((-take n list) (-drop n list))
(-split-at 3 '(1 2 3 4 5)) ;; => '((1 2 3) (4 5))
(-split-at 17 '(1 2 3 4 5)) ;; => '((1 2 3 4 5) nil)Returns a list of ((-take-while pred list) (-drop-while pred list))
(-split-with 'even? '(1 2 3 4)) ;; => '(nil (1 2 3 4))
(-split-with 'even? '(2 4 5 6)) ;; => '((2 4) (5 6))
(--split-with (< it 4) '(1 2 3 4 3 2 1)) ;; => '((1 2 3) (4 3 2 1))Returns a list of ((-filter pred list) (-remove pred list)).
(-separate (lambda (num) (= 0 (% num 2))) '(1 2 3 4 5 6 7)) ;; => '((2 4 6) (1 3 5 7))
(--separate (< it 5) '(3 7 5 9 3 2 1 4 6)) ;; => '((3 3 2 1 4) (7 5 9 6))
(-separate 'cdr '((1 2) (1) (1 2 3) (4))) ;; => '(((1 2) (1 2 3)) ((1) (4)))Returns a new list with the items in list grouped into n-sized sublists.
If there are not enough items to make the last group n-sized,
those items are discarded.
(-partition 2 '(1 2 3 4 5 6)) ;; => '((1 2) (3 4) (5 6))
(-partition 2 '(1 2 3 4 5 6 7)) ;; => '((1 2) (3 4) (5 6))
(-partition 3 '(1 2 3 4 5 6 7)) ;; => '((1 2 3) (4 5 6))Returns a new list with the items in list grouped into n-sized sublists.
The last group may contain less than n items.
(-partition-all 2 '(1 2 3 4 5 6)) ;; => '((1 2) (3 4) (5 6))
(-partition-all 2 '(1 2 3 4 5 6 7)) ;; => '((1 2) (3 4) (5 6) (7))
(-partition-all 3 '(1 2 3 4 5 6 7)) ;; => '((1 2 3) (4 5 6) (7))Applies fn to each value in list, splitting it each time fn returns a new value.
(-partition-by 'even? '()) ;; => '()
(-partition-by 'even? '(1 1 2 2 2 3 4 6 8)) ;; => '((1 1) (2 2 2) (3) (4 6 8))
(--partition-by (< it 3) '(1 2 3 4 3 2 1)) ;; => '((1 2) (3 4 3) (2 1))Returns a new list of all elements in list separated by sep.
(-interpose "-" '()) ;; => '()
(-interpose "-" '("a")) ;; => '("a")
(-interpose "-" '("a" "b" "c")) ;; => '("a" "-" "b" "-" "c")Returns a new list of the first item in each list, then the second etc.
(-interleave '(1 2) '("a" "b")) ;; => '(1 "a" 2 "b")
(-interleave '(1 2) '("a" "b") '("A" "B")) ;; => '(1 "a" "A" 2 "b" "B")
(-interleave '(1 2 3) '("a" "b")) ;; => '(1 "a" 2 "b")Returns the first x in list where (pred x) is non-nil, else nil.
To get the first item in the list no questions asked, use car.
(-first 'even? '(1 2 3)) ;; => 2
(-first 'even? '(1 3 5)) ;; => nil
(--first (> it 2) '(1 2 3)) ;; => 3Return a new list containing the elements of list1 and elements of list2 that are not in list1.
The test for equality is done with equal,
or with -compare-fn if that's non-nil.
(-union '(1 2 3) '(3 4 5)) ;; => '(1 2 3 4 5)
(-union '(1 2 3 4) '()) ;; => '(1 2 3 4)
(-union '(1 1 2 2) '(3 2 1)) ;; => '(1 1 2 2 3)Return a new list with only the members of list that are not in list2.
The test for equality is done with equal,
or with -compare-fn if that's non-nil.
(-difference '() '()) ;; => '()
(-difference '(1 2 3) '(4 5 6)) ;; => '(1 2 3)
(-difference '(1 2 3 4) '(3 4 5 6)) ;; => '(1 2)Return a new list containing only the elements that are members of both list and list2.
The test for equality is done with equal,
or with -compare-fn if that's non-nil.
(-intersection '() '()) ;; => '()
(-intersection '(1 2 3) '(4 5 6)) ;; => '()
(-intersection '(1 2 3 4) '(3 4 5 6)) ;; => '(3 4)Return a new list with all duplicates removed.
The test for equality is done with equal,
or with -compare-fn if that's non-nil.
Alias: -uniq
(-distinct '()) ;; => '()
(-distinct '(1 2 2 4)) ;; => '(1 2 4)Return whether list contains element.
The test for equality is done with equal,
or with -compare-fn if that's non-nil.
(-contains? '(1 2 3) 1) ;; => t
(-contains? '(1 2 3) 2) ;; => t
(-contains? '(1 2 3) 4) ;; => nilTakes a function fn and fewer than the normal arguments to fn,
and returns a fn that takes a variable number of additional args.
When called, the returned function calls fn with args first and
then additional args.
(funcall (-partial '- 5) 3) ;; => 2
(funcall (-partial '+ 5 2) 3) ;; => 10Takes a function fn and fewer than the normal arguments to fn,
and returns a fn that takes a variable number of additional args.
When called, the returned function calls fn with the additional
args first and then args.
Requires Emacs 24 or higher.
(funcall (-rpartial '- 5) 8) ;; => 3
(funcall (-rpartial '- 5 2) 10) ;; => 3Threads the expr through the forms. Inserts x as the second
item in the first form, making a list of it if it is not a list
already. If there are more forms, inserts the first form as the
second item in second form, etc.
(-> "Abc") ;; => "Abc"
(-> "Abc" (concat "def")) ;; => "Abcdef"
(-> "Abc" (concat "def") (concat "ghi")) ;; => "Abcdefghi"Threads the expr through the forms. Inserts x as the last item
in the first form, making a list of it if it is not a list
already. If there are more forms, inserts the first form as the
last item in second form, etc.
(->> "Abc" (concat "def")) ;; => "defAbc"
(->> "Abc" (concat "def") (concat "ghi")) ;; => "ghidefAbc"
(->> 5 (- 8)) ;; => 3Threads the expr through the forms. Inserts x at the position
signified by the token it in the first form. If there are more
forms, inserts the first form at the position signified by it
in in second form, etc.
(--> "def" (concat "abc" it "ghi")) ;; => "abcdefghi"
(--> "def" (concat "abc" it "ghi") (upcase it)) ;; => "ABCDEFGHI"
(--> "def" (concat "abc" it "ghi") upcase) ;; => "ABCDEFGHI"Destructive: Sets cdr to the cons of car and cdr.
(let (l) (!cons 5 l) l) ;; => '(5)
(let ((l '(3))) (!cons 5 l) l) ;; => '(5 3)Destructive: Sets list to the cdr of list.
(let ((l '(3))) (!cdr l) l) ;; => '()
(let ((l '(3 5))) (!cdr l) l) ;; => '(5)Yes, please do. Pure functions in the list manipulation realm only,
please. There's a suite of tests in examples.el, so remember to add
tests for your function, or I might break it later.
You'll find the repo at:
https://github.com/magnars/dash.el
Run the tests with
./run-tests.sh
Create the docs with
./create-docs.sh
I highly recommend that you install these as a pre-commit hook, so that the tests are always running and the docs are always in sync:
cp pre-commit.sh .git/hooks/pre-commit
Oh, and don't edit README.md directly, it is auto-generated.
Change readme-template.md or examples-to-docs.el instead.
- Fuco contributed
-unionand-separate.
Thanks!
Copyright (C) 2012 Magnar Sveen
Authors: Magnar Sveen magnars@gmail.com Keywords: lists
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.