3a54a58 · rel8 · git.iko.soy

git.iko.soy/rel8

More docs

commit3a54a58658fd68950555f08c9659fbcf85948a49 authorOliver Charles <ollie@ocharles.org.uk> dateFri 2 Apr 2021, 21:43 (6 years ago) parent6e001f8

18 files changed+44−46

compare with master

unifiedsplit

src/Rel8/Aggregate.hs+1−1 src/Rel8/Expr/Bool.hs+2−2 src/Rel8/Expr/Null.hs+2−2 src/Rel8/Expr/Serialize.hs+2−2 src/Rel8/Order.hs+3−2 src/Rel8/Query/Maybe.hs+2−1 src/Rel8/Query/Values.hs+1−1 src/Rel8/Table.hs+5−3 src/Rel8/Table/Alternative.hs+2−2 src/Rel8/Table/Insert.hs+5−5 src/Rel8/Table/List.hs+1−1 src/Rel8/Table/Maybe.hs+4−4 src/Rel8/Table/NonEmpty.hs+1−1 src/Rel8/Tabulate.hs+7−13 src/Rel8/Type/Information.hs+1−1 src/Rel8/Type/JSONBEncoded.hs+1−1 src/Rel8/Type/Monoid.hs+2−2 src/Rel8/Type/Semigroup.hs+2−2

src/Rel8/Aggregate.hs+1−1

@@ -48,7 +48,7 @@ import Data.Functor.Apply ( Apply, WrappedApplicative(..) )

4848

4949

5050-- | An @Aggregate a@ describes how to aggregate @Table@s of type @a@. You can

51−-- unpack an @Aggregate@ back to @a@ by running it with 'aggregate'. As

51+-- unpack an @Aggregate@ back to @a@ by running it with 'Rel8.aggregate'. As

5252-- @Aggregate@ is almost an 'Applicative' functor - but there is no 'pure'

5353-- operation. This means 'Aggregate' is an instance of 'Apply', and you can

5454-- combine @Aggregate@s using the @<.>@ combinator.

src/Rel8/Expr/Bool.hs+2−2

@@ -79,8 +79,8 @@ caseExpr branches (Expr fallback) =

7979

8080

8181-- | Convert a @Expr (Maybe Bool)@ to a @Expr Bool@ by treating @Nothing@ as

82−-- @False@. This can be useful when combined with 'where_', which expects a

83−-- @Bool@, and produces expressions that optimize better than general case

82+-- @False@. This can be useful when combined with 'Rel8.where_', which expects

83+-- a @Bool@, and produces expressions that optimize better than general case

8484-- analysis.

8585coalesce :: Expr (Maybe Bool) -> Expr Bool

8686coalesce (Expr a) = Expr a &&. Expr (Opaleye.FunExpr "COALESCE" [a, untrue])

src/Rel8/Expr/Null.hs+2−2

@@ -48,12 +48,12 @@ nullableOf :: DBType a => Maybe (Expr a) -> Expr (Maybe a)

4848nullableOf = maybe null nullify

4949

5050

51−-- | Like 'isNothing', but for @null@.

51+-- | Like 'Data.Maybe.isNothing', but for @null@.

5252isNull :: Expr (Maybe a) -> Expr Bool

5353isNull = mapPrimExpr (Opaleye.UnExpr Opaleye.OpIsNull)

5454

5555

56−-- | Like 'isJust', but for @null@.

56+-- | Like 'Data.Maybe.isJust', but for @null@.

5757isNonNull :: Expr (Maybe a) -> Expr Bool

5858isNonNull = mapPrimExpr (Opaleye.UnExpr Opaleye.OpIsNotNull)

5959

src/Rel8/Expr/Serialize.hs+2−2

@@ -32,8 +32,8 @@ import Rel8.Type.Information ( TypeInformation(..) )

3232

3333-- | Produce an expression from a literal.

3434--

35−-- Note that you can usually use 'lit', but @litExpr@ can solve problems of

36−-- inference in polymorphic code.

35+-- Note that you can usually use 'Rel8.lit', but @litExpr@ can solve problems

36+-- of inference in polymorphic code.

3737litExpr :: Sql DBType a => a -> Expr a

3838litExpr = slitExpr nullabilization typeInformation

3939

src/Rel8/Order.hs+3−2

@@ -19,8 +19,9 @@ import Data.Functor.Contravariant.Divisible ( Decidable, Divisible )

1919import qualified Opaleye.Internal.Order as Opaleye

2020

2121

