-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Tiny web application framework for WAI.
--   
--   Twain is tiny web application framework for WAI. It provides routing,
--   parameter parsing, and an either-like monad for composing responses.
@package twain
@version 2.1.0.0

module Web.Twain.Types

-- | <a>ResponderM</a> is an Either-like monad that can "short-circuit" and
--   return a response, or pass control to the next middleware. This
--   provides convenient branching with do notation for redirects, error
--   responses, etc.
data ResponderM a
ResponderM :: (Request -> IO (Either RouteAction (a, Request))) -> ResponderM a
data RouteAction
Respond :: Response -> RouteAction
Next :: RouteAction
data ParsedRequest
ParsedRequest :: Maybe ParsedBody -> [Param] -> [Param] -> [Param] -> ParsedRequest
[preqBody] :: ParsedRequest -> Maybe ParsedBody
[preqCookieParams] :: ParsedRequest -> [Param]
[preqPathParams] :: ParsedRequest -> [Param]
[preqQueryParams] :: ParsedRequest -> [Param]
data ResponderOptions
ResponderOptions :: Word64 -> ParseRequestBodyOptions -> ResponderOptions
[optsMaxBodySize] :: ResponderOptions -> Word64
[optsParseBody] :: ResponderOptions -> ParseRequestBodyOptions
data ParsedBody
FormBody :: ([Param], [File ByteString]) -> ParsedBody
JSONBody :: Value -> ParsedBody
data HttpError
HttpError :: Status -> String -> HttpError
type Param = (Text, Text)
data PathPattern
MatchPath :: (Request -> Maybe [Param]) -> PathPattern
matchPath :: Text -> Request -> Maybe [Param]

-- | Parse values from request parameters.
class ParsableParam a
parseParam :: ParsableParam a => Text -> Either HttpError a

-- | Default implementation parses comma-delimited lists.
parseParamList :: ParsableParam a => Text -> Either HttpError [a]

-- | Useful for creating <a>ParsableParam</a> instances for things that
--   already implement <a>Read</a>.
readEither :: Read a => Text -> Either HttpError a
instance GHC.Show.Show Web.Twain.Types.HttpError
instance GHC.Classes.Eq Web.Twain.Types.HttpError
instance Web.Twain.Types.ParsableParam Data.Text.Internal.Lazy.Text
instance Web.Twain.Types.ParsableParam Data.Text.Internal.Text
instance Web.Twain.Types.ParsableParam Data.ByteString.Internal.ByteString
instance Web.Twain.Types.ParsableParam Data.ByteString.Lazy.Internal.ByteString
instance Web.Twain.Types.ParsableParam GHC.Types.Char
instance Web.Twain.Types.ParsableParam ()
instance Web.Twain.Types.ParsableParam a => Web.Twain.Types.ParsableParam [a]
instance Web.Twain.Types.ParsableParam GHC.Types.Bool
instance Web.Twain.Types.ParsableParam GHC.Types.Double
instance Web.Twain.Types.ParsableParam GHC.Types.Float
instance Web.Twain.Types.ParsableParam GHC.Types.Int
instance Web.Twain.Types.ParsableParam GHC.Int.Int8
instance Web.Twain.Types.ParsableParam GHC.Int.Int16
instance Web.Twain.Types.ParsableParam GHC.Int.Int32
instance Web.Twain.Types.ParsableParam GHC.Int.Int64
instance Web.Twain.Types.ParsableParam GHC.Num.Integer.Integer
instance Web.Twain.Types.ParsableParam GHC.Types.Word
instance Web.Twain.Types.ParsableParam GHC.Word.Word8
instance Web.Twain.Types.ParsableParam GHC.Word.Word16
instance Web.Twain.Types.ParsableParam GHC.Word.Word32
instance Web.Twain.Types.ParsableParam GHC.Word.Word64
instance Web.Twain.Types.ParsableParam GHC.Num.Natural.Natural
instance Data.String.IsString Web.Twain.Types.PathPattern
instance GHC.Exception.Type.Exception Web.Twain.Types.HttpError
instance GHC.Base.Functor Web.Twain.Types.ResponderM
instance GHC.Base.Applicative Web.Twain.Types.ResponderM
instance GHC.Base.Monad Web.Twain.Types.ResponderM
instance Control.Monad.IO.Class.MonadIO Web.Twain.Types.ResponderM
instance Control.Monad.Catch.MonadThrow Web.Twain.Types.ResponderM
instance Control.Monad.Catch.MonadCatch Web.Twain.Types.ResponderM


