uri_string

20172017 Ericsson AB. All Rights Reserved. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. uri_string Péter Dimitrov 1 2017-10-24 A

uri_string URI processing functions.

This module contains functions for parsing and handling URIs (RFC 3986) and form-urlencoded query strings (RFC 1866).

A URI is an identifier consisting of a sequence of characters matching the syntax rule named URI in RFC 3986.

The generic URI syntax consists of a hierarchical sequence of components referred to as the scheme, authority, path, query, and fragment:

    URI         = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
    hier-part   = "//" authority path-abempty
                   / path-absolute
                   / path-rootless
                   / path-empty
    scheme      = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
    authority   = [ userinfo "@" ] host [ ":" port ]
    userinfo    = *( unreserved / pct-encoded / sub-delims / ":" )

    reserved    = gen-delims / sub-delims
    gen-delims  = ":" / "/" / "?" / "#" / "[" / "]" / "@"
    sub-delims  = "!" / "$" / "&" / "'" / "(" / ")"
                / "*" / "+" / "," / ";" / "="

    unreserved  = ALPHA / DIGIT / "-" / "." / "_" / "~"

The interpretation of a URI depends only on the characters used and not on how those characters are represented in a network protocol.

The functions implemented by this module covers the following use cases:

Parsing URIs

parse/1 Recomposing URIs

recompose/2 Transcoding URIs

transcode/2 Working with form-urlencoded query strings

compose_query/[1,2], dissect_query/1

There are four different encodings present during the handling of URIs:

Inbound binary encoding in binaries Inbound percent-encoding in lists and binaries Outbound binary encoding in binaries Outbound percent-encoding in lists and binaries

Unless otherwise specified the return value type and encoding are the same as the input type and encoding. That is, binary input returns binary output, list input returns a list output but mixed input returns list output. Input and output encodings are the same except for transcode/2.

All of the functions but transcode/2 expects input as unicode codepoints in lists, UTF-8 encoding in binaries and UTF-8 encoding in percent-encoded URI parts. transcode/2 provides the means to convert between the supported URI encodings.

URI map holding the main components of a URI.

List of unicode codepoints, UTF-8 encoded binary, or a mix of the two, representing an RFC 3986 compliant URI (percent-encoded form). A URI is a sequence of characters from a very limited set: the letters of the basic Latin alphabet, digits, and a few special characters.

Compose urlencoded query string.

Composes a form-urlencoded QueryString based on a QueryList, a list of unescaped key-value pairs. Media type application/x-www-form-urlencoded is defined in section 8.2.1 of RFC 1866 (HTML 2.0). Reserved and unsafe characters, as defined by RFC 1738 (Uniform Resource Locators), are percent-encoded.

Example:

1> uri_string:compose_query([{"foo bar","1"},{"city","örebro"}]).

Compose urlencoded query string.

Same as compose_query/1 but with an additional Options parameter, that controls the type of separator used between key-value pairs. There are three supported separator types: amp (), escaped_amp () and semicolon (;). If the parameter Options is empty, separator takes the default value (escaped_amp).

Example:

1> uri_string:compose_query([{"foo bar","1"},{"city","örebro"}],
2> [{separator, semicolon}]).
"foo+bar=1;city=%C3%B6rebro"

Dissect query string.

Dissects an urlencoded QueryString and returns a QueryList, a list of unescaped key-value pairs. Media type application/x-www-form-urlencoded is defined in section 8.2.1 of RFC 1866 (HTML 2.0). Percent-encoded segments are decoded as defined by RFC 1738 (Uniform Resource Locators).

Example:

1> uri_string:dissect_query("foo+bar=1;city=%C3%B6rebro").
[{"foo bar","1"},{"city","örebro"}]

Parse URI into a map.

Returns a URIMap, that is a uri_map() with the parsed components of the URIString.

If parsing fails, an error tuple is returned.

Example:

1> uri_string:parse("foo://user@example.com:8042/over/there?name=ferret#nose").
#{fragment => "nose",host => "example.com",
  path => "/over/there",port => 8042,query => "name=ferret",
  scheme => foo,userinfo => "user"}

Recompose URI.

Returns an RFC 3986 compliant URIString (percent-encoded).

If the URIMap is invalid, an error tuple is returned.

Example:

1> URIMap = #{fragment => "nose", host => "example.com", path => "/over/there",
port => 8042, query => "name=ferret", scheme => "foo", userinfo => "user"}.
#{fragment => "top",host => "example.com",
  path => "/over/there",port => 8042,query => "?name=ferret",
  scheme => foo,userinfo => "user"}

2> uri_string:recompose(URIMap).
"foo://example.com:8042/over/there?name=ferret#nose"

Transcode URI.

Transcodes an RFC 3986 compliant URIString, where Options is a list of tagged tuples, specifying the inbound (in_encoding) and outbound (out_encoding) encodings.

If an argument is invalid, an error tuple is returned.

Example:

1> >,]]>
2> [{in_encoding, utf32},{out_encoding, utf8}]).
>]]>