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


-- | A library for writing CGI programs
--   
--   This is a Haskell library for writing CGI programs.
@package cgi
@version 3001.1.8


-- | An implementation of the program side of the CGI protocol.
module Network.CGI.Protocol

-- | The input to a CGI action.
data CGIRequest
CGIRequest :: Map String String -> [(String, Input)] -> ByteString -> CGIRequest

-- | Environment variables.
cgiVars :: CGIRequest -> Map String String

-- | Input parameters. For better laziness in reading inputs, this is not a
--   Map.
cgiInputs :: CGIRequest -> [(String, Input)]

-- | Raw request body. To avoid memory leaks, this is the empty string if
--   the request body has been interpreted as inputs in
--   <a>application/x-www-form-urlencoded</a> or <a>multipart/form-data</a>
--   format.
cgiRequestBody :: CGIRequest -> ByteString

-- | The value of an input parameter, and some metadata.
data Input
Input :: ByteString -> Maybe String -> ContentType -> Input
inputValue :: Input -> ByteString
inputFilename :: Input -> Maybe String
inputContentType :: Input -> ContentType

-- | The result of a CGI program.
data CGIResult
CGIOutput :: ByteString -> CGIResult
CGINothing :: CGIResult

-- | HTTP headers.
type Headers = [(HeaderName, String)]

-- | A string with case insensitive equality and comparisons.
newtype HeaderName
HeaderName :: String -> HeaderName

-- | Runs a CGI action in a given environment. Uses Handles for input and
--   output.
hRunCGI :: (MonadIO m) => [(String, String)] -> Handle -> Handle -> (CGIRequest -> m (Headers, CGIResult)) -> m ()

-- | Runs a CGI action in a given environment. Uses lazy ByteStrings for
--   input and output.
runCGIEnvFPS :: (Monad m) => [(String, String)] -> ByteString -> (CGIRequest -> m (Headers, CGIResult)) -> m ByteString

-- | Gets and decodes the input according to the request method and the
--   content-type.
decodeInput :: [(String, String)] -> ByteString -> ([(String, Input)], ByteString)

-- | Takes the right number of bytes from the input.
takeInput :: [(String, String)] -> ByteString -> ByteString

-- | Gets the values of all CGI variables from the program environment.
getCGIVars :: (MonadIO m) => m [(String, String)]

-- | Logs some message using the server's logging facility. FIXME: does
--   this have to be more general to support FastCGI etc? Maybe we should
--   store log messages in the CGIState?
logCGI :: (MonadIO m) => String -> m ()

-- | Formats name-value pairs as application/x-www-form-urlencoded.
formEncode :: [(String, String)] -> String

-- | Converts a single value to the application/x-www-form-urlencoded
--   encoding.
urlEncode :: String -> String

-- | Gets the name-value pairs from application/x-www-form-urlencoded data.
formDecode :: String -> [(String, String)]

-- | Converts a single value from the application/x-www-form-urlencoded
--   encoding.
urlDecode :: String -> String
maybeRead :: (Read a) => String -> Maybe a

-- | Replaces all instances of a value in a list by another value.
replace :: (Eq a) => a -> a -> [a] -> [a]
instance Show CGIResult
instance Read CGIResult
instance Eq CGIResult
instance Ord CGIResult
instance Show Input
instance Show CGIRequest
instance Typeable CGIResult


-- | Internal stuff that most people shouldn't have to use. This module
--   mostly deals with the internals of the CGIT monad transformer.
module Network.CGI.Monad

-- | The class of CGI monads. Most CGI actions can be run in any monad
--   which is an instance of this class, which means that you can use your
--   own monad transformers to add extra functionality.
class (Monad m) => MonadCGI m
cgiAddHeader :: (MonadCGI m) => HeaderName -> String -> m ()
cgiGet :: (MonadCGI m) => (CGIRequest -> a) -> m a

-- | The CGIT monad transformer.
newtype CGIT m a
CGIT :: ReaderT CGIRequest (WriterT Headers m) a -> CGIT m a
unCGIT :: CGIT m a -> ReaderT CGIRequest (WriterT Headers m) a

