ESC
No recent searches
Search by
Standard Library  /  Uri

Grain Docs

Welcome to Grain! Editor Setup Getting Grain

The Guide

Hello World The Basics Conditionals Functions Shadowing and Mutation Loops Lists and arrays Custom Data Types Modules Pattern Matching

Reference

Building for Production Built-in Types The Grain CLI Graindoc

Standard Library

Pervasives BigInt Array Buffer Bytes Char Exception Float32 Float64 Hash Int16 Int32 Int64 Int8 Json List Map Marshal Number Option Path PriorityQueue Queue Random Range Rational Regex Result Stack Set String Uint16 Uint32 Uint64 Uint8 Uri wasi / File wasi / Process wasi / Random wasi / Time

Uri

Utilities for working with URIs.

Edit on GitHub
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

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

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:

str: The string to encode
?encodeSet: An indication for which characters to percent-encode. EncodeNonUnreserved by default

Returns:

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:

str: The string to decode

Returns:

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

Encodes a list of key-value pairs into an query string.

Parameters:

urlVals: A list of key-value pairs

Returns:

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:

str: A query string

Returns:

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:

str: The RFC 3986 URI string to parse

Returns:

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:

base: The base URI to resolve a URI reference on
ref: The URI reference to apply onto the base

Returns:

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:

?scheme: Some(scheme) containing the desired scheme component or None for a scheme-less URI
?userinfo: Some(userinfo) containing the desired userinfo component or None for a userinfo-less URI
?host: Some(host) containing the desired host component or None for a host-less URI
?port: Some(port) containing the desired port component or None for a port-less URI
?path: The desired path for the URI. "" by default
?query: Some(query) containing the desired query string component or None for a query-less URI
?fragment: Some(fragment) containing the desired fragment component or None for a fragment-less URI
?encodeComponents: 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:

uri: The Uri to update
?scheme: Some(scheme) containing the desired updated scheme component or None to maintain the base URI’s scheme
?userinfo: Some(userinfo) containing the desired updated userinfo component or None to maintain the base URI’s userinfo
?host: Some(host) containing the desired updated host component or None to maintain the base URI’s host
?port: Some(port) containing the desired updated port component or None to maintain the base URI’s port
?path: Some(path) containing the desired updated path component or None to maintain the base URI’s path
?query: Some(query) containing the desired updated query string component or None to maintain the base URI’s query
?fragment: Some(fragment) containing the desired updated fragment component or None to maintain the base URI’s fragment
?encodeComponents: 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:

uri: The Uri to consider

Returns:

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:

uri: The Uri to consider

Returns:

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:

uri: The Uri to convert

Returns:

String: A string representation of the Uri
Uint8 File

Sign up for farm-to-inbox developer news

You can unsubscribe at any time. Read our privacy policy.

Copyright © 2024 The Grain Programming Language