webgear-core-1.0.1: Composable, type-safe library to build HTTP APIs
Safe HaskellNone
LanguageHaskell2010

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 link 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.

Synopsis

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

Instances details
Trait Method Request Source # 
Instance details

Defined in WebGear.Core.Trait.Method

Associated Types

type Attribute Method Request Source #

Trait PathEnd Request Source # 
Instance details

Defined in WebGear.Core.Trait.Path

Associated Types

type Attribute PathEnd Request Source #

Trait Path Request Source # 
Instance details

Defined in WebGear.Core.Trait.Path

Associated Types

type Attribute Path Request Source #

Trait Status Response Source # 
Instance details

Defined in WebGear.Core.Trait.Status

Associated Types

type Attribute Status Response Source #

Trait (JSONBody t) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Body

Associated Types

type Attribute (JSONBody t) Response Source #

Trait (JSONBody t) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Body

Associated Types

type Attribute (JSONBody t) Request Source #

Trait (Body t) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Body

Associated Types

type Attribute (Body t) Response Source #

Trait (Body t) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Body

Associated Types

type Attribute (Body t) Request Source #

Trait (PathVar tag val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Path

Associated Types

type Attribute (PathVar tag val) Request Source #

Trait (Header 'Required 'Strict name val) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Required 'Strict name val) Response Source #

Trait (Header 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Required 'Strict name val) Request Source #

Trait (Header 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Required 'Lenient name val) Request Source #

Trait (Header 'Optional 'Strict name val) Response Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Optional 'Strict name val) Response Source #

Trait (Header 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Optional 'Strict name val) Request Source #

Trait (Header 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Attribute (Header 'Optional 'Lenient name val) Request Source #

Trait (QueryParam 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.QueryParam

Associated Types

type Attribute (QueryParam 'Required 'Strict name val) Request Source #

Trait (QueryParam 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.QueryParam

Associated Types

type Attribute (QueryParam 'Required 'Lenient name val) Request Source #

Trait (QueryParam 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.QueryParam

Associated Types

type Attribute (QueryParam 'Optional 'Strict name val) Request Source #

Trait (QueryParam 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.QueryParam

Associated Types

type Attribute (QueryParam 'Optional 'Lenient name val) Request Source #

Trait (JWTAuth' 'Required scheme m e a) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Auth.JWT

Associated Types

type Attribute (JWTAuth' 'Required scheme m e a) Request Source #

Trait (JWTAuth' 'Optional scheme m e a) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Auth.JWT

Associated Types

type Attribute (JWTAuth' 'Optional scheme m e a) Request Source #

Trait (BasicAuth' 'Required scheme m e a) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Auth.Basic

Associated Types

type Attribute (BasicAuth' 'Required scheme m e a) Request Source #

Trait (BasicAuth' 'Optional scheme m e a) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Auth.Basic

Associated Types

type Attribute (BasicAuth' 'Optional scheme m e a) Request Source #

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

Instances details
TraitAbsence Method Request Source # 
Instance details

Defined in WebGear.Core.Trait.Method

Associated Types

type Absence Method Request Source #

TraitAbsence PathEnd Request Source # 
Instance details

Defined in WebGear.Core.Trait.Path

Associated Types

type Absence PathEnd Request Source #

TraitAbsence Path Request Source # 
Instance details

Defined in WebGear.Core.Trait.Path

Associated Types

type Absence Path Request Source #

TraitAbsence (JSONBody t) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Body

Associated Types

type Absence (JSONBody t) Request Source #

TraitAbsence (Body t) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Body

Associated Types

type Absence (Body t) Request Source #

TraitAbsence (PathVar tag val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Path

Associated Types

type Absence (PathVar tag val) Request Source #

TraitAbsence (Header 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Absence (Header 'Required 'Strict name val) Request Source #

TraitAbsence (Header 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Absence (Header 'Required 'Lenient name val) Request Source #

TraitAbsence (Header 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Absence (Header 'Optional 'Strict name val) Request Source #

TraitAbsence (Header 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Header

Associated Types

type Absence (Header 'Optional 'Lenient name val) Request Source #

TraitAbsence (QueryParam 'Required 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.QueryParam

Associated Types

type Absence (QueryParam 'Required 'Strict name val) Request Source #

TraitAbsence (QueryParam 'Required 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.QueryParam

Associated Types

type Absence (QueryParam 'Required 'Lenient name val) Request Source #

TraitAbsence (QueryParam 'Optional 'Strict name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.QueryParam

Associated Types

type Absence (QueryParam 'Optional 'Strict name val) Request Source #

TraitAbsence (QueryParam 'Optional 'Lenient name val) Request Source # 
Instance details

Defined in WebGear.Core.Trait.QueryParam

Associated Types

type Absence (QueryParam 'Optional 'Lenient name val) Request Source #

TraitAbsence (JWTAuth' 'Required scheme m e a) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Auth.JWT

Associated Types

type Absence (JWTAuth' 'Required scheme m e a) Request Source #

TraitAbsence (JWTAuth' 'Optional scheme m e a) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Auth.JWT

Associated Types

type Absence (JWTAuth' 'Optional scheme m e a) Request Source #

TraitAbsence (BasicAuth' 'Required scheme m e a) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Auth.Basic

Associated Types

type Absence (BasicAuth' 'Required scheme m e a) Request Source #

TraitAbsence (BasicAuth' 'Optional scheme m e a) Request Source # 
Instance details

Defined in WebGear.Core.Trait.Auth.Basic

Associated Types

type Absence (BasicAuth' 'Optional scheme m e a) Request Source #

class (Arrow h, TraitAbsence t a) => Get h t a where Source #

Extract trait attributes from a value.

Methods

getTrait Source #

Arguments

:: t

The trait to extract

-> h (Linked ts a) (Either (Absence t a) (Attribute t a))

Arrow that extracts the trait and can possibly fail

Attempt to deduce the trait attribute from the value a.

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].

Equations

Gets h '[] a = () 
Gets h (t ': ts) a = (Get h t a, Gets h ts a) 

data Linked (ts :: [Type]) a Source #

A value linked with a type-level list of traits.

class (Arrow h, Trait t a) => Set h (t :: Type) a where Source #

Set a trait attribute on a value

Methods

setTrait Source #

Arguments

:: t

The trait to set

-> (Linked ts a -> a -> Attribute t a -> Linked (t ': ts) a)

A function to generate a linked value. This function must be called by the setTrait implementation to generate a linked value.

-> h (Linked ts a, Attribute t a) (Linked (t ': ts) a)

An arrow that attches a new trait attribute to a value linked with other traits

Set a trait attribute t on the value a.

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].

Equations

Sets h '[] a = () 
Sets h (t ': ts) a = (Set h t a, Sets h ts a) 

Linking values with attributes

linkzero :: a -> Linked '[] a Source #

Wrap a value with an empty list of traits.

linkminus :: Linked (t ': ts) a -> Linked ts a Source #

Forget the head trait

unlink :: Linked ts a -> a Source #

Retrive the value from a linked value

probe :: forall t ts h a. Get h t a => t -> h (Linked ts a) (Either (Absence t a) (Linked (t ': ts) a)) Source #

Attempt to link an additional trait with an already linked value. This can fail indicating an Absence of the trait.

plant :: forall t ts h a. Set h t a => t -> h (Linked ts a, Attribute t a) (Linked (t ': ts) a) Source #

Set a trait attribute on linked value to produce another linked value

Retrive trait attributes from linked values

class HasTrait t ts where Source #

Constraint that proves that the trait t is present in the list of traits ts.

Methods

from :: Linked ts a -> Tagged t (Attribute t a) Source #

Get the attribute associated with t from a linked value. See also: pick.

Instances

Instances details
(TypeError (MissingTrait t) :: Constraint) => HasTrait t ('[] :: [Type]) Source # 
Instance details

Defined in WebGear.Core.Trait

Methods

from :: Linked '[] a -> Tagged t (Attribute t a) Source #

HasTrait t ts => HasTrait t (t' ': ts) Source # 
Instance details

Defined in WebGear.Core.Trait

Methods

from :: Linked (t' ': ts) a -> Tagged t (Attribute t a) Source #

HasTrait t (t ': ts) Source # 
Instance details

Defined in WebGear.Core.Trait

Methods

from :: Linked (t ': ts) a -> Tagged t (Attribute t a) Source #

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) 

pick :: Tagged t a -> a Source #

Retrieve a trait.

pick is used along with from to retrieve an attribute from a linked value:

pick @t $ from val

type MissingTrait t = ((((((((Text "The request doesn't have the trait \8216" :<>: ShowType t) :<>: Text "\8217.") :$$: Text "") :$$: Text "Did you use a wrong trait type?") :$$: Text "For e.g., \8216QueryParam \"foo\" Int\8217 instead of \8216QueryParam \"foo\" String\8217?") :$$: Text "") :$$: Text "Or did you forget to apply an appropriate middleware?") :$$: Text "For e.g. The trait \8216JSONBody t\8217 can be used with \8216jsonRequestBody @t\8217 middleware.") :$$: Text "" Source #

Type error for nicer UX of missing traits