@@ -78,6 +78,13 @@ import Data.Functor.Bind ( Bind, (>>-) )
7878import Data.These ( These )
7979
8080
81+-- | @TheseTable a b@ is a Rel8 table that contains either the table @a@, the
82+-- table @b@, or both tables @a@ and @b@. You can construct @TheseTable@s using
83+-- 'thisTable', 'thatTable' and 'thoseTable'. @TheseTable@s can be
84+-- eliminated/pattern matched using 'theseTable'.
85+--
86+-- @TheseTable@ is operationally the same as Haskell's 'These' type, but
87+-- adapted to work with Rel8.
8188type TheseTable :: Type -> Type -> Type
8289data TheseTable a b = TheseTable
8390 { here :: MaybeTable a
@@ -180,46 +187,57 @@ toThereTag :: Tag "isJust" a -> Tag "hasThere" a
180187toThereTag Tag {..} = Tag {..}
181188
182189
190+-- | Test if a 'TheseTable' was constructed with 'thisTable'.
183191isThisTable :: TheseTable a b -> Expr Bool
184192isThisTable a = hasHereTable a &&. not_ (hasThereTable a)
185193
186194
195+-- | Test if a 'TheseTable' was constructed with 'thatTable'.
187196isThatTable :: TheseTable a b -> Expr Bool
188197isThatTable a = not_ (hasHereTable a) &&. hasThereTable a
189198
190199
200+-- | Test if a 'TheseTable' was constructed with 'thoseTable'.
191201isThoseTable :: TheseTable a b -> Expr Bool
192202isThoseTable a = hasHereTable a &&. hasThereTable a
193203
194204
205+-- | Test if the @a@ table of @TheseTable a b@ is present.
195206hasHereTable :: TheseTable a b -> Expr Bool
196207hasHereTable TheseTable {here} = isJustTable here
197208
198209
210+-- | Test if the @b@ table of @TheseTable a b@ is present.
199211hasThereTable :: TheseTable a b -> Expr Bool
200212hasThereTable TheseTable {there} = isJustTable there
201213
202214
215+-- | Attempt to project out the @a@ table of a @TheseTable a b@.
203216justHereTable :: TheseTable a b -> MaybeTable a
204217justHereTable = here
205218
206219
220+-- | Attempt to project out the @b@ table of a @TheseTable a b@.
207221justThereTable :: TheseTable a b -> MaybeTable b
208222justThereTable = there
209223
210224
225+-- | Construct a @TheseTable@. Corresponds to 'This'.
211226thisTable :: Table Expr b => a -> TheseTable a b
212227thisTable a = TheseTable (justTable a) nothingTable
213228
214229
230+-- | Construct a @TheseTable@. Corresponds to 'That'.
215231thatTable :: Table Expr a => b -> TheseTable a b
216232thatTable b = TheseTable nothingTable (justTable b)
217233
218234
235+-- | Construct a @TheseTable@. Corresponds to 'These'.
219236thoseTable :: a -> b -> TheseTable a b
220237thoseTable a b = TheseTable (justTable a) (justTable b)
221238
222239
240+-- | Pattern match on a 'TheseTable'.
223241theseTable :: Table Expr c
224242 => (a -> c) -> (b -> c) -> (a -> b -> c) -> TheseTable a b -> c
225243theseTable f g h TheseTable {here, there} =