Elements

Access all elements of a collection that implements map. An alias for Elements() is available as ∗ (\ast). This optic can also be written as @o _[∗].

julia> using Accessors

julia> obj = (1,2,3);

julia> set(obj, Elements(), 0)
(0, 0, 0)

julia> modify(x -> 2x, obj, Elements())
(2, 4, 6)

If(modify_condition)

Restric access to locations for which modify_condition holds.

julia> using Accessors

julia> obj = (1,2,3,4,5,6);

julia> @set obj |> Elements() |> If(iseven) *= 10
(1, 20, 3, 40, 5, 60)

This function/type is experimental. It can be changed or deleted at any point without warning

IndexLens(indices::Tuple)
IndexLens(indices::Integer...)

Construct a lens for accessing an element of an object at indices via [].

Properties()

Access all properties of an object. An alias for Properties() is available as ∗ₚ (\ast\_p). This optic can also be written as @o _[∗ₚ].

julia> using Accessors

julia> obj = (a=1, b=2, c=3)
(a = 1, b = 2, c = 3)

julia> set(obj, Properties(), "hi")
(a = "hi", b = "hi", c = "hi")

julia> modify(x -> 2x, obj, Properties())
(a = 2, b = 4, c = 6)

Based on mapproperties.

PropertyLens{fieldname}()
PropertyLens(fieldname)

Construct a lens for accessing a property fieldname of an object.

The second constructor may not be type stable when fieldname is not a constant.

PropertyLensRuntime(propertyname)

Construct a lens for accessing a property propertyname of an object where the property name is stored as a runtime value rather than a type parameter. This is useful when the property name cannot be a type parameter (e.g., strings, arbitrary objects).

Automatically supports getting a value, but set requires explicit support for each object type.

Recursive(descent_condition, optic)

Apply optic recursively as long as descent_condition holds.

julia> using Accessors

julia> obj = (a=missing, b=1, c=(d=missing, e=(f=missing, g=2)))
(a = missing, b = 1, c = (d = missing, e = (f = missing, g = 2)))

julia> set(obj, Recursive(!ismissing, Properties()), 100)
(a = 100, b = 1, c = (d = 100, e = (f = 100, g = 2)))

julia> obj = (1,2,(3,(4,5),6))
(1, 2, (3, (4, 5), 6))

julia> modify(x -> 100x, obj, Recursive(x -> (x isa Tuple), Elements()))
(100, 200, (300, (400, 500), 600))

delete(obj, optic)

Delete a part according to optic of obj.

Note that optic(delete(obj, optic)) can still have a valid value: for example, when deleting an element from a Tuple or Vector.

julia> using Accessors

julia> obj = (a=1, b=2); lens=@optic _.a;

julia> obj_d = delete(obj, lens)
(b = 2,)

julia> lens(obj_d)
ERROR: type NamedTuple has no field a


julia> obj = (1, 2); lens=first;

julia> obj_d = delete(obj, lens)
(2,)

julia> lens(obj_d)
2

See also set, insert.

getall(obj, optic)

Extract all parts of obj that are selected by optic. Returns a flat Tuple of values, or an AbstractVector if the selected parts contain arrays.

The details of getall behavior are consireded experimental: in particular, the precise output container type might change in the future.

See also setall.

julia> using Accessors

julia> obj = (a=1, b=(2, 3));

julia> getall(obj, @optic _.a)
(1,)

julia> getall(obj, @optic _ |> Elements() |> last)
(1, 3)

insert(obj, optic, val)

Insert a part according to optic into obj with the value val.

For a callable optic, this law defines the insert operation: optic(insert(obj, optic, val)) == val (for an appropriate notion of equality).

julia> using Accessors

julia> obj = (a=1, b=2); lens=@optic _.c; val = 100;

julia> insert(obj, lens, val)
(a = 1, b = 2, c = 100)

See also set, delete.

modify(f, obj, optic)

Replace a part x of obj by f(x). The optic argument selects which part to replace.

julia> using Accessors

julia> obj = (a=1, b=2); optic=@optic _.a; f = x -> "hello $x";

julia> modify(f, obj, optic)
(a = "hello 1", b = 2)

