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


-- | Happstack minus the useless stuff
--   
--   This packages provides a subset of Happstack that is easier to learn
--   but still very useful. It as 100% compatible with the full version of
--   Happstack.
@package happstack-lite
@version 7.2.0


-- | <tt>happstack-lite</tt> provides a simplied introduction to
--   <tt>happstack-server</tt>. (Nearly) all the functions in
--   <tt>happstack-lite</tt> are simple re-exports from the
--   <tt>happstack-server</tt> package. <tt>happstack-lite</tt> offers two
--   key advantages over <tt>happstack-server</tt>:
--   
--   <ol>
--   <li>it only contains the most commonly used functions, gathered in one
--   convenient location.</li>
--   <li>the type signatures have been simplified to remove most references
--   to type classes, monad transformers, and other potentially confusing
--   type signatures.</li>
--   </ol>
--   
--   The beautiful part about <tt>happstack-lite</tt> is that because it
--   merely <tt>re-exports</tt> functions and types from
--   <tt>happstack-server</tt> it is possible to gradually import extra
--   functionality from <tt>happstack-server</tt> on an as-need basis.
--   
--   There is a brief introduction to <tt>happstack-lite</tt> located here:
--   
--   <a>http://www.happstack.com/C/ViewPage/9</a>
--   
--   More detailed examples and information can be found in the Happstack
--   Crash Course:
--   
--   <a>http://www.happstack.com/docs/crashcourse/index.html</a>
--   
--   The Happstack Crash Course is written against
--   <tt>happstack-server</tt> but the behavior of the functions available
--   in <tt>happstack-lite</tt> is almost identical.
module Happstack.Lite

-- | an HTTP request
data Request :: *

-- | an HTTP Response
data Response :: *

-- | An alias for <tt><a>ServerPartT</a> <a>IO</a></tt>
type ServerPart a = ServerPartT IO a

-- | configuration to be used with <a>serve</a> function
data ServerConfig
ServerConfig :: Int -> Int64 -> Int64 -> FilePath -> ServerConfig

-- | port to listen on
port :: ServerConfig -> Int

-- | maximum amount of POST data (in bytes)
ramQuota :: ServerConfig -> Int64

-- | maximum file upload size (in bytes)
diskQuota :: ServerConfig -> Int64

-- | temporary directory for file uploads
tmpDir :: ServerConfig -> FilePath

-- | a reasonable default <a>ServerConfig</a>
--   
--   <pre>
--   ServerConfig { port      = 8000
--                , ramQuota  = 1 * 10^6
--                , diskQuota = 20 * 10^6
--                , tmpDir    = "/tmp/"
--                }
--   </pre>
defaultServerConfig :: ServerConfig

-- | start the server and handle requests using the supplied
--   <a>ServerPart</a>
serve :: Maybe ServerConfig -> ServerPart Response -> IO ()

-- | Guard against the request method
--   
--   Example:
--   
--   <pre>
--   handler :: ServerPart Response
--   handler =
--       do method [GET, HEAD]
--          ...
--   </pre>
method :: MatchMethod method => method -> ServerPart ()

-- | HTTP request method
data Method :: *
GET :: Method
HEAD :: Method
POST :: Method
PUT :: Method
DELETE :: Method
TRACE :: Method
OPTIONS :: Method
CONNECT :: Method

-- | instances of this class provide a variety of ways to match on the
--   <a>Request</a> method.
--   
--   Examples:
--   
--   <pre>
--   method GET                  -- match GET or HEAD
--   method [GET, POST]          -- match GET, HEAD or POST
--   method HEAD                 -- match HEAD /but not/ GET
--   method (== GET)             -- match GET or HEAD
--   method (not . (==) DELETE)  -- match any method except DELETE
--   method ()                   -- match any method
--   </pre>
--   
--   As you can see, GET implies that HEAD should match as well. This is to
--   make it harder to write an application that uses HTTP incorrectly.
--   Happstack handles HEAD requests automatically, but we still need to
--   make sure our handlers don't mismatch or a HEAD will result in a 404.
--   
--   If you must, you can still do something like this to match GET without
--   HEAD:
--   
--   <pre>
--   guardRq ((== GET) . rqMethod)
--   </pre>
class MatchMethod m
matchMethod :: MatchMethod m => m -> Method -> Bool

-- | Pop a path element and run the supplied handler if it matches the
--   given string.
--   
--   <pre>
--   handler :: ServerPart Response
--   handler = dir "foo" $ dir "bar" $ subHandler
--   </pre>
--   
--   The path element can not contain '/'. See also <tt>dirs</tt>.
dir :: String -> ServerPart a -> ServerPart a

-- | Pop a path element and parse it using the <tt>fromReqURI</tt> in the
--   <a>FromReqURI</a> class.
path :: FromReqURI a => (a -> ServerPart b) -> ServerPart b

