dash.el Emacs

The Emacs Series Exploring dash.el

dash.el is an inventory library for Emacs released underneath the GNU Common Public License v3.zero. It has been written by Magnar Sveen and the newest launch is v2.15.0. The supply code is accessible at https://github.com/magnars/dash.el. On this first part of the collection of articles on dash.el, we’ll explore features on map transformations, sublist choice, record operations and reductions.

Earlier than going into any details about dash.el, let’s first get the installation completed.

Installation
The dash.el package deal is out there in Milkypostman’s Emacs Lisp Package deal Archive (MELPA) and within the Marmalede repo. You possibly can set up the package deal utilizing the next command in GNU Emacs:

M-x package-install dash

If you would like the perform combinators, you then also needs to set up the following:

M-x package-install dash-functional

The other technique of set up is to repeat the dash.el source file to your Emacs load path and use it.
In an effort to get syntax highlighting of dash features in Emacs buffers, you possibly can add the following to your Emacs initialisation settings:

(eval-after-load ‘sprint ‘(dash-enable-font-lock))

Utilization
The API features obtainable in dash.el are prefixed with a touch
(‘-‘). Allow us to first discover the map transformation features on lists.

Maps
The ‘-map’ perform applies a given perform to each component in an inventory. In the following example, the ‘square’ perform squares every aspect in the record:

(-map perform listing) ;; Syntax

(defun square (n) (* n n))
(-map ‘sq. ‘(2 three 4))
(4 9 16)

The ‘-map-when’ perform takes three arguments — a predicate perform, an software perform, and an inventory. All the weather of the record that match the predicate perform are reworked using the appliance perform. If a component does not satisfy the predicate perform, the value is unchanged. The ‘even?’ perform takes a quantity as the enter and determines if it is a good or odd number. This can be used as the predicate perform, along with the sq. perform as the appliance perform to the listing (2 three 4) as proven under:

(-map-when predicate software record) ;; Syntax

(defun even? (num) (= 0 (% num 2)))
(-map-when ‘even? ‘sq. ‘(2 three Four))
(Four 3 16)

The ‘-map-first’ perform replaces the first factor within the record that matches the predicate perform and executes the appliance perform on the aspect. Equally, the ‘-map-last’ perform replaces the last component in the listing that satisfies the predicate perform by executing the appliance perform on the aspect. A couple of examples are given under:

(-map-first predicate software listing) ;; Syntax
(-map-last predicate software listing) ;; Syntax

(-map-first ‘even? ‘square ‘(2 3 Four))
(4 three Four)

(-map-last ‘even? ‘sq. ‘(2 3 Four))
(2 three 16)

The ‘-annotate’API applies a perform to each factor of the record, and pairs the end result to the unmodified record. An instance is proven under:

(-annotate perform listing) ;; Syntax

(-annotate ‘length ‘((“a” “b” “c”) (“foo” “bar”)))
((3 “a” “b” “c”) (2 “foo” “bar”))

The ‘-splice-list’ perform takes three arguments — a predicate perform, a brand new record and the input record. It splices the enter record at locations the place the weather match the predicate perform with the new record. In the following instance, the input listing ‘(x :symbol y)’ is spliced between x and y because the predicate perform checks for a key phrase, and replaces it with the new listing ‘(a b c)’.

(-splice-list predicate new-list record) ;; Syntax

(-splice-list ‘keywordp ‘(a b c) ‘(x :image y))
(x a b c y)

The ‘-mapcat’ perform takes a perform and an inventory, applies the perform to every component of the listing, and concatenates the results. For instance:

(-mapcat perform listing) ;; Syntax

(–mapcat (record ‘* it) ‘(9 8 7))
(* 9 * Eight * 7)

Sublist choice
The ‘-filter’ perform returns only these parts of an inventory that match the predicate perform handed to it as an argument:

(-filter predicate record) ;; Syntax

(-filter ‘even? ‘(1 2 3 Four))
(2 Four)

The ‘-remove’ perform removes those parts that match the predicate perform from the input record, and returns a new record as proven under:

(-remove predicate listing) ;; Syntax

(-remove ‘even? ‘(1 2 3 Four))
(1 3)

Should you only need to remove the primary factor or final factor from the input listing that matches the predicate perform, then you need to use the ‘-remove-first’ and ‘-remove-last’ features respectively. A few examples are given under for reference:

(-remove-first predicate listing) ;; Syntax
(-remove-last predicate record) ;; Syntax

(-remove-first ‘even? ‘(1 2 three Four))
(1 3 4)

(-remove-last ‘even? ‘(1 2 three 4 5 6 7 8 9 zero))
(1 2 three Four 5 6 7 8 9)

The ‘-non-nil’ perform returns all the weather from the input listing that are not nil. For instance:

