http-types-0.12.4: Generic HTTP types for Haskell (for both client and server code).
Safe HaskellSafe-Inferred
LanguageHaskell2010

Network.HTTP.Types.URI

Description

Query strings generally have the following form: "key1=value1&key2=value2"

>>> renderQuery False [("key1", Just "value1"), ("key2", Just "value2")]
"key1=value1&key2=value2"

But if the value of key1 is Nothing, it becomes: key1&key2=value2

>>> renderQuery False [("key1", Nothing), ("key2", Just "value2")]
"key1&key2=value2"

This module also provides type synonyms and functions to handle queries that do not allow/expect keys without values (SimpleQuery), handle queries which have partially escaped characters

Synopsis

Query strings

Query

type Query = [QueryItem] Source #

A sequence of QueryItems.

type QueryItem = (ByteString, Maybe ByteString) Source #

An item from the query string, split up into two parts.

The second part should be Nothing if there was no key-value separator after the query item name.

Since: 0.2.0

renderQuery :: Bool -> Query -> ByteString Source #

Renders the given Query into a ByteString.

If you want a question mark (?) added to the front of the result, use True.

Since: 0.2.0

renderQueryBuilder :: Bool -> Query -> Builder Source #

Renders the given Query into a Builder.

If you want a question mark (?) added to the front of the result, use True.

Since: 0.5

parseQuery :: ByteString -> Query Source #

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 ' '

Since: 0.2.0

parseQueryReplacePlus :: Bool -> ByteString -> Query Source #

Same functionality as parseQuery, but with the option to decode '+' characters to ' ' or to preserve any '+' encountered.

If you want to replace any '+' with a space, use True.

Since: 0.12.2

Query (Text)

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

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

Since: 0.5.2

queryTextToQuery :: QueryText -> Query Source #

Convert QueryText to Query.

Since: 0.5.2

queryToQueryText :: Query -> QueryText Source #

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

Since: 0.5.2

renderQueryText :: Bool -> QueryText -> Builder Source #

Convert QueryText to a Builder.

If you want a question mark (?) added to the front of the result, use True.

Since: 0.5.2

parseQueryText :: ByteString -> QueryText Source #

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

queryToQueryText . parseQuery

Since: 0.5.2

SimpleQuery

If values are guaranteed, it might be easier working with SimpleQuery.

This way, you don't have to worry about any Maybes, though when parsing a query string and there's no '=' after the key in the query item, the value will just be an empty ByteString.

type SimpleQuery = [SimpleQueryItem] Source #

A sequence of SimpleQueryItems.

type SimpleQueryItem = (ByteString, ByteString) Source #

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

Since: 0.2.0

simpleQueryToQuery :: SimpleQuery -> Query Source #

Convert SimpleQuery to Query.

Since: 0.5

renderSimpleQuery :: Bool -> SimpleQuery -> ByteString Source #

Render the given SimpleQuery into a ByteString.

If you want a question mark (?) added to the front of the result, use True.

Since: 0.2.0

parseSimpleQuery :: ByteString -> SimpleQuery Source #

Parse SimpleQuery from a ByteString.

This uses parseQuery under the hood, and will transform any Nothing values into an empty ByteString.

Since: 0.2.0

PartialEscapeQuery

For some values in query items, certain characters must not be percent-encoded, for example '+' or ':' in

q=a+language:haskell+created:2009-01-01..2009-02-01&sort=stars

Using specific EscapeItems provides a way to decide which parts of a query string value will be URL encoded and which won't.

This is mandatory when searching for '+' (%2B being a percent-encoded '+'):

q=%2B+language:haskell

type PartialEscapeQuery = [PartialEscapeQueryItem] Source #

Query with some characters that should not be escaped.

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

Since: 0.12.1

type PartialEscapeQueryItem = (ByteString, [EscapeItem]) Source #

Partially escaped query item.

The key will always be encoded using 'urlEncode True', but the value will be encoded depending on which EscapeItems are used.

Since: 0.12.1

