-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Another Haskell web framework for rapid development
--
-- API definition DSL for Spock web framework
@package Spock-api
@version 0.14.0.0
module Web.Spock.Api
-- | Describes an endpoint with path parameters, an optional json body and
-- a json response
data Endpoint (p :: [*]) (i :: Maybe *) (o :: *)
[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
-- | Proxy is a type that holds no data, but has a phantom parameter
-- of arbitrary type (or even kind). Its use is to provide type
-- information, even though there is no value available of that type (or
-- it may be too costly to create one).
--
-- Historically, Proxy :: Proxy a is a safer
-- alternative to the undefined :: a idiom.
--
--
-- >>> Proxy :: Proxy (Void, Int -> Int)
-- Proxy
--
--
-- Proxy can even hold types of higher kinds,
--
--
-- >>> Proxy :: Proxy Either
-- Proxy
--
--
--
-- >>> Proxy :: Proxy Functor
-- Proxy
--
--
--
-- >>> Proxy :: Proxy complicatedStructure
-- Proxy
--
data Proxy (t :: k)
Proxy :: Proxy (t :: k)
type family MaybeToList (a :: Maybe Type) :: [Type]
() :: Path as 'Open -> Path bs ps -> Path (Append as bs) ps
-- | A route parameter
var :: (Typeable a, FromHttpApiData a) => Path '[a] 'Open
data Path (as :: [Type]) (pathState :: PathState)
[Empty] :: Path ('[] :: [Type]) 'Open
[StaticCons] :: forall (as :: [Type]) (pathState :: PathState). Text -> Path as pathState -> Path as pathState
[VarCons] :: forall a (as1 :: [Type]) (pathState :: PathState). (FromHttpApiData a, Typeable a) => Path as1 pathState -> Path (a : as1) pathState
[Wildcard] :: forall (as1 :: [Type]). Path as1 'Open -> Path (Text : as1) 'Closed
renderRoute :: forall (as :: [Type]). AllHave ToHttpApiData as => Path as 'Open -> HVect as -> Text
-- | Representable types of kind *. This class is derivable in GHC
-- with the DeriveGeneric flag on.
--
-- A Generic instance must satisfy the following laws:
--
--
-- from . to ≡ id
-- to . from ≡ id
--
class Generic a
-- | 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 write Text literals.
-- {-# LANGUAGE OverloadedStrings #-}
--
-- data Coord = Coord { x :: Double, y :: Double }
--
-- instance ToJSON Coord where
-- toJSON (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 Generic
-- clause to your datatype and declare a ToJSON 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 = map toUpper
-- }
--
-- instance ToJSON Coord where
-- toJSON = genericToJSON customOptions
-- toEncoding = genericToEncoding customOptions
--
--
-- Previous versions of this library only had the toJSON method.
-- Adding toEncoding had two reasons:
--
--
-- - toEncoding is more efficient for the common case that the output
-- of toJSON is directly serialized to a ByteString.
-- 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 toEncoding still
-- compile and have the correct semantics. This is ensured by making the
-- default implementation of toEncoding use toJSON. This
-- produces correct results, but since it performs an intermediate
-- conversion to a Value, it will be less efficient than directly
-- emitting an Encoding. (this also means that specifying nothing
-- more than instance ToJSON Coord would be sufficient as a
-- generically decoding instance, but there probably exists no good
-- reason to not specify toEncoding in new instances.)
--
class ToJSON a
-- | 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:
--
--
-- - fail yields a custom error message: it is the recommended
-- way of reporting a failure;
-- - empty (or mzero) is uninformative: use it when the
-- error is meant to be caught by some (<|>);
-- - typeMismatch can be used to report a failure when the
-- encountered value is not of the expected JSON type; unexpected
-- is an appropriate alternative when more than one type may be expected,
-- or to keep the expected type implicit.
--
--
-- prependFailure (or modifyFailure) add more information
-- to a parser's error messages.
--
-- An example type and instance using typeMismatch and
-- prependFailure:
--
--
-- -- Allow ourselves to write Text literals.
-- {-# LANGUAGE OverloadedStrings #-}
--
-- data Coord = Coord { x :: Double, y :: Double }
--
-- instance FromJSON Coord where
-- parseJSON (Object v) = Coord
-- <$> v .: "x"
-- <*> v .: "y"
--
-- -- We do not expect a non-Object value here.
-- -- We could use empty to fail, but typeMismatch
-- -- gives a much more informative error message.
-- parseJSON invalid =
-- prependFailure "parsing Coord failed, "
-- (typeMismatch "Object" invalid)
--
--
-- For this common case of only being concerned with a single type of
-- JSON value, the functions withObject, withScientific,
-- 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:
--
--
-- instance FromJSON Coord where
-- parseJSON = 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 Generic
-- clause to your datatype and declare a FromJSON 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 =
-- genericParseJSON defaultOptions; if you need
-- different options, you can customize the generic decoding by defining:
--
--
-- customOptions = defaultOptions
-- { fieldLabelModifier = map toUpper
-- }
--
-- instance FromJSON Coord where
-- parseJSON = genericParseJSON customOptions
--
class FromJSON a
-- | A class of types that can be fully evaluated.
class NFData a
-- | The class Typeable allows a concrete representation of a type
-- to be calculated.
class Typeable (a :: k)