From b0c682a8118c5775da784e9a0f569ee995319f80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Thu, 26 Oct 2017 11:29:48 +0200 Subject: stdlib: Update documentation, error tuples --- lib/stdlib/doc/src/uri_string.xml | 117 +++++++++++++++++++++++++++----------- 1 file changed, 85 insertions(+), 32 deletions(-) (limited to 'lib/stdlib/doc/src') diff --git a/lib/stdlib/doc/src/uri_string.xml b/lib/stdlib/doc/src/uri_string.xml index d67c687fd1..8322eecb24 100644 --- a/lib/stdlib/doc/src/uri_string.xml +++ b/lib/stdlib/doc/src/uri_string.xml @@ -30,10 +30,13 @@ uri_string URI processing functions. -

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

+

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.

+ 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:

@@ -55,16 +58,24 @@


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:

+

The functions implemented by this module cover 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 + Parsing URIs into its components and returing a map

+ parse/1 + + Recomposing a map of URI components into a URI string

+ recompose/1 + + Changing inbound binary and percent-encoding of URIs

+ transcode/2 + + Composing form-urlencoded query strings from a list of key-value pairs

+ compose_query/1

+ compose_query/2 + + Dissecting form-urlencoded query strings into a list of key-value pairs

+ dissect_query/1 +

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

@@ -75,14 +86,29 @@

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.

+ output but mixed input returns list output.

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.

 + + + +

Error tuple indicating the type of error. Possible values of the second component:

+ + invalid_character + invalid_input + invalid_map + invalid_percent_encoding + invalid_scheme + invalid_uri + invalid_utf8 + missing_value + + + @@ -93,7 +119,8 @@

List of unicode codepoints, UTF-8 encoded binary, or a mix of the two, - representing an RFC 3986 compliant URI (percent-encoded form). + 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.

 @@ -109,13 +136,21 @@

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. + 8.2.1 of RFC 1866 + (HTML 2.0). Reserved and unsafe characters, as + defined by RFC 1738 + (Uniform Resource Locators), are percent-encoded.

+

See also the opposite operation + dissect_query/1.

Example:

-1> uri_string:compose_query([{"foo bar","1"},{"city","örebro"}]).
-
+1> uri_string:compose_query([{"foo bar","1"},{"city","örebro"}],
+1> [{separator, semicolon}]).
+"foo+bar=1;city=%C3%B6rebro"
+2> >,<<"1">>},
+2> {<<"city">>,<<"örebro"/utf8>>}]).]]>
+>]]>
@@ -127,11 +162,14 @@

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

+

See also the opposite operation + dissect_query/1. +

Example:

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

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). + 8.2.1 of RFC 1866 + (HTML 2.0). Percent-encoded segments are decoded + as defined by RFC 1738 + (Uniform Resource Locators).

+

See also the opposite operation + compose_query/1.

Example:

 1> uri_string:dissect_query("foo+bar=1;city=%C3%B6rebro").
 [{"foo bar","1"},{"city","örebro"}]
+2> >).]]>
+>,<<"1">>},{<<"city">>,<<"örebro"/utf8>>}] ]]>
@@ -159,14 +203,19 @@ 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.

+ of the URIString. If parsing fails, an error tuple is returned.

+

See also the opposite operation + recompose/1.

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"}
+2> >).]]>
+ <<"example.com">>,path => <<"/over/there">>,
+  port => 8042,query => <<"name=ferret">>,scheme => <<"foo">>,
+  userinfo => <<"user">>}]]>
@@ -175,12 +224,15 @@ Recompose URI. -

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

-

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

+

Returns an RFC 3986 compliant + URIString (percent-encoded). + If the URIMap is invalid, an error tuple is returned.

+

See also the opposite operation + parse/1.

Example:

 1> URIMap = #{fragment => "nose", host => "example.com", path => "/over/there",
-port => 8042, query => "name=ferret", scheme => "foo", userinfo => "user"}.
+1> 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"}
@@ -194,14 +246,15 @@ port => 8042, query => "name=ferret", scheme => "foo", userinfo => "user"}.
       
       Transcode URI.
       
-        
Transcodes an RFC 3986 compliant URIString,
+        
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.

+	(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}]).
+1> [{in_encoding, utf32},{out_encoding, utf8}]).
 >]]>
 	

       
-- 
cgit v1.2.3