title
Uri

Utilities for working with URIs.

Added in next

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

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

enum ResolveReferenceError {
  BaseNotAbsolute,
}

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

Uri.PercentDecodingError

enum PercentDecodingError {
  InvalidPercentEncoding,
}

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

Uri.PercentEncodeSet

enum PercentEncodeSet {
  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.percentEncode

Added in next

No other changes yet.

percentEncode : (str: String, ?encodeSet: PercentEncodeSet) => String

Percent-encodes characters in a string based on the specified PercentEncodeSet.

Parameters:

param	type	description
`str`	`String`	The string to encode
`?encodeSet`	`PercentEncodeSet`	An indication for which characters to percent-encode. `EncodeNonUnreserved` by default

Returns:

type	description
`String`	A percent-encoding of the given string

Examples:

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

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

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

Uri.percentDecode

Added in next

No other changes yet.

percentDecode : (str: String) => Result<String, PercentDecodingError>

Decodes any percent-encoded characters in a string.

Parameters:

param	type	description
`str`	`String`	The string to decode

Returns:

type	description
`Result<String, PercentDecodingError>`	`Ok(decoded)` containing a the decoded string or `Err(err)` if the decoding failed

Uri.encodeQuery

Added in next

No other changes yet.

encodeQuery :
  (urlVals: List<(String, String)>, ?encodeSet: PercentEncodeSet) => 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 next

No other changes yet.

decodeQuery :
  (str: String) => Result<List<(String, String)>, PercentDecodingError>

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)>, PercentDecodingError>`	A list of key-value pairs containing the values of the encoded string

Uri.parse

Added in next

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, `Err(ParseError)` otherwise

Examples:

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

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

Uri.resolveReference

Added in next

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

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>, ?percentEncodeComponents: 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
`?percentEncodeComponents`	`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"), percentEncodeComponents=false) // Err(Uri.InvalidHostError)

Uri.make(scheme=Some("abc"), host=Some("g/r@in"), query=Some("k/ey=v^@l"), percentEncodeComponents=true) // abc://g%2Fr%40in?k/ey=v%5E@l

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

Uri.update

Added in next

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>>,
   ?percentEncodeComponents: 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 base `Uri` to apply updates on top of
`?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
`?percentEncodeComponents`	`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")), percentEncodeComponents=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 next

No other changes yet.

hasAuthority : (uri: Uri) => Bool

Determines whether or not 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, `false` otherwise

Uri.isAbsolute

Added in next

No other changes yet.

isAbsolute : (uri: Uri) => Bool

Determines whether or not 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), `false` otherwise

Uri.toString

Added in next

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 to a string

Returns:

type	description
`String`	A string representation of the `Uri`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

uri.md

uri.md

Types

Uri.Uri

Uri.ParseError

Uri.ConstructUriError

Uri.ResolveReferenceError

Uri.PercentDecodingError

Uri.PercentEncodeSet

Values

Uri.percentEncode

Uri.percentDecode

Uri.encodeQuery

Uri.decodeQuery

Uri.parse

Uri.resolveReference

Uri.make

Uri.update

Uri.hasAuthority

Uri.isAbsolute

Uri.toString

Files

uri.md

Latest commit

History

uri.md

File metadata and controls

Types

Uri.Uri

Uri.ParseError

Uri.ConstructUriError

Uri.ResolveReferenceError

Uri.PercentDecodingError

Uri.PercentEncodeSet

Values

Uri.percentEncode

Uri.percentDecode

Uri.encodeQuery

Uri.decodeQuery

Uri.parse

Uri.resolveReference

Uri.make

Uri.update

Uri.hasAuthority

Uri.isAbsolute

Uri.toString