-- | A simple CGI monad with just IO.
type CGI a = CGIT IO a

-- | Run a CGI action.
runCGIT :: (Monad m) => CGIT m a -> CGIRequest -> m (Headers, a)

-- | The input to a CGI action.
data CGIRequest
CGIRequest :: Map String String -> [(String, Input)] -> ByteString -> CGIRequest

-- | Environment variables.
cgiVars :: CGIRequest -> Map String String

-- | Input parameters. For better laziness in reading inputs, this is not a
--   Map.
cgiInputs :: CGIRequest -> [(String, Input)]

-- | Raw request body. To avoid memory leaks, this is the empty string if
--   the request body has been interpreted as inputs in
--   <a>application/x-www-form-urlencoded</a> or <a>multipart/form-data</a>
--   format.
cgiRequestBody :: CGIRequest -> ByteString

-- | Throw an exception in a CGI monad. The monad is required to be a
--   <a>MonadIO</a>, so that we can use <a>throwIO</a> to guarantee
--   ordering.
throwCGI :: (MonadCGI m, MonadIO m) => SomeException -> m a

-- | Catches any expection thrown by a CGI action, and uses the given
--   exception handler if an exception is thrown.
catchCGI :: (MonadCGI m, MonadCatchIO m) => m a -> (SomeException -> m a) -> m a

-- | Catches any exception thrown by an CGI action, and returns either the
--   exception, or if no exception was raised, the result of the action.
tryCGI :: (MonadCGI m, MonadCatchIO m) => m a -> m (Either SomeException a)

-- | Deprecated version of <a>catchCGI</a>. Use <a>catchCGI</a> instead.
handleExceptionCGI :: (MonadCGI m, MonadCatchIO m) => m a -> (SomeException -> m a) -> m a
instance (MonadCatchIO m) => MonadError SomeException (CGIT m)
instance MonadTrans CGIT
instance (Monad m) => MonadCGI (CGIT m)
instance (MonadCatchIO m) => MonadCatchIO (CGIT m)
instance (MonadIO m) => MonadIO (CGIT m)
instance (Monad m) => Monad (CGIT m)
instance (Monad m) => Functor (CGIT m)
instance (Typeable1 m, Typeable a) => Typeable (CGIT m a)


-- | TODO
--   
--   <ul>
--   <li>Add client side stuff (basically parsing Set-Cookie: value)</li>
--   <li>Update for RFC2109 <a>http://www.ietf.org/rfc/rfc2109.txt</a></li>
--   </ul>
module Network.CGI.Cookie

-- | Contains all information about a cookie set by the server.
data Cookie
Cookie :: String -> String -> Maybe CalendarTime -> Maybe String -> Maybe String -> Bool -> Cookie

-- | Name of the cookie.
cookieName :: Cookie -> String

-- | Value of the cookie.
cookieValue :: Cookie -> String

-- | Expiry date of the cookie. If <a>Nothing</a>, the cookie expires when
--   the browser sessions ends. If the date is in the past, the client
--   should delete the cookie immediately.
cookieExpires :: Cookie -> Maybe CalendarTime

-- | The domain suffix to which this cookie will be sent.
cookieDomain :: Cookie -> Maybe String

-- | The path to which this cookie will be sent.
cookiePath :: Cookie -> Maybe String

-- | <a>True</a> if this cookie should only be sent using secure means.
cookieSecure :: Cookie -> Bool

-- | Construct a cookie with only name and value set. This client will
--   expire when the browser sessions ends, will only be sent to the server
--   and path which set it and may be sent using any means.
newCookie :: String -> String -> Cookie

-- | Get the value of a cookie from a string on the form
--   <tt>"cookieName1=cookieValue1;...;cookieName2=cookieValue2"</tt>. This
--   is the format of the <tt>Cookie</tt> HTTP header.
findCookie :: String -> String -> Maybe String

-- | Delete a cookie from the client by setting the cookie expiry date to a
--   date in the past.
deleteCookie :: Cookie -> Cookie

