Esqueleto.Legacy (#259)

* Esqueleto.Legacy * Add changelog entry * Delete deprecated modules * a bit more * ghc 9 support, clean warns * yes * okkk
bitemyapp · May 26, 2021 · b295bc6 · b295bc6
1 parent ea4ff33
commit b295bc6
Show file tree

Hide file tree

Showing 18 changed files with 626 additions and 433 deletions.
diff --git a/.github/workflows/haskell.yml b/.github/workflows/haskell.yml
@@ -33,7 +33,7 @@ jobs:
     strategy:
       matrix:
         cabal: ["3.4"]
-        ghc: ["8.6.5", "8.8.4", "8.10.4"]
+        ghc: ["8.6.5", "8.8.4", "8.10.4", "9.0.1"]
     env:
       CONFIG: "--enable-tests --enable-benchmarks "
     steps:
@@ -71,6 +71,6 @@ jobs:
             ${{ runner.os }}-${{ matrix.ghc }}-${{ hashFiles('cabal.project.freeze') }}
             ${{ runner.os }}-${{ matrix.ghc }}-
       - run: cabal v2-build --disable-optimization -j $CONFIG
-      - run: cabal v2-test --disable-optimization -j $CONFIG
+      - run: cabal v2-test --disable-optimization -j $CONFIG --test-options "--fail-on-focus"
       - run: cabal v2-haddock -j $CONFIG
       - run: cabal v2-sdist
diff --git a/changelog.md b/changelog.md
@@ -1,14 +1,27 @@
 3.5.0.0
-======= 
+=======
 - @belevy
   - [#228](https://github.com/bitemyapp/esqueleto/pull/228)
-        - Destroy all GADTs; Removes the From GADT and SqlExpr GADT 
-        - From GADT is replaced with a From data type and FromRaw 
+        - Destroy all GADTs; Removes the From GADT and SqlExpr GADT
+        - From GADT is replaced with a From data type and FromRaw
         - SqlExpr is now all defined in terms of ERaw
-        - Modified ERaw to contain a SqlExprMeta with any extra information 
+        - Modified ERaw to contain a SqlExprMeta with any extra information
           that may be needed
-        - Experimental top level is now strictly for documentation and all the 
+        - Experimental top level is now strictly for documentation and all the
           implementation details are in Experimental.* modules
+- @parsonsmatt
+    - [#259](https://github.com/bitemyapp/esqueleto/pull/259)
+        - Create the `Database.Esqueleto.Legacy` module. The
+          `Database.Esqueleto` module now emits a warning, directing users to
+          either import `Database.Esqueleto.Legacy` to keep the old behavior or
+          to import `Database.Esqueleto.Experimental` to opt in to the new
+          behavior.
+        - Deleted the deprecated modules
+          `Database.Esqueleto.Internal.{Language,Sql}`. Please use
+          `Database.Esqueleto.Internal.Internal` instead, or ideally post what
+          you need from the library so we can support you safely.
+        - Support GHC 9
+
 3.4.2.2
 =======
 - @parsonsmatt

diff --git a/esqueleto.cabal b/esqueleto.cabal
@@ -29,9 +29,8 @@ source-repository head
 library
     exposed-modules:
         Database.Esqueleto
+        Database.Esqueleto.Legacy
         Database.Esqueleto.Experimental
-        Database.Esqueleto.Internal.Language
-        Database.Esqueleto.Internal.Sql
         Database.Esqueleto.Internal.Internal
         Database.Esqueleto.Internal.ExprParser
         Database.Esqueleto.MySQL
@@ -76,7 +75,6 @@ library
         -Wpartial-fields
         -Wmissing-home-modules
         -Widentities
-        -Wredundant-constraints
         -Wcpp-undef
         -Wcpp-undef
         -Wmonomorphism-restriction

diff --git a/src/Database/Esqueleto.hs b/src/Database/Esqueleto.hs
@@ -2,6 +2,7 @@
 {-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE GADTs #-}
 {-# LANGUAGE RankNTypes #-}
+
 -- | The @esqueleto@ EDSL (embedded domain specific language).
 -- This module replaces @Database.Persist@, so instead of
 -- importing that module you should just import this one:
@@ -31,11 +32,15 @@
 -- Other than identifier name clashes, @esqueleto@ does not
 -- conflict with @persistent@ in any way.
 --
--- Note that the faciliites for @JOIN@ have been significantly improved in the
+-- Note that the facilities for @JOIN@ have been significantly improved in the
 -- "Database.Esqueleto.Experimental" module. The definition of 'from' and 'on'
 -- in this module will be replaced with those at the 4.0.0.0 version, so you are
 -- encouraged to migrate to the new method.
-module Database.Esqueleto
+--
+-- This module has an attached WARNING message indicating that the Experimental
+-- syntax will become the default. If you want to continue using the old syntax,
+-- please refer to "Database.Esqueleto.Legacy" as a drop-in replacement.
+module Database.Esqueleto {-# WARNING "This module will switch over to the Experimental syntax in an upcoming major version release. Please migrate to the Database.Esqueleto.Legacy module to continue using the old syntax, or translate to the new and improved syntax in Database.Esqueleto.Experimental." #-}
   ( -- * Setup
     -- $setup
 
@@ -123,14 +128,8 @@ module Database.Esqueleto
   , module Database.Esqueleto.Internal.PersistentImport
   ) where
 
-import Control.Monad.IO.Class (MonadIO)
-import Control.Monad.Trans.Reader (ReaderT)
-import Data.Int (Int64)
-import qualified Data.Map.Strict as Map
-import Database.Esqueleto.Internal.Language
+import Database.Esqueleto.Legacy
 import Database.Esqueleto.Internal.PersistentImport
-import Database.Esqueleto.Internal.Sql
-import qualified Database.Persist
 
 
 -- $setup

diff --git a/src/Database/Esqueleto/Experimental.hs b/src/Database/Esqueleto/Experimental.hs
@@ -4,8 +4,8 @@
 -- Haskell. The old method was a bit finicky and could permit runtime errors,
 -- and this new way is both significantly safer and much more powerful.
 --
--- Esqueleto users are encouraged to migrate to this module, as it will become
--- the default in a new major version @4.0.0.0@.
+-- This syntax will become the default syntax exported from the library in
+-- version @3.6.0.0@. To use the old syntax, see "Database.Esqueleto.Legacy".
 module Database.Esqueleto.Experimental
     ( -- * Setup
       -- $setup
@@ -229,9 +229,6 @@ import Database.Esqueleto.Experimental.ToAlias
 import Database.Esqueleto.Experimental.ToAliasReference
 import Database.Esqueleto.Experimental.ToMaybe
 
-import GHC.TypeLits
-import Database.Persist (EntityNameDB(..))
-
 -- $setup
 --
 -- If you're already using "Database.Esqueleto", then you can get

diff --git a/src/Database/Esqueleto/Experimental/From.hs b/src/Database/Esqueleto/Experimental/From.hs
@@ -18,8 +18,6 @@
 module Database.Esqueleto.Experimental.From
     where
 
-import Control.Arrow (first)
-import Control.Monad (ap)
 import qualified Control.Monad.Trans.Writer as W
 import Data.Coerce (coerce)
 import Data.Proxy
@@ -56,7 +54,7 @@ type RawFn = NeedParens -> IdentInfo -> (TLB.Builder, [PersistValue])
 -- the FromRaw FromClause constructor directly when converting
 -- from a @From@ to a @SqlQuery@ using @from@
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 newtype From a = From
     { unFrom :: SqlQuery (a, RawFn)}
 
@@ -66,13 +64,13 @@ newtype From a = From
 -- as well as supporting backwards compatibility for the
 -- data constructor join tree used prior to /3.5.0.0/
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 class ToFrom a r | a -> r where
     toFrom :: a -> From r
 instance ToFrom (From a) a where
     toFrom = id
 
-{-# DEPRECATED Table "/Since: 3.5.0.0/ - use 'table' instead" #-}
+{-# DEPRECATED Table "@since 3.5.0.0 - use 'table' instead" #-}
 data Table a = Table
 
 instance PersistEntity ent => ToFrom (Table ent) (SqlExpr (Entity ent)) where
@@ -84,7 +82,7 @@ instance PersistEntity ent => ToFrom (Table ent) (SqlExpr (Entity ent)) where
 -- select $ from $ table \@People
 -- @
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 table :: forall ent. PersistEntity ent => From (SqlExpr (Entity ent))
 table = From $ do
     let ed = entityDef (Proxy @ent)
@@ -123,7 +121,7 @@ instance (SqlSelect a r, ToAlias a, ToAliasReference a) => ToFrom (SqlQuery a) a
 --      ...
 -- @
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 selectQuery :: (SqlSelect a r, ToAlias a, ToAliasReference a) => SqlQuery a -> From a
 selectQuery subquery = From $ do
     -- We want to update the IdentState without writing the query to side data

diff --git a/src/Database/Esqueleto/Experimental/From/Join.hs b/src/Database/Esqueleto/Experimental/From/Join.hs
@@ -1,37 +1,31 @@
-{-# LANGUAGE DataKinds              #-}
-{-# LANGUAGE FlexibleContexts       #-}
-{-# LANGUAGE FlexibleInstances      #-}
+{-# LANGUAGE DataKinds #-}
+{-# LANGUAGE FlexibleContexts #-}
+{-# LANGUAGE FlexibleInstances #-}
 {-# LANGUAGE FunctionalDependencies #-}
-{-# LANGUAGE MultiParamTypeClasses  #-}
-{-# LANGUAGE OverloadedStrings      #-}
-{-# LANGUAGE ScopedTypeVariables    #-}
-{-# LANGUAGE TypeApplications       #-}
-{-# LANGUAGE TypeFamilies           #-}
-{-# LANGUAGE TypeOperators          #-}
-{-# LANGUAGE UndecidableInstances   #-}
+{-# LANGUAGE MultiParamTypeClasses #-}
+{-# LANGUAGE OverloadedStrings #-}
+{-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications #-}
+{-# LANGUAGE TypeFamilies #-}
+{-# LANGUAGE TypeOperators #-}
+{-# LANGUAGE UndecidableInstances #-}
+
+{-# OPTIONS_GHC -fno-warn-orphans #-}
 
 module Database.Esqueleto.Experimental.From.Join
     where
 
-import           Data.Bifunctor                                       (first)
-import           Data.Kind                                            (Constraint)
-import           Data.Proxy
-import qualified Data.Text.Lazy.Builder                               as TLB
-import           Database.Esqueleto.Experimental.From
-import           Database.Esqueleto.Experimental.From.SqlSetOperation
-import           Database.Esqueleto.Experimental.ToAlias
-import           Database.Esqueleto.Experimental.ToAliasReference
-import           Database.Esqueleto.Experimental.ToMaybe
-import           Database.Esqueleto.Internal.Internal                 hiding
-                                                                      (From (..),
-                                                                       from,
-                                                                       fromJoin,
-                                                                       on)
-import           Database.Esqueleto.Internal.PersistentImport         (Entity (..),
-                                                                       EntityField,
-                                                                       PersistEntity,
-                                                                       PersistField)
-import           GHC.TypeLits
+import Data.Bifunctor (first)
+import Data.Kind (Constraint)
+import Data.Proxy
+import qualified Data.Text.Lazy.Builder as TLB
+import Database.Esqueleto.Experimental.From
+import Database.Esqueleto.Experimental.ToAlias
+import Database.Esqueleto.Experimental.ToAliasReference
+import Database.Esqueleto.Experimental.ToMaybe
+import Database.Esqueleto.Internal.Internal hiding
+       (From(..), from, fromJoin, on)
+import GHC.TypeLits
 
 -- | A left-precedence pair. Pronounced \"and\". Used to represent expressions
 -- that have been joined together.
@@ -110,7 +104,7 @@ type family HasOnClause actual expected :: Constraint where
 --         p ^. PersonId ==. bp ^. BlogPostAuthorId)
 -- @
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 innerJoin :: ( ToFrom a a'
              , ToFrom b b'
              , HasOnClause rhs (a' :& b')
@@ -132,7 +126,7 @@ innerJoin lhs (rhs, on') = From $ do
 --
 -- See example 6
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 innerJoinLateral :: ( ToFrom a a'
                     , HasOnClause rhs (a' :& b)
                     , SqlSelect b r
@@ -157,7 +151,7 @@ innerJoinLateral lhs (rhsFn, on') = From $ do
 -- \`crossJoin\` table \@BlogPost
 -- @
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 crossJoin :: ( ToFrom a a'
              , ToFrom b b'
              ) => a -> b -> From (a' :& b')
@@ -176,7 +170,7 @@ crossJoin lhs rhs = From $ do
 --
 -- See example 6
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 crossJoinLateral :: ( ToFrom a a'
                     , SqlSelect b r
                     , ToAlias b
@@ -205,7 +199,7 @@ crossJoinLateral lhs rhsFn = From $ do
 --         p ^. PersonId ==. bp ?. BlogPostAuthorId)
 -- @
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 leftJoin :: ( ToFrom a a'
             , ToFrom b b'
             , ToMaybe b'
@@ -229,7 +223,7 @@ leftJoin lhs (rhs, on') = From $ do
 --
 -- See example 6 for how to use LATERAL
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 leftJoinLateral :: ( ToFrom a a'
                    , SqlSelect b r
                    , HasOnClause rhs (a' :& ToMaybeT b)
@@ -261,7 +255,7 @@ leftJoinLateral lhs (rhsFn, on') = From $ do
 --         p ?. PersonId ==. bp ^. BlogPostAuthorId)
 -- @
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 rightJoin :: ( ToFrom a a'
              , ToFrom b b'
              , ToMaybe a'
@@ -289,7 +283,7 @@ rightJoin lhs (rhs, on') = From $ do
 --         p ?. PersonId ==. bp ?. BlogPostAuthorId)
 -- @
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 fullOuterJoin :: ( ToFrom a a'
                  , ToFrom b b'
                  , ToMaybe a'

diff --git a/src/Database/Esqueleto/Experimental/From/SqlSetOperation.hs b/src/Database/Esqueleto/Experimental/From/SqlSetOperation.hs
@@ -21,15 +21,14 @@ import Database.Esqueleto.Experimental.From
 import Database.Esqueleto.Experimental.ToAlias
 import Database.Esqueleto.Experimental.ToAliasReference
 import Database.Esqueleto.Internal.Internal hiding (From(..), from, on)
-import Database.Esqueleto.Internal.PersistentImport
-       (Entity, PersistEntity, PersistValue)
+import Database.Esqueleto.Internal.PersistentImport (PersistValue)
 
 -- | Data type used to implement the SqlSetOperation language
 -- this type is implemented in the same way as a @From@
 --
 -- Semantically a @SqlSetOperation@ is always a @From@ but not vice versa
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 newtype SqlSetOperation a = SqlSetOperation
     { unSqlSetOperation :: NeedParens -> SqlQuery (a, IdentInfo -> (TLB.Builder, [PersistValue]))}
 
@@ -42,7 +41,7 @@ instance ToAliasReference a => ToFrom (SqlSetOperation a) a where
 
 -- | Type class to support direct use of @SqlQuery@ in a set operation tree
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 class ToSqlSetOperation a r | a -> r where
     toSqlSetOperation :: a -> SqlSetOperation r
 instance ToSqlSetOperation (SqlSetOperation a) a where
@@ -67,7 +66,7 @@ instance (SqlSelect a r, ToAlias a, ToAliasReference a) => ToSqlSetOperation (Sq
             pure (aliasedValue, \info -> first (parensM p') $ toRawSql SELECT info aliasedQuery)
 
 -- | Helper function for defining set operations
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 mkSetOperation :: (ToSqlSetOperation a a', ToSqlSetOperation b a')
                => TLB.Builder -> a -> b -> SqlSetOperation a'
 mkSetOperation operation lhs rhs = SqlSetOperation $ \p -> do
@@ -83,7 +82,7 @@ instance ToSqlSetOperation a a' => ToSqlSetOperation (Union a a) a' where
 -- | Overloaded @union_@ function to support use in both 'SqlSetOperation'
 -- and 'withRecursive'
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 class Union_ a where
     -- | @UNION@ SQL set operation. Can be used as an infix function between 'SqlQuery' values.
     union_ :: a
@@ -95,7 +94,7 @@ instance (ToSqlSetOperation a c, ToSqlSetOperation b c, res ~ SqlSetOperation c)
 -- | Overloaded @unionAll_@ function to support use in both 'SqlSetOperation'
 -- and 'withRecursive'
 --
--- /Since: 3.5.0.0/
+-- @since 3.5.0.0
 class UnionAll_ a where
     -- | @UNION@ @ALL@ SQL set operation. Can be used as an infix function between 'SqlQuery' values.
     unionAll_ :: a