Network.HTTP.Types.URI

http-types-0.12.3: Generic HTTP types for Haskell (for both client and server code).

Safe Haskell | Safe-Inferred
Language | Haskell98

Network.HTTP.Types.URI

Contents

- Query string
  - Escape only parts
  - Text query string (UTF8 encoded)
- Path segments
- Path (segments + query string)
- URL encoding / decoding

Synopsis

- type QueryItem = (ByteString, Maybe ByteString)
- type Query = [QueryItem]
- type SimpleQueryItem = (ByteString, ByteString)
- type SimpleQuery = [SimpleQueryItem]
- simpleQueryToQuery :: SimpleQuery -> Query
- renderQuery :: Bool -> Query -> ByteString
- renderQueryBuilder :: Bool -> Query -> Builder
- renderSimpleQuery :: Bool -> SimpleQuery -> ByteString
- parseQuery :: ByteString -> Query
- parseQueryReplacePlus :: Bool -> ByteString -> Query
- parseSimpleQuery :: ByteString -> SimpleQuery
- renderQueryPartialEscape :: Bool -> PartialEscapeQuery -> ByteString
- renderQueryBuilderPartialEscape :: Bool -> PartialEscapeQuery -> Builder
- data EscapeItem
  - = QE ByteString
  - | QN ByteString
- type PartialEscapeQueryItem = (ByteString, [EscapeItem])
- type PartialEscapeQuery = [PartialEscapeQueryItem]
- type QueryText = [(Text, Maybe Text)]
- queryTextToQuery :: QueryText -> Query
- queryToQueryText :: Query -> QueryText
- renderQueryText :: Bool -> QueryText -> Builder
- parseQueryText :: ByteString -> QueryText
- encodePathSegments :: [Text] -> Builder
- decodePathSegments :: ByteString -> [Text]
- encodePathSegmentsRelative :: [Text] -> Builder
- extractPath :: ByteString -> ByteString
- encodePath :: [Text] -> Query -> Builder
- decodePath :: ByteString -> ([Text], Query)
- urlEncodeBuilder :: Bool -> ByteString -> Builder
- urlEncode :: Bool -> ByteString -> ByteString
- urlDecode :: Bool -> ByteString -> ByteString

# Query string

type QueryItem = (ByteString, Maybe ByteString) #

Query item

type Query = [QueryItem] #

Query.

General form: `a=b&c=d`, but if the value is Nothing, it becomes `a&c=d`.

type SimpleQueryItem = (ByteString, ByteString) #

Simplified Query item type without support for parameter-less items.

type SimpleQuery = [SimpleQueryItem] #

Simplified Query type without support for parameter-less items.

simpleQueryToQuery :: SimpleQuery -> Query #

Convert `SimpleQuery` to `Query`.

renderQuery #

Arguments

:: Bool | prepend question mark?
-> Query |
-> ByteString |

Convert `Query` to `ByteString`.

renderQueryBuilder #

Arguments

:: Bool | prepend a question mark?
-> Query |
-> Builder |

Convert `Query` to a `Builder`.

renderSimpleQuery #

Arguments

:: Bool | prepend question mark?
-> SimpleQuery |
-> ByteString |

Convert `SimpleQuery` to `ByteString`.

parseQuery :: ByteString -> Query #

Split out the query string into a list of keys and values. A few importants points:

- The result returned is still bytestrings, since we perform no character decoding here. Most likely, you will want to use UTF-8 decoding, but this is left to the user of the library.
- Percent decoding errors are ignored. In particular, `"%Q"` will be output as `"%Q"`.
- It decodes `'+'` characters to `' '`

parseQueryReplacePlus :: Bool -> ByteString -> Query #

Same functionality as `parseQuery` with the option to decode `'+'` characters to `' '` or preserve `'+'`

parseSimpleQuery :: ByteString -> SimpleQuery #

Parse `SimpleQuery` from a `ByteString`.

