-----------------------------------------------------------------------------
-- |
-- Module      :  Network.CGI
-- Copyright   :  (c) The University of Glasgow 2001
--                (c) Bjorn Bringert 2004-2006
--                (c) Ian Lynagh 2005
--                (c) Jeremy Shaw 2005
-- License     :  BSD-style
--
-- Maintainer  :  John Chee <cheecheeo@gmail.com>
-- Stability   :  experimental
-- Portability :  non-portable (uses Control.Monad.State)
--
-- Simple Library for writing CGI programs.
-- See <https://web.archive.org/web/20100109233524/http://hoohoo.ncsa.illinois.edu/cgi/interface.html> 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 <http://www.cs.chalmers.se/~bringert/darcs/cgi-compat/doc/>
--
-- Based on the original Haskell binding for CGI:
--
-- Original Version by Erik Meijer <mailto:erik@cs.ruu.nl>.
-- Further hacked on by Sven Panne <mailto:sven.panne@aedion.de>.
-- Further hacking by Andy Gill <mailto:andy@galconn.com>.
-- A new, hopefully more flexible, interface
-- and support for file uploads by Bjorn Bringert <mailto:bjorn@bringert.net>.
--
-- Here is a simple example, including error handling (not that there is
-- much that can go wrong with Hello World):
--
-- > import Network.CGI
-- >
-- > cgiMain :: CGI CGIResult
-- > cgiMain = output "Hello World!"
-- >
-- > main :: IO ()
-- > main = runCGI (handleErrors cgiMain)
--
--
-----------------------------------------------------------------------------

module Network.CGI (
  -- * CGI monad
    MonadCGI, CGIT, CGIResult, CGI
  , MonadIO, liftIO
  , runCGI
  -- * Error handling
  , throwCGI, catchCGI, tryCGI, handleExceptionCGI
  , handleErrors
  -- * Logging
  , logCGI
  -- * Output
  , output, outputFPS, outputNothing, redirect
  , setHeader, setStatus
  -- * Error pages
  , outputError, outputException
  , outputNotFound, outputMethodNotAllowed, outputInternalServerError
  -- * Input
  , getInput, getInputFPS, readInput
  , getBody, getBodyFPS
  , getInputs, getInputsFPS, getInputNames
  , getMultiInput, getMultiInputFPS
  , getInputFilename, getInputContentType
  -- * Environment
  , getVar, getVarWithDefault, getVars
  -- * Request information
  , serverName, serverPort
  , requestMethod, pathInfo
  , pathTranslated, scriptName
  , queryString
  , remoteHost, remoteAddr
  , authType, remoteUser
  , requestContentType, requestContentLength
  , requestHeader
  -- * Program and request URI
  , progURI, queryURI, requestURI
  -- * Content negotiation
  , Acceptable, Accept
  , Charset(..), ContentEncoding(..), Language(..)
  , requestAccept, requestAcceptCharset, requestAcceptEncoding, requestAcceptLanguage
  , negotiate
  -- * Content type
  , ContentType(..), showContentType, parseContentType
  -- * Cookies
  , Cookie(..), newCookie
  , getCookie, readCookie
  , setCookie, deleteCookie
  -- * URL encoding
  , formEncode, urlEncode, formDecode, urlDecode
  ) where

import Control.Exception (Exception(..), SomeException, ErrorCall(..))
import Control.Monad.Catch (MonadCatch(..), handle)
import Control.Monad.Trans (MonadIO, liftIO)
import Data.Char (toUpper)
import Data.List (intercalate, sort, group)
import Data.Maybe (fromMaybe, isJust)
import qualified Data.Map as Map
import Network.Multipart
import Network.Multipart.Header
import Network.URI (URI(..), URIAuth(..), nullURI, parseRelativeReference,
                    escapeURIString, isUnescapedInURI)
import System.IO (stdin, stdout)

import qualified Data.ByteString.Lazy.Char8 as BS
import Data.ByteString.Lazy.Char8 (ByteString)

import Network.CGI.Cookie (Cookie(..), showCookie, newCookie, findCookie)
import qualified Network.CGI.Cookie as Cookie (deleteCookie)
import Network.CGI.Accept
import Network.CGI.Monad
import Network.CGI.Protocol

import Text.XHtml (Html, renderHtml, header, (<<), thetitle, (+++),
                   body, h1, paragraph, hr, address)

-- | 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 ()
runCGI :: forall (m :: * -> *). MonadIO m => CGIT m CGIResult -> m ()
runCGI CGIT m CGIResult
f = do [(String, String)]
env <- forall (m :: * -> *). MonadIO m => m [(String, String)]
getCGIVars
              forall (m :: * -> *).