22−-- | An ordering expression for @a@. Primitive orderings are defined with 'asc'

23−-- and 'desc', and you can combine @Order@ via its various instances.

22+-- | An ordering expression for @a@. Primitive orderings are defined with

23+-- 'Rel8.asc' and 'Rel8.desc', and you can combine @Order@ via its various

24+-- instances.

2425--

2526-- A common pattern is to use '<>' to combine multiple orderings in sequence,

2627-- and '>$<' (from 'Contravariant') to select individual columns.

src/Rel8/Query/Maybe.hs+2−1

@@ -60,7 +60,8 @@ catMaybeTable ma@(MaybeTable _ a) = do

6060

6161-- | @bindMaybeTable f x@ is similar to the monadic bind (@>>=@) operation. It

6262-- allows you to "extend" an optional query with another query. If either the

63−-- input or output are 'noTable', then the result is 'noTable'.

63+-- input or output are 'Rel8.nothingTable', then the result is

64+-- 'Rel8.nothingTable'.

6465--

6566-- This is similar to 'traverseMaybeTable', followed by a @join@ on the

6667-- resulting @MaybeTable@s.

src/Rel8/Query/Values.hs+1−1

@@ -21,7 +21,7 @@ import Rel8.Table.Opaleye ( valuesspec )

2121

2222

2323-- | Construct a query that returns the given input list of rows. This is like

24−-- folding a list of 'return' statements under 'union', but uses the SQL

24+-- folding a list of 'return' statements under 'Rel8.union', but uses the SQL

2525-- @VALUES@ expression for efficiency.

2626values :: (Table Expr a, Foldable f) => f a -> Query a

2727values = fromOpaleye . Opaleye.valuesExplicit valuesspec . toList

src/Rel8/Table.hs+5−3

@@ -42,11 +42,13 @@ import Rel8.Type ( DBType )

4242-- types that have a finite number of columns. Each of these columns contains

4343-- data under a shared context, and contexts describe how to interpret the

4444-- metadata about a column to a particular Haskell type. In Rel8, we have

45−-- contexts for expressions (the 'Expr' context), aggregations (the 'Aggregate'

46−-- context), insert values (the 'Insert' contex), among others.

45+-- contexts for expressions (the 'Rel8.Expr' context), aggregations (the

46+-- 'Rel8.Aggregate' context), insert values (the 'Rel8.Insert' contex), among

47+-- others.

4748--

4849-- In typical usage of Rel8 you don't need to derive instances of 'Table'

49−-- yourself, as anything that's an instance of 'Rel8able' is always a 'Table'.

50+-- yourself, as anything that's an instance of 'Rel8.Rel8able' is always a

51+-- 'Table'.

5052type Table :: K.Context -> Type -> Constraint

5153class (HTable (Columns a), context ~ Context a) => Table context a | a -> context where

5254 -- | The 'HTable' functor that describes the schema of this table.

src/Rel8/Table/Alternative.hs+2−2

@@ -20,8 +20,8 @@ import Rel8.Table ( Table )

2020-- | Like 'Alt' in Haskell. This class is purely a Rel8 concept, and allows you

2121-- to take a choice between two tables. See also 'AlternativeTable'.

2222--

23−-- For example, using '<|>:' on 'MaybeTable' allows you to combine two tables

24−-- and to return the first one that is a "just" MaybeTable.

23+-- For example, using '<|>:' on 'Rel8.MaybeTable' allows you to combine two

24+-- tables and to return the first one that is a "just" MaybeTable.

2525type AltTable :: (Type -> Type) -> Constraint

2626class AltTable f where

2727 -- | An associative binary operation on 'Table's.

src/Rel8/Table/Insert.hs+5−5

@@ -22,9 +22,9 @@ import Rel8.Table ( fromColumns, toColumns )

2222

2323

2424-- | @toInsert@ converts a 'Table' of 'Expr's into a 'Table' that can be used

25−-- with 'insert'. This will override any columns that have default values to

26−-- use exactly what is given. If you want to use default values, you can either

27−-- override the result of @toInsert@, or use 'toInsertDefaults'.

25+-- with 'Rel8.insert'. This will override any columns that have default values

26+-- to use exactly what is given. If you want to use default values, you can

27+-- either override the result of @toInsert@, or use 'toInsertDefaults'.

2828toInsert :: Inserts exprs inserts => exprs -> inserts

2929toInsert (toColumns -> exprs) = fromColumns $ htabulate $ \field ->

3030 case hfield hspecs field of

