package accessor_base

Accessors are commonly not indexed and don't need to support polymorphic updates. In such cases, it may be easier to read and write types in terms of t instead of General.t. Here is an example where the improvement by using t is significant:

val date_ofday
  :  Time.Zone.t
  -> ( 'i -> Date.t * Time.Ofday.t -> Date.t * Time.Ofday.t
     , 'i -> Time.t -> Time.t
     , [< isomorphism] )
       Accessor.General.t

It is more cleanly written like this:

val date_ofday
  :  Time.Zone.t
  -> (_, Date.t * Time.Ofday.t, Time.t, [< isomorphism]) Accessor.t

To use Accessor in your own code, it is recommended to add the following to your import.ml:

a @> b is the composition of the two accessors a and b. From left to right, a chain of composed accessors goes from outermost to innermost values. The resulting accessor kind is determined by the least powerful argument. Here are a few examples:

• An isomorphism composed with a field is a field.
• A field composed with a variant is an optional.
• A getter composed with a variant is an optional_getter.

It's normally more intuitive to think of the operations you need than to think of exactly which kind of accessor you are creating. For example, if you are trying to extract a value from a data structure using a field, you would probably use get. However, if you compose the field with an optional, get no longer makes sense; you must use something like get_option, instead.

The non-operator name is Accessor.compose.

x.@(t) extracts a single value from x as identified by t. The non-operator name is Accessor.get.

x.@?(t) extracts at most one value from x as identified by t. The non-operator name is Accessor.get_option.

x.@*(t) extracts any number of values from x as identified by t. The non-operator name is Accessor.to_list.

x.@(t) <- y replaces any number of values in x with y, as identified by t. The non-operator name is Accessor.set.

id can be used as any kind of accessor. It is also the only way to summon an equality.

compose is the same as ( @> ). See the documentation of ( @> ) for more information.

dummy is an accessor of a value that is never present. get_option dummy will always return None, and map dummy is always a no-op.

An Index.t is a heterogeneous stack of values intended to serve as "breadcrumbs" that show how you got to some value currently being accessed inside a composite data structure. For example, if on the way in you traversed a Map.t, one component of the index might be the key of the data being accessed.

The Subtyping module contains all the types used for accessor subtyping. You shouldn't have to use it, but it's here for the documentation.

get t at reads a value from at.

geti t at reads a value and its index from at.

get_option t at reads a value from at, if present.

get_optioni t at reads a value and its index from at, if present.

match_ t at is like get_option, but in the failure case it may be able to give you the input data structure with a different type.

An indexed version of match_.

Extract all the values targetted by an accessor in some composite data structure into a list.

An indexed version of to_list.

Extract all the values targetted by an accessor in some composite data structure into an array.

An indexed version of to_array.

Fold across all the values targetted by an accessor with an accumulator.

Indexed version of fold.

Iterate over all the values targetted by an accessor, applying the function argument to each one.

An indexed version of iter.

length t at returns the number of targets in at.

is_empty t at is true iff there are no targets in at.

sum (module Summable) t at ~f returns the sum of f a for all targets a in at.

sumi is the indexed version of sum.

count t at ~f returns the number of targets in at for which f evaluates to true.

counti is the indexed version of count.

exists t at ~f returns true iff there is a target in at for which f returns true. This is a short-circuiting operation.

existsi is the indexed version of exists.

for_all t at ~f returns true iff f returns true for all targets in at. This is a short-circuiting operation.

for_alli is the indexed version of for_all.

find_map returns the first evaluation of f that returns Some.

find_mapi is the indexed version of find_map.

find t at ~f returns the first target in at for which the evaluation of f returns true.

findi is the indexed version of find.

min_elt t at ~compare uses compare to compare each target in at and returns the first target with the smallest value.

min_elt_option t at ~compare uses compare to compare each target in at and returns the first target with the smallest value, if any.

max_elt t at ~compare uses compare to compare each target in at and returns the first target with the largest value.

max_elt_option t at ~compare uses compare to compare each target in at and returns the first target with the largest value, if any.

hd t at returns the first targetted element of at.

An indexed version of hd.

hd_option t at returns the first targetted element of at, if any.

An indexed version of hd_option.

map_reduce t at ~empty ~combine ~f applies f to each targetted value in at and combines the results using combine. The result is empty if there were no values. empty and combine are expected to satisfy the following properties:

• combine empty a = a
• combine a empty = a
• combine (combine a b) c = combine a (combine b c)

An indexed version of map_reduce.

reduce t at ~empty ~combine combines all accessed values in at using combine. The result is empty if there were no values accessed. empty and combine are expected to satisfy the following properties:

• combine empty a = a
• combine a empty = a
• combine (combine a b) c = combine a (combine b c)

map_reduce_nonempty t at ~combine ~f applies f to each targetted value in at and combines the results using combine. combine is expected to satisfy the property: combine (combine a b) c = combine a (combine b c).

An indexed version of map_reduce_nonempty.