-- | Show a cookie on the format used as the value of the Set-Cookie
--   header.
showCookie :: Cookie -> String

-- | Gets all the cookies from a Cookie: header value
readCookies :: String -> [(String, String)]
instance Show Cookie
instance Read Cookie
instance Eq Cookie
instance Ord Cookie


-- | Compatibility functions for the old Network.CGI API.
module Network.CGI.Compat
data Html :: *

-- | Compatibility wrapper for the old CGI interface. Output the output
--   from a function from CGI environment and input variables to an HTML
--   document.
wrapper :: ([(String, String)] -> IO Html) -> IO ()

-- | Compatibility wrapper for the old CGI interface. Runs a simple CGI
--   server. Note: if using Windows, you might need to wrap
--   <tt>Network.withSocketsDo</tt> around main.
pwrapper :: PortID -> ([(String, String)] -> IO Html) -> IO ()

-- | Note: if using Windows, you might need to wrap
--   <tt>Network.withSocketsDo</tt> around main.
connectToCGIScript :: String -> PortID -> IO ()


-- | Simple Library for writing CGI programs. See
--   <a>http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</a> for the CGI
--   specification.
--   
--   This version of the library is for systems with version 2.0 or greater
--   of the network package. This includes GHC 6.6 and later. For older
--   systems, see
--   <a>http://www.cs.chalmers.se/~bringert/darcs/cgi-compat/doc/</a>
--   
--   Based on the original Haskell binding for CGI:
--   
--   Original Version by Erik Meijer <a>mailto:erik@cs.ruu.nl</a>. Further
--   hacked on by Sven Panne <a>mailto:sven.panne@aedion.de</a>. Further
--   hacking by Andy Gill <a>mailto:andy@galconn.com</a>. A new, hopefully
--   more flexible, interface and support for file uploads by Bjorn
--   Bringert <a>mailto:bjorn@bringert.net</a>.
--   
--   Here is a simple example, including error handling (not that there is
--   much that can go wrong with Hello World):
--   
--   <pre>
--   import Network.CGI
--   
--   cgiMain :: CGI CGIResult
--   cgiMain = output "Hello World!"
--   
--   main :: IO ()
--   main = runCGI (handleErrors cgiMain)
--   </pre>
module Network.CGI

-- | The class of CGI monads. Most CGI actions can be run in any monad
--   which is an instance of this class, which means that you can use your
--   own monad transformers to add extra functionality.
class (Monad m) => MonadCGI m

-- | The CGIT monad transformer.
data CGIT m a

-- | The result of a CGI program.
data CGIResult

-- | A simple CGI monad with just IO.
type CGI a = CGIT IO a
class (Monad m) => MonadIO m :: (* -> *)
liftIO :: (MonadIO m) => IO a -> m a
liftIO :: (MonadIO m) => forall a. IO a -> m a

-- | Run a CGI action. Typically called by the main function. Reads input
--   from stdin and writes to stdout. Gets CGI environment variables from
--   the program environment.
runCGI :: (MonadIO m) => CGIT m CGIResult -> m ()

-- | Throw an exception in a CGI monad. The monad is required to be a
--   <a>MonadIO</a>, so that we can use <a>throwIO</a> to guarantee
--   ordering.
throwCGI :: (MonadCGI m, MonadIO m) => SomeException -> m a

-- | Catches any expection thrown by a CGI action, and uses the given
--   exception handler if an exception is thrown.
catchCGI :: (MonadCGI m, MonadCatchIO m) => m a -> (SomeException -> m a) -> m a

-- | Catches any exception thrown by an CGI action, and returns either the
--   exception, or if no exception was raised, the result of the action.
tryCGI :: (MonadCGI m, MonadCatchIO m) => m a -> m (Either SomeException a)

-- | Deprecated version of <a>catchCGI</a>. Use <a>catchCGI</a> instead.
handleExceptionCGI :: (MonadCGI m, MonadCatchIO m) => m a -> (SomeException -> m a) -> m a

