Docs on boolean operators

changelog.md

@@ -2,15 +2,16 @@
 ========
 - @blujupiter32
     - [#379](https://github.com/bitemyapp/esqueleto/pull/379)
-        - Fix a bug where `not_ (a &&. b)` would be interpeted as `(not_ a) &&.
-          b`
+        - Fix a bug where `not_ (a &&. b)` would be interpeted as `(not_ a) &&. b`
 - @TeofilC
-  - [#394](https://github.com/bitemyapp/esqueleto/pull/394)
-    - Use TH quotes to eliminate some CPP.
+    - [#394](https://github.com/bitemyapp/esqueleto/pull/394)
+        - Use TH quotes to eliminate some CPP.
+- @parsonsmatt, @jappeace
+    - [#346](#https://github.com/bitemyapp/esqueleto/pull/346), [#411](https://github.com/bitemyapp/esqueleto/pull/411)
+        - Add docs for more SQL operators
 
 3.5.13.1
 ========
-
 - @csamak
     - [#405](https://github.com/bitemyapp/esqueleto/pull/405)
       - Fix a bug introduced in 3.5.12.0 where deriveEsqueletoRecord incorrectly errors

src/Database/Esqueleto/Internal/Internal.hs

@@ -60,7 +60,7 @@
 import Data.Kind (Type)
 import qualified Data.List as List
 import qualified Data.Map.Strict as Map
 import qualified Data.Monoid as Monoid
 import Data.Proxy (Proxy(..))
 import Data.Set (Set)
 import qualified Data.Set as Set
@@ -70,7 +70,7 @@
 import Data.Typeable (Typeable)
 import Database.Esqueleto.Internal.ExprParser (TableAccess(..), parseOnExpr)
 import Database.Esqueleto.Internal.PersistentImport
 import Database.Persist (EntityNameDB(..), FieldNameDB(..), SymbolToField(..))
 import qualified Database.Persist
 import Database.Persist.Sql.Util
        ( entityColumnCount
@@ -727,42 +727,157 @@
                 else
                     f Parens info
 
+-- | This operator produces the SQL operator @=@, which is used to compare
+-- values for equality.
+--
+-- Example:
+--
+-- @
+--  query :: UserId -> SqlPersistT IO [Entity User]
+--  query userId = select $ do
+--      user <- from $ table \@User
+--      where_ (user ^. UserId ==. val userId)
+--      pure user
+-- @
+--
+-- This would generate the following SQL:
+--
+-- @
+--  SELECT user.*
+--  FROM user
+--  WHERE user.id = ?
+-- @
 (==.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
 (==.) = unsafeSqlBinOpComposite " = " " AND "
 
+-- | This operator translates to the SQL operator @>=@.
+--
+-- Example:
+--
+-- @
+--  where_ $ user ^. UserAge >=. val 21
+-- @
 (>=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
 (>=.) = unsafeSqlBinOp " >= "
 
+-- | This operator translates to the SQL operator @>@.
+--
+-- Example:
+--
+-- @
+--  where_ $ user ^. UserAge >. val 20
+-- @
 (>.)  :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
 (>.)  = unsafeSqlBinOp " > "
 
+-- | This operator translates to the SQL operator @<=@.
+--
+-- Example:
+--
+-- @
+--  where_ $ val 21 <=. user ^. UserAge
+-- @
 (<=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
 (<=.) = unsafeSqlBinOp " <= "
 
+-- | This operator translates to the SQL operator @<@.
+--
+-- Example:
+--
+-- @
+--  where_ $ val 20 <. user ^. UserAge
+-- @
 (<.)  :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
 (<.)  = unsafeSqlBinOp " < "
+
+-- | This operator translates to the SQL operator @!=@.
+--
+-- Example:
+--
+-- @
+--  where_ $ user ^. UserName !=. val "Bob"
+-- @
 (!=.) :: PersistField typ => SqlExpr (Value typ) -> SqlExpr (Value typ) -> SqlExpr (Value Bool)
 (!=.) = unsafeSqlBinOpComposite " != " " OR "
 
+-- | This operator translates to the SQL operator @AND@.
+--
+-- Example:
+--
+-- @
+--  where_ $
+--          user ^. UserName ==. val "Matt"
+--      &&. user ^. UserAge >=. val 21
+-- @
 (&&.) :: SqlExpr (Value Bool) -> SqlExpr (Value Bool) -> SqlExpr (Value Bool)
 (&&.) = unsafeSqlBinOp " AND "
 
+-- | This operator translates to the SQL operator @AND@.
+--
+-- Example:
+--
+-- @
+--  where_ $
+--          user ^. UserName ==. val "Matt"
+--      ||. user ^. UserName ==. val "John"
+-- @
 (||.) :: SqlExpr (Value Bool) -> SqlExpr (Value Bool) -> SqlExpr (Value Bool)
 (||.) = unsafeSqlBinOp " OR "
 
+-- | This operator translates to the SQL operator @+@.
+--
+-- This does not require or assume anything about the SQL values. Interpreting
+-- what @+.@ means for a given type is left to the database engine.
+--
+-- Example:
+--
+-- @
+--  user ^. UserAge +. val 10
+-- @
 (+.)  :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
 (+.)  = unsafeSqlBinOp " + "
 
+-- | This operator translates to the SQL operator @-@.
+--
+-- This does not require or assume anything about the SQL values. Interpreting
+-- what @-.@ means for a given type is left to the database engine.
+--
+-- Example:
+--
+-- @
+--  user ^. UserAge -. val 10
+-- @
 (-.)  :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
 (-.)  = unsafeSqlBinOp " - "
 
+-- | This operator translates to the SQL operator @/@.
+--
+-- This does not require or assume anything about the SQL values. Interpreting
+-- what @/.@ means for a given type is left to the database engine.
+--
+-- Example:
+--
+-- @
+--  user ^. UserAge /. val 10
+-- @
 (/.)  :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
 (/.)  = unsafeSqlBinOp " / "
 
+-- | This operator translates to the SQL operator @*@.
+--
+-- This does not require or assume anything about the SQL values. Interpreting
+-- what @*.@ means for a given type is left to the database engine.
+--
+-- Example:
+--
+-- @
+--  user ^. UserAge *. val 10
+-- @
 (*.)  :: PersistField a => SqlExpr (Value a) -> SqlExpr (Value a) -> SqlExpr (Value a)
 (*.)  = unsafeSqlBinOp " * "
 
--- | @BETWEEN@.
+-- | @a `between` (b, c)@ translates to the SQL expression @a >= b AND a <= c@.
+-- It does not use a SQL @BETWEEN@ operator.
 --
 -- @since: 3.1.0
 between :: PersistField a => SqlExpr (Value a) -> (SqlExpr (Value a), SqlExpr (Value a)) -> SqlExpr (Value Bool)
@@ -1318,7 +1433,7 @@
     unique = finalR uniqueConstructor
     -- there must be a better way to get the constrain name from a unique, make this not a list search
     filterF = (==) (persistUniqueToFieldNames unique) . uniqueFields
     uniqueDef = head . filter filterF . getEntityUniques . entityDef $ proxy
 
 -- | Render updates to be use in a SET clause for a given sql backend.
 --