MonadIO m =>
[(String, String)]
-> Handle
-> Handle
-> (CGIRequest -> m (Headers, CGIResult))
-> m ()
hRunCGI [(String, String)]
env Handle
stdin Handle
stdout (forall (m :: * -> *) a.
Monad m =>
CGIT m a -> CGIRequest -> m (Headers, a)
runCGIT CGIT m CGIResult
f)


--
-- * Output \/ redirect
--

-- | Output a 'String'. The output is assumed to be text\/html, encoded using
--   ISO-8859-1. To change this, set the Content-type header using
--   'setHeader'.
output :: MonadCGI m =>
          String        -- ^ The string to output.
       -> m CGIResult
output :: forall (m :: * -> *). MonadCGI m => String -> m CGIResult
output = forall (m :: * -> *) a. Monad m => a -> m a
return forall b c a. (b -> c) -> (a -> b) -> a -> c
. ByteString -> CGIResult
CGIOutput forall b c a. (b -> c) -> (a -> b) -> a -> c
. String -> ByteString
BS.pack

-- | Output a 'ByteString'. The output is assumed to be text\/html,
--   encoded using ISO-8859-1. To change this, set the
--   Content-type header using 'setHeader'.
outputFPS :: MonadCGI m =>
             ByteString        -- ^ The string to output.
          -> m CGIResult
outputFPS :: forall (m :: * -> *). MonadCGI m => ByteString -> m CGIResult
outputFPS = forall (m :: * -> *) a. Monad m => a -> m a
return forall b c a. (b -> c) -> (a -> b) -> a -> c
. ByteString -> CGIResult
CGIOutput

-- | Do not output anything (except headers).
outputNothing :: MonadCGI m => m CGIResult
outputNothing :: forall (m :: * -> *). MonadCGI m => m CGIResult
outputNothing = forall (m :: * -> *) a. Monad m => a -> m a
return CGIResult
CGINothing

-- | Redirect to some location.
redirect :: MonadCGI m =>
            String        -- ^ A URL to redirect to.
         -> m CGIResult
redirect :: forall (m :: * -> *). MonadCGI m => String -> m CGIResult
redirect String
url = do forall (m :: * -> *). MonadCGI m => String -> String -> m ()
setHeader String
"Location" String
url
                  forall (m :: * -> *). MonadCGI m => m CGIResult
outputNothing

--
-- * Error handling
--

-- | 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:
--
-- > cgiMain :: CGI CGIResult
-- > cgiMain = ...
-- >
-- > main :: IO ()
-- > main = runCGI (handleErrors cgiMain)
handleErrors :: (MonadCGI m, MonadCatch m, MonadIO m) => m CGIResult -> m CGIResult
handleErrors :: forall (m :: * -> *).
(MonadCGI m, MonadCatch m, MonadIO m) =>
m CGIResult -> m CGIResult
handleErrors = forall (m :: * -> *) e a.
(MonadCatch m, Exception e) =>
(e -> m a) -> m a -> m a
handle forall (m :: * -> *).
(MonadCGI m, MonadIO m) =>
SomeException -> m CGIResult
outputException

--
-- * Error output
--

-- | Output a 500 Internal Server Error with information from
--   an 'Exception'.
outputException :: (MonadCGI m,MonadIO m) => SomeException -> m CGIResult
outputException :: forall (m :: * -> *).
(MonadCGI m, MonadIO m) =>
SomeException -> m CGIResult
outputException SomeException
e = forall (m :: * -> *).
(MonadIO m, MonadCGI m) =>
[String] -> m CGIResult
outputInternalServerError [String]
es
    where es :: [String]
es = case forall e. Exception e => SomeException -> Maybe e
fromException SomeException
e of
                 Just (ErrorCall String
msg) -> [String
msg]
                 Maybe ErrorCall
_ -> [forall a. Show a => a -> String
show SomeException
e]

-- | Output an error page to the user, with the given
--   HTTP status code in the response. Also logs the error information
--   using 'logCGI'.
outputError :: (MonadCGI m, MonadIO m) =>
               Int      -- ^ HTTP Status code
            -> String   -- ^ Status message
            -> [String] -- ^ Error information
            -> m CGIResult
outputError :: forall (m :: * -> *).
(MonadCGI m, MonadIO m) =>
Int -> String -> [String] -> m CGIResult
outputError Int
c String
m [String]
es =
      do forall (m :: * -> *). MonadIO m => String -> m ()
logCGI forall a b. (a -> b) -> a -> b
$ forall a. Show a => a -> String
show (Int
c,String
m,[String]
es)
         forall (m :: * -> *). MonadCGI m => Int -> String -> m ()
setStatus Int
c String
m
         let textType :: ContentType
textType = String -> String -> [(String, String)] -> ContentType
ContentType String
"text" String
"plain" [(String
"charset",String
"ISO-8859-1")]
             htmlType :: ContentType
