-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Lens-based HTTP toolkit
--
@package nero
@version 0.2
-- | Control.Applicative re-exports <$>,
-- <*>, pure
--
-- Data.Foldable re-exports fold
--
-- Data.Monoid re-exports Monoid, <>,
-- mappend, mempty
--
-- Control.Lens
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 to the first
-- element of a Match.
--
--
-- >>> pure "/hello/there" ^? prefixed "/hello/" . _head
-- Just "there"
--
--
--
-- >>> prefixed "/hello/" # pure "there" & view _head
-- "/hello/there"
--
--
-- If matching the entire source it previews to an empty Text. You
-- might use exact if you are expecting this behavior.
--
--
-- >>> pure "hello" ^? prefixed "hello" . _head
-- Just ""
--
--
-- This also means that to review an entire source, you need to
-- give it an empty Text.
--
--
-- >>> prefixed "hello" # pure mempty & view _head
-- "hello"
--
--
-- An empty Match matches to itself regardless of the pattern.
--
--
-- >>> preview (prefixed "hello") (review (prefixed "hello") mempty) <&> is _Empty
-- Just True
--
prefixed :: Text -> Prism' Match Match
-- | This Prism' strips/appends a suffix to the first value
-- of a Match.
--
--
-- >>> pure "/hello/there" ^? suffixed "there" . _head
-- Just "/hello/"
--
--
--
-- >>> suffixed "there" # pure "/hello/" & view _head
-- "/hello/there"
--
--
-- If matching the entire source it previews to an empty Text. You
-- might use exact if you are expecting this behavior.
--
--
-- >>> pure "hello" ^? suffixed "hello" . _head
-- Just ""
--
--
-- This also means that to review an entire source, you need to
-- give it an empty Text.
--
--
-- >>> suffixed "hello" # pure mempty & view _head
-- "hello"
--
--
-- An empty Match matches to itself regardless of the pattern.
--
--
-- >>> preview (suffixed "hello") (review (suffixed "hello") mempty) <&> is _Empty
-- Just True
--
suffixed :: Text -> Prism' Match 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 ()
-- | 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
-- | Prism' between a Match and a target type.
class Target a
target :: Target a => Prism' Match a
instance (Target a, Target b) => Target (a, b)
instance Target Float
instance Target Int
instance Target Text
instance Target Match
-- | This module is mainly intended to be used for rare occassions.
-- Nero.Request and Nero.Payload should provide everything
-- you need for 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 most web frameworks.
data MultiMap
-- | Encode a MultiMap with the typical query string format. This is
-- useful to render MultiMaps when testing. The web server adapter
-- for Nero should do this for you in the real application.
encodeMultiMap :: MultiMap -> ByteString
instance Eq MultiMap
instance Param MultiMap
instance At MultiMap
instance Ixed MultiMap
instance Wrapped MultiMap
instance Monoid MultiMap
instance Show 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 Traversal' for types with a Payload.
class Payloaded a
payload :: Payloaded a => Traversal' 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 Show Encoding
instance Eq Encoding
instance Show Payload
instance Eq Payload
instance Param Payload
instance Formed Payload
instance HasBody Payload
module Nero.Url
-- | Composite type of a Scheme, Host, Path,
-- Query.
data Url
-- | The scheme given in the Url, i.e. http or
-- https.
data 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 Scheme
instance Eq Url
instance Param Url
instance HasQuery Url
instance HasPath Url
instance HasHost Url
instance Show Url
instance Show Scheme
module Nero.Request
-- | An HTTP Request.
data Request
-- | Show Request method.
method :: Request -> ByteString
-- | Prism' to filter GET Requests.
--
--
-- >>> dummyRequest ^? _GET <&> method
-- Just "GET"
--
-- >>> dummyRequestForm ^? _GET <&> method
-- Nothing
--
_GET :: Prism' Request Request
-- | Prism' to filter for POST Requests.
--
--
-- >>> dummyRequest ^? _POST <&> method
-- Nothing
--
-- >>> dummyRequestForm ^? _POST <&> method
-- Just "POST"
--
_POST :: Prism' Request Request
-- | 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
-- | 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 Show Request
instance Eq Request
instance Formed Request
instance Param Request
instance Payloaded Request
instance HasQuery Request
instance HasPath Request
instance HasHost Request
instance HasUrl Request
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
-- | The HTTP status code and description.
data Status
-- | Obtain the Status from a Response.
status :: Response -> Status
instance Show Response
instance Eq Response
instance Show Status
instance HasBody Response
instance Location Response
module Nero.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
--
--
--
-- >>> app (mkRequest "/hello/there") <&> status
-- Just "301 Moved Permanently"
--
-- >>> app (mkRequest "/hello/there") >>= preview location
-- 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 => Prism' Match Match -> (a -> Response) -> 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
-- | An HTTP Request.
data Request
-- | Show Request method.
method :: Request -> ByteString
-- | Prism' to filter GET Requests.
--
--
-- >>> dummyRequest ^? _GET <&> method
-- Just "GET"
--
-- >>> dummyRequestForm ^? _GET <&> method
-- Nothing
--
_GET :: Prism' Request Request
-- | Prism' to filter for POST Requests.
--
--
-- >>> dummyRequest ^? _POST <&> method
-- Nothing
--
-- >>> dummyRequestForm ^? _POST <&> method
-- Just "POST"
--
_POST :: Prism' Request Request
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
-- | 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
-- | This is just to pure with a refined type.
match :: Getter Text Match
-- | This Prism' strips/prepends a prefix to the first
-- element of a Match.
--
--
-- >>> pure "/hello/there" ^? prefixed "/hello/" . _head
-- Just "there"
--
--
--
-- >>> prefixed "/hello/" # pure "there" & view _head
-- "/hello/there"
--
--
-- If matching the entire source it previews to an empty Text. You
-- might use exact if you are expecting this behavior.
--
--
-- >>> pure "hello" ^? prefixed "hello" . _head
-- Just ""
--
--
-- This also means that to review an entire source, you need to
-- give it an empty Text.
--
--
-- >>> prefixed "hello" # pure mempty & view _head
-- "hello"
--
--
-- An empty Match matches to itself regardless of the pattern.
--
--
-- >>> preview (prefixed "hello") (review (prefixed "hello") mempty) <&> is _Empty
-- Just True
--
prefixed :: Text -> Prism' Match Match
-- | This Prism' strips/appends a suffix to the first value
-- of a Match.
--
--
-- >>> pure "/hello/there" ^? suffixed "there" . _head
-- Just "/hello/"
--
--
--
-- >>> suffixed "there" # pure "/hello/" & view _head
-- "/hello/there"
--
--
-- If matching the entire source it previews to an empty Text. You
-- might use exact if you are expecting this behavior.
--
--
-- >>> pure "hello" ^? suffixed "hello" . _head
-- Just ""
--
--
-- This also means that to review an entire source, you need to
-- give it an empty Text.
--
--
-- >>> suffixed "hello" # pure mempty & view _head
-- "hello"
--
--
-- An empty Match matches to itself regardless of the pattern.
--
--
-- >>> preview (suffixed "hello") (review (suffixed "hello") mempty) <&> is _Empty
-- Just True
--
suffixed :: Text -> Prism' Match 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 ()
-- | 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
-- | 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