@@ -88,13 +88,13 @@ module Squeal.PostgreSQL.Expression
8888 , upper
8989 , charLength
9090 , like
91− -- ** Json functions and operators
91+ -- ** Json
9292 -- *** Json and Jsonb operators
9393 , (.->)
9494 , (.->>)
9595 , (.#>)
9696 , (.#>>)
97− -- *** Additional Jsonb operators
97+ -- *** Jsonb operators
9898 , (.@>)
9999 , (.<@)
100100 , (.?)
@@ -102,7 +102,7 @@ module Squeal.PostgreSQL.Expression
102102 , (.?&)
103103 , (.-.)
104104 , (#-.)
105− -- *** Json creation functions
105+ -- *** functions
106106 , jsonLit
107107 , jsonbLit
108108 , toJson
@@ -443,9 +443,11 @@ array
443443array xs = UnsafeExpression $
444444 "ARRAY[" <> commaSeparated (renderExpression <$> xs) <> "]"
445445
446+-- | >>> printSQL $ array [null_, false, true] & index 2
447+-- (ARRAY[NULL, FALSE, TRUE])[2]
446448index
447− :: Word64
448− -> Expression schema from grouping params (nullity ('PGvararray ty))
449+ :: Word64 -- ^ index
450+ -> Expression schema from grouping params (nullity ('PGvararray ty)) -- ^ array
449451 -> Expression schema from grouping params (NullifyType ty)
450452index n expr = UnsafeExpression $
451453 parenthesized (renderExpression expr) <> "[" <> fromString (show n) <> "]"
@@ -467,20 +469,31 @@ instance (KnownSymbol label, label `In` labels) => IsPGlabel label
467469-- >>> printSQL i
468470-- ROW(0, 1)
469471row
470− :: SListI fields
471− => NP (Aliased (Expression schema from grouping params)) fields
472+ :: SListI row
473+ => NP (Aliased (Expression schema from grouping params)) row
472474 -- ^ zero or more expressions for the row field values
473− -> Expression schema from grouping params (nullity ('PGcomposite fields))
475+ -> Expression schema from grouping params (nullity ('PGcomposite row))
474476row exprs = UnsafeExpression $ "ROW" <> parenthesized
475477 (renderCommaSeparated (\ (expr `As` _) -> renderExpression expr) exprs)
476478
479+-- | >>> :{
480+-- type Complex = 'PGcomposite
481+-- '[ "real" ::: 'NotNull 'PGfloat8
482+-- , "imaginary" ::: 'NotNull 'PGfloat8 ]
483+-- :}
484+--
485+-- >>> let i = row (0 `as` #real :* 1 `as` #imaginary) :: Expression '["complex" ::: 'Typedef Complex] '[] 'Ungrouped '[] ('NotNull Complex)
486+-- >>> printSQL $ i & field #complex #imaginary
487+-- (ROW(0, 1)::"complex")."imaginary"
477488field
478− :: forall field fields ty schema from grouping params. Has field fields ty
479− => Expression schema from grouping params ('NotNull ('PGcomposite fields))
489+ :: (Has tydef schema ('Typedef ('PGcomposite row)), Has field row ty)
490+ => Alias tydef -- ^ row type
491+ -> Alias field -- ^ field name
492+ -> Expression schema from grouping params ('NotNull ('PGcomposite row))
480493 -> Expression schema from grouping params ty
481−field expr = UnsafeExpression $
482− parenthesized (renderExpression expr) <> "." <>
483− renderSymbol @field
494+field td fld expr = UnsafeExpression $
495+ parenthesized (renderExpression expr <> "::" <> renderAlias td)
496+ <> "." <> renderAlias fld
484497
485498instance Semigroup
486499 (Expression schema from grouping params (nullity ('PGvararray ty))) where
@@ -1611,18 +1624,23 @@ newtype TypeExpression (schema :: SchemaType) (ty :: NullityType)
16111624 = UnsafeTypeExpression { renderTypeExpression :: ByteString }
16121625 deriving (GHC.Generic,Show,Eq,Ord,NFData)
16131626
1627+-- | The enum or composite type in a `Typedef` can be expressed by its alias.
16141628typedef
16151629 :: Has alias schema ('Typedef ty)
16161630 => Alias alias
16171631 -> TypeExpression schema (nullity ty)
16181632typedef = UnsafeTypeExpression . renderAlias
16191633
1634+-- | The composite type corresponding to a `Table` definition can be expressed
1635+-- by its alias.
16201636typetable
16211637 :: Has alias schema ('Table tab)
16221638 => Alias alias
16231639 -> TypeExpression schema (nullity ('PGcomposite (TableToRow tab)))
16241640typetable = UnsafeTypeExpression . renderAlias
16251641
1642+-- | The composite type corresponding to a `View` definition can be expressed
1643+-- by its alias.
16261644typeview
16271645 :: Has alias schema ('View view)
16281646 => Alias alias