See also set.

set(obj, optic, val)

Replace a part according to optic of obj by val.

For a callable optic, this law defines the set operation: optic(set(obj, optic, val)) == val (for an appropriate notion of equality).

julia> using Accessors

julia> obj = (a=1, b=2); lens=@optic _.a; val = 100;

julia> set(obj, lens, val)
(a = 100, b = 2)

julia> lens = Elements();

julia> set(obj, lens, val)
(a = 100, b = 100)

See also modify.

setall(obj, optic, values)

Replace a part of obj that is selected by optic with values. The values collection should have the same number of elements as selected by optic.

The details of setall behavior are consireded experimental: in particular, supported container types for the values argument might change in the future.

See also getall, set. The former is dual to setall:

julia> using Accessors

julia> obj = (a=1, b=(2, 3));

julia> optic = @optic _ |> Elements() |> last;

julia> getall(obj, optic)
(1, 3)

julia> setall(obj, optic, (4, 5))
(a = 4, b = (2, 5))

optic₁ ⨟ optic₂

Compose optics optic₁, optic₂, ..., opticₙ to access nested objects.

Example

julia> using Accessors

julia> obj = (a = (b = (c = 1,),),);

julia> la = @optic _.a
       lb = @optic _.b
       lc = @optic _.c
       lens = la ⨟ lb ⨟ lc
(@o _.c) ∘ ((@o _.a.b))

julia> lens(obj)
1

@accessor func

Given a simple getter function, define the corresponding set method automatically.

Example

julia> @accessor my_func(x) = x.a

julia> my_func((a=1, b=2))
1

julia> set((a=1, b=2), my_func, 100)
(a = 100, b = 2)

@delete obj_optic

Define an optic and call delete on it.

julia> using Accessors

julia> xs = (1,2,3);

julia> ys = @delete xs[2]
(1, 3)

Supports the same syntax as @optic. See also @set.

@insert assignment

Return a modified copy of deeply nested objects.

Example

julia> using Accessors

julia> t = (a=1, b=2);

julia> @insert t.c = 5
(a = 1, b = 2, c = 5)

julia> t
(a = 1, b = 2)

Supports the same syntax as @optic. See also @set.

@modify(f, obj_optic)

Define an optic and call modify on it.

julia> using Accessors

julia> xs = (1,2,3);

julia> ys = @modify(xs |> Elements() |> If(isodd)) do x
           x + 1
       end
(2, 2, 4)

Supports the same syntax as @optic. See also @set.

@optic expr
@o expr

Construct an optic from an expression containing property/index access, function calls, and more.

Inside the macro, _ is used as the placehold to refer to the target object.

The two forms, @optic and @o, are equivalent. We recommend using @o for brevity unless there is a potential for confusion.

Example

julia> using Accessors

julia> struct T;a;b;end

julia> t = T("A1", T(T("A3", "B3"), "B2"))
T("A1", T(T("A3", "B3"), "B2"))

julia> l = @optic _.b.a.b
(@o _.b.a.b)

julia> l(t)
"B3"

julia> set(t, l, 100)
T("A1", T(T("A3", 100), "B2"))

julia> t = ("one", "two")
("one", "two")

julia> set(t, (@o _[1]), "1")
("1", "two")

julia> l = @o _[∗].a
(@o _[∗].a)

julia> modify(x -> x + 1, ((a=1,), (a=2,)), l)
((a = 2,), (a = 3,))

See also @set.

@reset assignment

Shortcut for obj = @set obj....

Example

julia> using Accessors

julia> t = (a=1,)
(a = 1,)

julia> @reset t.a=2
(a = 2,)

julia> t
(a = 2,)

Supports the same syntax as @optic. See also @set.

@set assignment

Return a modified copy of deeply nested objects.

Example

julia> using Accessors

julia> struct T;a;b end

julia> t = T(1,2)
T(1, 2)

julia> @set t.a = 5
T(5, 2)

julia> t
T(1, 2)

julia> t = @set t.a = T(2,2)
T(T(2, 2), 2)

julia> @set t.a.b = 3
T(T(2, 3), 2)

Supports the same syntax as @optic. See also @reset.