htmlType = String -> String -> [(String, String)] -> ContentType
ContentType String
"text" String
"html"  [(String
"charset",String
"ISO-8859-1")]
         [ContentType]
cts <- forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall a. Acceptable a => [a] -> Maybe (Accept a) -> [a]
negotiate [ContentType
htmlType,ContentType
textType]) forall (m :: * -> *). MonadCGI m => m (Maybe (Accept ContentType))
requestAccept
         case [ContentType]
cts of
           ContentType
ct:[ContentType]
_ | ContentType
ct forall a. Eq a => a -> a -> Bool
== ContentType
textType ->
                do forall (m :: * -> *). MonadCGI m => String -> String -> m ()
setHeader String
"Content-type" (ContentType -> String
showContentType ContentType
textType)
                   String
text <- forall (m :: * -> *).
MonadCGI m =>
Int -> String -> [String] -> m String
errorText Int
c String
m [String]
es
                   forall (m :: * -> *). MonadCGI m => String -> m CGIResult
output String
text
           [ContentType]
_ -> do forall (m :: * -> *). MonadCGI m => String -> String -> m ()
setHeader String
"Content-type" (ContentType -> String
showContentType ContentType
htmlType)
                   Html
page <- forall (m :: * -> *).
MonadCGI m =>
Int -> String -> [String] -> m Html
errorPage Int
c String
m [String]
es
                   forall (m :: * -> *). MonadCGI m => String -> m CGIResult
output forall a b. (a -> b) -> a -> b
$ forall html. HTML html => html -> String
renderHtml Html
page

-- | Create an HTML error page.
errorPage :: MonadCGI m =>
             Int      -- ^ Status code
          -> String   -- ^ Status message
          -> [String] -- ^ Error information
          -> m Html
errorPage :: forall (m :: * -> *).
MonadCGI m =>
Int -> String -> [String] -> m Html
errorPage Int
c String
m [String]
es =
    do Maybe String
server <- forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"SERVER_SOFTWARE"
       Maybe String
host   <- forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"SERVER_NAME"
       Maybe String
port   <- forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"SERVER_PORT"
       let tit :: String
tit = forall a. Show a => a -> String
show Int
c forall a. [a] -> [a] -> [a]
++ String
" " forall a. [a] -> [a] -> [a]
++ String
m
           sig :: String
sig = String
"Haskell CGI"
                 forall a. [a] -> [a] -> [a]
++ String
" on " forall a. [a] -> [a] -> [a]
++ forall a. a -> Maybe a -> a
fromMaybe String
"" Maybe String
server
                 forall a. [a] -> [a] -> [a]
++ String
" at " forall a. [a] -> [a] -> [a]
++ forall a. a -> Maybe a -> a
fromMaybe String
"" Maybe String
host forall a. [a] -> [a] -> [a]
++ forall b a. b -> (a -> b) -> Maybe a -> b
maybe String
"" (String
", port "forall a. [a] -> [a] -> [a]
++) Maybe String
port
       forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ Html -> Html
header forall a b. HTML a => (Html -> b) -> a -> b
<< Html -> Html
thetitle forall a b. HTML a => (Html -> b) -> a -> b
<< String
tit
                  forall a b. (HTML a, HTML b) => a -> b -> Html
+++ Html -> Html
body forall a b. HTML a => (Html -> b) -> a -> b
<< (Html -> Html
h1 forall a b. HTML a => (Html -> b) -> a -> b
<< String
tit forall a b. (HTML a, HTML b) => a -> b -> Html
+++ forall a b. (a -> b) -> [a] -> [b]
map (Html -> Html
paragraph forall a b. HTML a => (Html -> b) -> a -> b
<<) [String]
es
                               forall a b. (HTML a, HTML b) => a -> b -> Html
+++ Html
hr forall a b. (HTML a, HTML b) => a -> b -> Html
+++ Html -> Html
address forall a b. HTML a => (Html -> b) -> a -> b
<< String
sig)

errorText :: MonadCGI m =>
             Int      -- ^ Status code
          -> String   -- ^ Status message
          -> [String] -- ^ Error information
          -> m String
errorText :: forall (m :: * -> *).
MonadCGI m =>
Int -> String -> [String] -> m String
errorText Int
c String
m [String]
es = forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ [String] -> String
unlines forall a b. (a -> b) -> a -> b
$ (forall a. Show a => a -> String
show Int
c forall a. [a] -> [a] -> [a]
++ String
" " forall a. [a] -> [a] -> [a]
++ String
m) forall a. a -> [a] -> [a]
: [String]
es

--
-- * Specific HTTP errors
--

-- | Use 'outputError' to output and log a 404 Not Found error.
outputNotFound :: (MonadIO m, MonadCGI m) =>
                 String -- ^ The name of the requested resource.
              -> m CGIResult