-- | Catches any exception thrown by the given CGI action, returns an error
--   page with a 500 Internal Server Error, showing the exception
--   information, and logs the error.
--   
--   Typical usage:
--   
--   <pre>
--   cgiMain :: CGI CGIResult
--   cgiMain = ...
--   
--   main :: IO ()
--   main = runCGI (handleErrors cgiMain)
--   </pre>
handleErrors :: (MonadCGI m, MonadCatchIO m) => m CGIResult -> m CGIResult

-- | Logs some message using the server's logging facility. FIXME: does
--   this have to be more general to support FastCGI etc? Maybe we should
--   store log messages in the CGIState?
logCGI :: (MonadIO m) => String -> m ()

-- | Output a <a>String</a>. The output is assumed to be text/html, encoded
--   using ISO-8859-1. To change this, set the Content-type header using
--   <a>setHeader</a>.
output :: (MonadCGI m) => String -> m CGIResult

-- | Output a <a>ByteString</a>. The output is assumed to be text/html,
--   encoded using ISO-8859-1. To change this, set the Content-type header
--   using <a>setHeader</a>.
outputFPS :: (MonadCGI m) => ByteString -> m CGIResult

-- | Do not output anything (except headers).
outputNothing :: (MonadCGI m) => m CGIResult

-- | Redirect to some location.
redirect :: (MonadCGI m) => String -> m CGIResult

-- | Add a response header. Example:
--   
--   <pre>
--   setHeader "Content-type" "text/plain"
--   </pre>
setHeader :: (MonadCGI m) => String -> String -> m ()

-- | Set the HTTP response status.
setStatus :: (MonadCGI m) => Int -> String -> m ()

-- | Output an error page to the user, with the given HTTP status code in
--   the response. Also logs the error information using <a>logCGI</a>.
outputError :: (MonadCGI m, MonadIO m) => Int -> String -> [String] -> m CGIResult

-- | Output a 500 Internal Server Error with information from an
--   <a>Exception</a>.
outputException :: (MonadCGI m, MonadIO m) => SomeException -> m CGIResult

-- | Use <a>outputError</a> to output and log a 404 Not Found error.
outputNotFound :: (MonadIO m, MonadCGI m) => String -> m CGIResult

-- | Use <a>outputError</a> to output and log a 405 Method Not Allowed
--   error.
outputMethodNotAllowed :: (MonadIO m, MonadCGI m) => [String] -> m CGIResult

-- | Use <a>outputError</a> to output and log a 500 Internal Server Error.
outputInternalServerError :: (MonadIO m, MonadCGI m) => [String] -> m CGIResult

-- | Get the value of an input variable, for example from a form. If the
--   variable has multiple values, the first one is returned. Example:
--   
--   <pre>
--   query &lt;- getInput "query"
--   </pre>
getInput :: (MonadCGI m) => String -> m (Maybe String)

-- | Like <a>getInput</a>, but returns a <a>ByteString</a>.
getInputFPS :: (MonadCGI m) => String -> m (Maybe ByteString)

-- | Same as <a>getInput</a>, but tries to read the value to the desired
--   type.
readInput :: (Read a, MonadCGI m) => String -> m (Maybe a)

-- | Get the uninterpreted request body as a String
getBody :: (MonadCGI m) => m String

-- | Get the uninterpreted request body as lazy ByteString
getBodyFPS :: (MonadCGI m) => m ByteString

-- | Get the names and values of all inputs. Note: the same name may occur
--   more than once in the output, if there are several values for the
--   name.
getInputs :: (MonadCGI m) => m [(String, String)]

-- | Get the names and values of all inputs. Note: the same name may occur
--   more than once in the output, if there are several values for the
--   name.
getInputsFPS :: (MonadCGI m) => m [(String, ByteString)]

-- | Get the names of all input variables.
getInputNames :: (MonadCGI m) => m [String]

-- | Get all the values of an input variable, for example from a form. This
--   can be used to get all the values from form controls which allow
--   multiple values to be selected. Example:
--   
--   <pre>
--   vals &lt;- getMultiInput "my_checkboxes"
--   </pre>
getMultiInput :: (MonadCGI m) => String -> m [String]

