{-# LANGUAGE UndecidableInstances #-}
-- |
-- Copyright        : (c) Raghu Kaippully, 2020
-- License          : MPL-2.0
-- Maintainer       : rkaippully@gmail.com
--
-- Traits are optional attributes associated with a value. For
-- example, a list containing totally ordered values might have a
-- @Maximum@ trait where the associated attribute is the maximum
-- value. This trait exists only if the list is non-empty. The 'Trait'
-- typeclass provides an interface to extract such trait attributes.
--
-- Traits help to link attributes with values in a type-safe manner.
--
-- Traits are somewhat similar to [refinement
-- types](https://hackage.haskell.org/package/refined), but allow
-- arbitrary attributes to be associated with a value instead of only
-- a predicate.
--
module WebGear.Trait
  ( -- * Core Types
    Trait (..)
  , Result (..)
  , Linked

    -- * Linking values with attributes
  , link
  , unlink
  , probe
  , remove

    -- * Retrive trait attributes from linked values
  , Has (..)
  , Have

  , MissingTrait
  ) where

import Data.Kind (Constraint, Type)
import Data.Proxy (Proxy (..))
import GHC.TypeLits (ErrorMessage (..), TypeError)


-- | A trait is an optional attribute @t@ associated with a value
-- @a@.
class Monad m => Trait t a m where
  -- | Type of the associated attribute when the trait holds for a
  -- value
  type Attribute t a :: Type

  -- | Type that indicates that the trait does not exist for a
  -- value. This could be an error message, parse error etc.
  type Absence t a :: Type

  -- | Attempt to deduce the trait attribute from the value @a@. It is
  -- possible that deducing a trait's presence can alter the value,
  -- hence this function returns a possibly updated value along with
  -- the trait attribute on success.
  toAttribute :: a -> m (Result t a)


-- | The result of 'toAttribute' - either a successful deduction of an
-- attribute or an error.
data Result t a = NotFound (Absence t a)
                | Found (Attribute t a)

-- | A trivial derivable trait that is always present and whose
-- attribute does not carry any meaningful information.
instance Monad m => Trait '[] a m where
  type Attribute '[] a = ()
  type Absence '[] a = ()

  toAttribute :: a -> m (Result '[] a)
  toAttribute :: a -> m (Result '[] a)
toAttribute = m (Result '[] a) -> a -> m (Result '[] a)
forall a b. a -> b -> a
const (m (Result '[] a) -> a -> m (Result '[] a))
-> m (Result '[] a) -> a -> m (Result '[] a)
forall a b. (a -> b) -> a -> b
$ Result '[] a -> m (Result '[] a)
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Result '[] a -> m (Result '[] a))
-> Result '[] a -> m (Result '[] a)
forall a b. (a -> b) -> a -> b
$ Attribute '[] a -> Result '[] a
forall k (t :: k) a. Attribute t a -> Result t a
Found ()

-- | Combination of many derivable traits all of which are present for
-- a value.
instance (Trait t a m, Trait ts a m, Monad m) => Trait (t:ts) a m where
  type Attribute (t:ts) a = (Attribute t a, Attribute ts a)
  type Absence (t:ts) a = Either (Result t a) (Result ts a)

  toAttribute :: a -> m (Result (t:ts) a)
  toAttribute :: a -> m (Result (t : ts) a)
toAttribute a
a = a -> m (Result t a)
forall k (t :: k) a (m :: * -> *).
Trait t a m =>
a -> m (Result t a)
toAttribute @t a
a m (Result t a)
-> (Result t a -> m (Result (t : ts) a)) -> m (Result (t : ts) a)
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
    e :: Result t a
e@(NotFound Absence t a
_) -> Result (t : ts) a -> m (Result (t : ts) a)
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Result (t : ts) a -> m (Result (t : ts) a))
-> Result (t : ts) a -> m (Result (t : ts) a)
forall a b. (a -> b) -> a -> b
$ Absence (t : ts) a -> Result (t : ts) a
forall k (t :: k) a. Absence t a -> Result t a
NotFound (Absence (t : ts) a -> Result (t : ts) a)
-> Absence (t : ts) a -> Result (t : ts) a
forall a b. (a -> b) -> a -> b
$ Result t a -> Either (Result t a) (Result ts a)
forall a b. a -> Either a b
Left Result t a
e
    Found Attribute t a