-- | This class is used by <a>path</a> to parse a path component into a
--   value.
--   
--   The instances for number types (<a>Int</a>, <a>Float</a>, etc) use
--   <a>readM</a> to parse the path component.
--   
--   The instance for <a>String</a>, on the other hand, returns the
--   unmodified path component.
--   
--   See the following section of the Happstack Crash Course for detailed
--   instructions using and extending <a>FromReqURI</a>:
--   
--   
--   <a>http://www.happstack.com/docs/crashcourse/RouteFilters.html#FromReqURI</a>
class FromReqURI a
fromReqURI :: FromReqURI a => String -> Maybe a

-- | guard which only succeeds if there are no remaining path segments
--   
--   Often used if you want to explicitly assign a route for <a>/</a>
nullDir :: ServerPart ()

-- | Guard using an arbitrary function on the <a>Request</a>.
guardRq :: (Request -> Bool) -> ServerPart ()

-- | <a>toResponse</a> will convert a value into a <a>Response</a> body,
--   set the <tt>content-type</tt>, and set the default response code for
--   that type.
--   
--   <tt>happstack-server</tt> Example:
--   
--   <pre>
--   main = simpleHTTP nullConf $ toResponse "hello, world!"
--   </pre>
--   
--   will generate a <a>Response</a> with the content-type
--   <tt>text/plain</tt>, the response code <tt>200 OK</tt>, and the body:
--   <tt>hello, world!</tt>.
--   
--   <tt>simpleHTTP</tt> will call <a>toResponse</a> automatically, so the
--   above can be shortened to:
--   
--   <pre>
--   main = simpleHTTP nullConf $ "hello, world!"
--   </pre>
--   
--   <tt>happstack-lite</tt> Example:
--   
--   <pre>
--   main = serve Nothing $ toResponse "hello, world!"
--   </pre>
--   
--   Minimal definition: <a>toMessage</a> (and usually
--   <a>toContentType</a>).
class ToMessage a
toContentType :: ToMessage a => a -> ByteString
toMessage :: ToMessage a => a -> ByteString
toResponse :: ToMessage a => a -> Response

-- | A low-level function to build a <a>Response</a> from a content-type
--   and a <a>ByteString</a>.
--   
--   Creates a <a>Response</a> in a manner similar to the <a>ToMessage</a>
--   class, but without requiring an instance declaration.
--   
--   example:
--   
--   <pre>
--   import Data.ByteString.Char8 as C
--   import Data.ByteString.Lazy.Char8 as L
--   import Happstack.Lite
--   
--   main = serve Nothing $ ok $ toResponseBS (C.pack "text/plain") (L.pack "hello, world")
--   </pre>
--   
--   (note: <a>pack</a> and <a>pack</a> only work for ascii. For unicode
--   strings you would need to use <tt>utf8-string</tt>, <tt>text</tt>, or
--   something similar to create a valid <a>ByteString</a>).
toResponseBS :: ByteString -> ByteString -> Response

-- | Respond with <tt>200 OK</tt>.
--   
--   <pre>
--   main = serve Nothing $ ok "Everything is OK"
--   </pre>
ok :: a -> ServerPart a

-- | Respond with <tt>500 Internal Server Error</tt>.
--   
--   <pre>
--   main = serve Nothing $ internalServerError "Sorry, there was an internal server error."
--   </pre>
internalServerError :: a -> ServerPart a

-- | Respond with <tt>401 Unauthorized</tt>.
--   
--   <pre>
--   main = serve Nothing $ unauthorized "You are not authorized."
--   </pre>
unauthorized :: a -> ServerPart a

-- | Respond with <tt>404 Not Found</tt>.
--   
--   <pre>
--   main = serve Nothing $ notFound "What you are looking for has not been found."
--   </pre>
notFound :: a -> ServerPart a

-- | Respond with <tt>303 See Other</tt>.
--   
--   <pre>
--   main = serve Nothing $ seeOther "http://example.org/" "What you are looking for is now at http://example.org/"
--   </pre>
--   
--   NOTE: The second argument of <a>seeOther</a> is the message body which
--   will sent to the browser. According to the HTTP 1.1 spec,
--   
--   <pre>
--   the entity of the response SHOULD contain a short hypertext note with a hyperlink to the new URI(s).
--   </pre>
--   
--   This is because pre-HTTP/1.1 user agents do not support 303. However,
--   in practice you can probably just use <tt>""</tt> as the second
--   argument.
seeOther :: ToSURI uri => uri -> a -> ServerPart a