(-non-nil ‘(1 2 three nil 4 5 6 nil))
(1 2 3 4 5 6)

The ‘-slice’ perform takes an input listing as an argument and returns all the weather between a ‘from’ and ‘to’ position. The record index begins from zero, and an elective step may also be given. Within the following instance, the second factor from the enter listing is returned.

(-slice listing from to step) ;; Syntax

(-slice ‘(1 2 3 Four 5) 2 3)
(three)

The ‘-take’ perform returns a brand new record with the first N (quantity) parts from the enter record. If N is bigger than the number of parts in the record, then your complete listing is returned. For example:

(-take N listing) ;; Syntax

(-take three ‘(1 2 3 Four 5))
(1 2 3)

The ‘-take-last’ perform returns the final N gadgets from the input record.

(-take-last N record) ;; Syntax

(-take-last three ‘(1 2 3 Four 5))
(3 Four 5)

The ‘-drop’ perform removes the first N gadgets from the input record, and returns the rest of the listing (tail), while the ‘-drop-last’ perform removes the final N gadgets from the record and returns the remainder of the record. A couple of examples are proven under:

(-drop N record) ;; Syntax
(-drop-last N listing) ;; Syntax

(-drop 3 ‘(1 2 3 4 5))
(Four 5)

(-drop-last three ‘(1 2 three 4 5))
(1 2)

The ‘-take-while’ perform returns the input record until each factor satisfies the predicate perform. The perform usage is demonstrated with the next examples:

(-take-while predicate listing) ;; Syntax

(-take-while ‘even? ‘(1 2 3))
nil

(-take-while ‘even? ‘(2 3 Four))
(2)

The ‘-drop-while’ perform removes the weather from the input listing so long as the predicate perform matches, and returns the rest of the listing. A couple of examples are proven under:

(-drop-while predicate listing) ;; Syntax

(-drop-while ‘even? ‘(1 2 3 Four))
(1 2 3 4)
(-drop-while ‘even? ‘(2 3 4 5))
(three Four 5)

The parts of an inventory at specific indices may be returned utilizing the ‘-select-by-indices’ perform. It takes an inventory of indices as an argument and an enter listing. For instance:

(-select-by-indices indices record) ;; Syntax

(-select-by-indices ‘(0 2 3) ‘(“a” “b” “c” “d” “e”))
(“a” “c” “d”)

A matrix or desk could be represented as an inventory of lists. The parts in a selected column could be returned as an inventory utilizing the ‘-select-column’ perform. An example is given under:

(-select-column columns desk) ;; Syntax

(-select-column 1 ‘((1 2 three) (Four 5 6) (7 8 9)))
(2 5 8)
3.3.

Listing to record operations
The ‘-keep’ perform takes a perform as an argument and applies the previous to each factor within the record. It then returns a new record with those parts that return a non-nil value for the perform software. For instance:

(-keep perform listing) ;; Syntax

(-keep ‘cdr ‘((7 Eight 9) (7 Eight) (7)))
((Eight 9) (Eight))

If you wish to concatenate lists collectively, you need to use the ‘-concat’ perform as shown under:

(-concat ‘(1) ‘(2 3) ‘(Four))

(1 2 3 4)

Nested lists may be flattened to a single listing utilizing the ‘-flatten’ perform. You can even specify the level of the nested record to flatten using the ‘-flatten-n’ perform. A couple of examples are offered under for instance the perform’s use:

(-flatten listing) ;; Syntax
(-flatten-n N record) ;; Syntax

(-flatten ‘((5)))
(5)
(-flatten ‘((1 (2 three) (((Four (5)))))))
(1 2 3 4 5)

(-flatten-n 1 ‘((1 2) ((3 4) ((5 6)))))
(1 2 (3 Four) ((5 6)))

The ‘-replace’ perform replaces previous gadgets in the listing with the brand new item. For instance:

(-replace previous new record) ;; Syntax

(-replace 1 “one” ‘(1 2 three 4 5))
(“one” 2 three Four 5)

The ‘-replace-first’ perform replaces the primary prevalence of the previous item in the listing with the new item, while, the ‘-replace-last’ perform replaces the last prevalence of the previous item with the new merchandise. A couple of examples to reveal the perform software are given under:

(-replace-first previous new record) ;; Syntax
(-replace-last previous new listing) ;; Syntax

(-replace-first 1 “one” ‘(1 2 1 2 1 2))
(“one” 2 1 2 1 2)

(-replace-last 1 “one” ‘(1 2 1 2 1 2))
(1 2 1 2 “one” 2)

The ‘-insert-at’ perform returns an inventory with the input component inserted on the specified position in the argument record. For instance:

(-insert-at position aspect record) ;; Syntax