@@ -35,8 +35,8 @@ toInsert (toColumns -> exprs) = fromColumns $ htabulate $ \field ->

3535

3636

3737-- | @toInsertDefaults@ converts a 'Table' of 'Expr's into a 'Table' that can

38−-- be used with 'insert'. Any columns that have a default value will override

39−-- whatever is in the input expression.

38+-- be used with 'Rel8.insert'. Any columns that have a default value will

39+-- override whatever is in the input expression.

4040--

4141-- One example where this is useful is for any table that has a special @id@

4242-- column, which has a default value to draw a new value from a sequence. If we

src/Rel8/Table/List.hs+1−1

@@ -39,7 +39,7 @@ import Rel8.Table.Recontextualize ( Recontextualize )

3939

4040

4141-- | A @ListTable@ value contains zero or more instances of @a@. You construct

42−-- @ListTable@s with 'many' or 'listAgg'.

42+-- @ListTable@s with 'Rel8.many' or 'Rel8.listAgg'.

4343type ListTable :: Type -> Type

4444newtype ListTable a = ListTable (HListTable (Columns a) (Col (Context a)))

4545

src/Rel8/Table/Maybe.hs+4−4

@@ -91,7 +91,7 @@ instance Apply MaybeTable where

9191

9292

9393-- | Has the same behavior as the @Applicative@ instance for @Maybe@. See also:

94−-- 'traverseMaybeTable'.

94+-- 'Rel8.traverseMaybeTable'.

9595instance Applicative MaybeTable where

9696 (<*>) = (<.>)

9797 pure = justTable

@@ -103,7 +103,7 @@ instance Bind MaybeTable where

103103

104104

105105-- | Has the same behavior as the @Monad@ instance for @Maybe@. See also:

106−-- 'bindMaybeTable'.

106+-- 'Rel8.bindMaybeTable'.

107107instance Monad MaybeTable where

108108 (>>=) = (>>-)

109109

@@ -182,12 +182,12 @@ instance OrdTable a => OrdTable (MaybeTable a) where

182182 ordTable = toColumns1 (hlabel hlabeler) (justTable (ordTable @a))

183183

184184

185−-- | Check if a @MaybeTable@ is absent of any row.. Like 'isNothing'.

185+-- | Check if a @MaybeTable@ is absent of any row. Like 'Data.Maybe.isNothing'.

186186isNothingTable :: MaybeTable a -> Expr Bool

187187isNothingTable (MaybeTable tag _) = isNull (expr tag)

188188

189189

190−-- | Check if a @MaybeTable@ contains a row. Like 'isJust'.

190+-- | Check if a @MaybeTable@ contains a row. Like 'Data.Maybe.isJust'.

191191isJustTable :: MaybeTable a -> Expr Bool

192192isJustTable (MaybeTable tag _) = isNonNull (expr tag)

193193

src/Rel8/Table/NonEmpty.hs+1−1

@@ -38,7 +38,7 @@ import Rel8.Table.Recontextualize ( Recontextualize )

3838

3939

4040-- | A @NonEmptyTable@ value contains one or more instances of @a@. You

41−-- construct @NonEmptyTable@s with 'some' or 'nonEmptyAgg'.

41+-- construct @NonEmptyTable@s with 'Rel8.some' or 'nonEmptyAgg'.

4242type NonEmptyTable :: Type -> Type

4343newtype NonEmptyTable a =

4444 NonEmptyTable (HNonEmptyTable (Columns a) (Col (Context a)))

src/Rel8/Tabulate.hs+7−13

@@ -177,13 +177,7 @@ ifilter f tabulation = snd <$> do

177177 filter (uncurry f) `postbind` indexed tabulation

178178

179179

180−-- | Map a 'Query' over the input side of a 'Tabulation'. In particular, you

181−-- can turn a @'Tabulation' k a@ into a @'Tabulation' k a@ (for use with

182−-- 'leftAlign' and friends) by 'prebind'ing with 'queryTable', like this:

183−--

184−-- @

185−-- tabulation `'prebind'` 'queryTable'

186−-- @

180+-- | Map a 'Query' over the input side of a 'Tabulation'.

187181prebind :: (a -> Tabulation k b) -> Query a -> Tabulation k b

188182prebind f as = Tabulation $ \k -> do

189183 a <- as

@@ -242,7 +236,7 @@ alignWith f kas kbs = do

242236-- | If 'zip' makes an @INNER JOIN@, then 'leftAlign' makes a @LEFT JOIN@.

