Uri

Utilities for working with URIs.

Added in 0.6.0

No other changes yet.

from "uri" include Uri

Types

Type declarations included in the Uri module.

Uri.Uri

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

1
2
3

enum ParseError {
  ParseError,
}

Represents an error encountered while parsing a URI.

Uri.ConstructUriError

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

1
2
3

enum ResolveReferenceError {
  BaseNotAbsolute,
}

Represents an error encountered while attempting to resolve a URI reference to a target URI.

Uri.DecodingError

1
2
3

enum DecodingError {
  InvalidEncoding,
}

Represents an error encountered while attempting to percent-decode a string.

Uri.EncodeSet

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

Added in 0.6.0

No other changes yet.

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:

Uri.encode("h3ll0_.w ?o+rld", encodeSet=Uri.EncodeNonUnreserved) // "h3ll0_.w%20%3Fo%2Brld"

Uri.encode("d+om@i:n.com", encodeSet=Uri.EncodeRegisteredHost) // "d+om%40i%3An.com"

Uri.encode("word", encodeSet=Uri.EncodeCustom(c => c == 'o')) // "w%6Frd"

Uri.decode

Added in 0.6.0

No other changes yet.

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

Added in 0.6.0

No other changes yet.

1
2

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

Added in 0.6.0

No other changes yet.

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

Added in 0.6.0

No other changes yet.

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:

Uri.parse("https://grain-lang.org") == Ok(...)

Uri.parse("http://@*^%") == Err(Uri.ParseError)

Uri.resolveReference

Added in 0.6.0

No other changes yet.

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:

resolveReference(unwrap(parse("https://grain-lang.org/docs/stdlib/uri")), unwrap(parse("../intro"))) // https://grain-lang.org/docs/intro

resolveReference(unwrap(parse("https://grain-lang.org/docs")), unwrap(parse("?key=val"))) // https://grain-lang.org/docs?key=val

resolveReference(unwrap(parse("https://grain-lang.org/docs")), unwrap(parse("google.com/search"))) // https://google.com/search

Uri.make

Added in 0.6.0

No other changes yet.

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:

Uri.make(scheme=Some("https"), host=Some("grain-lang.org")) // https://grain-lang.org

Uri.make(host=Some("g/r@in"), encodeComponents=false) // Err(Uri.InvalidHostError)

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

Uri.make(port=Some(80)) // Err(Uri.PortWithNoHost)

Uri.update

Added in 0.6.0

No other changes yet.

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:

let uri = Result.unwrap(Uri.parse("https://grain-lang.org/docs?k=v")) // Base URI for following examples

Uri.update(uri, scheme=Some(Some("ftp"))) // ftp://grain-lang.org/docs?k=v

Uri.update(uri, query=Some(None)) // https://grain-lang.org/docs

Uri.update(uri, host=Some(Some("g/r@in")), encodeComponents=true) // https://g%2Fr%40in/docs?k=v

Uri.update(uri, host=Some(None), port=Some(Some(80))) // Err(Uri.PortWithNoHost)

Uri.hasAuthority

Added in 0.6.0

No other changes yet.

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

Added in 0.6.0

No other changes yet.

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

Added in 0.6.0

No other changes yet.

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`