-- | Set an arbitrary return code in your response.
--   
--   A filter for setting the response code. Generally you will use a
--   helper function like <a>ok</a> or <a>seeOther</a>.
--   
--   <pre>
--   main = serve Nothing $ do setResponseCode 200
--                             return "Everything is OK"
--   </pre>
setResponseCode :: Int -> ServerPart ()

-- | Gets the first matching named input parameter as a lazy
--   <a>ByteString</a>
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   see also: <a>lookBSs</a>
lookBS :: String -> ServerPart ByteString

-- | Gets all matches for the named input parameter as lazy
--   <a>ByteString</a>s
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   see also: <a>lookBS</a>
lookBSs :: String -> ServerPart [ByteString]

-- | Gets the first matching named input parameter as a lazy <a>Text</a>
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookTexts</a>
lookText :: String -> ServerPart Text

-- | Gets all matches for the named input parameter as lazy <a>Text</a>s
--   
--   Searches the QUERY_STRING followed by the Request body.
--   
--   This function assumes the underlying octets are UTF-8 encoded.
--   
--   see also: <a>lookText</a>
lookTexts :: String -> ServerPart [Text]

-- | Gets the first matching named file
--   
--   Files can only appear in the request body. Additionally, the form must
--   set enctype="multipart/form-data".
--   
--   This function returns a tuple consisting of:
--   
--   <ol>
--   <li>The temporary location of the uploaded file</li>
--   <li>The local filename supplied by the browser</li>
--   <li>The content-type supplied by the browser</li>
--   </ol>
--   
--   NOTE: You must move the file from the temporary location before the
--   <a>Response</a> is sent. The temporary files are automatically removed
--   after the <a>Response</a> is sent.
lookFile :: String -> ServerPart (FilePath, FilePath, ContentType)

-- | A MIME media type value. The <a>Show</a> instance is derived
--   automatically. Use <a>showContentType</a> to obtain the standard
--   string representation. See <a>http://www.ietf.org/rfc/rfc2046.txt</a>
--   for more information about MIME media types.
data ContentType :: *
ContentType :: String -> String -> [(String, String)] -> ContentType

-- | The top-level media type, the general type of the data. Common
--   examples are "text", "image", "audio", "video", "multipart", and
--   "application".
ctType :: ContentType -> String

-- | The media subtype, the specific data format. Examples include "plain",
--   "html", "jpeg", "form-data", etc.
ctSubtype :: ContentType -> String

-- | Media type parameters. On common example is the charset parameter for
--   the "text" top-level type, e.g. <tt>("charset","ISO-8859-1")</tt>.
ctParameters :: ContentType -> [(String, String)]

-- | a type for HTTP cookies. Usually created using <a>mkCookie</a>.
data Cookie :: *
Cookie :: String -> String -> String -> String -> String -> Bool -> Bool -> Cookie
cookieVersion :: Cookie -> String
cookiePath :: Cookie -> String
cookieDomain :: Cookie -> String
cookieName :: Cookie -> String
cookieValue :: Cookie -> String
secure :: Cookie -> Bool
httpOnly :: Cookie -> Bool

-- | Specify the lifetime of a cookie.
--   
--   Note that we always set the max-age and expires headers because
--   internet explorer does not honor max-age. You can specific
--   <a>MaxAge</a> or <a>Expires</a> and the other will be calculated for
--   you. Choose which ever one makes your life easiest.
data CookieLife :: *

-- | session cookie - expires when browser is closed
Session :: CookieLife

-- | life time of cookie in seconds
MaxAge :: Int -> CookieLife

-- | cookie expiration date
Expires :: UTCTime -> CookieLife

-- | cookie already expired
Expired :: CookieLife

-- | Creates a cookie with a default version of 1, empty domain, a path of
--   <a>/</a>, secure == False and httpOnly == False
--   
--   see also: <tt>addCookie</tt>
mkCookie :: String -> String -> Cookie

-- | Add the list <a>Cookie</a> to the <a>Response</a>.
addCookies :: [(CookieLife, Cookie)] -> ServerPart ()

-- | Expire the named cookie immediately and set the cookie value to
--   <tt>""</tt>
--   
--   <pre>
--   main = serve Nothing $
--     do expireCookie "name"
--        ok $ "The cookie has been expired."
--   </pre>
expireCookie :: String -> ServerPart ()

-- | gets the named cookie as a string
lookCookieValue :: String -> ServerPart String

-- | Add headers into the response. This method does not overwrite any
--   existing header of the same name, hence the name <a>addHeaderM</a>. If
--   you want to replace a header use <a>setHeaderM</a>.
addHeaderM :: String -> String -> ServerPart ()

-- | Set a header into the response. This will replace an existing header
--   of the same name. Use <a>addHeaderM</a> if you want to add more than
--   one header of the same name.
setHeaderM :: String -> String -> ServerPart ()