-- | Same as <a>getMultiInput</a> but using <a>ByteString</a>s.
getMultiInputFPS :: (MonadCGI m) => String -> m [ByteString]

-- | Get the file name of an input.
getInputFilename :: (MonadCGI m) => String -> m (Maybe String)

-- | Get the content-type of an input, if the input exists, e.g.
--   <a>image/jpeg</a>. For non-file inputs, this function returns
--   <a>text/plain</a>. You can use <a>parseContentType</a> to get a
--   structured representation of the the content-type value.
getInputContentType :: (MonadCGI m) => String -> m (Maybe String)

-- | Get the value of a CGI environment variable. Example:
--   
--   <pre>
--   remoteAddr &lt;- getVar "REMOTE_ADDR"
--   </pre>
getVar :: (MonadCGI m) => String -> m (Maybe String)
getVarWithDefault :: (MonadCGI m) => String -> String -> m String

-- | Get all CGI environment variables and their values.
getVars :: (MonadCGI m) => m [(String, String)]

-- | The server's hostname, DNS alias, or IP address as it would appear in
--   self-referencing URLs.
serverName :: (MonadCGI m) => m String

-- | The port number to which the request was sent.
serverPort :: (MonadCGI m) => m Int

-- | The method with which the request was made. For HTTP, this is "GET",
--   "HEAD", "POST", etc.
requestMethod :: (MonadCGI m) => m String

-- | The extra path information, as given by the client. This is any part
--   of the request path that follows the CGI program path. If the string
--   returned by this function is not empty, it is guaranteed to start with
--   a <tt>'/'</tt>.
--   
--   Note that this function returns an unencoded string. Make sure to
--   percent-encode any characters that are not allowed in URI paths before
--   using the result of this function to construct a URI. See
--   <a>progURI</a>, <a>queryURI</a> and <a>requestURI</a> for a
--   higher-level interface.
pathInfo :: (MonadCGI m) => m String

-- | The path returned by <a>pathInfo</a>, but with virtual-to-physical
--   mapping applied to it.
pathTranslated :: (MonadCGI m) => m String

-- | A virtual path to the script being executed, used for self-referencing
--   URIs.
--   
--   Note that this function returns an unencoded string. Make sure to
--   percent-encode any characters that are not allowed in URI paths before
--   using the result of this function to construct a URI. See
--   <a>progURI</a>, <a>queryURI</a> and <a>requestURI</a> for a
--   higher-level interface.
scriptName :: (MonadCGI m) => m String

-- | The information which follows the ? in the URL which referenced this
--   program. This is the percent-encoded query information. For most
--   normal uses, <a>getInput</a> and friends are probably more convenient.
queryString :: (MonadCGI m) => m String

-- | The hostname making the request. If the server does not have this
--   information, Nothing is returned. See also <a>remoteAddr</a>.
remoteHost :: (MonadCGI m) => m (Maybe String)

-- | The IP address of the remote host making the request.
remoteAddr :: (MonadCGI m) => m String

-- | If the server supports user authentication, and the script is
--   protected, this is the protocol-specific authentication method used to
--   validate the user.
authType :: (MonadCGI m) => m (Maybe String)

-- | If the server supports user authentication, and the script is
--   protected, this is the username they have authenticated as.
remoteUser :: (MonadCGI m) => m (Maybe String)

-- | For queries which have attached information, such as HTTP POST and
--   PUT, this is the content type of the data. You can use
--   <a>parseContentType</a> to get a structured representation of the the
--   content-type value.
requestContentType :: (MonadCGI m) => m (Maybe String)

-- | For queries which have attached information, such as HTTP POST and
--   PUT, this is the length of the content given by the client.
requestContentLength :: (MonadCGI m) => m (Maybe Int)

-- | Gets the value of the request header with the given name. The header
--   name is case-insensitive. Example:
--   
--   <pre>
--   requestHeader "User-Agent"
--   </pre>
requestHeader :: (MonadCGI m) => String -> m (Maybe String)