outputNotFound :: forall (m :: * -> *).
(MonadIO m, MonadCGI m) =>
String -> m CGIResult
outputNotFound String
r =
    forall (m :: * -> *).
(MonadCGI m, MonadIO m) =>
Int -> String -> [String] -> m CGIResult
outputError Int
404 String
"Not Found" [String
"The requested resource was not found: " forall a. [a] -> [a] -> [a]
++ String
r]

-- | Use 'outputError' to output and log a 405 Method Not Allowed error.
outputMethodNotAllowed :: (MonadIO m, MonadCGI m) =>
                          [String] -- ^ The allowed methods.
                       -> m CGIResult
outputMethodNotAllowed :: forall (m :: * -> *).
(MonadIO m, MonadCGI m) =>
[String] -> m CGIResult
outputMethodNotAllowed [String]
ms =
    do let allow :: String
allow = forall a. [a] -> [[a]] -> [a]
intercalate String
", " [String]
ms
       forall (m :: * -> *). MonadCGI m => String -> String -> m ()
setHeader String
"Allow" String
allow
       forall (m :: * -> *).
(MonadCGI m, MonadIO m) =>
Int -> String -> [String] -> m CGIResult
outputError Int
405 String
"Method Not Allowed" [String
"Allowed methods : " forall a. [a] -> [a] -> [a]
++ String
allow]

-- | Use 'outputError' to output and log a 500 Internal Server Error.
outputInternalServerError :: (MonadIO m, MonadCGI m) =>
                             [String] -- ^ Error information.
                          -> m CGIResult
outputInternalServerError :: forall (m :: * -> *).
(MonadIO m, MonadCGI m) =>
[String] -> m CGIResult
outputInternalServerError = forall (m :: * -> *).
(MonadCGI m, MonadIO m) =>
Int -> String -> [String] -> m CGIResult
outputError Int
500 String
"Internal Server Error"


--
-- * Environment variables
--

-- | Get the value of a CGI environment variable. Example:
--
-- > remoteAddr <- getVar "REMOTE_ADDR"
getVar :: MonadCGI m =>
          String             -- ^ The name of the variable.
       -> m (Maybe String)
getVar :: forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
name = forall k a. Ord k => k -> Map k a -> Maybe a
Map.lookup String
name forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> Map String String
cgiVars

getVarWithDefault :: MonadCGI m =>
                     String -- ^ The name of the variable.
                  -> String -- ^ Default value
                  -> m String
getVarWithDefault :: forall (m :: * -> *). MonadCGI m => String -> String -> m String
getVarWithDefault String
name String
def = forall a. a -> Maybe a -> a
fromMaybe String
def forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
name

-- | Get all CGI environment variables and their values.
getVars :: MonadCGI m =>
           m [(String,String)]
getVars :: forall (m :: * -> *). MonadCGI m => m [(String, String)]
getVars = forall k a. Map k a -> [(k, a)]
Map.toList forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> Map String String
cgiVars

--
-- * Request information
--

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

-- | The port number to which the request was sent.
serverPort :: MonadCGI m => m Int
serverPort :: forall (m :: * -> *). MonadCGI m => m Int
serverPort = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall a. a -> Maybe a -> a
fromMaybe Int
80 forall b c a. (b -> c) -> (a -> b) -> a -> c
. (forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= forall a. Read a => String -> Maybe a
maybeRead)) (forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"SERVER_PORT")

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

-- | 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 @\'\/\'@.
--
-- 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 'progURI', 'queryURI' and 'requestURI' for a higher-level
-- interface.
pathInfo :: MonadCGI m => m String
pathInfo :: forall (m :: * -> *). MonadCGI m => m String
pathInfo = String -> String
slash forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *). MonadCGI m => String -> String -> m String
getVarWithDefault String
"PATH_INFO" String
""
  where slash :: String -> String
slash String
s = if Bool -> Bool
not (forall (t :: * -> *) a. Foldable t => t a -> Bool
null String
s) Bool -> Bool -> Bool
&& forall a. [a] -> a
head String
s forall a. Eq a => a -> a -> Bool
/= Char
'/' then Char
'/'forall a. a -> [a] -> [a]
:String
s else String
s

-- | The path returned by 'pathInfo', but with virtual-to-physical
--   mapping applied to it.
pathTranslated :: MonadCGI m => m String
pathTranslated :: forall (m :: * -> *). MonadCGI m => m String
pathTranslated = forall (m :: * -> *). MonadCGI m => String -> String -> m String
getVarWithDefault String
"PATH_TRANSLATED" 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 'progURI', 'queryURI' and 'requestURI' for a higher-level
-- interface.
scriptName :: MonadCGI m => m String
scriptName :: forall (m :: * -> *). MonadCGI m => m String
scriptName = forall (m :: * -> *). MonadCGI m => String -> String -> m String
getVarWithDefault String
"SCRIPT_NAME" String
""

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

