| Safe Haskell | Safe-Inferred |
|---|---|
| Language | Haskell2010 |
WebGear.Core.Trait
Description
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 associate attributes with values in a type-safe manner.
Traits are somewhat similar to refinement types, but allow arbitrary attributes to be associated with a value instead of only a predicate.
A value a associated with traits ts is referred to as a witnessed
value, represented by the type a ` where With` tsts is a
type-level list. You can extract a trait attribute from a witnessed
value with:
pick@t (fromwitnessedValue)
The above expression will result in a compile-time error if t is
not present in the type-level list of the witnessed value's type.
You can create a witnessed value in a number of ways:
First, you can use wzero to lift a regular value to a witnessed
value with no associated traits.
Second, you can use probe to search for the presence of a trait and
add it to the witnessed value; this will adjust the type-level list
accordingly. This is used in cases where the regular value already
contains the trait attribute which can be extracted using the Get
typeclass.
Third, you can use plant to add a trait attribute to a witnessed
value, thereby extending its type-level list with one more
trait. This is used in cases where you want to modify the witnessed
value. This operation requires an implementation of the Set
typeclass.
Synopsis
- class Trait (t :: Type) a where
- class Trait t a => TraitAbsence t a where
- type family Prerequisite (t :: Type) (ts :: [Type]) (a :: Type) :: Constraint
- class (Arrow h, TraitAbsence t a) => Get h t a where
- type family Gets h ts a :: Constraint where ...
- class (Arrow h, Trait t a) => Set h (t :: Type) a where
- type family Sets h ts a :: Constraint where ...
- data With a (ts :: [Type])
- wzero :: a -> a `With` '[]
- wminus :: (a `With` (t : ts)) -> a `With` ts
- unwitness :: With a ts -> a
- probe :: forall t ts h a. (Get h t a, Prerequisite t ts a) => t -> h (a `With` ts) (Either (Absence t a) (a `With` (t : ts)))
- plant :: forall t ts h a. Set h t a => t -> h (a `With` ts, Attribute t a) (a `With` (t : ts))
- class HasTrait t ts where
- type family HaveTraits ts qs :: Constraint where ...
- pick :: Tagged t a -> a
- type MissingTrait t = ((((((((Text "The value doesn't have the \8216" :<>: ShowType t) :<>: Text "\8217 trait.") :$$: Text "") :$$: Text "Did you forget to apply an appropriate middleware?") :$$: Text "For e.g. The trait \8216Body JSON t\8217 requires \8216requestBody @t JSON\8217 middleware.") :$$: Text "") :$$: Text "or did you use a wrong trait type?") :$$: Text "For e.g., \8216RequiredQueryParam \"foo\" Int\8217 instead of \8216RequiredQueryParam \"foo\" String\8217?") :$$: Text ""
Core Types
class Trait (t :: Type) a Source #
A trait is an attribute t associated with a value a.
Associated Types
type Attribute t a :: Type Source #
Type of the associated attribute when the trait holds for a value
Instances
class Trait t a => TraitAbsence t a Source #
A trait t that can be retrieved from a but could be absent.
Associated Types
type Absence t a :: Type Source #
Type that indicates that the trait does not exist for a value. This could be an error message, exception etc.
Instances
type family Prerequisite (t :: Type) (ts :: [Type]) (a :: Type) :: Constraint Source #
Indicates the constraints a trait depends upon as a
prerequisite. This is used to assert that a trait t can be
extracted from a value a only if one or more other traits are
present in the trait list ts associated with it.
If a trait does not depend on other traits this can be set to the
empty contraint ().
Instances
class (Arrow h, TraitAbsence t a) => Get h t a where Source #
Extract trait attributes from a value.
type family Gets h ts a :: Constraint where ... Source #
Gets h ts a is equivalent to (Get h t1 a, Get h t2 a, ..., Get
h tn a) where ts = [t1, t2, ..., tn].
class (Arrow h, Trait t a) => Set h (t :: Type) a where Source #
Associate a trait attribute on a value
Methods
Arguments
| :: t | The trait to set |
| -> ((a `With` ts) -> a -> Attribute t a -> a `With` (t : ts)) | A function to generate a witnessed value. This function must
be called by the |
| -> h (a `With` ts, Attribute t a) (a `With` (t : ts)) | An arrow that attaches a new trait attribute to a witnessed value. |
Set a trait attribute t on the value a `With` ts.
type family Sets h ts a :: Constraint where ... Source #
Sets h ts a is equivalent to (Set h t1 a, Set h t2 a, ..., Set
h tn a) where ts = [t1, t2, ..., tn].
data With a (ts :: [Type]) Source #
A value associated with a list of traits, referred to as a witnessed value. Typically, this is used as an infix type constructor:
a `With` ts
where a is a value and ts is a list of traits associated with
that value.
If t is a type present in the list of types ts, it is possible to
extract its attribute from a witnessed value:
let witnessedValue :: a `With` ts
witnessedValue = ...
let attr :: Attribute t a
attr = pick @t (from witnessedValue)
Associating values with attributes
probe :: forall t ts h a. (Get h t a, Prerequisite t ts a) => t -> h (a `With` ts) (Either (Absence t a) (a `With` (t : ts))) Source #
Attempt to witness an additional trait with a witnessed value. This
can fail indicating an Absence of the trait.
plant :: forall t ts h a. Set h t a => t -> h (a `With` ts, Attribute t a) (a `With` (t : ts)) Source #
Set a trait attribute on witnessed value to produce another witnessed value with the additional trait attached to it.
Retrieve trait attributes from witnessed values
class HasTrait t ts where Source #
Constraint that proves that the trait t is present in the list
of traits ts.
Methods
from :: (a `With` ts) -> Tagged t (Attribute t a) Source #
Get the attribute associated with t from a witnessed
value. See also: pick.
type family HaveTraits ts qs :: Constraint where ... Source #
Constraint that proves that all the traits in the list ts are
also present in the list qs.
Equations
| HaveTraits '[] qs = () | |
| HaveTraits (t : ts) qs = (HasTrait t qs, HaveTraits ts qs) |
type MissingTrait t = ((((((((Text "The value doesn't have the \8216" :<>: ShowType t) :<>: Text "\8217 trait.") :$$: Text "") :$$: Text "Did you forget to apply an appropriate middleware?") :$$: Text "For e.g. The trait \8216Body JSON t\8217 requires \8216requestBody @t JSON\8217 middleware.") :$$: Text "") :$$: Text "or did you use a wrong trait type?") :$$: Text "For e.g., \8216RequiredQueryParam \"foo\" Int\8217 instead of \8216RequiredQueryParam \"foo\" String\8217?") :$$: Text "" Source #
Type error for nicer UX of missing traits