HTTP-4000.2.20: A library for client-side HTTP

Copyright | See LICENSE file
License | BSD
Maintainer | Ganesh Sittampalam <ganesh@earth.li>
Stability | experimental
Portability | non-portable (not tested)
Safe Haskell | Safe
Language | Haskell98

Network.HTTP.Headers

Description

This module provides the data types for representing HTTP headers, and operations for looking up header values and working with sequences of header values in `Request`s and `Response`s. To avoid having to provide separate set of operations for doing so, we introduce a type class `HasHeaders` to facilitate writing such processing using overloading instead.

Synopsis

- class HasHeaders x where
  - getHeaders :: x -> [Header]
  - setHeaders :: x -> [Header] -> x
- data Header = Header HeaderName String
- mkHeader :: HeaderName -> String -> Header
- hdrName :: Header -> HeaderName
- hdrValue :: Header -> String
- data HeaderName
  - = HdrCacheControl
  - | HdrConnection
  - | HdrDate
  - | HdrPragma
  - | HdrTransferEncoding
  - | HdrUpgrade
  - | HdrVia
  - | HdrAccept
  - | HdrAcceptCharset
  - | HdrAcceptEncoding
  - | HdrAcceptLanguage
  - | HdrAuthorization
  - | HdrCookie
  - | HdrExpect
  - | HdrFrom
  - | HdrHost
  - | HdrIfModifiedSince
  - | HdrIfMatch
  - | HdrIfNoneMatch
  - | HdrIfRange
  - | HdrIfUnmodifiedSince
  - | HdrMaxForwards
  - | HdrProxyAuthorization
  - | HdrRange
  - | HdrReferer
  - | HdrUserAgent
  - | HdrAge
  - | HdrLocation
  - | HdrProxyAuthenticate
  - | HdrPublic
  - | HdrRetryAfter
  - | HdrServer
  - | HdrSetCookie
  - | HdrTE
  - | HdrTrailer
  - | HdrVary
  - | HdrWarning
  - | HdrWWWAuthenticate
  - | HdrAllow
  - | HdrContentBase
  - | HdrContentEncoding
  - | HdrContentLanguage
  - | HdrContentLength
  - | HdrContentLocation
  - | HdrContentMD5
  - | HdrContentRange
  - | HdrContentType
  - | HdrETag
  - | HdrExpires
  - | HdrLastModified
  - | HdrContentTransferEncoding
  - | HdrCustom String
- insertHeader :: HasHeaders a => HeaderSetter a
- insertHeaderIfMissing :: HasHeaders a => HeaderSetter a
- insertHeaders :: HasHeaders a => [Header] -> a -> a
- retrieveHeaders :: HasHeaders a => HeaderName -> a -> [Header]
- replaceHeader :: HasHeaders a => HeaderSetter a
- findHeader :: HasHeaders a => HeaderName -> a -> Maybe String
- lookupHeader :: HeaderName -> [Header] -> Maybe String
- parseHeader :: String -> Result Header
- parseHeaders :: [String] -> Result [Header]
- headerMap :: [(String, HeaderName)]
- type HeaderSetter a = HeaderName -> String -> a -> a

# Documentation

class HasHeaders x where

`HasHeaders` is a type class for types containing HTTP headers, allowing you to write overloaded header manipulation functions for both `Request` and `Response` data types, for instance.

Methods

getHeaders :: x -> [Header]

setHeaders :: x -> [Header] -> x

Instances

HasHeaders (Response a) |
HasHeaders (Request a) |

data Header

The `Header` data type pairs header names & values.

Constructors

Header HeaderName String |

Instances

Show Header |

mkHeader :: HeaderName -> String -> Header

Header constructor as a function, hiding above rep.

hdrName :: Header -> HeaderName

hdrValue :: Header -> String

data HeaderName

HTTP `HeaderName` type, a Haskell data constructor for each specification-defined header, prefixed with `Hdr` and CamelCased, (i.e., eliding the `-` in the process.) Should you require using a custom header, there's the `HdrCustom` constructor which takes a `String` argument.

Encoding HTTP header names differently, as Strings perhaps, is an equally fine choice..no decidedly clear winner, but let's stick with data constructors here.

Constructors

HdrCacheControl |
HdrConnection |
HdrDate |
HdrPragma |
HdrTransferEncoding |
HdrUpgrade |
HdrVia |
HdrAccept |
HdrAcceptCharset |
HdrAcceptEncoding |
HdrAcceptLanguage |
HdrAuthorization |
HdrCookie |
HdrExpect |
HdrFrom |
HdrHost |
HdrIfModifiedSince |
HdrIfMatch |
HdrIfNoneMatch |
HdrIfRange |
HdrIfUnmodifiedSince |
HdrMaxForwards |
HdrProxyAuthorization |
HdrRange |
HdrReferer |
HdrUserAgent |
HdrAge |
HdrLocation |
HdrProxyAuthenticate |
HdrPublic |
HdrRetryAfter |
HdrServer |
HdrSetCookie |
HdrTE |
HdrTrailer |
HdrVary |
HdrWarning |
HdrWWWAuthenticate |
HdrAllow |
HdrContentBase |
HdrContentEncoding |
HdrContentLanguage |
HdrContentLength |
HdrContentLocation |
HdrContentMD5 |
HdrContentRange |
HdrContentType |
HdrETag |
HdrExpires |
HdrLastModified |
HdrContentTransferEncoding | MIME entity headers (for sub-parts)
HdrCustom String | Allows for unrecognised or experimental headers.

Instances

Eq HeaderName |
Show HeaderName |

insertHeader :: HasHeaders a => HeaderSetter a

`insertHeader hdr val x` inserts a header with the given header name and value. Does not check for existing headers with same name, allowing duplicates to be introduce (use `replaceHeader` if you want to avoid this.)

insertHeaderIfMissing :: HasHeaders a => HeaderSetter a

`insertHeaderIfMissing hdr val x` adds the new header only if no previous header with name `hdr` exists in `x`.

insertHeaders :: HasHeaders a => [Header] -> a -> a

`insertHeaders hdrs x` appends multiple headers to `x`'s existing set.

retrieveHeaders :: HasHeaders a => HeaderName -> a -> [Header]

`retrieveHeaders hdrNm x` gets a list of headers with `HeaderName` `hdrNm`.

replaceHeader :: HasHeaders a => HeaderSetter a

`replaceHeader hdr val o` replaces the header `hdr` with the value `val`, dropping any existing

findHeader :: HasHeaders a => HeaderName -> a -> Maybe String

`findHeader hdrNm x` looks up `hdrNm` in `x`, returning the first header that matches, if any.

lookupHeader :: HeaderName -> [Header] -> Maybe String

`lookupHeader hdr hdrs` locates the first header matching `hdr` in the list `hdrs`.

parseHeader :: String -> Result Header

`parseHeader headerNameAndValueString` tries to unscramble a `header: value` pairing and returning it as a `Header`.

parseHeaders :: [String] -> Result [Header]

`parseHeaders hdrs` takes a sequence of strings holding header information and parses them into a set of headers (preserving their order in the input argument.) Handles header values split up over multiple lines.

headerMap :: [(String, HeaderName)]

`headerMap` is a straight assoc list for translating between header names and values.

type HeaderSetter a = HeaderName -> String -> a -> a