active.clojure.lens — de.active-group/active-clojure 0.37.0

Lenses should obey the following laws:

GetPut, or YankShove:

(= (yank (shove data my-lens val)
         my-lens)
   val)

Meaning: you get back what you put in.

PutGet, or ShoveYank:

(= (shove data
          my-lens
          (yank data my-lens))
   data)

Meaning: putting back what you got does not change anything.

PutPut, or ShoveShove:

  (= (shove data my-lens val-1)
     (shove (shove data my-lens val-2) my-lens val-1))

Meaning: second shove wins, or shoving once is the same as shoving twice.

A lens that satisfies these three laws is usually called "very well-behaved". See also active.clojure.lens-test/lens-laws-hold.

** clj/s

(** & lenses)

Return the product of several lenses, which means that each lens is held over an element of a collection in the order they appear in the argument list.

++ clj/s

(++ & lenses)

Returns a lens over some data structure that shows a sequence of elements that each of the given lenses show on that. Note that the behaviour is undefined if those lenses do not show distrinct parts of the data structure.

>> clj/s

(>> & lenses)

Returns a concatenation of lenses, so that the combination shows the value of the last one, in a data structure that the first one is put over.

as-map clj/s

A lens that views a sequence of pairs as a map.

as-set clj/s

A lens that views a sequence as a set.

at-index clj/s

(at-index n)

Returns a lens that focuses on the value at index n in a collection. The sequence must have >= n elements. Preserves the collection type when shoving.

contains clj/s

(contains v)

Returns a lens showing the membership of the given value in a set.

default clj/s

(default dflt)

Returns a lens that shows nil as the given default value, but does not change any other value.

ExplicitLens clj/s

ExplicitLensWithoutArgs clj/s

first clj/s

A lens over the first element in a collection. Equivent to at-index of 0.

head clj/s

A lens focusing on the first element in a collection. It yanks nil if the collection is empty, and will not insert nil into an empty collection.

id clj/s

Identity lens, that just show a data structure as it is. It's also the neutral element of lens concatenation reacl.lens/>>.

is clj/s

(is v)

Returns a lens showing if a data structure equals the non-nil value v.

lens clj/s

(lens yanker shover)

(lens yanker shover & args)

Returns a new lens defined by the given yanker function, which takes a data structure and must return the focused value, and the given shover function which takes a data structure and the new value in the focus. Any additional arguments are passed unchanged to the yank and shove functions.

member clj/s

(member key & [not-found])

Returns a lens showing the value mapped to the given key in a map, not-found or nil if key is not present. Note that when not-found (or nil) is shoved into the map, the association is removed.

merge clj/s

A lens over a sequence of maps or records, that yields a merged map of all of them. If maps or records have fields of the same name, the value in right most map is used and updated on a change. If an update contains new keys, they are put in the left-most map. If an update misses keys, those fields are removed on the right-most element where they were before.

nel-head clj/s

A lens focusing on the first element in a non-empty collection. Behaviour on an empty collection is undefined.

nel-tail clj/s

A lens focusing on the all but the first element in a non-empty collection. Behaviour on an empty collection is undefined.

overhaul clj/s

(overhaul data lens f)

(overhaul data lens f & args)

Updates data using a lens. The new value will be determined by applying f to the old value and any other supplied arguments.

pattern clj/s

(pattern p)

A lens over any value yielding to a map or a vector, depending on the given pattern.

For example

  (pattern {:bar (at-index 0) :foo (at-index 2)})

will focus on the first and third elements of a sequence, as a map with the given keys.

Similarly, you can create a lens that yield a vector, given some fields of a map:

  (pattern [:bar :foo])

pos clj/s

(pos n)

A lens over the nth element in a sequence. Note that when shoving a new value nils may be added before the given position, if the collection is smaller.

second clj/s

A lens over the second element in a collection. Equivent to at-index of 1.

shove clj/s

(shove data lens v)

Shove a new value v into the given data value, as defined by the given lens, and return the updated data structure.

tail clj/s

A lens focusing on the all but the first element in a collection. Note that nil will be prepended when shoving into an empty collection.

void clj/s

A trivial lens that just shows nil over anything, and does never change anything.

xmap clj/s

(xmap f g & args)

Returns a "view lens", that transforms a whole data structure to something else (f) and back (g).

yank clj/s

(yank data lens)

Yank a value from the given data value, as defined by the given lens.