(-insert-at 1 2 ‘(1 3 4))
(1 2 three 4)

The ‘-replace-at’ perform replaces an element within the specified position with the enter component for the given argument record. In the following instance, the aspect at index 1 is changed with the number ‘2’.

(-replace-at place aspect record) ;; Syntax

(-replace-at 1 2 ‘(1 1 three Four))
(1 2 3 Four)

The ‘–update-at’ perform takes three arguments — a position, a perform and an input listing. It takes the aspect at the place, applies the perform on the component changing it with the perform outcome, and returns the listing. For instance:

(-update-at position perform record) ;; Syntax

(–update-at 1 (length it) ‘(“thank” “you” “very” “much”))
(“thank” 3 “very” “much”)

The ‘-remove-at’ perform returns an inventory with the factor on the given place faraway from the argument listing. An instance is given under:

(-remove-at place record) ;; Syntax

(-remove-at 2 ‘(1 2 three 4 5))
(1 2 4 5)

Reductions
In this part, we’ll go through features that scale back an inventory to a single worth. This can be a discount or merge perform.
The ‘-reduce-from’ perform takes three arguments — a perform, an initial value and an inventory. It begins by applying the perform to the preliminary worth and the first component of the record. The outcome then turns into the new preliminary worth or accumulator. The perform is then utilized to this new value and the second component of the listing, and so on. For example:

(-reduce-from perform initial-value record) ;; Syntax

(-reduce-from ‘- 100 ‘(10 20 30))
40

The perform software happens in the following order for the above example:

((- 100 10) 20 30) ; 100 – 10 = 90
((- 90 20) 30) ; 90 – 20 = 70
(- 70 30) ; 70 – 30 = 40

The ‘-reduce-r-from’API is just like the ‘-reduce-from’ perform, besides that the operation association occurs from the right-hand aspect as an alternative of the left-hand aspect. An example is given under for example the perform software:

(-reduce-r-from perform initial-value record) ;; Syntax

(-reduce-r-from ‘- 100 ‘(10 20 30))
-80

The perform software evaluates within the following order for the above instance:

((- 30 100) 10 20) ; 30 – 100 = -70
((- 20 (-70)) 10) ; 20 – (-70) = 90
(- 10 90) ; 10 – 90 = -80

The ‘-reduce’ perform applies the perform to the primary two parts of the listing, then applies the perform to the earlier outcome, after which to the third aspect of the listing, and so forth. For instance:

(-reduce perform record) ;; Syntax

(-reduce ‘- ‘(1 2 three Four))
-Eight

The perform software analysis order for the above instance is as follows:

((- 1 2) 3 4) ; 1 – 2 = -1
((- (-1) 3) 4) ; (-1) – 3 = -4
(- (-Four) Four) ; (-Four) – 4 = -Eight

The ‘-reduce-r’ perform is just like the ‘-reduce’ perform with the exception that it evaluates from right-to-left. An instance for example the perform is given under:

(-reduce-r perform listing) ;; Syntax

(-reduce-r ‘- ‘(1 2 3 4))
-2

The perform software evaluation order is as follows for the above instance:

((- 3 Four) 1 2) ; 3 – 4 = -1
((- 2 (-1)) 1) ; 2 – (-1) = three
(- 1 3) ; 1 – three = -2

The ‘-count’ perform takes a predicate perform and an inventory as arguments. It counts the number of gadgets that fulfill the predicate perform. For example:

(-count predicate record) ;; Syntax

(-count ‘even? ‘(1 2 three 4))
2

The ‘-sum’ perform merely returns the sum of the record. A couple of examples are proven under:

(-sum listing) ;; Syntax

(-sum ‘())
0
(-sum ‘(1))
1
(-sum ‘(1 2 three 4))
10

The ‘-product’ perform computes the product of the weather in an inventory. An example is given under:

(-product listing) ;; Syntax

(-product ‘(1 2 three 4))
24

The ‘-min’ and ‘-max’ features return the smallest and largest values from the gadgets in an inventory. A couple of examples are proven under:

(-min record) ;; Syntax
(-max record) ;; Syntax

(-min ‘(5 2 3 Four))
2

(-max ‘(1 2 3))
3

The ‘-min-by’ and ‘-max-by’ features take a comparator perform as an argument, and return the least and biggest parts in an inventory, based mostly on the comparison perform. A number of examples are given under:

(-min-by comparator record) ;; Syntax
(-max-by comparator listing) ;; Syntax

(-min-by ‘> ‘(5 2 three Four))
2

(-max-by ‘> ‘(5 2 three 4))
5

(–max-by (> (length it) (size different)) ‘((1 2 three) (Four) (5 6)))
(1 2 3)

We’ll explore more features from dash.el within the second a part of this collection of articles.

About the author

Admin