-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Lens-based HTTP toolkit
--
-- This package provides the core functionality of the Nero HTTP
-- toolkit.
--
-- Check the README for a more detailed explanation.
@package nero
@version 0.3.1
-- | This module is meant to be imported unqualified. It takes care of
-- different versions of base and re-exports the following:
--
--
module Nero.Prelude
-- | This module should be mostly used for matching the Path of a
-- Request, also known as routing.
module Nero.Match
-- | This contains matched Text in reverse order to how it was
-- matched.
type Match = [Text]
-- | This is just to pure with a refined type.
match :: Getter Text Match
-- | This Prism' strips/prepends a prefix.
--
--
-- >>> ("/hello/there"::Text) ^? prefixed "/hello/"
-- Just "there"
--
--
--
-- >>> prefixed "/hello/" # ("there"::Text)
-- "/hello/there"
--
--
-- If matching the entire source it previews to an empty Text. You
-- might use exact if you are expecting this behavior.
--
--
-- >>> ("hello"::Text) ^? prefixed "hello"
-- Just ""
--
--
-- This also means that to review an entire source, you need to
-- give it an empty Text.
--
--
-- >>> prefixed "hello" # (mempty::Text)
-- "hello"
--
--
-- An empty Match matches to itself regardless of the pattern.
--
--
-- >>> preview (prefixed "hello") (review (prefixed "hello") (mempty::Text)) <&> is _Empty
-- Just True
--
class Prefixed a
prefixed :: Prefixed a => Text -> Prism' a a
-- | This Prism' strips/appends a suffix.
--
--
-- >>> ("/hello/there"::Text) ^? suffixed "there"
-- Just "/hello/"
--
--
--
-- >>> suffixed "there" # ("/hello/"::Text)
-- "/hello/there"
--
--
-- If matching the entire source it previews to an empty Text. You
-- might use exact if you are expecting this behavior.
--
--
-- >>> ("hello"::Text) ^? suffixed "hello"
-- Just ""
--
--
-- This also means that to review an entire source, you need to
-- give it an empty Text.
--
--
-- >>> suffixed "hello" # (mempty::Text)
-- "hello"
--
--
-- An empty Match matches to itself regardless of the pattern.
--
--
-- >>> preview (suffixed "hello") (review (suffixed "hello") (mempty::Text)) <&> is _Empty
-- Just True
--
class Suffixed a
suffixed :: Suffixed a => Text -> Prism' a a
-- | This Prism' splits/joins at the first occurrence of a
-- boundary for the first value of a Match.
--
--
-- >>> pure "hello/out/there" ^? sep "/" <&> toListOf folded
-- Just ["out/there","hello"]
--
--
--
-- >>> sep "/" # (pure "out/there" <> pure "hello") & view _head
-- "hello/out/there"
--
--
-- Notice what happens when there is no source before or after a
-- boundary:
--
--
-- >>> pure "hello/" ^? sep "/"
-- Just ["","hello"]
--
-- >>> (pure "hello/" <> pure "there") ^? sep "/"
-- Just ["","hello","there"]
--
--
--
-- >>> pure "/hello" ^? sep "/"
-- Just ["hello",""]
--
-- >>> (pure "/hello" <> pure "there") ^? sep "/"
-- Just ["hello","","there"]
--
--
-- When the source is identical to the boundary: >>> pure
-- "hello" ^? sep "hello" Just []
sep :: Text -> Prism' Match Match
-- | This is the composition of match and sep. Use this to
-- avoid lifting a Match explicitly. Notice that, unlike
-- sep, this is not reversible.
split :: Text -> Fold Text Match
-- | This is just an alias to only. Use this to match the entirety
-- of the source. The source mustn't be lifted to a Match.
--
--
-- >>> "hello" ^? exact "hello"
-- Just ()
--
exact :: Text -> Prism' Text ()
-- | Prism' between a Match and a target type.
class Target a
target :: Target a => Prism' Match a
instance Prefixed Text
instance Prefixed Match
instance Suffixed Text
instance Suffixed Match
instance Target Match
instance Target Text
instance Target Int
instance Target Float
instance (Target a, Target b) => Target (a, b)
module Nero.Binary
-- | Represents something that can be serialized to a ByteString
-- with the context of Nero.
class Renderable a
render :: Renderable a => a -> ByteString
-- | Represents something that can be deserialized from a ByteString
-- within the context of Nero. Notice that the whole
-- ByteString has to be consumed.
class Parseable a
parse :: Parseable a => ByteString -> Maybe a
-- | A convenient Prism' to pack serializers/deserializers.
binary :: (Renderable a, Parseable a) => Prism' ByteString a
-- | This module is mainly intended for internal use. Nero.Request
-- and Nero.Payload should provide everything you need for dealing
-- with HTTP parameters.
module Nero.Param
-- | A Traversal' of the values of a given HTTP parameter.
class Param a
param :: Param a => Text -> Traversal' a Text
-- | A Map with multiple values. Also known as a MultiDict
-- in other web frameworks.
data MultiMap
-- | Like fromList from Data.Map but mappending the
-- values.
fromList :: [(Text, [Text])] -> MultiMap
-- | Is the map empty?
null :: MultiMap -> Bool
instance Show MultiMap
instance Eq MultiMap
instance Monoid MultiMap
instance Wrapped MultiMap
instance Ixed MultiMap
instance At MultiMap
instance Param MultiMap
instance Renderable MultiMap
module Nero.Payload
-- | Contains the Body and any metadata associated with it.
data Payload
payloadText :: Encoding -> Body -> Payload
-- | Indicates a Text encoding.
data Encoding
utf8Encoding :: Encoding
-- | A Lens' for types with a Payload.
class HasPayload a
payload :: HasPayload a => Lens' a Payload
-- | It's the main data associated with the Payload of
-- Request or a Response.
type Body = ByteString
-- | Get the Body for types with one.
class HasBody a
body :: HasBody a => a -> Body
-- | A MultiMap in the context of a form.
type Form = MultiMap
-- | A Prism' to obtain a Form from a Payload and make
-- Payload from a Form.
_Form :: Prism' Payload Form
-- | A Traversal' to access a potential Form.
class Formed a
form :: Formed a => Traversal' a Form
-- | A Payload with an empty Form useful for testing.
dummyPayloadForm :: Payload
instance Eq Payload
instance Show Payload
instance Eq Encoding
instance Show Encoding
instance HasBody Payload
instance Formed Payload
instance Param Payload
module Nero.Url
-- | Composite type of a Scheme, Host, Path,
-- Query.
data Url
[Url] :: Scheme -> Host -> Path -> Query -> Url
-- | The scheme given in the Url, i.e. http or
-- https.
data Scheme
[Http] :: Scheme
[Https] :: Scheme
-- | The host name of a Url.
type Host = ByteString
-- | Path after the host name in a Url.
type Path = Text
-- | The query string in the form of a MultiMap.
type Query = MultiMap
-- | Lens' for types with an Url.
class HasUrl a
url :: HasUrl a => Lens' a Url
-- | Traversal' to obtain the Url of types with
-- Location.
class Location a
location :: Location a => Traversal' a Url
-- | Lens' for types with a Host.
class HasHost a
host :: HasHost a => Lens' a Host
-- | Lens' for types with a Path.
class HasPath a
path :: HasPath a => Lens' a Path
-- | Lens' for types with a Query.
class HasQuery a
query :: HasQuery a => Lens' a Query
-- | A Traversal' of the values of a given HTTP parameter.
class Param a
param :: Param a => Text -> Traversal' a Text
-- | Empty Url useful for testing.
dummyUrl :: Url
instance Eq Url
instance Show Url
instance Eq Scheme
instance Show Scheme
instance Renderable Scheme
instance Parseable Scheme
instance HasHost Url
instance HasPath Url
instance HasQuery Url
instance Param Url
instance Renderable Url
module Nero.Request
-- | An HTTP Request.
data Request
-- | Smart constructor for GET Requests.
get :: Url -> Request
-- | Smart constructor for POST Requests.
post :: Url -> Payload -> Request
-- | Prism' for GET Requests.
_GET :: Prism' Request GET
-- | Prism' to filter for POST Requests.
_POST :: Prism' Request POST
-- | Show Request method.
method :: Request -> ByteString
-- | Traversal' to obtain a Payload from a Request.
-- This is not a Lens' because some Requests, such has
-- GET, are not allowed to have a Payload.
payloaded :: Traversal' Request Payload
-- | This Traversal lets you traverse every HTTP parameter
-- regardless of whether it's present in the query string or in
-- the form encoded body of a POST Request. In the
-- rare case where there are HTTP parameters in both, every parameter is
-- still being traversed starting from the /query string/.
--
-- You might want to use param for traversing a specific
-- parameter.
--
--
-- >>> let request = dummyRequestForm & query . at "name" ?~ ["hello", "out"] & form . at "name" ?~ ["there"]
--
-- >>> foldOf params request ^? ix "name"
-- Just ["hello","out","there"]
--
params :: Traversal' Request MultiMap
-- | A GET Request.
data GET
-- | A POST Request.
data POST
-- | An empty GET request useful for testing.
dummyRequest :: Request
-- | An empty POST request with an empty form encoded body useful
-- for testing.
dummyRequestForm :: Request
instance Eq Request
instance Show Request
instance Eq POST
instance Show POST
instance Eq GET
instance Show GET
instance HasUrl Request
instance HasHost Request
instance HasPath Request
instance HasQuery Request
instance Param Request
instance Formed Request
instance HasBody Request
instance HasUrl GET
instance HasHost GET
instance HasPath GET
instance HasQuery GET
instance HasUrl POST
instance HasPayload POST
instance HasHost POST
instance HasPath POST
instance HasQuery POST
module Nero.Response
-- | An HTTP response.
data Response
-- | Creates an 200 OK response from the given text. It
-- automatically encodes the text to 'utf-8'. The Mime type is
-- text/plain.
ok :: Text -> Response
-- | Creates an 301 Moved Permanently response with the
-- Location corresponding to the given Url.
movedPermanently :: Url -> Response
-- | Creates an 404 Not Found response from the given text. It
-- automatically encodes the text to 'utf-8'. The Mime type is
-- text/plain.
notFound :: Text -> Response
-- | A Prism' to obtain/convert a Payload
-- from/to a 200 OK Response.
_Ok :: Prism' Response Payload
-- | A Prism' to obtain/convert a Payload
-- from/to a 301 Moved Permanently Response.
_MovedPermanently :: Prism' Response Url
-- | A Prism' to obtain/convert a Payload
-- from/to a 404 Not Found Response.
_NotFound :: Prism' Response Payload
-- | The HTTP status code and description.
data Status
-- | Obtain the Status from a Response.
status :: Response -> Status
instance Eq Response
instance Show Response
instance Location Response
instance HasBody Response
instance Show Status
module Nero.Application
type Application = Request -> IO Response
-- | Ultimately any valid Nero server application must be transformed
-- Request -> IO Response. This type
-- class facilitates the creation of web server handling Nero
-- applications.
class Server a
application :: Server a => a -> Application
-- | Redirect with slash appended URL if only a trailing slash is needed
-- for successful matching, otherwise it responds normally.
--
--
-- >>> let mkRequest p = dummyRequest & host .~ "example.com" & path .~ p
--
-- >>> let respond name = ok $ "<h1>Hello " <> name <> "</h1>"
--
-- >>> let app = slashRedirect (prefixed "/hello/" . suffixed "/") respond :: Request -> Maybe Response
--
--
--
-- >>> app (mkRequest "/hello/there") <&> status
-- Just "301 Moved Permanently"
--
-- >>> app (mkRequest "/hello/there") >>= preview location <&> render
-- Just "http://example.com/hello/there/"
--
--
--
-- >>> app (mkRequest "/hello/there/") <&> status
-- Just "200 OK"
--
-- >>> app (mkRequest "/hello/there/") <&> body
-- Just "<h1>Hello there</h1>"
--
--
--
-- >>> app $ mkRequest "/bye/"
-- Nothing
--
slashRedirect :: (Target a, HasUrl r, HasPath r) => Prism' Match Match -> (a -> Response) -> r -> Maybe Response
instance Server Response
instance Server (Request -> Response)
instance Server (Request -> Maybe Response)
-- | This module re-exports the essential functions for quickly writing
-- Nero applications. Use the original modules for more
-- specialized functions.
module Nero
type Application = Request -> IO Response
-- | Ultimately any valid Nero server application must be transformed
-- Request -> IO Response. This type
-- class facilitates the creation of web server handling Nero
-- applications.
class Server a
application :: Server a => a -> Application
-- | An HTTP Request.
data Request
-- | Smart constructor for GET Requests.
get :: Url -> Request
-- | Smart constructor for POST Requests.
post :: Url -> Payload -> Request
-- | Prism' for GET Requests.
_GET :: Prism' Request GET
-- | Prism' to filter for POST Requests.
_POST :: Prism' Request POST
-- | Show Request method.
method :: Request -> ByteString
path :: HasPath a => Lens' a Path
query :: HasQuery a => Lens' a Query
form :: Formed a => Traversal' a Form
-- | This Traversal lets you traverse every HTTP parameter
-- regardless of whether it's present in the query string or in
-- the form encoded body of a POST Request. In the
-- rare case where there are HTTP parameters in both, every parameter is
-- still being traversed starting from the /query string/.
--
-- You might want to use param for traversing a specific
-- parameter.
--
--
-- >>> let request = dummyRequestForm & query . at "name" ?~ ["hello", "out"] & form . at "name" ?~ ["there"]
--
-- >>> foldOf params request ^? ix "name"
-- Just ["hello","out","there"]
--
params :: Traversal' Request MultiMap
param :: Param a => Text -> Traversal' a Text
body :: HasBody a => a -> Body
-- | A GET Request.
data GET
-- | A POST Request.
data POST
-- | An HTTP response.
data Response
-- | Creates an 200 OK response from the given text. It
-- automatically encodes the text to 'utf-8'. The Mime type is
-- text/plain.
ok :: Text -> Response
-- | Creates an 301 Moved Permanently response with the
-- Location corresponding to the given Url.
movedPermanently :: Url -> Response
-- | Composite type of a Scheme, Host, Path,
-- Query.
data Url
-- | This is just to pure with a refined type.
match :: Getter Text Match
-- | This Prism' strips/prepends a prefix.
--
--
-- >>> ("/hello/there"::Text) ^? prefixed "/hello/"
-- Just "there"
--
--
--
-- >>> prefixed "/hello/" # ("there"::Text)
-- "/hello/there"
--
--
-- If matching the entire source it previews to an empty Text. You
-- might use exact if you are expecting this behavior.
--
--
-- >>> ("hello"::Text) ^? prefixed "hello"
-- Just ""
--
--
-- This also means that to review an entire source, you need to
-- give it an empty Text.
--
--
-- >>> prefixed "hello" # (mempty::Text)
-- "hello"
--
--
-- An empty Match matches to itself regardless of the pattern.
--
--
-- >>> preview (prefixed "hello") (review (prefixed "hello") (mempty::Text)) <&> is _Empty
-- Just True
--
class Prefixed a
prefixed :: Prefixed a => Text -> Prism' a a
-- | This Prism' strips/appends a suffix.
--
--
-- >>> ("/hello/there"::Text) ^? suffixed "there"
-- Just "/hello/"
--
--
--
-- >>> suffixed "there" # ("/hello/"::Text)
-- "/hello/there"
--
--
-- If matching the entire source it previews to an empty Text. You
-- might use exact if you are expecting this behavior.
--
--
-- >>> ("hello"::Text) ^? suffixed "hello"
-- Just ""
--
--
-- This also means that to review an entire source, you need to
-- give it an empty Text.
--
--
-- >>> suffixed "hello" # (mempty::Text)
-- "hello"
--
--
-- An empty Match matches to itself regardless of the pattern.
--
--
-- >>> preview (suffixed "hello") (review (suffixed "hello") (mempty::Text)) <&> is _Empty
-- Just True
--
class Suffixed a
suffixed :: Suffixed a => Text -> Prism' a a
-- | This Prism' splits/joins at the first occurrence of a
-- boundary for the first value of a Match.
--
--
-- >>> pure "hello/out/there" ^? sep "/" <&> toListOf folded
-- Just ["out/there","hello"]
--
--
--
-- >>> sep "/" # (pure "out/there" <> pure "hello") & view _head
-- "hello/out/there"
--
--
-- Notice what happens when there is no source before or after a
-- boundary:
--
--
-- >>> pure "hello/" ^? sep "/"
-- Just ["","hello"]
--
-- >>> (pure "hello/" <> pure "there") ^? sep "/"
-- Just ["","hello","there"]
--
--
--
-- >>> pure "/hello" ^? sep "/"
-- Just ["hello",""]
--
-- >>> (pure "/hello" <> pure "there") ^? sep "/"
-- Just ["hello","","there"]
--
--
-- When the source is identical to the boundary: >>> pure
-- "hello" ^? sep "hello" Just []
sep :: Text -> Prism' Match Match
-- | This is the composition of match and sep. Use this to
-- avoid lifting a Match explicitly. Notice that, unlike
-- sep, this is not reversible.
split :: Text -> Fold Text Match
-- | This is just an alias to only. Use this to match the entirety
-- of the source. The source mustn't be lifted to a Match.
--
--
-- >>> "hello" ^? exact "hello"
-- Just ()
--
exact :: Text -> Prism' Text ()
-- | Prism' between a Match and a target type.
class Target a
target :: Target a => Prism' Match a
-- | An empty GET request useful for testing.
dummyRequest :: Request
-- | An empty POST request with an empty form encoded body useful
-- for testing.
dummyRequestForm :: Request
-- | Empty Url useful for testing.
dummyUrl :: Url