reduce_nonempty t at ~combine combines all accessed values in at using combine. combine is expected to satisfy the property: combine (combine a b) c = combine a (combine b c).

map t at ~f applies f to each targetted value inside at, replacing it with the result.

mapi is the indexed version of map.

folding_map is a version of map that threads an accumulator through calls to f.

folding_mapi is the indexed version of folding_map.

fold_map is a combination of fold and map that threads an accumulator through calls to f.

fold_mapi is the indexed version of fold_map.

set t at ~to_ replaces targetted values inside at with to_.

The monad signatures differ from the applicative ones in that some of the functions have an optional how argument. They always default to `Sequential, which is the behavior that interleaves side effects with monadic effects. If you override this argument to `Parallel then all the side effects are performed up front, and then the results are combined.

Of_functor, Of_functor2, and Of_functor3 generate map-like functions that work under some "functor", which is like a monad or applicative, except that it only supports map.

Of_applicative and Of_applicative2 can be used to generate map-like functions that can use applicative effects. See also Of_monad, which gives more control over the relationship between side effects and monadic effects.

See Of_applicative.

See Of_applicative.

Of_monad is similar to Of_applicative. There are two differences.

See Of_monad.

See Of_monad.

Like Of_applicative, but without return.

Like Of_applicative2, but without return.

Like Of_monad, but without return.

Like Of_monad2, but without return.

transform t a ~f applies f everywhere it can inside of a once. It operates from the bottom up in one pass. t is used to find the children at each level, where the children are expected to have the same type as their parent.

rewrite t a ~f applies the rewrite rule f everywhere it can inside of a until it cannot be applied anywhere else. It operates from the bottom up, retrying subtrees each time a rule is applied successfully. t is used to find the children at each level, where the children are expected to have the same type as their parent.

An Identical.t is similar to a Type_equal.t, but it relates two pairs of types with each other instead of merely two types. It is a more natural way of using an equality accessor than Type_equal.t would be, since you only need to match on one constructor.

An equality is more powerful even than an isomorphism. It can be used to prove that the types are equal using the identical function.

construct goes the opposite way to most access patterns. It allows you to construct a composite data structure without reading from one.

An equality can transform any mapping. There is no need for you to provide any functionality of your own.

field ~get ~set creates a field accessor. A field accesses exactly one value within a composite data structure. For the field to be well behaved, get and set should satisfy the following properties:

• get (set at a) = a
• set at (get at) = at
• set (set at a) b = set at b

field' is the same as field, just with a slightly different interface. field is usually more convenient to use, but field' can be useful to allow get and set to share the computation of finding the location to modify.

A Field.t is sufficient to define a field accessor, but the resulting accessor might not be as polymorphic as it could have been if defined by hand or using @@deriving accessor.

fieldi is the indexed version of field.

fieldi' is the indexed version of field'.

A Field.t is sufficient to define an indexed field accessor, where the index is the name of the field as a string. The resulting accessor might not be as polymorphic as it could have been if defined by hand or using @@deriving accessor.

variant ~match_ ~construct creates a variant accessor. A variant accesses at most one value within a composite data structure, and if it does access a value then that value is representative of the entire data structure. A well behaved variant should satisfy the following properties:

• match_ (construct a) = First a
• if match_ at = First a then construct a = at
• if match_ at = Second bt then at = bt

varianti is the indexed version of variant.

optional ~match_ ~set creates an optional accessor. An optional accesses at most one value within a composite data structure. A well behaved optional should satisfy the following properties:

• match_ (set at a) = Either.First.map (match_ at) ~f:(const a)
• if match_ at = First a then set at a = at
• if match_ at = Second bt then at = bt and set at b = at
• set (set at a) b = set at b

optional' is the same as optional, just with a slightly different interface. optional is usually more convenient to use, but optional' can be useful to allow match_ and set to share the computation of finding the location to modify.

optionali is the indexed version of optional.

optionali' is the indexed version of optional'.

filter_index predicate accesses the entire value if its index satisfies predicate, otherwise it accesses nothing. Compose it with a many accessor to access a subset of values.

filter_map_index f is like filter_index, but it can also modify the indices.

isomorphism ~get ~construct creates an isomorphism accessor. An isomorphism accesses exactly one value which exactly represents the entire data structure. A well behaved isomorphism should satisfy the following properties:

• get (construct b) = b
• construct (get at) = at

isomorphismi is the indexed version of isomorphism.

map_index f applies f to the the indices that pass through it in a chain of composed accessors.

add_to_index adds the value to index without making any changes to the value. It's useful for marking the current value before doing further transformations. It's equivalent to isomorphismi ~get:(fun x -> x, x) ~construct:Fn.id.

mapper map creates a mapper accessor. A mapper can modify values inside a composite data structure, but cannot read anything out. A well behaved mapper should satisfy the following properties:

• map at ~f:Fn.id = at
• map at ~f:(Fn.compose f g) = map (map at ~f:g) ~f

mapperi is the indexed version of mapper.

many traverse creates a many accessor. A many accesses any number of values within a composite data structure.

