Documentation

Using HListPP syntax for short hand, dredge `foo expands out to something like `path . `to . `foo, with the restriction that there is only one possible `path . `to which leads to the label foo.

For example, if we have the following definitions,

type BVal a = Record '[Tagged "x" a, Tagged "a" Char]
type R a = Record  [Tagged "a" Int, Tagged "b" (BVal a)]
type V a = Variant [Tagged "a" Int, Tagged "b" (BVal a)]
lx = Label :: Label "x"

Then we have:

dredge `x :: Lens (R a) (R b) a b
dredge lx :: Lens (R a) (R b) a b

dredge `x :: Traversal (V a) (V b) a b -- there were only variants along the path we'd get a Prism
dredge lx :: Traversal (V a) (V b) a b

result-type directed operations are supported

There are two ways to access a field with tag a in the R type defined above, but they result in fields with different types being looked up:

`a        :: Lens' (R a) Char
`b . `a   :: Lens' (R a) Int

so provided that the result type is disambiguated by the context, the following two types can happen

dredge `a :: Lens' (R a) Char
dredge `a :: Lens' (R a) Int

TIP & TIC

type indexed collections are allowed along those paths, but as explained in the Labelable instances, only simple optics (Lens' Prism' Traversal' ) are produced. dredgeTI' works better if the target is a TIP or TIC

dredge except a simple (s ~ t, a ~ b) optic is produced

dredgeND (named directed only) is the same as dredge, except the result type (a) is not used when the label would otherwise be ambiguous. dredgeND might give better type errors, but otherwise there should be no reason to pick it over dredge

dredgeND except a simple (s ~ t, a ~ b) optic is produced

The same as dredgeND', except intended for TIP/TICs because the assumption is made that l ~ v for the Tagged l v elements. In other words, ticPrism' and tipyLens' could usually be replaced by

dredgeTI' :: _ => Label a -> Lens'  (TIP s) a
dredgeTI' :: _ => Label a -> Prism' (TIC s) a

where we might have s ~ '[Tagged a a, Tagged b b]

HSingleton msg xs x is like '[x] ~ xs if that constraint can hold, otherwise it is Fail msg. See comments on Fail about how its kind varies with ghc version.

HGuardNonNull msg xs is like when (null xs) (fail msg)

ConsTrue b x xs r is like r = if b then x:xs else xs

FilterLastEq x xs ys ys' determines ys' such that it contains all of the ys !! i such that last (xs !! i) == x. In other words it is like

ys' = [ y |  (xsElt, y) <- zip xs ys, last xsElt == x ]

The same as FilterLastEq except id is used instead of last

like FilterVEq, except if there is

LabelPathEndingWith r l path

determines a unique path suitable for hLookupByLabelPath (calling Fail otherwise) through the nested records/variants in r ending with l

XXX

let x = 'x'; y = [pun| x |]; z = [pun| y |]
z & dredge (Label :: Label "x") %~ (succ :: Int -> Int)

Should reference this type error, but for whatever reason it doesn't

see hLookupByLabelPath

lookup along a path

>>> let v = mkVariant1 Label (mkVariant1 Label 'r') :: Variant '[Tagged "x" (Variant '[Tagged "y" Char])]
>>> let r = hBuild (hBuild 'r') :: Record '[Tagged "x" (Record '[Tagged "y" Char])]
>>> let p = Label :: Label [Label "x", Label "y"]
>>> let lx = Label :: Label "y"

>>> hLookupByLabelPath p v
Just 'r'

>>> hLookupByLabelPath p r
'r'

>>> hLookupByLabelDredge lx v
Just 'r'

>>> hLookupByLabelDredge lx r
'r'

hLens'Path labc == hLens' la . hLens' lb . hLens' lc
 where
      la :: Label "a"
      lb :: Label "b"
      lc :: Label "c"
      labc :: Label '["a", "b", "c"]

(FieldTree r ns, FieldTreeVal r vs)

defines ns and vs such that looking up path (ns !! i) in r gives the type (vs !! i). This is almost HasFieldPath False (ns !! i) (vs !! i), except there is no additional Maybe when a Variant is encountered along the path (and we don't have a type level !!)

list all paths through nested records or variants. An example instance would be

FieldTree r v

where

v ~ [[ Label "x",  Label Dat ], '[Label "y"], '[Label "x"] ]
r ~ Record [ Tagged "x" x, Tagged "y" String ]

x ~ Variant '[ Tagged Dat Char ]

MapCons x xs xxs is like xxs = map (x : ) xs