duckdb-simple-1.0.0.0: src/Database/DuckDB/Simple/Conversion.hs
-- |
-- Module : Database.DuckDB.Simple.Conversion
-- Description : Effectful conversion from DuckDB values.
module Database.DuckDB.Simple.Conversion (
Conversion,
runConversion,
liftConversion,
conversionError,
conversionErrorWith,
mapConversionErrors,
mapConversionErrorsWith,
) where
import Control.Applicative (Alternative (..))
import Control.Exception (Exception, SomeException, evaluate, toException)
import Control.Monad (MonadPlus (..), ap)
import qualified Control.Monad.Fail as Fail
import Database.DuckDB.Simple.Ok (Ok (..))
-- | A conversion with explicit IO and deferred conversion errors.
-- See Note [Conversion effects].
newtype Conversion a = Conversion (IO (Either (IO [SomeException]) a))
{- Note [Conversion effects]
~~~~~~~~~~~~~~~~~~~~~~~~~~~
A conversion can read native metadata through liftConversion. These reads run
only when the conversion demands them. IO exceptions, including cancellation,
propagate to the caller. They are not conversion errors.
A failed conversion stores an action that makes its diagnostics. Alternative
discards this action when the other branch succeeds. runConversion runs the
actions only after all branches fail. Thus a discarded error does not read
metadata, such as an ENUM dictionary, just to name the SQL type.
Field metadata uses Conversion too. Its native owner and successful-result
cache belong to its result or callback scope. Native type actions fail after
that scope closes. See Note [Scoped field types] in
"Database.DuckDB.Simple.TypeScope". A child field maps its type projection
over the parent's conversion. No pure thunk performs IO or stores an IO
exception.
Each successful step forces its value to weak head normal form, as Ok does.
The force runs in IO with the caller's masking state. Thus a value nested in
the final row cannot defer its field conversion until after runConversion.
-}
instance Functor Conversion where
{-# INLINE fmap #-}
fmap f (Conversion action) = Conversion $ fmap mapResult action
where
mapResult (Left errors) = Left errors
mapResult (Right value) = strictRight (f value)
instance Applicative Conversion where
{-# INLINE pure #-}
pure value = Conversion (pure (strictRight value))
{-# INLINE (<*>) #-}
(<*>) = ap
instance Monad Conversion where
{-# INLINE (>>=) #-}
Conversion action >>= next = Conversion $ do
result <- action
case result of
Left errors -> pure (Left errors)
Right value -> case next value of
Conversion following -> following
instance Alternative Conversion where
empty = Conversion (pure (Left (pure [])))
Conversion first <|> Conversion second = Conversion $ do
result <- first
case result of
Right value -> pure (Right value)
Left firstErrors -> do
alternative <- second
pure $ case alternative of
Right value -> Right value
Left secondErrors -> Left ((<>) <$> firstErrors <*> secondErrors)
instance MonadPlus Conversion where
mzero = empty
mplus = (<|>)
instance Fail.MonadFail Conversion where
fail = conversionError . userError
-- | Run a conversion and resolve the diagnostics if it fails.
-- Force a successful value to weak head normal form. IO exceptions propagate
-- to the caller.
runConversion :: Conversion a -> IO (Ok a)
{-# INLINE runConversion #-}
runConversion (Conversion action) = do
result <- action
case result of
Left errors -> Errors <$> errors
Right value -> evaluate (Ok value)
-- | Run an IO action when the conversion demands its result.
-- A decoder in a registered callback must use another connection for nested
-- SQL. Reads of the owned field type need no connection lock.
liftConversion :: IO a -> Conversion a
{-# INLINE liftConversion #-}
liftConversion action = Conversion (strictRight <$> action)
-- | Construct a success that forces its value when its result tag is read.
strictRight :: a -> Either e a
{-# INLINE strictRight #-}
strictRight value = value `seq` Right value
-- | Fail with a conversion error.
conversionError :: (Exception e) => e -> Conversion a
conversionError err = Conversion (pure (Left (pure [toException err])))
-- | Make an error only if the final conversion fails.
-- See Note [Conversion effects].
conversionErrorWith :: (Exception e) => Conversion e -> Conversion a
conversionErrorWith (Conversion diagnostic) = Conversion $ pure $ Left $ do
result <- diagnostic
case result of
Left errors -> errors
Right err -> pure [toException err]
-- | Change deferred diagnostics without running them.
mapConversionErrors :: ([SomeException] -> [SomeException]) -> Conversion a -> Conversion a
mapConversionErrors f (Conversion action) = Conversion $ do
result <- action
pure $ case result of
Left errors -> Left (f <$> errors)
Right value -> Right value
-- | Change the diagnostics with a conversion when the final conversion fails.
mapConversionErrorsWith :: ([SomeException] -> Conversion [SomeException]) -> Conversion a -> Conversion a
mapConversionErrorsWith f (Conversion action) = Conversion $ do
result <- action
pure $ case result of
Right value -> Right value
Left errors -> Left $ do
original <- errors
case f original of
Conversion following -> do
mapped <- following
case mapped of
Left failures -> failures
Right replacement -> pure replacement