243237-- This means it will return at least one row for every row in the left

244238-- 'Tabulation', even if there is no corresponding row in the right (hence the

245−-- 'MaybeTable').

239+-- 'Rel8.MaybeTable').

246240--

247241-- Analagous to

248242-- [@rpadZip@](https://hackage.haskell.org/package/semialign/docs/Data-Semialign.html#v:rpadZip).

@@ -268,9 +262,9 @@ leftAlignWith f left right = liftA2 f left (optionalTabulation right)

268262--

269263-- You can think of it as @'Data.Map.Strict.intersectionWith'

270264-- ('Control.Applicative.liftA2' (,))@. That is, @intersect@ the two

271−-- `Tabulation`s by 'match'ing their keys together, and combine their values

272−-- (remembering that 'Tabulation' is a 'MultiMap' so that the values are keys)

273−-- by getting their cartesian product.

265+-- `Tabulation`s by matching their keys together (with 'Rel8.==:'), and combine

266+-- their values (remembering that 'Tabulation' is a 'MultiMap' so that the

267+-- values are keys) by getting their cartesian product.

274268--

275269-- You can think of it as performing a cross product of the underlying 'Query's

276270-- of the given 'Tabulation's and filtering the results for 'match'ing keys.

@@ -305,7 +299,7 @@ zipWith = liftA2

305299-- each entry would contain the /product/ of the number of rows of their

306300-- respective entries in @x@ and @y@.

307301--

308−-- See 'with'.

302+-- See 'Rel8.with'.

309303similarity :: EqTable k => Tabulation k a -> Tabulation k b -> Tabulation k a

310304similarity kas kbs = do

311305 as <- toQuery kas

@@ -317,7 +311,7 @@ similarity kas kbs = do

317311-- exist in the right 'Tabulation'. This corresponds to an antijoin in

318312-- relational algebra.

319313--

320−-- See 'without'.

314+-- See 'Rel8.without'.

321315difference :: EqTable k => Tabulation k a -> Tabulation k b -> Tabulation k a

322316difference kas kbs = do

323317 as <- toQuery kas

src/Rel8/Type/Information.hs+1−1

@@ -40,7 +40,7 @@ data TypeInformation a = TypeInformation

4040

4141-- | Simultaneously map over how a type is both encoded and decoded, while

4242-- retaining the name of the type. This operation is useful if you want to

43−-- essentially @newtype@ another 'DBType'.

43+-- essentially @newtype@ another 'Rel8.DBType'.

4444--

4545-- The mapping is required to be total. If you have a partial mapping, see

4646-- 'parseTypeInformation'.

src/Rel8/Type/JSONBEncoded.hs+1−1

@@ -19,7 +19,7 @@ import Rel8.Type.Information ( TypeInformation(..) )

1919import Data.Text ( pack )

2020

2121

22−-- | Like 'JSONEncoded', but works for @jsonb@ columns.

22+-- | Like 'Rel8.JSONEncoded', but works for @jsonb@ columns.

2323newtype JSONBEncoded a = JSONBEncoded { fromJSONBEncoded :: a }

2424

2525

src/Rel8/Type/Monoid.hs+2−2

@@ -42,8 +42,8 @@ import qualified Data.Text.Lazy as Lazy ( Text )

4242import Data.Time.LocalTime ( CalendarDiffTime( CalendarDiffTime ) )

4343

4444

45−-- | The class of 'DBType's that form a semigroup. This class is purely a Rel8

46−-- concept, and exists to mirror the 'Monoid' class.

45+-- | The class of 'Rel8.DBType's that form a semigroup. This class is purely a

46+-- Rel8 concept, and exists to mirror the 'Monoid' class.

4747type DBMonoid :: Type -> Constraint

4848class DBSemigroup a => DBMonoid a where

4949 -- The identity for '<>.'

src/Rel8/Type/Semigroup.hs+2−2

@@ -42,8 +42,8 @@ import qualified Data.Text.Lazy as Lazy ( Text )

4242import Data.Time.LocalTime ( CalendarDiffTime )

4343

4444

45−-- | The class of 'DBType's that form a semigroup. This class is purely a Rel8

46−-- concept, and exists to mirror the 'Semigroup' class.

45+-- | The class of 'Rel8.DBType's that form a semigroup. This class is purely a

46+-- Rel8 concept, and exists to mirror the 'Semigroup' class.

4747type DBSemigroup :: Type -> Constraint

4848class DBType a => DBSemigroup a where

4949 -- | An associative operation.