@@ -47,34 +47,6 @@ optional = mapOpaleye $ Opaleye.QueryArr . go
4747-- This operation can be used to "undo" the effect of 'optional', which
4848-- operationally is like turning a @LEFT JOIN@ back into a full @JOIN@. You
4949-- can think of this as analogous to 'Data.Maybe.catMaybes'.
50−--
51−-- To see this in action, first consider the following 'optional' query:
52−--
53−-- >>> :{
54−-- select c $ do
55−-- author <- each authorSchema
56−-- maybeRel8 <- optional $
57−-- each projectSchema
58−-- >>= filter (\p -> projectAuthorId p ==. authorId author)
59−-- >>= filter (\p -> projectName p ==. "rel8")
60−-- return (authorName author, projectName <$> maybeRel8)
61−-- :}
62−-- [("Ollie",Just "rel8"),("Bryan O'Sullivan",Nothing),("Emily Pillmore",Nothing)]
63−--
64−-- Here @optional@ is acting as a @LEFT JOIN@. We can turn this into a proper
65−-- join by using @catMaybeTable@ to filter out rows where the join failed:
66−--
67−-- >>> :{
68−-- select c $ do
69−-- author <- each authorSchema
70−-- maybeRel8 <- optional $
71−-- each projectSchema
72−-- >>= filter (\p -> projectAuthorId p ==. authorId author)
73−-- >>= filter (\p -> projectName p ==. "rel8")
74−-- rel8 <- catMaybeTable maybeRel8
75−-- return (authorName author, projectName rel8)
76−-- :}
77−-- [("Ollie","rel8")]
7850catMaybeTable :: MaybeTable a -> Query a
7951catMaybeTable ma@(MaybeTable _ a) = do
8052 where_ $ isJustTable ma
@@ -87,15 +59,6 @@ catMaybeTable ma@(MaybeTable _ a) = do
8759--
8860-- This is similar to 'traverseMaybeTable', followed by a @join@ on the
8961-- resulting @MaybeTable@s.
90−--
91−-- >>> select c $ bindMaybeTable (optional . values . pure . not_) =<< optional (values [lit True])
92−-- [Just False]
93−--
94−-- >>> select c $ bindMaybeTable (\_ -> return (noTable :: MaybeTable (Expr Bool))) =<< optional (values [lit True])
95−-- [Nothing]
96−--
97−-- >>> select c $ bindMaybeTable (optional . values . pure . not_) =<< return (noTable :: MaybeTable (Expr Bool))
98−-- [Nothing]
9962bindMaybeTable :: Monad m
10063 => (a -> m (MaybeTable b)) -> MaybeTable a -> m (MaybeTable b)
10164bindMaybeTable query (MaybeTable input a) = do
@@ -107,30 +70,10 @@ bindMaybeTable query (MaybeTable input a) = do
10770-- to step through multiple @LEFT JOINs@.
10871--
10972-- Note that @traverseMaybeTable@ takes a @a -> Query b@ function, which means
110−-- you also have the ability to "expand" one row into multiple rows.
111−--
112−-- >>> :{
113−-- duplicate :: Expr Bool -> Query (Expr Bool)
114−-- duplicate x = unionAll (return x) (return x)
115−-- :}
116−--
117−-- >>> select c $ traverseMaybeTable duplicate =<< optional (values [lit True])
118−-- [Just True,Just True]
119−--
120−-- Note that if the @a -> Query b@ function returns no rows, then the resulting
121−-- query will also have no rows:
122−--
123−-- >>> select c $ traverseMaybeTable (limit 0 . pure) =<< optional (values [lit True])
124−-- []
125−--
126−-- However, regardless of the given @a -> Query b@ function, if the input is
127−-- @noTable@, you will always get exactly one @noTable@ back:
128−--
129−-- >>> select c $ traverseMaybeTable duplicate (noTable :: MaybeTable (Expr Bool))
130−-- [Nothing]
131−--
132−-- >>> select c $ traverseMaybeTable (limit 0 . pure) (noTable :: MaybeTable (Expr Bool))
133−-- [Nothing]
73+-- you also have the ability to "expand" one row into multiple rows. If the
74+-- @a -> Query b@ function returns no rows, then the resulting query will also
75+-- have no rows. However, regardless of the given @a -> Query b@ function, if
76+-- the input is @noTable@, you will always get exactly one @noTable@ back.
13477traverseMaybeTable :: (a -> Query b) -> MaybeTable a -> Query (MaybeTable b)
13578traverseMaybeTable query ma@(MaybeTable input _) = do
13679 MaybeTable output b <- optional (query =<< catMaybeTable ma)