@grain/stdlib 0.5.12 → 0.6.0

package/uri.md

@@ -0,0 +1,477 @@
+---
+title: Uri
+---
+
+Utilities for working with URIs.
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+from "uri" include Uri
+```
+
+## Types
+
+Type declarations included in the Uri module.
+
+### Uri.**Uri**
+
+```grain
+record Uri {
+  scheme: Option<String>,
+  userinfo: Option<String>,
+  host: Option<String>,
+  port: Option<Number>,
+  path: String,
+  query: Option<String>,
+  fragment: Option<String>,
+}
+```
+
+Represents a parsed RFC 3986 URI.
+
+### Uri.**ParseError**
+
+```grain
+enum ParseError {
+  ParseError,
+}
+```
+
+Represents an error encountered while parsing a URI.
+
+### Uri.**ConstructUriError**
+
+```grain
+enum ConstructUriError {
+  UserinfoWithNoHost,
+  PortWithNoHost,
+  InvalidSchemeError,
+  InvalidUserinfoError,
+  InvalidHostError,
+  InvalidPortError,
+  InvalidPathError,
+  InvalidQueryError,
+  InvalidFragmentError,
+}
+```
+
+Represents an error encountered while constructing a URI with `make` or `update`.
+
+### Uri.**ResolveReferenceError**
+
+```grain
+enum ResolveReferenceError {
+  BaseNotAbsolute,
+}
+```
+
+Represents an error encountered while attempting to resolve a URI reference to a target URI.
+
+### Uri.**DecodingError**
+
+```grain
+enum DecodingError {
+  InvalidEncoding,
+}
+```
+
+Represents an error encountered while attempting to percent-decode a string.
+
+### Uri.**EncodeSet**
+
+```grain
+enum EncodeSet {
+  EncodeNonUnreserved,
+  EncodeUserinfo,
+  EncodeRegisteredHost,
+  EncodePath,
+  EncodePathSegment,
+  EncodeQueryOrFragment,
+  EncodeCustom((Char => Bool)),
+}
+```
+
+Used to specify which characters to percent-encode from a string.
+
+## Values
+
+Functions and constants included in the Uri module.
+
+### Uri.**encode**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+encode : (str: String, ?encodeSet: EncodeSet) => String
+```
+
+Percent-encodes characters in a string based on the specified `EncodeSet`.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`str`|`String`|The string to encode|
+|`?encodeSet`|`EncodeSet`|An indication for which characters to percent-encode. `EncodeNonUnreserved` by default|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`String`|A percent-encoding of the given string|
+
+Examples:
+
+```grain
+Uri.encode("h3ll0_.w ?o+rld", encodeSet=Uri.EncodeNonUnreserved) // "h3ll0_.w%20%3Fo%2Brld"
+```
+
+```grain
+Uri.encode("d+om@i:n.com", encodeSet=Uri.EncodeRegisteredHost) // "d+om%40i%3An.com"
+```
+
+```grain
+Uri.encode("word", encodeSet=Uri.EncodeCustom(c => c == 'o')) // "w%6Frd"
+```
+
+### Uri.**decode**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+decode : (str: String) => Result<String, DecodingError>
+```
+
+Decodes any percent-encoded characters in a string.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`str`|`String`|The string to decode|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<String, DecodingError>`|`Ok(decoded)` containing the decoded string or `Err(err)` if the decoding failed|
+
+### Uri.**encodeQuery**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+encodeQuery :
+  (urlVals: List<(String, String)>, ?encodeSet: EncodeSet) => String
+```
+
+Encodes a list of key-value pairs into an query string.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`urlVals`|`List<(String, String)>`|A list of key-value pairs|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`String`|A query string|
+
+### Uri.**decodeQuery**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+decodeQuery : (str: String) => Result<List<(String, String)>, DecodingError>
+```
+
+Decodes a query string into a list of pairs.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`str`|`String`|A query string|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<List<(String, String)>, DecodingError>`|`Ok(decoded)` containing a list of key-value pairs from the decoded string or `Err(err)` if the decoding failed|
+
+### Uri.**parse**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+parse : (str: String) => Result<Uri, ParseError>
+```
+
+Parses a string into a `Uri` according to RFC 3986. If the URI string has a
+path it will be automatically normalized, removing unnecessary `.` and `..`
+segments.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`str`|`String`|The RFC 3986 URI string to parse|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<Uri, ParseError>`|`Ok(uri)` containing a `Uri` if the given string is a valid URI or `Err(ParseError)` otherwise|
+
+Examples:
+
+```grain
+Uri.parse("https://grain-lang.org") == Ok(...)
+```
+
+```grain
+Uri.parse("http://@*^%") == Err(Uri.ParseError)
+```
+
+### Uri.**resolveReference**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+resolveReference :
+  (base: Uri, ref: Uri) => Result<Uri, ResolveReferenceError>
+```
+
+Transforms a base URI and a URI reference into a target URI
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`base`|`Uri`|The base URI to resolve a URI reference on|
+|`ref`|`Uri`|The URI reference to apply onto the base|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Result<Uri, ResolveReferenceError>`|`Ok(uri)` containing the target `Uri` or `Err(err)` if the input is malformed|
+
+Examples:
+
+```grain
+resolveReference(unwrap(parse("https://grain-lang.org/docs/stdlib/uri")), unwrap(parse("../intro"))) // https://grain-lang.org/docs/intro
+```
+
+```grain
+resolveReference(unwrap(parse("https://grain-lang.org/docs")), unwrap(parse("?key=val"))) // https://grain-lang.org/docs?key=val
+```
+
+```grain
+resolveReference(unwrap(parse("https://grain-lang.org/docs")), unwrap(parse("google.com/search"))) // https://google.com/search
+```
+
+### Uri.**make**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+make :
+  (?scheme: Option<String>, ?userinfo: Option<String>, ?host: Option<String>,
+   ?port: Option<Number>, ?path: String, ?query: Option<String>,
+   ?fragment: Option<String>, ?encodeComponents: Bool) =>
+   Result<Uri, ConstructUriError>
+```
+
+Constructs a new `Uri` from components.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`?scheme`|`Option<String>`|`Some(scheme)` containing the desired scheme component or `None` for a scheme-less URI|
+|`?userinfo`|`Option<String>`|`Some(userinfo)` containing the desired userinfo component or `None` for a userinfo-less URI|
+|`?host`|`Option<String>`|`Some(host)` containing the desired host component or `None` for a host-less URI|
+|`?port`|`Option<Number>`|`Some(port)` containing the desired port component or `None` for a port-less URI|
+|`?path`|`String`|The desired path for the URI. `""` by default|
+|`?query`|`Option<String>`|`Some(query)` containing the desired query string component or `None` for a query-less URI|
+|`?fragment`|`Option<String>`|`Some(fragment)` containing the desired fragment component or `None` for a fragment-less URI|
+|`?encodeComponents`|`Bool`|Whether or not to apply percent encoding for each component to remove unsafe characters for each component|
+
+Examples:
+
+```grain
+Uri.make(scheme=Some("https"), host=Some("grain-lang.org")) // https://grain-lang.org
+```
+
+```grain
+Uri.make(host=Some("g/r@in"), encodeComponents=false) // Err(Uri.InvalidHostError)
+```
+
+```grain
+Uri.make(scheme=Some("abc"), host=Some("g/r@in"), query=Some("k/ey=v^@l"), encodeComponents=true) // abc://g%2Fr%40in?k/ey=v%5E@l
+```
+
+```grain
+Uri.make(port=Some(80)) // Err(Uri.PortWithNoHost)
+```
+
+### Uri.**update**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+update :
+  (uri: Uri, ?scheme: Option<Option<String>>,
+   ?userinfo: Option<Option<String>>, ?host: Option<Option<String>>,
+   ?port: Option<Option<Number>>, ?path: Option<String>,
+   ?query: Option<Option<String>>, ?fragment: Option<Option<String>>,
+   ?encodeComponents: Bool) => Result<Uri, ConstructUriError>
+```
+
+Constructs a new `Uri` from a base `Uri` and components to update. The
+pattern used to update each component is that `None` means the base URI's
+component should be used and `Some(val)` means that a new value should be
+used for that component.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`uri`|`Uri`|The `Uri` to update|
+|`?scheme`|`Option<Option<String>>`|`Some(scheme)` containing the desired updated scheme component or `None` to maintain the base URI's scheme|
+|`?userinfo`|`Option<Option<String>>`|`Some(userinfo)` containing the desired updated userinfo component or `None` to maintain the base URI's userinfo|
+|`?host`|`Option<Option<String>>`|`Some(host)` containing the desired updated host component or `None` to maintain the base URI's host|
+|`?port`|`Option<Option<Number>>`|`Some(port)` containing the desired updated port component or `None` to maintain the base URI's port|
+|`?path`|`Option<String>`|`Some(path)` containing the desired updated path component or `None` to maintain the base URI's path|
+|`?query`|`Option<Option<String>>`|`Some(query)` containing the desired updated query string component or `None` to maintain the base URI's query|
+|`?fragment`|`Option<Option<String>>`|`Some(fragment)` containing the desired updated fragment component or `None` to maintain the base URI's fragment|
+|`?encodeComponents`|`Bool`|Whether or not to apply percent encoding for each updated component to remove unsafe characters|
+
+Examples:
+
+```grain
+let uri = Result.unwrap(Uri.parse("https://grain-lang.org/docs?k=v")) // Base URI for following examples
+```
+
+```grain
+Uri.update(uri, scheme=Some(Some("ftp"))) // ftp://grain-lang.org/docs?k=v
+```
+
+```grain
+Uri.update(uri, query=Some(None)) // https://grain-lang.org/docs
+```
+
+```grain
+Uri.update(uri, host=Some(Some("g/r@in")), encodeComponents=true) // https://g%2Fr%40in/docs?k=v
+```
+
+```grain
+Uri.update(uri, host=Some(None), port=Some(Some(80))) // Err(Uri.PortWithNoHost)
+```
+
+### Uri.**hasAuthority**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+hasAuthority : (uri: Uri) => Bool
+```
+
+Determines whether a `Uri` has an authority (i.e. has a host component)
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`uri`|`Uri`|The `Uri` to consider|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the `Uri` has an authority component or `false` otherwise|
+
+### Uri.**isAbsolute**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+isAbsolute : (uri: Uri) => Bool
+```
+
+Determines whether a `Uri` is an absolute URI (has a scheme component)
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`uri`|`Uri`|The `Uri` to consider|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`Bool`|`true` if the `Uri` is absolute (has a scheme component) or `false` otherwise|
+
+### Uri.**toString**
+
+<details disabled>
+<summary tabindex="-1">Added in <code>0.6.0</code></summary>
+No other changes yet.
+</details>
+
+```grain
+toString : (uri: Uri) => String
+```
+
+Converts the given `Uri` into a string.
+
+Parameters:
+
+|param|type|description|
+|-----|----|-----------|
+|`uri`|`Uri`|The `Uri` to convert|
+
+Returns:
+
+|type|description|
+|----|-----------|
+|`String`|A string representation of the `Uri`|
+