Network.CGI.Protocol

cgi-3001.2.2.2: 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 | Safe
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

Show CGIRequest |

data Input

The value of an input parameter, and some metadata.

Constructors

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

Instances

Show Input |

# CGI response

data CGIResult

The result of a CGI program.

Constructors

CGIOutput ByteString |
CGINothing |

Instances

Eq CGIResult |
Ord CGIResult |
Read CGIResult |
Show CGIResult |

type Headers = [(HeaderName, String)]

HTTP headers.

newtype HeaderName :: *

A string with case insensitive equality and comparisons.

Constructors

HeaderName String |

Instances

Eq HeaderName |
Ord HeaderName |
Show HeaderName |

# 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.