data EscapeItem Source #

Section of a query item value that decides whether to use regular URL encoding (using 'urlEncode True') with QE, or to not encode anything with QN.

Since: 0.12.1

Constructors

QE ByteString

will be URL encoded

QN ByteString

will NOT at all be URL encoded

Instances

Instances details
Show EscapeItem Source # 
Instance details

Defined in Network.HTTP.Types.URI

Methods

showsPrec :: Int -> EscapeItem -> ShowS #

show :: EscapeItem -> String #

showList :: [EscapeItem] -> ShowS #

Eq EscapeItem Source # 
Instance details

Defined in Network.HTTP.Types.URI

Methods

(==) :: EscapeItem -> EscapeItem -> Bool #

(/=) :: EscapeItem -> EscapeItem -> Bool #

Ord EscapeItem Source # 
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 #

renderQueryPartialEscape :: Bool -> PartialEscapeQuery -> ByteString Source #

Convert PartialEscapeQuery to ByteString.

If you want a question mark (?) added to the front of the result, use True.

>>> renderQueryPartialEscape True [("a", [QN "x:z + ", QE (encodeUtf8 "They said: \"שלום\"")])]
"?a=x:z + They%20said%3A%20%22%D7%A9%D7%9C%D7%95%D7%9D%22"

Since: 0.12.1

renderQueryBuilderPartialEscape :: Bool -> PartialEscapeQuery -> Builder Source #

Convert a PartialEscapeQuery to a Builder.

If you want a question mark (?) added to the front of the result, use True.

Since: 0.12.1

Path

Segments + Query String

extractPath :: ByteString -> ByteString Source #

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

Though a more accurate description of this function's behaviour is that it removes the domain/origin if the string starts with an HTTP protocol. (i.e. http:// or https://)

This function will not change anything when given any other ByteString. (except return a root path "/" if given an empty string)

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

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

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

>>> extractPath ""
"/"

>>> extractPath "www.google.com/some/path"
"www.google.com/some/path"

Since: 0.8.5

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

Encode a whole path (path segments + query).

Since: 0.5

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

Decode a whole path (path segments + query).

Since: 0.5

Path Segments

encodePathSegments :: [Text] -> Builder Source #

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

This function takes the following three steps:

  • UTF-8 encodes the characters.
  • Prepends each segment with a slash.

  • Performs percent-encoding on all characters that are not:

    • alphanumeric (i.e. A-Z and a-z)
    • digits (i.e. 0-9)
    • a dash '-', an underscore '_', a dot '.', or a tilde '~'

For example:

>>> encodePathSegments ["foo", "bar1", "~baz"]
"/foo/bar1/~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.

Since: 0.5

encodePathSegmentsRelative :: [Text] -> Builder Source #

Like encodePathSegments, but without the initial slash.

Since: 0.6.10

decodePathSegments :: ByteString -> [Text] Source #

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

Will also decode any percent-encoded characters.

Since: 0.5

URL encoding / decoding

urlEncode :: Bool -> ByteString -> ByteString Source #

Percent-encoding for URLs.

In short:

  • if you're encoding (parts of) a path element, use False.
  • if you're encoding (parts of) a query string, use True.

In-depth explanation

Expand

This will substitute every byte with its percent-encoded equivalent unless:

  • The byte is alphanumeric. (i.e. A-Z, a-z, or 0-9)
  • The byte is either a dash '-', an underscore '_', a dot '.', or a tilde '~'

  • If False is used, the following will also not be percent-encoded:

    • colon ':', at sign '@', ampersand '&', equals sign '=', plus sign '+', dollar sign '$' or a comma ','

Since: 0.2.0

urlEncodeBuilder :: Bool -> ByteString -> Builder Source #

Percent-encoding for URLs.

Like urlEncode, but only makes the Builder.

Since: 0.5

urlDecode :: Bool -> ByteString -> ByteString Source #

Percent-decoding.

If you want to replace any '+' with a space, use True.

Since: 0.2.0