cgi-3001.5.0.0: A library for writing CGI programs

Copyright | (c) Bjorn Bringert 2006
License | BSD-style
Maintainer | John Chee <cheecheeo@gmail.com>
Stability | experimental
Portability | non-portable
Safe Haskell | None
Language | Haskell98

Network.CGI.Protocol

Contents

- CGI request
- CGI response
- Running CGI actions
- Inputs
- Environment variables
- Logging
- URL encoding
- Utilities

Description

An implementation of the program side of the CGI protocol.

Synopsis

- data CGIRequest = CGIRequest {
  - cgiVars :: Map String String
  - cgiInputs :: [(String, Input)]
  - cgiRequestBody :: ByteString
  }
- data Input = Input {
  - inputValue :: ByteString
  - inputFilename :: Maybe String
  - inputContentType :: ContentType
  }
- data CGIResult
  - = CGIOutput ByteString
  - | CGINothing
- type Headers = [(HeaderName, String)]
- newtype HeaderName = HeaderName String
- hRunCGI :: MonadIO m => [(String, String)] -> Handle -> Handle -> (CGIRequest -> m (Headers, CGIResult)) -> m ()
- runCGIEnvFPS :: Monad m => [(String, String)] -> ByteString -> (CGIRequest -> m (Headers, CGIResult)) -> m ByteString
- decodeInput :: [(String, String)] -> ByteString -> ([(String, Input)], ByteString)
- takeInput :: [(String, String)] -> ByteString -> ByteString
- getCGIVars :: MonadIO m => m [(String, String)]
- logCGI :: MonadIO m => String -> m ()
- formEncode :: [(String, String)] -> String
- urlEncode :: String -> String
- formDecode :: String -> [(String, String)]
- urlDecode :: String -> String
- maybeRead :: Read a => String -> Maybe a
- replace :: Eq a => a -> a -> [a] -> [a]

# CGI request

data CGIRequest #

The input to a CGI action.

Constructors

CGIRequest |
Fields cgiVars :: Map String String Environment variables. cgiInputs :: [(String, Input)] Input parameters. For better laziness in reading inputs, this is not a Map. cgiRequestBody :: ByteString Raw request body. To avoid memory leaks, this is the empty string if the request body has been interpreted as inputs in "application/x-www-form-urlencoded" or "multipart/form-data" format.

#### Instances

Instances details

Show CGIRequest # |
Instance details Defined in Network.CGI.Protocol Methods showsPrec :: Int -> CGIRequest -> ShowS # show :: CGIRequest -> String # showList :: [CGIRequest] -> ShowS #

data Input #

The value of an input parameter, and some metadata.

Constructors

Input |
Fields inputValue :: ByteString inputFilename :: Maybe String inputContentType :: ContentType

#### Instances

Instances details

Show Input # |
Instance details Defined in Network.CGI.Protocol Methods showsPrec :: Int -> Input -> ShowS # show :: Input -> String # showList :: [Input] -> ShowS #

# CGI response

data CGIResult #

The result of a CGI program.

Constructors

CGIOutput ByteString |
CGINothing |

#### Instances

Instances details

Eq CGIResult # |
Instance details Defined in Network.CGI.Protocol Methods (==) :: CGIResult -> CGIResult -> Bool # (/=) :: CGIResult -> CGIResult -> Bool #
Ord CGIResult # |
Instance details Defined in Network.CGI.Protocol Methods compare :: CGIResult -> CGIResult -> Ordering # (<) :: CGIResult -> CGIResult -> Bool # (<=) :: CGIResult -> CGIResult -> Bool # (>) :: CGIResult -> CGIResult -> Bool # (>=) :: CGIResult -> CGIResult -> Bool # max :: CGIResult -> CGIResult -> CGIResult # min :: CGIResult -> CGIResult -> CGIResult #
Read CGIResult # |
Instance details Defined in Network.CGI.Protocol Methods readsPrec :: Int -> ReadS CGIResult # readList :: ReadS [CGIResult] # readPrec :: ReadPrec CGIResult # readListPrec :: ReadPrec [CGIResult] #
Show CGIResult # |
Instance details Defined in Network.CGI.Protocol Methods showsPrec :: Int -> CGIResult -> ShowS # show :: CGIResult -> String # showList :: [CGIResult] -> ShowS #

type Headers = [(HeaderName, String)] #

HTTP headers.

newtype HeaderName #

A string with case insensitive equality and comparisons.

Constructors

HeaderName String |

#### Instances

Instances details

Eq HeaderName |
Instance details Defined in Network.Multipart.Header Methods (==) :: HeaderName -> HeaderName -> Bool # (/=) :: HeaderName -> HeaderName -> Bool #
Ord HeaderName |
Instance details Defined in Network.Multipart.Header Methods compare :: HeaderName -> HeaderName -> Ordering # (<) :: HeaderName -> HeaderName -> Bool # (<=) :: HeaderName -> HeaderName -> Bool # (>) :: HeaderName -> HeaderName -> Bool # (>=) :: HeaderName -> HeaderName -> Bool # max :: HeaderName -> HeaderName -> HeaderName # min :: HeaderName -> HeaderName -> HeaderName #
Show HeaderName |
Instance details Defined in Network.Multipart.Header Methods showsPrec :: Int -> HeaderName -> ShowS # show :: HeaderName -> String # showList :: [HeaderName] -> ShowS #

# Running CGI actions

hRunCGI #

Arguments

:: MonadIO m |
=> [(String, String)] | CGI environment variables, e.g. from `getCGIVars`.
-> Handle | Handle that input will be read from, e.g. `stdin`.
-> Handle | Handle that output will be written to, e.g. `stdout`.
-> (CGIRequest -> m (Headers, CGIResult)) | CGI action
-> m () |

Runs a CGI action in a given environment. Uses Handles for input and output.

runCGIEnvFPS #

Arguments

:: Monad m |
=> [(String, String)] | CGI environment variables.
-> ByteString | Request body.
-> (CGIRequest -> m (Headers, CGIResult)) | CGI action.
-> m ByteString | Response (headers and content).

Runs a CGI action in a given environment. Uses lazy ByteStrings for input and output.

# Inputs

decodeInput #

Arguments

:: [(String, String)] | CGI environment variables.
-> ByteString | Request body.
-> ([(String, Input)], ByteString) | A list of input variables and values, and the request body if it was not interpreted.

Gets and decodes the input according to the request method and the content-type.

takeInput #

Arguments

:: [(String, String)] | CGI environment variables.
-> ByteString | Request body.
-> ByteString | CONTENT_LENGTH bytes from the request body, or the empty string if there is no CONTENT_LENGTH.

Takes the right number of bytes from the input.

# Environment variables

getCGIVars :: MonadIO m => m [(String, String)] #

Gets the values of all CGI variables from the program environment.

# Logging

logCGI :: MonadIO m => String -> m () #

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?

# URL encoding

formEncode :: [(String, String)] -> String #

Formats name-value pairs as application/x-www-form-urlencoded.

urlEncode :: String -> String #

Converts a single value to the application/x-www-form-urlencoded encoding.

formDecode :: String -> [(String, String)] #

Gets the name-value pairs from application/x-www-form-urlencoded data.

urlDecode :: String -> String #

Converts a single value from the application/x-www-form-urlencoded encoding.

# Utilities

maybeRead :: Read a => String -> Maybe a #

replace #

Arguments

:: Eq a |
=> a | Value to look for
-> a | Value to replace it with
-> [a] | Input list
-> [a] | Output list

Replaces all instances of a value in a list by another value.