-- | The hostname making the request. If the server does not have
--   this information, Nothing is returned. See also 'remoteAddr'.
remoteHost :: MonadCGI m => m (Maybe String)
remoteHost :: forall (m :: * -> *). MonadCGI m => m (Maybe String)
remoteHost = forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"REMOTE_HOST"

-- | The IP address of the remote host making the request.
remoteAddr :: MonadCGI m => m String
remoteAddr :: forall (m :: * -> *). MonadCGI m => m String
remoteAddr = forall (m :: * -> *). MonadCGI m => String -> String -> m String
getVarWithDefault String
"REMOTE_ADDR" 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)
authType :: forall (m :: * -> *). MonadCGI m => m (Maybe String)
authType = forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"AUTH_TYPE"

-- | 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)
remoteUser :: forall (m :: * -> *). MonadCGI m => m (Maybe String)
remoteUser = forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"REMOTE_USER"

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

-- | 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)
requestContentLength :: forall (m :: * -> *). MonadCGI m => m (Maybe Int)
requestContentLength = (forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= forall a. Read a => String -> Maybe a
maybeRead) forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"CONTENT_LENGTH"

-- | Gets the value of the request header with the given name.
--   The header name is case-insensitive.
--   Example:
--
-- > requestHeader "User-Agent"
requestHeader :: MonadCGI m => String -> m (Maybe String)
requestHeader :: forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
requestHeader String
name = forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
var
  where var :: String
var = String
"HTTP_" forall a. [a] -> [a] -> [a]
++ forall a b. (a -> b) -> [a] -> [b]
map Char -> Char
toUpper (forall a. Eq a => a -> a -> [a] -> [a]
replace Char
'-' Char
'_' String
name)

--
-- * Content negotiation
--

requestHeaderValue :: (MonadCGI m, HeaderValue a) => String -> m (Maybe a)
requestHeaderValue :: forall (m :: * -> *) a.
(MonadCGI m, HeaderValue a) =>
String -> m (Maybe a)
requestHeaderValue String
h = (forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= forall (m :: * -> *) a.
MonadFail m =>
Parser a -> String -> String -> m a
parseM forall a. HeaderValue a => Parser a
parseHeaderValue String
h) forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
requestHeader String
h

requestAccept :: MonadCGI m => m (Maybe (Accept ContentType))
requestAccept :: forall (m :: * -> *). MonadCGI m => m (Maybe (Accept ContentType))
requestAccept = forall (m :: * -> *) a.
(MonadCGI m, HeaderValue a) =>
String -> m (Maybe a)
requestHeaderValue String
"Accept"

requestAcceptCharset :: MonadCGI m => m (Maybe (Accept Charset))
requestAcceptCharset :: forall (m :: * -> *). MonadCGI m => m (Maybe (Accept Charset))
requestAcceptCharset = forall (m :: * -> *) a.
(MonadCGI m, HeaderValue a) =>
String -> m (Maybe a)
requestHeaderValue String
"Accept-Charset"

requestAcceptEncoding :: MonadCGI m => m (Maybe (Accept ContentEncoding))
requestAcceptEncoding :: forall (m :: * -> *).
MonadCGI m =>
m (Maybe (Accept ContentEncoding))
requestAcceptEncoding = forall (m :: * -> *) a.
(MonadCGI m, HeaderValue a) =>
String -> m (Maybe a)
requestHeaderValue String
"Accept-Encoding"

requestAcceptLanguage :: MonadCGI m => m (Maybe (Accept Language))
requestAcceptLanguage :: forall (m :: * -> *). MonadCGI m => m (Maybe (Accept Language))
requestAcceptLanguage = forall (m :: * -> *) a.
(MonadCGI m, HeaderValue a) =>
String -> m (Maybe a)
requestHeaderValue String
"Accept-Language"

--
-- * Program and request URI
--

-- | Attempts to reconstruct the absolute URI of this program.
--   This does not include
--   any extra path information or query parameters. See
--   'queryURI' for that.
--   If the server is rewriting request URIs, this URI can
--   be different from the one requested by the client.
--   See also 'requestURI'.
--
-- Characters in the components of the returned URI are escaped
-- when needed, as required by "Network.URI".
progURI :: MonadCGI m => m URI
progURI :: forall (m :: * -> *). MonadCGI m => m URI
progURI =
    do -- Use HTTP_HOST if available, otherwise SERVER_NAME
       String