-- | Attempts to reconstruct the absolute URI of this program. This does
--   not include any extra path information or query parameters. See
--   <a>queryURI</a> for that. If the server is rewriting request URIs,
--   this URI can be different from the one requested by the client. See
--   also <a>requestURI</a>.
--   
--   Characters in the components of the returned URI are escaped when
--   needed, as required by <a>Network.URI</a>.
progURI :: (MonadCGI m) => m URI

-- | Like <a>progURI</a>, but the returned <a>URI</a> also includes any
--   extra path information, and any query parameters. If the server is
--   rewriting request URIs, this URI can be different from the one
--   requested by the client. See also <a>requestURI</a>.
--   
--   Characters in the components of the returned URI are escaped when
--   needed, as required by <a>Network.URI</a>.
queryURI :: (MonadCGI m) => m URI

-- | Attempts to reconstruct the absolute URI requested by the client,
--   including extra path information and query parameters. If no request
--   URI rewriting is done, or if the web server does not provide the
--   information needed to reconstruct the request URI, this function
--   returns the same value as <a>queryURI</a>.
--   
--   Characters in the components of the returned URI are escaped when
--   needed, as required by <a>Network.URI</a>.
requestURI :: (MonadCGI m) => m URI
class (Eq a) => Acceptable a
data Accept a
newtype Charset
Charset :: String -> Charset
newtype ContentEncoding
ContentEncoding :: String -> ContentEncoding
newtype Language
Language :: String -> Language
requestAccept :: (MonadCGI m) => m (Maybe (Accept ContentType))
requestAcceptCharset :: (MonadCGI m) => m (Maybe (Accept Charset))
requestAcceptEncoding :: (MonadCGI m) => m (Maybe (Accept ContentEncoding))
requestAcceptLanguage :: (MonadCGI m) => m (Maybe (Accept Language))
negotiate :: (Acceptable a) => [a] -> Maybe (Accept a) -> [a]

-- | 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)]
showContentType :: ContentType -> String

-- | Parse the standard representation of a content-type. If the input
--   cannot be parsed, this function calls <a>fail</a> with a (hopefully)
--   informative error message.
parseContentType :: (Monad m) => String -> m ContentType

-- | Contains all information about a cookie set by the server.
data Cookie
Cookie :: String -> String -> Maybe CalendarTime -> Maybe String -> Maybe String -> Bool -> Cookie

-- | Name of the cookie.
cookieName :: Cookie -> String

-- | Value of the cookie.
cookieValue :: Cookie -> String

-- | Expiry date of the cookie. If <a>Nothing</a>, the cookie expires when
--   the browser sessions ends. If the date is in the past, the client
--   should delete the cookie immediately.
cookieExpires :: Cookie -> Maybe CalendarTime

-- | The domain suffix to which this cookie will be sent.
cookieDomain :: Cookie -> Maybe String

-- | The path to which this cookie will be sent.
cookiePath :: Cookie -> Maybe String

-- | <a>True</a> if this cookie should only be sent using secure means.
cookieSecure :: Cookie -> Bool

-- | Construct a cookie with only name and value set. This client will
--   expire when the browser sessions ends, will only be sent to the server
--   and path which set it and may be sent using any means.
newCookie :: String -> String -> Cookie

-- | Get the value of a cookie.
getCookie :: (MonadCGI m) => String -> m (Maybe String)

-- | Same as <a>getCookie</a>, but tries to read the value to the desired
--   type.
readCookie :: (Read a, MonadCGI m) => String -> m (Maybe a)

-- | Set a cookie.
setCookie :: (MonadCGI m) => Cookie -> m ()

-- | Delete a cookie from the client
deleteCookie :: (MonadCGI m) => Cookie -> m ()

-- | Formats name-value pairs as application/x-www-form-urlencoded.
formEncode :: [(String, String)] -> String

-- | Converts a single value to the application/x-www-form-urlencoded
--   encoding.
urlEncode :: String -> String

-- | Gets the name-value pairs from application/x-www-form-urlencoded data.
formDecode :: String -> [(String, String)]

-- | Converts a single value from the application/x-www-form-urlencoded
--   encoding.
urlDecode :: String -> String