l        -> a -> m (Result ts a)
forall k (t :: k) a (m :: * -> *).
Trait t a m =>
a -> m (Result t a)
toAttribute @ts a
a m (Result ts a)
-> (Result ts a -> m (Result (t : ts) a)) -> m (Result (t : ts) a)
forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= \case
      e :: Result ts a
e@(NotFound Absence ts a
_) -> Result (t : ts) a -> m (Result (t : ts) a)
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Result (t : ts) a -> m (Result (t : ts) a))
-> Result (t : ts) a -> m (Result (t : ts) a)
forall a b. (a -> b) -> a -> b
$ Absence (t : ts) a -> Result (t : ts) a
forall k (t :: k) a. Absence t a -> Result t a
NotFound (Absence (t : ts) a -> Result (t : ts) a)
-> Absence (t : ts) a -> Result (t : ts) a
forall a b. (a -> b) -> a -> b
$ Result ts a -> Either (Result t a) (Result ts a)
forall a b. b -> Either a b
Right Result ts a
e
      Found Attribute ts a
r        -> Result (t : ts) a -> m (Result (t : ts) a)
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Result (t : ts) a -> m (Result (t : ts) a))
-> Result (t : ts) a -> m (Result (t : ts) a)
forall a b. (a -> b) -> a -> b
$ Attribute (t : ts) a -> Result (t : ts) a
forall k (t :: k) a. Attribute t a -> Result t a
Found (Attribute t a
l, Attribute ts a
r)


-- | A value linked with a type-level list of traits.
data Linked (ts :: [Type]) a = Linked
    { Linked ts a -> Attribute ts a
linkAttribute :: !(Attribute ts a)
    , Linked ts a -> a
unlink        :: !a                 -- ^ Retrive the value from a linked value
    }

-- | Wrap a value with an empty list of traits.
link :: a -> Linked '[] a
link :: a -> Linked '[] a
link = Attribute '[] a -> a -> Linked '[] a
forall (ts :: [*]) a. Attribute ts a -> a -> Linked ts a
Linked ()

-- | Attempt to link an additional trait with an already linked value
-- via the 'toAttribute' operation. This can fail indicating an
-- 'Absence' of the trait.
probe :: forall t ts a m. Trait t a m
      => Linked ts a
      -> m (Either (Absence t a) (Linked (t:ts) a))
probe :: Linked ts a -> m (Either (Absence t a) (Linked (t : ts) a))
probe Linked ts a
l = do
  Result t a
v <- a -> m (Result t a)
forall k (t :: k) a (m :: * -> *).
Trait t a m =>
a -> m (Result t a)
toAttribute @t (Linked ts a -> a
forall (ts :: [*]) a. Linked ts a -> a
unlink Linked ts a
l)
  Either (Absence t a) (Linked (t : ts) a)
-> m (Either (Absence t a) (Linked (t : ts) a))
forall (f :: * -> *) a. Applicative f => a -> f a
pure (Either (Absence t a) (Linked (t : ts) a)
 -> m (Either (Absence t a) (Linked (t : ts) a)))
-> Either (Absence t a) (Linked (t : ts) a)
-> m (Either (Absence t a) (Linked (t : ts) a))
forall a b. (a -> b) -> a -> b
$ Result t a
-> Linked ts a -> Either (Absence t a) (Linked (t : ts) a)
mkLinked Result t a
v Linked ts a
l
  where
    mkLinked :: Result t a -> Linked ts a -> Either (Absence t a) (Linked (t:ts) a)
    mkLinked :: Result t a
-> Linked ts a -> Either (Absence t a) (Linked (t : ts) a)
mkLinked (Found Attribute t a
left) Linked ts a
lv = Linked (t : ts) a -> Either (Absence t a) (Linked (t : ts) a)
forall a b. b -> Either a b
Right (Linked (t : ts) a -> Either (Absence t a) (Linked (t : ts) a))
-> Linked (t : ts) a -> Either (Absence t a) (Linked (t : ts) a)
forall a b. (a -> b) -> a -> b
$ Attribute (t : ts) a -> a -> Linked (t : ts) a
forall (ts :: [*]) a. Attribute ts a -> a -> Linked ts a
Linked (Attribute t a
left, Linked ts a -> Attribute ts a
forall (ts :: [*]) a. Linked ts a -> Attribute ts a
linkAttribute Linked ts a
lv) (Linked ts a -> a
forall (ts :: [*]) a. Linked ts a -> a
unlink Linked ts a
lv)
    mkLinked (NotFound Absence t a
e) Linked ts a
_  = Absence t a -> Either (Absence t a) (Linked (t : ts) a)
forall a b. a -> Either a b
Left Absence t a
e