h <- forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
requestHeader String
"Host" forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= forall b a. b -> (a -> b) -> Maybe a -> b
maybe forall (m :: * -> *). MonadCGI m => m String
serverName forall (m :: * -> *) a. Monad m => a -> m a
return
       Int
p <- forall (m :: * -> *). MonadCGI m => m Int
serverPort
       String
name <- forall (m :: * -> *). MonadCGI m => m String
scriptName
       Bool
https <- forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap forall a. Maybe a -> Bool
isJust (forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"HTTPS")
       -- SERVER_PORT might not be the port that the client used
       -- if the server listens on multiple ports, so we give priority
       -- to the port in HTTP_HOST.
       -- HTTP_HOST should include the port according to RFC2616 sec 14.23
       -- Some servers (e.g. lighttpd) also seem to include the port in
       -- SERVER_NAME.
       -- We include the port if it is in HTTP_HOST or SERVER_NAME, or if
       -- it is a non-standard port.
       let (String
host,String
port) = case forall a. (a -> Bool) -> [a] -> ([a], [a])
break (forall a. Eq a => a -> a -> Bool
==Char
':') String
h of
                           (String
_,String
"")  -> (String
h, if (Bool -> Bool
not Bool
https Bool -> Bool -> Bool
&& Int
p forall a. Eq a => a -> a -> Bool
== Int
80)
                                            Bool -> Bool -> Bool
|| (Bool
https Bool -> Bool -> Bool
&& Int
p forall a. Eq a => a -> a -> Bool
== Int
443)
                                           then String
"" else Char
':'forall a. a -> [a] -> [a]
:forall a. Show a => a -> String
show Int
p)
                           (String
h',String
p') -> (String
h',String
p')
       let auth :: URIAuth
auth = URIAuth { uriUserInfo :: String
uriUserInfo = String
"",
                            uriRegName :: String
uriRegName = String
host,
                            uriPort :: String
uriPort = String
port }
       forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ URI
nullURI { uriScheme :: String
uriScheme = if Bool
https then String
"https:" else String
"http:",
                          uriAuthority :: Maybe URIAuth
uriAuthority = forall a. a -> Maybe a
Just URIAuth
auth,
                          uriPath :: String
uriPath = String -> String
escapePath String
name }

-- | Like 'progURI', but the returned 'URI' 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 'requestURI'.
--
-- Characters in the components of the returned URI are escaped
-- when needed, as required by "Network.URI".
queryURI :: MonadCGI m => m URI
queryURI :: forall (m :: * -> *). MonadCGI m => m URI
queryURI =
    do URI
uri  <- forall (m :: * -> *). MonadCGI m => m URI
progURI
       String
path <- forall (m :: * -> *). MonadCGI m => m String
pathInfo
       String
qs   <- forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (\String
q -> if forall (t :: * -> *) a. Foldable t => t a -> Bool
null String
q then String
q else Char
'?'forall a. a -> [a] -> [a]
:String
q) forall (m :: * -> *). MonadCGI m => m String
queryString
       forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ URI
uri { uriPath :: String
uriPath = URI -> String
uriPath URI
uri forall a. [a] -> [a] -> [a]
++ String -> String
escapePath String
path,
                      uriQuery :: String
uriQuery = String
qs }

-- | Does percent-encoding as needed for URI path components.
escapePath :: String -> String
escapePath :: String -> String
escapePath = (Char -> Bool) -> String -> String
escapeURIString Char -> Bool
isUnescapedInURIPath
  where isUnescapedInURIPath :: Char -> Bool
isUnescapedInURIPath Char
c = Char -> Bool
isUnescapedInURI Char
c Bool -> Bool -> Bool
&& Char
c forall (t :: * -> *) a. (Foldable t, Eq a) => a -> t a -> Bool
`notElem` String
"?#"

-- | 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 'queryURI'.
--
-- Characters in the components of the returned URI are escaped
-- when needed, as required by "Network.URI".
requestURI :: MonadCGI m => m URI
requestURI :: forall (m :: * -> *). MonadCGI m => m URI
requestURI =
    do URI
uri <- forall (m :: * -> *). MonadCGI m => m URI
queryURI
       -- Apache sets REQUEST_URI to the original request URI,
       -- with percent-encoding intact.
       Maybe URI
mreq <- (forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= String -> Maybe URI
parseRelativeReference) forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
<$> forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"REQUEST_URI"
       forall (m :: * -> *) a. Monad m => a -> m a
return forall a b. (a -> b) -> a -> b
$ case Maybe URI
mreq of
                 Maybe URI
Nothing  -> URI
uri
                 Just URI
req -> URI
uri {
                                  uriPath :: String
uriPath  = URI -> String
uriPath URI
req,
                                  uriQuery :: String
uriQuery = URI -> String
uriQuery URI
req
                                 }


--
-- * Inputs
--

-- | Get the value of an input variable, for example from a form.
--   If the variable has multiple values, the first one is returned.
--   Example:
--
-- > query <- getInput "query"
getInput :: MonadCGI m =>
            String           -- ^ The name of the variable.
         -> m (Maybe String) -- ^ The value of the variable,
                             --   or Nothing, if it was not set.
getInput :: forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getInput = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap ByteString -> String
BS.unpack) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: * -> *). MonadCGI m => String -> m (Maybe ByteString)
getInputFPS