To define a many accessor, you must use Accessor.Many.t, which is an applicative. You should traverse the data structure as necessary, and each time you reach a value that should be accessed, apply Accessor.Many.access to it.

Here is an example of using many to define an accessor that reaches all the elements of a list:

Accessor.many (fun at -> Accessor.Many.all (List.map at ~f:Accessor.Many.access))

A well behaved many should satisfy the same properties as a well behaved mapper, but generalized for an applicative setting. The properties themselves are uselessly complicated when written out, but here they are anyway. A and B are assumed to have the of_many function generated by Many.Of_applicative, and Compose is assumed to be some functor behaving like Applicative.Compose that also uses Many.Of_applicative to generate an of_many function.

• A.of_many (traverse at) ~access:A.return = A.return at

• Compose(A)(B).of_many (traverse at) ~access:(fun a -> A.map (g a) ~f)
  = A.map (A.of_many (traverse at) ~access:g) ~f:(fun at ->
    B.of_many (traverse at) ~access:f)

manyi is the indexed version of many.

nonempty traverse creates a nonempty accessor. A nonempty accesses a nonzero number of values within a composite data structure.

To define a nonempty accessor, you must use Accessor.Nonempty.t, which is an applicative lacking return. You should traverse the data structure as necessary, and each time you reach a value that should be accessed, apply Accessor.Nonempty.access to it.

Here is an example of using nonempty to define an accessor that reaches both components of a tuple:

Accessor.nonempty (fun (a, b) ->
  let open Accessor.Nonempty.Let_syntax in
  let%map_open a = access a
  and b = access b in
  a, b)

A well behaved nonempty should satisfy the second property of a well behaved mapper, but generalized for an applicative setting. The property itself is uselessly complicated when written out, but here it is anyway. A and B are assumed to have the of_nonempty function generated by Nonempty.Of_applicative_without_return, and Compose is assumed to be some functor behaving like Applicative_without_return.Compose that also uses Nonempty.Of_applicative_without_return to generate an of_nonempty function.

Compose(A)(B).of_nonempty (traverse at) ~access:(fun a -> A.map (g a) ~f)
= A.map (A.of_nonempty (traverse at) ~access:g) ~f:(fun at ->
  B.of_nonempty (traverse at) ~access:f)

nonemptyi is the indexed version of nonempty.

getter get creates a getter accessor. A getter reads exactly one value from a composite data structure. There are no properties necessary for a getter to be well behaved.

getteri is the indexed version of getter.

optional_getter get creates an optional getter accessor. An optional getter reads at most one value from a composite data structure. There are no properties necessary for an optional getter to be well behaved.

optional_getteri is the indexed version of optional_getter.

many_getter map_reduce creates a many_getter accessor. A many getter reads any number of values from a composite data structure. There are no properties necessary for a many getter to be well behaved.

To define a many_getter, you must use the Many_getter interface. Like Many, it has an access function to designate which values to access. Unlike Many, instead of an applicative interface, it has empty and append (or ( @ )) functions.

Here is an example of defining a getter that reads all the elements of a list:

Accessor.many_getter (fun at ->
  Accessor.Many_getter.of_list (List.map at ~f:Accessor.Many_getter.access))

many_getteri is the indexed version of many_getter.

nonempty_getter map_reduce creates a nonempty getter accessor. A nonempty getter reads at least one value from a composite data structure. There are no properties necessary for a nonempty getter to be well behaved.

To define a nonempty_getter, you must use the Nonempty_getter interface. Like Nonempty, it has an access function to designate which values to access. Unlike Nonempty, instead of an applicative style interface, it has an append (or ( @ )) function.

Here is an example of defining a getter that reads both of the components of a tuple:

Accessor.nonempty_getter (fun (a, b) ->
  Accessor.Nonempty_getter.(access a @ access b))

nonempty_getteri is the indexed version of nonempty_getter.

constructor construct creates a constructor accessor. A constructor creates a composite data structure from an argument. There are no properties necessary for a constructor to be well behaved.

A Variant.t is not sufficient to define a variant accessor, but is at least sufficient to define a constructor accessor.

Turn an isomorphism around. invert (isomorphism ~get:f ~construct:g) is isomorphism ~get:g ~construct:f.

Turn a getter into a constructor. getter_to_constructor (getter f) is constructor f.

Turn a constructor into a getter. constructor_to_getter (constructor f) is getter f.

Given a many accessor, generate a field accessor that accesses all the elements that would be accessed by the many accessor in the form of a list. When replacing, if the list is too short then later elements in the data structure are left alone, and if the list is too long then extraneous elements are not used.

The resulting accessor is only well-behaved if you preserve the length of the list across getting and setting.

Combine two field accessors into one that accesses both inner values at once. The resulting accessor is only well-behaved if the two input accessors access disjoint parts of the outer structure.

Combine two many accessors into one that accesses each inner value accessed by each accessor. The resulting accessor is only well-behaved if the two input accessors access disjoint parts of the outer structure.