@@ -19,6 +19,21 @@ 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.
24+--
25+-- A common pattern is to use '<>' to combine multiple orderings in sequence,
26+-- and '>$<' (from 'Contravariant') to select individual columns. For example,
27+-- to sort a @Query@ on two columns, we could do:
28+--
29+-- >>> import Data.Functor.Contravariant ((>$<))
30+-- >>> :{
31+-- select c $ orderBy (mconcat [fst >$< asc, snd >$< desc]) $ do
32+-- x <- values [ lit x | x <- [1..3 :: Int32 ] ]
33+-- y <- values [ lit x | x <- [1..3 :: Int32 ] ]
34+-- return (x, y)
35+-- :}
36+-- [(1,3),(1,2),(1,1),(2,3),(2,2),(2,1),(3,3),(3,2),(3,1)]
2237type Order :: Type -> Type
2338newtype Order a = Order (Opaleye.Order a)
2439 deriving newtype (Contravariant, Divisible, Decidable, Semigroup, Monoid)