active.clojure.lens — de.active-group/active-clojure 0.43.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. Note that the resulting collection is a lazy sequence (since it is constructed with map).

++ 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 distinct 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.

conditional clj/s

(conditional clause & clauses)

A lens similar to either that allows to specify multiple variants at once. The last argument must a single default lens, which is used when no predicate matches:

(conditional
  [yank? shove? lens]
  ...
  default)
=>
(either yank? shove? lens default)

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. Note that this lens changed the type of the underlying data from Maybe a to a and thus you must not shove nil into it.

defer clj/s

(defer var-lens)

A lens that defers evaluation of the given lens by lifting [[clojure.core/deref]] into lenses.

Argument var-lens must be a [[clojure.core/Var]] with a lens as its value.

either clj/s

(either yank? shove? then-lens else-lens)

A lens that behaves like then-lens if (yank? data) is true when yanking, resp. (shove? data value) when shoving, and behaves like else-lens otherwise.

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/>>.

invert clj/s

(invert l & [empty])

A lens that inverts another lens. Optional argument empty is the initial new value that lens focusses on, which defaults to nil.

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.

mapl clj/s

(mapl l)

Returns a lens that maps a given lens over a collection.

mapl-kv clj/s

(mapl-kv key-lens val-lens)

Returns a lens that maps the given key-lens and val-lens over a key-value map and returns a key-value map. Note that this special lens is needed to since using mapl together with ** and as-map to achieve something similar is hard, due to the fact that ** returns a lazy list and as-map (or rather (into {} ...) expects a two-element vector to be equivalent to a clojure.lang.MapEntry). Something like this would work, but this is way to complicated and obscure:

(>> (invert as-map) (mapl (xmap vec vec)) (mapl (invert (invert (** key-lens value-lens) (first (seq {nil nil}))))) (mapl (xmap vec vec)) as-map)

Using a specialization of ** to return vectors or even MapEntrys would improve the above chain, but these specialized versions would only make sense for mapping maps, so let's just provide that lens.

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.

project clj/s

(project fields & [empty])

A lens that projects multiple derived values into a new value, with an optional empty being an initial new value, and fields a map or sequence of tuples, of a lens on the new value and lens over the 'outer' value the lens is used on.

The optional empty will default to nil, so you can nil-pun your way to blissful oblivion:

  (projection {(at-index 0) :a
               (at-index 1) :b})

projection clj/s

(projection empty fields)

A lens that projects multiple derived values into a new value, with empty being an initial new value, and fields a map or sequence of tuples, of a lens on the new value and lens over the 'outer' value the lens is used on.

As an example, this can be used to map between two record types like this:

  (projection (make-inner-record nil)
              {inner-record-field outer-record-field})

The returned lens can then be used on a value of type 'outer-record', to see it as a value of type 'inner-record'.

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.

surjection clj/s

(surjection & lenses)

A lens that focuses on many values in a data structure that should be identical. This is useful for invariants in data structures.

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.

union clj/s

(union & clauses)

A lens that combines multiple lenses depending on the values yanked or shoved from. Predicates on the values being yanked from or shoved to the lens must be given:

(union [d-1? v-1? lens-1] ...)

i.e. lens-1 is used when yanking, if d-1? is true for the data being yanked from, and lens-1 is used when shoving, if v-1? is true for the value being shoved though the lens. In each case the next triple are tried if the predicates do not hold. If none matches, an exception is thrown. You can provide an alternative fallback, by adding a clause that matches any value at the end.

union-tagged clj/s

(union-tagged & clauses)

A lens that associates different kinds of values with a tag on yanking, and optionally adds different lenses to that:

(union-tagged [d-1? tag-1 lens-1] [d-2? tag-2 lens-2] ... fallback-lens)

will yank a value where d-1? is true to a tuple [tag-1 v] where v is the result of yanking lens-1 to the data. The lens defaults to id. When shoving, that tag determines which lens to apply.

A optional fallback lens can be given as the last argument, which is used on the 'raw data' when either none of the predicates hold on yanking, or none if the tags match on shoving. If none is given, an exception is thrown in that case.

union-vector clj/s

(union-vector & clauses)

A lens that combines multiple lenses depending on the values yanked, into a vector corresponding in length to the number of clauses:

(union-vector [d-1? lens-1] [d-2? lens-2] ... fallback-lens)

i.e. lens-1 is used when yanking, if d-1? is true for the data being yanked from, and otherwise lens-2 if d-2? holds. Yanking then results in a vector with all items nil except one, which determines which lens to use when shoving. That also means none of the given lenses should yank to nil!

An optional fallback lens can be given as the last argument, which is applied to the 'raw data' directly. If none is given, and exception is thrown in that case.

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.