-- | Remove the leading trait from the type-level list of traits
remove :: Linked (t:ts) a -> Linked ts a
remove :: Linked (t : ts) a -> Linked ts a
remove Linked (t : ts) a
l = Attribute ts a -> a -> Linked ts a
forall (ts :: [*]) a. Attribute ts a -> a -> Linked ts a
Linked ((Attribute t a, Attribute ts a) -> Attribute ts a
forall a b. (a, b) -> b
snd ((Attribute t a, Attribute ts a) -> Attribute ts a)
-> (Attribute t a, Attribute ts a) -> Attribute ts a
forall a b. (a -> b) -> a -> b
$ Linked (t : ts) a -> Attribute (t : ts) a
forall (ts :: [*]) a. Linked ts a -> Attribute ts a
linkAttribute Linked (t : ts) a
l) (Linked (t : ts) a -> a
forall (ts :: [*]) a. Linked ts a -> a
unlink Linked (t : ts) a
l)


-- | Constraint that proves that the trait @t@ is present in the list
-- of traits @ts@.
class Has t ts where
  -- | Get the attribute associated with @t@ from a linked value
  get :: Proxy t -> Linked ts a -> Attribute t a

instance Has t (t:ts) where
  get :: Proxy t -> Linked (t:ts) a -> Attribute t a
  get :: Proxy t -> Linked (t : ts) a -> Attribute t a
get Proxy t
_ (Linked (lv, _) a
_) = Attribute t a
lv

instance {-# OVERLAPPABLE #-} Has t ts => Has t (t':ts) where
  get :: Proxy t -> Linked (t':ts) a -> Attribute t a
  get :: Proxy t -> Linked (t' : ts) a -> Attribute t a
get Proxy t
_ Linked (t' : ts) a
l = Proxy t -> Linked ts a -> Attribute t a
forall k (t :: k) (ts :: [*]) a.
Has t ts =>
Proxy t -> Linked ts a -> Attribute t a
get (Proxy t
forall k (t :: k). Proxy t
Proxy @t) (Linked (t' : ts) a -> Linked ts a
forall q (qs :: [*]) b. Linked (q : qs) b -> Linked qs b
rightLinked Linked (t' : ts) a
l)
    where
      rightLinked :: Linked (q:qs) b -> Linked qs b
      rightLinked :: Linked (q : qs) b -> Linked qs b
rightLinked (Linked (_, rv) b
a) = Attribute qs b -> b -> Linked qs b
forall (ts :: [*]) a. Attribute ts a -> a -> Linked ts a
Linked Attribute qs b
rv b
a

-- For better type errors
instance TypeError (MissingTrait t) => Has t '[] where
   get :: Proxy t -> Linked '[] a -> Attribute t a
get = Proxy t -> Linked '[] a -> Attribute t a
forall a. HasCallStack => a
undefined

-- | Type error for nicer UX of missing traits
type MissingTrait t = Text "The request doesn't have the trait ‘" :<>: ShowType t :<>: Text "’."
                      :$$: Text ""
                      :$$: Text "Did you use a wrong trait type?"
                      :$$: Text "For e.g., ‘PathVar \"foo\" Int’ instead of ‘PathVar \"foo\" String’?"
                      :$$: Text ""
                      :$$: Text "Or did you forget to apply an appropriate middleware?"
                      :$$: Text "For e.g. The trait ‘JSONRequestBody Foo’ can be used with ‘jsonRequestBody @Foo’ middleware."
                      :$$: Text ""


-- | Constraint that proves that all the traits in the list @ts@ are
-- also present in the list @qs@.
type family Have ts qs :: Constraint where
  Have '[]    qs = ()
  Have (t:ts) qs = (Has t qs, Have ts qs)