-- | Like 'getInput', but returns a 'ByteString'.
getInputFPS :: MonadCGI m =>
            String           -- ^ The name of the variable.
         -> m (Maybe ByteString) -- ^ The value of the variable,
                             --   or Nothing, if it was not set.
getInputFPS :: forall (m :: * -> *). MonadCGI m => String -> m (Maybe ByteString)
getInputFPS = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap Input -> ByteString
inputValue) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: * -> *). MonadCGI m => String -> m (Maybe Input)
getInput_

-- | 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:
--
-- > vals <- getMultiInput "my_checkboxes"
getMultiInput :: MonadCGI m =>
                 String -- ^ The name of the variable.
              -> m [String] -- ^ The values of the variable,
                            -- or the empty list if the variable was not set.
getMultiInput :: forall (m :: * -> *). MonadCGI m => String -> m [String]
getMultiInput = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall a b. (a -> b) -> [a] -> [b]
map ByteString -> String
BS.unpack) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: * -> *). MonadCGI m => String -> m [ByteString]
getMultiInputFPS

-- | Same as 'getMultiInput' but using 'ByteString's.
getMultiInputFPS :: MonadCGI m =>
                    String -- ^ The name of the variable.
                 -> m [ByteString] -- ^ The values of the variable,
                            -- or the empty list if the variable was not set.
getMultiInputFPS :: forall (m :: * -> *). MonadCGI m => String -> m [ByteString]
getMultiInputFPS String
n = do [(String, Input)]
is <- forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> [(String, Input)]
cgiInputs
                        forall (m :: * -> *) a. Monad m => a -> m a
return [Input -> ByteString
inputValue Input
v | (String
p,Input
v) <- [(String, Input)]
is, String
p forall a. Eq a => a -> a -> Bool
== String
n]

-- | Get the file name of an input.
getInputFilename :: MonadCGI m =>
                    String           -- ^ The name of the variable.
                 -> m (Maybe String) -- ^ The file name corresponding to the
                                     -- input, if there is one.
getInputFilename :: forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getInputFilename = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= Input -> Maybe String
inputFilename) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: * -> *). MonadCGI m => String -> m (Maybe Input)
getInput_

-- | Get the content-type of an input, if the input exists, e.g. "image\/jpeg".
--   For non-file inputs, this function returns "text\/plain".
--   You can use 'parseContentType' to get a structured
--   representation of the the content-type value.
getInputContentType :: MonadCGI m =>
                       String   -- ^ The name of the variable.
                    -> m (Maybe String) -- ^ The content type, formatted as a string.
getInputContentType :: forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getInputContentType =
    forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (ContentType -> String
showContentType forall b c a. (b -> c) -> (a -> b) -> a -> c
. Input -> ContentType
inputContentType)) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: * -> *). MonadCGI m => String -> m (Maybe Input)
getInput_

-- | Same as 'getInput', but tries to read the value to the desired type.
readInput :: (Read a, MonadCGI m) =>
             String        -- ^ The name of the variable.
          -> m (Maybe a) -- ^ 'Nothing' if the variable does not exist
                           --   or if the value could not be interpreted
                           --   at the desired type.
readInput :: forall a (m :: * -> *).
(Read a, MonadCGI m) =>
String -> m (Maybe a)
readInput = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= forall a. Read a => String -> Maybe a
maybeRead) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getInput

-- | 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)]
getInputs :: forall (m :: * -> *). MonadCGI m => m [(String, String)]
getInputs = do [(String, Input)]
is <- forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> [(String, Input)]
cgiInputs
               forall (m :: * -> *) a. Monad m => a -> m a
return [ (String
n, ByteString -> String
BS.unpack (Input -> ByteString
inputValue Input
i)) | (String
n,Input
i) <- [(String, Input)]
is ]

-- | 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)]
getInputsFPS :: forall (m :: * -> *). MonadCGI m => m [(String, ByteString)]
getInputsFPS = do [(String, Input)]
is <- forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> [(String, Input)]
cgiInputs
                  forall (m :: * -> *) a. Monad m => a -> m a
return [ (String
n, Input -> ByteString
inputValue Input
i) | (String
n,Input
i) <- [(String, Input)]
is ]

