| Safe Haskell | None |
|---|---|
| Language | Haskell98 |
Web.Spock.Api
- data Endpoint (p :: [*]) (i :: Maybe *) (o :: *) where
- MethodGet :: (ToJSON o, FromJSON o) => Path p Open -> Endpoint p Nothing o
- MethodPost :: (ToJSON i, FromJSON i, ToJSON o, FromJSON o) => Proxy (i -> o) -> Path p Open -> Endpoint p (Just i) o
- MethodPut :: (ToJSON i, FromJSON i, ToJSON o, FromJSON o) => Proxy (i -> o) -> Path p Open -> Endpoint p (Just i) o
- data Proxy k (t :: k) :: forall k. k -> * = Proxy
- type family MaybeToList (a :: Maybe *) :: [*] where ...
- (<//>) :: Path as Open -> Path bs ps -> Path (Append as bs) ps
- var :: (Typeable * a, FromHttpApiData a) => Path ((:) * a ([] *)) Open
- data Path (as :: [*]) (pathState :: PathState) :: [*] -> PathState -> * where
- renderRoute :: AllHave ToHttpApiData as => Path as Open -> HVect as -> Text
- class Generic a
- class ToJSON a
- class FromJSON a
- class NFData a
- class Typeable k (a :: k)
Documentation
data Endpoint (p :: [*]) (i :: Maybe *) (o :: *) where #
Describes an endpoint with path parameters, an optional json body and a json response
Constructors
| MethodGet :: (ToJSON o, FromJSON o) => Path p Open -> Endpoint p Nothing o | |
| MethodPost :: (ToJSON i, FromJSON i, ToJSON o, FromJSON o) => Proxy (i -> o) -> Path p Open -> Endpoint p (Just i) o | |
| MethodPut :: (ToJSON i, FromJSON i, ToJSON o, FromJSON o) => Proxy (i -> o) -> Path p Open -> Endpoint p (Just i) o |
data Proxy k (t :: k) :: forall k. k -> * #
A concrete, poly-kinded proxy type
Constructors
| Proxy |
Instances
| Generic1 k (Proxy k) | |
| Monad (Proxy *) | Since: 4.7.0.0 |
| Functor (Proxy *) | Since: 4.7.0.0 |
| Applicative (Proxy *) | Since: 4.7.0.0 |
| ToJSON1 (Proxy *) | |
| FromJSON1 (Proxy *) | |
| Alternative (Proxy *) | Since: 4.9.0.0 |
| MonadPlus (Proxy *) | Since: 4.9.0.0 |
| NFData1 (Proxy *) | Since: 1.4.3.0 |
| Bounded (Proxy k t) | |
| Enum (Proxy k s) | Since: 4.7.0.0 |
| Eq (Proxy k s) | Since: 4.7.0.0 |
| Ord (Proxy k s) | Since: 4.7.0.0 |
| Read (Proxy k s) | Since: 4.7.0.0 |
| Show (Proxy k s) | Since: 4.7.0.0 |
| Ix (Proxy k s) | Since: 4.7.0.0 |
| Generic (Proxy k t) | |
| Monoid (Proxy k s) | Since: 4.7.0.0 |
| ToJSON (Proxy k a) | |
| FromJSON (Proxy k a) | |
| NFData (Proxy k a) | Since: 1.4.0.0 |
| type Rep1 k (Proxy k) | |
| type Rep (Proxy k t) | |
type family MaybeToList (a :: Maybe *) :: [*] where ... #
Equations
| MaybeToList (Just * r) = (:) * r ([] *) | |
| MaybeToList (Nothing *) = [] * |
data Path (as :: [*]) (pathState :: PathState) :: [*] -> PathState -> * where #
renderRoute :: AllHave ToHttpApiData as => Path as Open -> HVect as -> Text #
Representable types of kind *. This class is derivable in GHC with the DeriveGeneric flag on.
Instances
| Generic Bool | |
| Generic Ordering | |
| Generic () | |
| Generic Fixity | |
| Generic Associativity | |
| Generic SourceUnpackedness | |
| Generic SourceStrictness | |
| Generic DecidedStrictness | |
| Generic [a] | |
| Generic (Maybe a) | |
| Generic (Par1 p) | |
| Generic (Either a b) | |
| Generic (V1 k p) | |
| Generic (U1 k p) | |
| Generic (a, b) | |
| Generic (Proxy k t) | |
| Generic (Rec1 k f p) | |
| Generic (URec k (Ptr ()) p) | |
| Generic (URec k Char p) | |
| Generic (URec k Double p) | |
| Generic (URec k Float p) | |
| Generic (URec k Int p) | |
| Generic (URec k Word p) | |
| Generic (a, b, c) | |
| Generic (K1 k i c p) | |
| Generic ((:+:) k f g p) | |
| Generic ((:*:) k f g p) | |
| Generic (a, b, c, d) | |
| Generic (M1 k i c f p) | |
| Generic ((:.:) k2 k1 f g p) | |
| Generic (a, b, c, d, e) | |
| Generic (a, b, c, d, e, f) | |
| Generic (a, b, c, d, e, f, g) | |
A type that can be converted to JSON.
Instances in general must specify toJSON and should (but don't need
to) specify toEncoding.
An example type and instance:
-- Allow ourselves to writeTextliterals. {-# LANGUAGE OverloadedStrings #-} data Coord = Coord { x :: Double, y :: Double } instanceToJSONCoord wheretoJSON(Coord x y) =object["x".=x, "y".=y]toEncoding(Coord x y) =pairs("x".=x<>"y".=y)
Instead of manually writing your ToJSON instance, there are two options
to do it automatically:
- Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time. The generated instance is optimized for your type so it will probably be more efficient than the following option.
- The compiler can provide a default generic implementation for
toJSON.
To use the second, simply add a deriving clause to your
datatype and declare a GenericToJSON instance. If you require nothing other than
defaultOptions, it is sufficient to write (and this is the only
alternative where the default toJSON implementation is sufficient):
{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics
data Coord = Coord { x :: Double, y :: Double } deriving Generic
instance ToJSON Coord where
toEncoding = genericToEncoding defaultOptions
If on the other hand you wish to customize the generic decoding, you have to implement both methods:
customOptions =defaultOptions{fieldLabelModifier=maptoUpper} instanceToJSONCoord wheretoJSON=genericToJSONcustomOptionstoEncoding=genericToEncodingcustomOptions
Previous versions of this library only had the toJSON method. Adding
toEncoding had to reasons:
- toEncoding is more efficient for the common case that the output of
toJSONis directly serialized to aByteString. Further, expressing either method in terms of the other would be non-optimal. - The choice of defaults allows a smooth transition for existing users:
Existing instances that do not define
toEncodingstill compile and have the correct semantics. This is ensured by making the default implementation oftoEncodingusetoJSON. This produces correct results, but since it performs an intermediate conversion to aValue, it will be less efficient than directly emitting anEncoding. (this also means that specifying nothing more thaninstance ToJSON Coordwould be sufficient as a generically decoding instance, but there probably exists no good reason to not specifytoEncodingin new instances.)
Instances
A type that can be converted from JSON, with the possibility of failure.
In many cases, you can get the compiler to generate parsing code for you (see below). To begin, let's cover writing an instance by hand.
There are various reasons a conversion could fail. For example, an
Object could be missing a required key, an Array could be of
the wrong size, or a value could be of an incompatible type.
The basic ways to signal a failed conversion are as follows:
emptyandmzerowork, but are terse and uninformative;failyields a custom error message;typeMismatchproduces an informative message for cases when the value encountered is not of the expected type.
An example type and instance using typeMismatch:
-- Allow ourselves to writeTextliterals. {-# LANGUAGE OverloadedStrings #-} data Coord = Coord { x :: Double, y :: Double } instanceFromJSONCoord whereparseJSON(Objectv) = Coord<$>v.:"x"<*>v.:"y" -- We do not expect a non-Objectvalue here. -- We could usemzeroto fail, buttypeMismatch-- gives a much more informative error message.parseJSONinvalid =typeMismatch"Coord" invalid
For this common case of only being concerned with a single
type of JSON value, the functions withObject, withNumber, etc.
are provided. Their use is to be preferred when possible, since
they are more terse. Using withObject, we can rewrite the above instance
(assuming the same language extension and data type) as:
instanceFromJSONCoord whereparseJSON=withObject"Coord" $ \v -> Coord<$>v.:"x"<*>v.:"y"
Instead of manually writing your FromJSON instance, there are two options
to do it automatically:
- Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time. The generated instance is optimized for your type so it will probably be more efficient than the following option.
- The compiler can provide a default generic implementation for
parseJSON.
To use the second, simply add a deriving clause to your
datatype and declare a GenericFromJSON instance for your datatype without giving
a definition for parseJSON.
For example, the previous example can be simplified to just:
{-# LANGUAGE DeriveGeneric #-}
import GHC.Generics
data Coord = Coord { x :: Double, y :: Double } deriving Generic
instance FromJSON Coord
The default implementation will be equivalent to
parseJSON = ; If you need different
options, you can customize the generic decoding by defining:genericParseJSON defaultOptions
customOptions =defaultOptions{fieldLabelModifier=maptoUpper} instanceFromJSONCoord whereparseJSON=genericParseJSONcustomOptions
Instances
| FromJSON Bool | |
| FromJSON Char | |
| FromJSON Double | |
| FromJSON Float | |
| FromJSON Int | |
| FromJSON Int8 | |
| FromJSON Int16 | |
| FromJSON Int32 | |
| FromJSON Int64 | |
| FromJSON Integer | WARNING: Only parse Integers from trusted input since an
attacker could easily fill up the memory of the target system by
specifying a scientific number with a big exponent like
|
| FromJSON Natural | |
| FromJSON Ordering | |
| FromJSON Word | |
| FromJSON Word8 | |
| FromJSON Word16 | |
| FromJSON Word32 | |
| FromJSON Word64 | |
| FromJSON () | |
| FromJSON Scientific | |
| FromJSON Number | |
| FromJSON Text | |
| FromJSON UTCTime | |
| FromJSON Value | |
| FromJSON DotNetTime | |
| FromJSON Text | |
| FromJSON Version | |
| FromJSON CTime | |
| FromJSON IntSet | |
| FromJSON ZonedTime | Supported string formats:
The first space may instead be a |
| FromJSON LocalTime | |
| FromJSON TimeOfDay | |
| FromJSON NominalDiffTime | WARNING: Only parse lengths of time from trusted input
since an attacker could easily fill up the memory of the target
system by specifying a scientific number with a big exponent like
|
| FromJSON DiffTime | WARNING: Only parse lengths of time from trusted input
since an attacker could easily fill up the memory of the target
system by specifying a scientific number with a big exponent like
|
| FromJSON Day | |
| FromJSON UUID | |
| FromJSON a => FromJSON [a] | |
| FromJSON a => FromJSON (Maybe a) | |
| (FromJSON a, Integral a) => FromJSON (Ratio a) | |
| HasResolution a => FromJSON (Fixed a) | WARNING: Only parse fixed-precision numbers from trusted input
since an attacker could easily fill up the memory of the target
system by specifying a scientific number with a big exponent like
|
| FromJSON a => FromJSON (Min a) | |
| FromJSON a => FromJSON (Max a) | |
| FromJSON a => FromJSON (First a) | |
| FromJSON a => FromJSON (Last a) | |
| FromJSON a => FromJSON (WrappedMonoid a) | |
| FromJSON a => FromJSON (Option a) | |
| FromJSON a => FromJSON (NonEmpty a) | |
| FromJSON a => FromJSON (Identity a) | |
| FromJSON a => FromJSON (Dual a) | |
| FromJSON a => FromJSON (First a) | |
| FromJSON a => FromJSON (Last a) | |
| FromJSON a => FromJSON (IntMap a) | |
| FromJSON v => FromJSON (Tree v) | |
| FromJSON a => FromJSON (Seq a) | |
| (Ord a, FromJSON a) => FromJSON (Set a) | |
| FromJSON a => FromJSON (DList a) | |
| (Eq a, Hashable a, FromJSON a) => FromJSON (HashSet a) | |
| (Vector Vector a, FromJSON a) => FromJSON (Vector a) | |
| (Storable a, FromJSON a) => FromJSON (Vector a) | |
| (Prim a, FromJSON a) => FromJSON (Vector a) | |
| FromJSON a => FromJSON (Vector a) | |
| (FromJSON a, FromJSON b) => FromJSON (Either a b) | |
| (FromJSON a, FromJSON b) => FromJSON (a, b) | |
| (FromJSON v, FromJSONKey k, Eq k, Hashable k) => FromJSON (HashMap k v) | |
| (FromJSONKey k, Ord k, FromJSON v) => FromJSON (Map k v) | |
| FromJSON (Proxy k a) | |
| (FromJSON a, FromJSON b, FromJSON c) => FromJSON (a, b, c) | |
| FromJSON a => FromJSON (Const k a b) | |
| FromJSON b => FromJSON (Tagged k a b) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d) => FromJSON (a, b, c, d) | |
| (FromJSON1 f, FromJSON1 g, FromJSON a) => FromJSON (Product * f g a) | |
| (FromJSON1 f, FromJSON1 g, FromJSON a) => FromJSON (Sum * f g a) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e) => FromJSON (a, b, c, d, e) | |
| (FromJSON1 f, FromJSON1 g, FromJSON a) => FromJSON (Compose * * f g a) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f) => FromJSON (a, b, c, d, e, f) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g) => FromJSON (a, b, c, d, e, f, g) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h) => FromJSON (a, b, c, d, e, f, g, h) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i) => FromJSON (a, b, c, d, e, f, g, h, i) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j) => FromJSON (a, b, c, d, e, f, g, h, i, j) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k) => FromJSON (a, b, c, d, e, f, g, h, i, j, k) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k, FromJSON l) => FromJSON (a, b, c, d, e, f, g, h, i, j, k, l) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k, FromJSON l, FromJSON m) => FromJSON (a, b, c, d, e, f, g, h, i, j, k, l, m) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k, FromJSON l, FromJSON m, FromJSON n) => FromJSON (a, b, c, d, e, f, g, h, i, j, k, l, m, n) | |
| (FromJSON a, FromJSON b, FromJSON c, FromJSON d, FromJSON e, FromJSON f, FromJSON g, FromJSON h, FromJSON i, FromJSON j, FromJSON k, FromJSON l, FromJSON m, FromJSON n, FromJSON o) => FromJSON (a, b, c, d, e, f, g, h, i, j, k, l, m, n, o) | |
A class of types that can be fully evaluated.
Since: 1.1.0.0
Instances
| NFData Bool | |
| NFData Char | |
| NFData Double | |
| NFData Float | |
| NFData Int | |
| NFData Int8 | |
| NFData Int16 | |
| NFData Int32 | |
| NFData Int64 | |
| NFData Integer | |
| NFData Natural | Since: 1.4.0.0 |
| NFData Ordering | |
| NFData Word | |
| NFData Word8 | |
| NFData Word16 | |
| NFData Word32 | |
| NFData Word64 | |
| NFData CallStack | Since: 1.4.2.0 |
| NFData () | |
| NFData TyCon | NOTE: Only defined for Since: 1.4.0.0 |
| NFData Void | Since: 1.4.0.0 |
| NFData Unique | Since: 1.4.0.0 |
| NFData Version | Since: 1.3.0.0 |
| NFData ThreadId | Since: 1.4.0.0 |
| NFData ExitCode | Since: 1.4.2.0 |
| NFData TypeRep | NOTE: Only defined for Since: 1.4.0.0 |
| NFData All | Since: 1.4.0.0 |
| NFData Any | Since: 1.4.0.0 |
| NFData CChar | Since: 1.4.0.0 |
| NFData CSChar | Since: 1.4.0.0 |
| NFData CUChar | Since: 1.4.0.0 |
| NFData CShort | Since: 1.4.0.0 |
| NFData CUShort | Since: 1.4.0.0 |
| NFData CInt | Since: 1.4.0.0 |
| NFData CUInt | Since: 1.4.0.0 |
| NFData CLong | Since: 1.4.0.0 |
| NFData CULong | Since: 1.4.0.0 |
| NFData CLLong | Since: 1.4.0.0 |
| NFData CULLong | Since: 1.4.0.0 |
| NFData CBool | Since: 1.4.3.0 |
| NFData CFloat | Since: 1.4.0.0 |
| NFData CDouble | Since: 1.4.0.0 |
| NFData CPtrdiff | Since: 1.4.0.0 |
| NFData CSize | Since: 1.4.0.0 |
| NFData CWchar | Since: 1.4.0.0 |
| NFData CSigAtomic | Since: 1.4.0.0 |
| NFData CClock | Since: 1.4.0.0 |
| NFData CTime | Since: 1.4.0.0 |
| NFData CUSeconds | Since: 1.4.0.0 |
| NFData CSUSeconds | Since: 1.4.0.0 |
| NFData CFile | Since: 1.4.0.0 |
| NFData CFpos | Since: 1.4.0.0 |
| NFData CJmpBuf | Since: 1.4.0.0 |
| NFData CIntPtr | Since: 1.4.0.0 |
| NFData CUIntPtr | Since: 1.4.0.0 |
| NFData CIntMax | Since: 1.4.0.0 |
| NFData CUIntMax | Since: 1.4.0.0 |
| NFData Fingerprint | Since: 1.4.0.0 |
| NFData SrcLoc | Since: 1.4.2.0 |
| NFData ZonedTime | |
| NFData LocalTime | |
| NFData a => NFData [a] | |
| NFData a => NFData (Maybe a) | |
| NFData a => NFData (Ratio a) | |
| NFData (Ptr a) | Since: 1.4.2.0 |
| NFData (FunPtr a) | Since: 1.4.2.0 |
| NFData a => NFData (Complex a) | |
| NFData (Fixed a) | Since: 1.3.0.0 |
| NFData a => NFData (Min a) | Since: 1.4.2.0 |
| NFData a => NFData (Max a) | Since: 1.4.2.0 |
| NFData a => NFData (First a) | Since: 1.4.2.0 |
| NFData a => NFData (Last a) | Since: 1.4.2.0 |
| NFData m => NFData (WrappedMonoid m) | Since: 1.4.2.0 |
| NFData a => NFData (Option a) | Since: 1.4.2.0 |
| NFData a => NFData (NonEmpty a) | Since: 1.4.2.0 |
| NFData (StableName a) | Since: 1.4.0.0 |
| NFData a => NFData (ZipList a) | Since: 1.4.0.0 |
| NFData a => NFData (Identity a) | Since: 1.4.0.0 |
| NFData (IORef a) | NOTE: Only strict in the reference and not the referenced value. Since: 1.4.2.0 |
| NFData a => NFData (Dual a) | Since: 1.4.0.0 |
| NFData a => NFData (Sum a) | Since: 1.4.0.0 |
| NFData a => NFData (Product a) | Since: 1.4.0.0 |
| NFData a => NFData (First a) | Since: 1.4.0.0 |
| NFData a => NFData (Last a) | Since: 1.4.0.0 |
| NFData a => NFData (Down a) | Since: 1.4.0.0 |
| NFData (MVar a) | NOTE: Only strict in the reference and not the referenced value. Since: 1.4.2.0 |
| NFData (a -> b) | This instance is for convenience and consistency with Since: 1.3.0.0 |
| (NFData a, NFData b) => NFData (Either a b) | |
| (NFData a, NFData b) => NFData (a, b) | |
| (NFData a, NFData b) => NFData (Array a b) | |
| (NFData a, NFData b) => NFData (Arg a b) | Since: 1.4.2.0 |
| NFData (Proxy k a) | Since: 1.4.0.0 |
| NFData (STRef s a) | NOTE: Only strict in the reference and not the referenced value. Since: 1.4.2.0 |
| (NFData a1, NFData a2, NFData a3) => NFData (a1, a2, a3) | |
| NFData a => NFData (Const k a b) | Since: 1.4.0.0 |
| NFData ((:~:) k a b) | Since: 1.4.3.0 |
| (NFData a1, NFData a2, NFData a3, NFData a4) => NFData (a1, a2, a3, a4) | |
| (NFData1 f, NFData1 g, NFData a) => NFData (Product * f g a) | Since: 1.4.3.0 |
| (NFData1 f, NFData1 g, NFData a) => NFData (Sum * f g a) | Since: 1.4.3.0 |
| NFData ((:~~:) k1 k2 a b) | Since: 1.4.3.0 |
| (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5) => NFData (a1, a2, a3, a4, a5) | |
| (NFData1 f, NFData1 g, NFData a) => NFData (Compose * * f g a) | Since: 1.4.3.0 |
| (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5, NFData a6) => NFData (a1, a2, a3, a4, a5, a6) | |
| (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5, NFData a6, NFData a7) => NFData (a1, a2, a3, a4, a5, a6, a7) | |
| (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5, NFData a6, NFData a7, NFData a8) => NFData (a1, a2, a3, a4, a5, a6, a7, a8) | |
| (NFData a1, NFData a2, NFData a3, NFData a4, NFData a5, NFData a6, NFData a7, NFData a8, NFData a9) => NFData (a1, a2, a3, a4, a5, a6, a7, a8, a9) | |