tfausak / quartz / Quartz

Optics


type alias Optic p l s t a b =
Type.Optic.Optic p l s t a b

This is the base optic type. All other optics are defined in terms of this type.

Don't be intimidated by all the type variables! Here's what they mean:


type alias SimpleOptic p l s a =
Type.Optic.SimpleOptic p l s a

This is an Optic where the input and output types are the same.


type alias Yes =
Type.Yes.Yes

Equivalent to (), the unit type. Used to signal that an Optic supports a certain feature.


type alias No =
Type.No.No

Equivalent to Never, the empty type. Like Yes, this is used to signal that an Optic does not support a certain feature.

re : Optic Yes Yes s t a b -> Optic p l b a t s

Use this function to flip an Optic around.

stringToList : SimpleIso String (List Char)
stringToList =
    iso String.toList String.fromList

listToString : SimpleIso (List Char) String
listToString =
    re stringToList

Isos


type alias Iso p l s t a b =
Type.Iso.Iso p l s t a b

This is an Optic that represents an isomorphism. Two types are isomorphic if you can convert between them without losing any information.


type alias SimpleIso p l s a =
Type.Iso.SimpleIso p l s a

This is an Iso where the input and output types are the same.

iso : (s -> a) -> (b -> t) -> Iso p l s t a b

Use this function to create a new Iso. You have to provide conversion functions for both directions.

type Name
    = Name String

nameIso : SimpleIso p l String Name
nameIso =
    iso Name <| \(Name s) -> s

Prisms


type alias Prism p s t a b =
Type.Prism.Prism p s t a b

This is an Optic that can be used to represent a constructor. Note that it cannot be used as a lens.


type alias SimplePrism p s a =
Type.Prism.SimplePrism p s a

This is a Prism where the input and output types are the same.

prism : (b -> t) -> (s -> Result t a) -> Prism p s t a b

Use this function to create a new Prism. You have to provide a way to call the constructor and a way to destructure a value.

type Number
    = Integral Int
    | Floating Float

iPrism : SimplePrism p Number Int
iPrism =
    prism Integral <|
        \n ->
            case n of
                Integral i ->
                    Ok u

                _ ->
                    Err n

Lenses


type alias Lens l s t a b =
Type.Lens.Lens l s t a b

This is an Optic that can be used to represent a field accessor. Note that it cannot be used as a prism.


type alias SimpleLens l s a =
Type.Lens.SimpleLens l s a

This is a Lens where the input and output types are the same.

lens : (s -> a) -> (s -> b -> t) -> Lens l s t a b

Use this function to create a new Lens. You have to provide a way to get the part out of the whole, and a way to construct the whole with a new part.

type alias Person =
    { name : String }

nameLens : SimpleLens l Person Name
nameLens =
    lens .name <| \person name -> { person | name = name }

Traversals


type alias Traversal s t a b =
Type.Traversal.Traversal s t a b

This is an Optic that may contain zero or many focused values. Note that it cannot be used as a prism nor a lens.


type alias SimpleTraversal s a =
Type.Traversal.SimpleTraversal s a

This is a Traversal where the input and output types are the same.

traversal : (s -> List a) -> ((a -> b) -> s -> t) -> Traversal s t a b

Use this function to create a new Traversal. You have to provide a way to convert the input into a List, as well as a way to map over values in the input.

data Pair a =
    Pair a a

pairTraversal : SimpleTraversal (Pair a) a
pairTraversal =
    traversal
        (\(Pair a1 a2) -> [ a1, a2 ])
        (\f (Pair a1 a2) -> Pair (f a1) (f a2))

Combinators

andThen : Optic p l u v a b -> Optic p l s t u v -> Optic p l s t a b

Composes two Optics. This is meant to be used in a pipeline. The first argument is the inner Optic and the second argument is the outer Optic.

preview (just |> andThen ok) <| Just <| Ok 1
-- Just 1

is : Optic p l s t a b -> s -> Basics.Bool

Returns True if the given Optic matches, False otherwise. Typically this is used as an alternative to preview.

is just <| Just 1
-- True

over : Optic p l s t a b -> (a -> b) -> s -> t

Maps the given function over the Optic. If the Optic doesn't match, nothing will happen. See set for a similar function that unconditionally sets the value rather than updating it.

over just negate <| Just 1
-- Just -1

preview : Optic p l s t a b -> s -> Maybe a

Returns Just if the Optic matches, Nothing otherwise. See toListOf for a similar function that can return multiple matches.

preview ok <| Ok 1
-- Just 1

review : Optic Yes l s t a b -> b -> t

Creates a new value using the given Optic.

review just 1
-- Just 1

set : Optic p l s t a b -> b -> s -> t

Sets the small value inside the big value using the provided Optic. See over for a similar function that allows modifying the value.

set first 3 ( 1, 2 )
-- ( 3, 2 )

toListOf : Optic p l s t a b -> s -> List a

Extracts all of the values that match the provided Optic. See preview for a similar function that only returns zero or one value.

toListOf array <| Array.fromList [ 1, 2 ]
-- [ 1, 2 ]

view : Optic p Yes s t a b -> s -> a

Extracts a value using the provided Optic. See preview for a similar function that works with more types of Optics.

view first ( 1, 2 )
-- 1

Arrays

elements : Iso p l (Array a) (Array b) (List a) (List b)

Converts between an Array and a List.

view elements <| Array.fromList [ 1, 2 ]
-- [ 1, 2 ]

array : Traversal (Array a) (Array b) a b

Focuses on each element of the Array.

over array negate <| Array.fromList [ 1, 2 ]
-- Array.fromList [ -1, -2 ]

idx : Basics.Int -> SimpleTraversal (Array a) a

Focuses on the element at the given index of the Array.

preview (idx 1) <| Array.fromList [ 1, 2 ]
-- Just 2

Dicts

pairs : Iso p l (Dict comparable1 a) (Dict comparable2 a) (List ( comparable1, a )) (List ( comparable2, a ))

Converts between a Dict and a List of pairs.

view pairs <| Dict.singleton "k" "v"
-- [ ( "k", "v" ) ]

key : comparable -> SimpleTraversal (Dict comparable a) a

Focuses on the given key in the Dict.

preview (key "k") (Dict.singleton "k" "v")
-- Just "v"

Lists

list : Traversal (List a) (List b) a b

Focuses on each element of the List.

over list negate [ 1, 2 ]
-- [ -1, -2 ]

nth : Basics.Int -> SimpleTraversal (List a) a

Focuses on the element at the given index of the List.

preview (nth 1) [ 1, 2 ]
-- Just 2

Maybes

nothing : SimplePrism p (Maybe a) ()

Focuses on the Nothing variant of a Maybe.

review nothing ()
-- Nothing

just : Prism p (Maybe a) (Maybe b) a b

Focuses on the Just variant of a Maybe.

review just "success"
-- Just "success"

Results

err : Prism p (Result a x) (Result b x) a b

Focuses on the Err variant of a Result.

review err "failure"
-- Err "failure"

ok : Prism p (Result x a) (Result x b) a b

Focuses on the Ok variant of a Result.

review ok "success"
-- Ok "success"

Tuples

swap : Iso p l ( a, b ) ( c, d ) ( b, a ) ( d, c )

Swaps the first and second elements of a tuple.

view swap ( 1, 2 )
-- ( 2, 1 )

first : Lens l ( a, x ) ( b, x ) a b

Focuses on the first element of a tuple.

view first ( 1, 2 )
-- 1

second : Lens l ( x, a ) ( x, b ) a b

Focuses on the second element of a tuple.

view second ( 1, 2 )
-- 2