-- | Get the names of all input variables.
getInputNames :: MonadCGI m => m [String]
getInputNames :: forall (m :: * -> *). MonadCGI m => m [String]
getInputNames = ([String] -> [String]
sortNub forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall a b. (a -> b) -> [a] -> [b]
map forall a b. (a, b) -> a
fst) forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
`fmap` forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> [(String, Input)]
cgiInputs
    where sortNub :: [String] -> [String]
sortNub = forall a b. (a -> b) -> [a] -> [b]
map forall a. [a] -> a
head forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall a. Eq a => [a] -> [[a]]
group forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall a. Ord a => [a] -> [a]
sort

-- Internal stuff

getInput_ ::  MonadCGI m => String -> m (Maybe Input)
getInput_ :: forall (m :: * -> *). MonadCGI m => String -> m (Maybe Input)
getInput_ String
n = forall a b. Eq a => a -> [(a, b)] -> Maybe b
lookup String
n forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
`fmap` forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> [(String, Input)]
cgiInputs

-- | Get the uninterpreted request body as a String
getBody :: MonadCGI m => m String
getBody :: forall (m :: * -> *). MonadCGI m => m String
getBody = ByteString -> String
BS.unpack forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
`fmap` forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> ByteString
cgiRequestBody

-- | Get the uninterpreted request body as lazy ByteString
getBodyFPS :: MonadCGI m => m ByteString
getBodyFPS :: forall (m :: * -> *). MonadCGI m => m ByteString
getBodyFPS = forall (m :: * -> *) a. MonadCGI m => (CGIRequest -> a) -> m a
cgiGet CGIRequest -> ByteString
cgiRequestBody

--
-- * Cookies
--

-- | Get the value of a cookie.
getCookie :: MonadCGI m =>
             String           -- ^ The name of the cookie.
          -> m (Maybe String) -- ^ 'Nothing' if the cookie does not exist.
getCookie :: forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getCookie String
name = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= String -> String -> Maybe String
findCookie String
name) (forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getVar String
"HTTP_COOKIE")

-- | Same as 'getCookie', but tries to read the value to the desired type.
readCookie :: (Read a, MonadCGI m) =>
              String       -- ^ The name of the cookie.
            -> m (Maybe a) -- ^ 'Nothing' if the cookie does not exist
                           --   or if the value could not be interpreted
                           --   at the desired type.
readCookie :: forall a (m :: * -> *).
(Read a, MonadCGI m) =>
String -> m (Maybe a)
readCookie = forall (f :: * -> *) a b. Functor f => (a -> b) -> f a -> f b
fmap (forall (m :: * -> *) a b. Monad m => m a -> (a -> m b) -> m b
>>= forall a. Read a => String -> Maybe a
maybeRead) forall b c a. (b -> c) -> (a -> b) -> a -> c
. forall (m :: * -> *). MonadCGI m => String -> m (Maybe String)
getCookie

-- | Set a cookie.
setCookie :: MonadCGI m => Cookie -> m ()
setCookie :: forall (m :: * -> *). MonadCGI m => Cookie -> m ()
setCookie = forall (m :: * -> *). MonadCGI m => String -> String -> m ()
setHeader String
"Set-cookie" forall b c a. (b -> c) -> (a -> b) -> a -> c
. Cookie -> String
showCookie

-- | Delete a cookie from the client
deleteCookie :: MonadCGI m => Cookie -> m ()
deleteCookie :: forall (m :: * -> *). MonadCGI m => Cookie -> m ()
deleteCookie = forall (m :: * -> *). MonadCGI m => Cookie -> m ()
setCookie forall b c a. (b -> c) -> (a -> b) -> a -> c
. Cookie -> Cookie
Cookie.deleteCookie


--
-- * Headers
--

-- | Add a response header.
--   Example:
--
-- > setHeader "Content-type" "text/plain"
setHeader :: MonadCGI m =>
             String -- ^ Header name.
          -> String -- ^ Header value.
          -> m ()
setHeader :: forall (m :: * -> *). MonadCGI m => String -> String -> m ()
setHeader String
n = forall (m :: * -> *). MonadCGI m => HeaderName -> String -> m ()
cgiAddHeader (String -> HeaderName
HeaderName String
n)

-- | Set the HTTP response status.
setStatus :: MonadCGI m =>
             Int -- ^  HTTP status code, e.g. @404@
          -> String -- ^ HTTP status message, e.g. @"Not Found"@
          -> m ()
setStatus :: forall (m :: * -> *). MonadCGI m => Int -> String -> m ()
setStatus Int
c String
m = forall (m :: * -> *). MonadCGI m => String -> String -> m ()
setHeader String
"Status" (forall a. Show a => a -> String
show Int
c forall a. [a] -> [a] -> [a]
++ String
" " forall a. [a] -> [a] -> [a]
++ String
m)