## Escape only parts

renderQueryPartialEscape #

Arguments

:: Bool | prepend question mark?
-> PartialEscapeQuery |
-> ByteString |

Convert `PartialEscapeQuery` to `ByteString`.

renderQueryBuilderPartialEscape #

Arguments

:: Bool | prepend a question mark?
-> PartialEscapeQuery |
-> Builder |

Convert `PartialEscapeQuery` to a `Builder`.

data EscapeItem #

For some URIs characters must not be URI encoded, e.g. `'+'` or `':'` in `q=a+language:haskell+created:2009-01-01..2009-02-01&sort=stars` The character list unreservedPI instead of unreservedQS would solve this. But we explicitly decide what part to encode. This is mandatory when searching for `'+'`: `q=%2B+language:haskell`.

Constructors

QE ByteString |
QN ByteString |

#### Instances

Instances details

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

type PartialEscapeQueryItem = (ByteString, [EscapeItem]) #

Query item

type PartialEscapeQuery = [PartialEscapeQueryItem] #

Query with some chars that should not be escaped.

General form: `a=b&c=d:e+f&g=h`

## Text query string (UTF8 encoded)

type QueryText = [(Text, Maybe Text)] #

Like Query, but with `Text` instead of `ByteString` (UTF8-encoded).

queryTextToQuery :: QueryText -> Query #

Convert `QueryText` to `Query`.

queryToQueryText :: Query -> QueryText #

Convert `Query` to `QueryText` (leniently decoding the UTF-8).

renderQueryText #

Arguments

:: Bool | prepend a question mark?
-> QueryText |
-> Builder |

Convert `QueryText` to a `Builder`.

parseQueryText :: ByteString -> QueryText #

Parse `QueryText` from a `ByteString`. See `parseQuery` for details.

# Path segments

encodePathSegments :: [Text] -> Builder #

Encodes a list of path segments into a valid URL fragment.

This function takes the following three steps:

- UTF-8 encodes the characters.
- Performs percent encoding on all unreserved characters, as well as `:@=+$`,
- Prepends each segment with a slash.

For example:

    encodePathSegments [\"foo\", \"bar\", \"baz\"]

"/foo/bar/baz"

    encodePathSegments [\"foo bar\", \"baz\/bin\"]

"/foo%20bar/baz%2Fbin"

    encodePathSegments [\"שלום\"]

"/%D7%A9%D7%9C%D7%95%D7%9D"

Huge thanks to Jeremy Shaw who created the original implementation of this function in web-routes and did such thorough research to determine all correct escaping procedures.

decodePathSegments :: ByteString -> [Text] #

Parse a list of path segments from a valid URL fragment.

encodePathSegmentsRelative :: [Text] -> Builder #

Like encodePathSegments, but without the initial slash.

# Path (segments + query string)

extractPath :: ByteString -> ByteString #

Extract whole path (path segments + query) from a RFC 2616 Request-URI.

    >>> extractPath "/path"
    "/path"

    >>> extractPath "http://example.com:8080/path"
    "/path"

    >>> extractPath "http://example.com"
    "/"

    >>> extractPath ""
    "/"

encodePath :: [Text] -> Query -> Builder #

Encode a whole path (path segments + query).

decodePath :: ByteString -> ([Text], Query) #

Decode a whole path (path segments + query).

# URL encoding / decoding

urlEncodeBuilder #

Arguments

:: Bool | Whether input is in query string. True: Query string, False: Path element
-> ByteString |
-> Builder |

Percent-encoding for URLs (using `Builder`).

urlEncode #

Arguments

:: Bool | Whether to decode `'+'` to `' '`
-> ByteString | The ByteString to encode as URL
-> ByteString | The encoded URL

Percent-encoding for URLs.

urlDecode #

Arguments

:: Bool | Whether to decode `'+'` to `' '`
-> ByteString |
-> ByteString |

Percent-decoding.