-- | Get a header out of the request.
getHeaderM :: String -> ServerPart (Maybe ByteString)

-- | see <a>serveDirectory</a>
data Browsing :: *
EnableBrowsing :: Browsing
DisableBrowsing :: Browsing

-- | Serve files and directories from a directory and its subdirectories
--   using <tt>sendFile</tt>.
--   
--   Usage:
--   
--   <pre>
--   serveDirectory EnableBrowsing ["index.html"] "path/to/files/on/disk"
--   </pre>
--   
--   If the requested path does not match a file or directory on the disk,
--   then <a>serveDirectory</a> calls <a>mzero</a>.
--   
--   If the requested path is a file then the file is served normally.
--   
--   If the requested path is a directory, then the result depends on what
--   the first two arguments to the function are.
--   
--   The first argument controls whether directory browsing is enabled.
--   
--   The second argument is a list of index files (such as index.html).
--   
--   When a directory is requested, <a>serveDirectory</a> will first try to
--   find one of the index files (in the order they are listed). If that
--   fails, it will show a directory listing if <tt>EnableBrowsing</tt> is
--   set, otherwise it will return <tt>forbidden "Directory index
--   forbidden"</tt>.
--   
--   Here is an explicit list of all the possible outcomes when the
--   argument is a (valid) directory:
--   
--   <ul>
--   <li><i><tt><tt>DisableBrowsing</tt>, empty index file
--   list</tt></i></li>
--   </ul>
--   
--   This will always return, forbidden "Directory index forbidden"
--   
--   <ul>
--   <li><i><tt><tt>DisableBrowsing</tt>, non-empty index file
--   list</tt></i></li>
--   </ul>
--   
--   <ol>
--   <li>If an index file is found it will be shown.</li>
--   <li>Otherwise returns, forbidden "Directory index forbidden"</li>
--   </ol>
--   
--   <ul>
--   <li><i><tt><tt>EnableBrowsing</tt>, empty index file
--   list</tt></i></li>
--   </ul>
--   
--   Always shows a directory index.
--   
--   <ul>
--   <li><i><tt><tt>EnableBrowsing</tt>, non-empty index file
--   list</tt></i></li>
--   </ul>
--   
--   <ol>
--   <li>If an index file is found it will be shown</li>
--   <li>Otherwise shows a directory index</li>
--   </ol>
--   
--   see also: <a>serveFile</a>
serveDirectory :: Browsing -> [FilePath] -> FilePath -> ServerPart Response

-- | Serve a single, specified file. The name of the file being served is
--   specified explicity. It is not derived automatically from the
--   <a>Request</a> url.
--   
--   example 1:
--   
--   Serve as a specific content-type:
--   
--   <pre>
--   serveFile (asContentType "image/jpeg") "/srv/data/image.jpg"
--   </pre>
--   
--   example 2:
--   
--   Serve guessing the content-type from the extension:
--   
--   <pre>
--   serveFile (guessContentTypeM mimeTypes) "/srv/data/image.jpg"
--   </pre>
--   
--   If the specified path does not exist or is not a file, this function
--   will return <a>mzero</a>.
--   
--   WARNING: No security checks are performed.
--   
--   NOTE: alias for <tt>serveFileUsing</tt> <tt>filePathSendFile</tt>
serveFile :: (FilePath -> ServerPart String) -> FilePath -> ServerPart Response

-- | returns a specific content type, completely ignoring the
--   <a>FilePath</a> argument.
--   
--   Use this with <a>serveFile</a> if you want to explicitly specify the
--   content-type.
--   
--   see also: <a>serveFile</a>
asContentType :: String -> (FilePath -> ServerPart String)

-- | a <a>Map</a> from file extensions to content-types
--   
--   example:
--   
--   <pre>
--   myMimeMap :: MimeMap
--   myMimeMap = Map.fromList [("gz","application/x-gzip"), ... ]
--   </pre>
--   
--   see also: <a>mimeTypes</a>
type MimeMap = Map String String

-- | try to guess the content-type of a file based on its extension
--   
--   defaults to <a>application/octet-stream</a> if no match was found.
--   
--   Useful as an argument to <a>serveFile</a>
--   
--   see also: <a>serveFile</a>, <a>mimeTypes</a>
guessContentTypeM :: MimeMap -> (FilePath -> ServerPart String)

-- | Ready collection of common mime types. Except for the first two
--   entries, the mappings come from an Ubuntu 8.04 /etc/mime.types file.
mimeTypes :: MimeMap

-- | Monads that also support choice and failure.
class Monad m => MonadPlus (m :: * -> *)
mzero :: MonadPlus m => m a
mplus :: MonadPlus m => m a -> m a -> m a

-- | This generalizes the list-based <a>concat</a> function.
msum :: MonadPlus m => [m a] -> m a