-- | Twain is a tiny web application framework for WAI
--   
--   <ul>
--   <li><a>ResponderM</a> for composing responses with do notation.</li>
--   <li>Routing with path captures that decompose <a>ResponderM</a> into
--   middleware.</li>
--   <li>Parameter parsing for cookies, path, query, and body.</li>
--   <li>Helpers for redirects, headers, status codes, and errors.</li>
--   </ul>
--   
--   <pre>
--   {-# language OverloadedStrings #-}
--   
--   import Network.Wai.Handler.Warp (run)
--   import Web.Twain
--   
--   main :: IO ()
--   main = do
--     run 8080 $
--       foldr ($)
--         (notFound missing)
--         [ get "/" index
--         , post "<i>echo</i>:name" echo
--         ]
--   
--   index :: ResponderM a
--   index = send $ html "Hello World!"
--   
--   echo :: ResponderM a
--   echo = do
--     name &lt;- param "name"
--     send $ html $ "Hello, " &lt;&gt; name
--   
--   missing :: ResponderM a
--   missing = send $ html "Not found..."
--   </pre>
module Web.Twain

-- | <a>ResponderM</a> is an Either-like monad that can "short-circuit" and
--   return a response, or pass control to the next middleware. This
--   provides convenient branching with do notation for redirects, error
--   responses, etc.
data ResponderM a
get :: PathPattern -> ResponderM a -> Middleware
put :: PathPattern -> ResponderM a -> Middleware
patch :: PathPattern -> ResponderM a -> Middleware
post :: PathPattern -> ResponderM a -> Middleware
delete :: PathPattern -> ResponderM a -> Middleware

-- | Route request matching optional <a>Method</a> and <a>PathPattern</a>
--   to <a>ResponderM</a>.
route :: Maybe Method -> PathPattern -> ResponderM a -> Middleware

-- | Respond if no other route responds.
--   
--   Sets the status to 404.
notFound :: ResponderM a -> Application

-- | Get a parameter. Looks in query, path, cookie, and body (in that
--   order).
--   
--   If no parameter is found, or parameter fails to parse, <a>next</a> is
--   called which passes control to subsequent routes and middleware.
param :: ParsableParam a => Text -> ResponderM a

-- | Get a parameter or error if missing or parse failure.
paramEither :: ParsableParam a => Text -> ResponderM (Either HttpError a)

-- | Get an optional parameter.
--   
--   Returns <a>Nothing</a> for missing parameter. Throws <a>HttpError</a>
--   on parse failure.
paramMaybe :: ParsableParam a => Text -> ResponderM (Maybe a)

-- | Get all parameters from query, path, cookie, and body (in that order).
params :: ResponderM [Param]

-- | Get uploaded <a>FileInfo</a>.
--   
--   If missing parameter or empty file, pass control to subsequent routes
--   and middleware.
file :: Text -> ResponderM (FileInfo ByteString)

-- | Get optional uploaded <a>FileInfo</a>.
--   
--   <a>Nothing</a> is returned for missing parameter or empty file
--   content.
fileMaybe :: Text -> ResponderM (Maybe (FileInfo ByteString))

-- | Get all uploaded files.
files :: ResponderM [File ByteString]

-- | Get the JSON value from request body.
fromBody :: FromJSON a => ResponderM a

-- | Get the value of a request <a>Header</a>. Header names are
--   case-insensitive.
header :: Text -> ResponderM (Maybe Text)

-- | Get the request headers.
headers :: ResponderM [Header]

-- | Get the WAI <a>Request</a>.
request :: ResponderM Request

-- | Send a <a>Response</a>.
--   
--   <pre>
--   send $ text "Hello, World!"
--   </pre>
--   
--   Send an <a>html</a> response:
--   
--   <pre>
--   send $ html "&lt;h1&gt;Hello, World!&lt;/h1&gt;"
--   </pre>
--   
--   Modify the <a>status</a>:
--   
--   <pre>
--   send $ status status404 $ text "Not Found"
--   </pre>
--   
--   Send a response <a>withHeader</a>:
--   
--   <pre>
--   send $ withHeader (hServer, "Twain + Warp") $ text "Hello"
--   </pre>
--   
--   Send a response <a>withCookie</a>:
--   
--   <pre>
--   send $ withCookie "key" "val" $ text "Hello"
--   </pre>
send :: Response -> ResponderM a

-- | Pass control to the next route or middleware.
next :: ResponderM a

-- | Create a redirect response with 301 status (Moved Permanently).
redirect301 :: Text -> Response

-- | Create a redirect response with 302 status (Found).
redirect302 :: Text -> Response

-- | Create a redirect response 303 status (See Other).
redirect303 :: Text -> Response

-- | Construct a <a>Text</a> response.
--   
--   Sets the Content-Type and Content-Length headers.
text :: Text -> Response

-- | Construct an HTML response.
--   
--   Sets the Content-Type and Content-Length headers.
html :: ByteString -> Response

-- | Construct a JSON response using <a>ToJSON</a>.
--   
--   Sets the Content-Type and Content-Length headers.
json :: ToJSON a => a -> Response

-- | Construct an XML response.
--   
--   Sets the Content-Type and Content-Length headers.
xml :: ByteString -> Response

-- | Construct a CSS response.
--   
--   Sets the Content-Type and Content-Length headers.
css :: ByteString -> Response

-- | Construct a raw response from a lazy <a>ByteString</a>.
--   
--   Sets the Content-Length header if missing.
raw :: Status -> [Header] -> ByteString -> Response

-- | Set the <a>Status</a> for a <a>Response</a>.
status :: Status -> Response -> Response

-- | Add a <a>Header</a> to response.
withHeader :: Header -> Response -> Response

-- | Add a cookie to the response with the given key and value.
--   
--   Note: This uses <a>defaultSetCookie</a>.
withCookie :: Text -> Text -> Response -> Response

-- | Add a <a>SetCookie</a> to the response.
withCookie' :: SetCookie -> Response -> Response

-- | Add a header to expire (unset) a cookie with the given key.
expireCookie :: Text -> Response -> Response
data HttpError
HttpError :: Status -> String -> HttpError
onException :: (SomeException -> ResponderM a) -> Middleware

-- | Specify <a>ParseRequestBodyOptions</a> to use when parsing request
--   body.
withParseBodyOpts :: ParseRequestBodyOptions -> Middleware

-- | Specify maximum request body size in bytes.
--   
--   Defaults to 64KB.
withMaxBodySize :: Word64 -> Middleware

-- | Parse values from request parameters.
class ParsableParam a
parseParam :: ParsableParam a => Text -> Either HttpError a

-- | Default implementation parses comma-delimited lists.
parseParamList :: ParsableParam a => Text -> Either HttpError [a]

-- | Information on an uploaded file.
data FileInfo c
FileInfo :: ByteString -> ByteString -> c -> FileInfo c
[fileName] :: FileInfo c -> ByteString
[fileContentType] :: FileInfo c -> ByteString
[fileContent] :: FileInfo c -> c
