package brr

  1. Overview
  2. Docs
Legend:
Library
Module
Module type
Parameter
Class
Class type

URIs and URI parameters.

Uri.t values are URL objects but we tweak the API to use RFC 3986 terminology and in contrast to the URL API we return component data without including separators like ':', '?' and '#' in the results.

URIs

type t

The type for URL objects.

val v : ?base:Jstr.t -> Jstr.t -> t

v ?base s is a URI from s relative to base (if specified). Raises in in case of error, use of_jstr if you need to deal with user input.

val scheme : t -> Jstr.t

scheme u is the scheme of u. This is what the URL API calls the protocol but without including the trailing ':'.

val host : t -> Jstr.t

host u is the host of u. This is not percent-decoded and what the URL API calls the hostname.

val port : t -> int option

port u is the port of u, if any. Parsed from the URL API's port.

val path : t -> Jstr.t

path u is the path of u. This is not percent-decoded and what the URL API calls pathname. Use path_segments for decoding the path.

Note. In hierarchical URI schemes like http this is "/" even if there is no path in u: no distinction is made between http://example.org and http://example.org/.

val query : t -> Jstr.t

query u is the query of u. This not percent-decoded and what the URL API calls the search but without including the leading '?'. Use query_params to decode key-value parameters.

val fragment : t -> Jstr.t

fragment u is fragment of u. This is not percent-decoded and what the URL API calls the hash but without including the leading '#'. Use fragment_params to decode key-value parameters.

val with_uri : ?scheme:Jstr.t -> ?host:Jstr.t -> ?port:int option -> ?path:Jstr.t -> ?query:Jstr.t -> ?fragment:Jstr.t -> t -> (t, Jv.Error.t) result

with_uri u is u with the specified components updated. The components are assumed to be appropriately percent-encoded. See also with_path_segments, with_query_params and with_fragment_params.

Path segments

type path = Jstr.t list

The type for absolute URI paths represented as non-empty lists of percent-decoded path segments. The empty list denotes the absence of a path.

Path segments can be Jstr.empty. The root path / is represented by the list [Jstr.empty] and /a by [Jstr.v "a"].

Warning. You should never concatenate these segments with a directory separator to get a file path because path segments may contain stray, percent-decoded, directory separators.

val path_segments : t -> (path, Jv.Error.t) result

path_segments u determines the segments of the path of u and percent-decodes them. This is the empty list if the path is empty. The root path is [Jstr.empty].

val with_path_segments : t -> path -> (t, Jv.Error.t) result

with_path_segments u segs is u with a path made by percent-encoding the segments, prepending a '/' to each segment and concatenating the result.

Note. In hierarchical URI schemes like http an empty segs is mapped to the root path, see path.

Fragment or query parameters

module Params : sig ... end

URI fragment or query parameters.

val query_params : t -> Params.t

query_params u is Params.of_jstr (query u).

val with_query_params : t -> Params.t -> t

with_query_params u ps is u with a query defined by parameters ps.

val fragment_params : t -> Params.t

fragment_params u is Params.of_jstr (fragment u).

val with_fragment_params : t -> Params.t -> t

with_fragment_params u ps is u with a fragment defined by parameters ps.

Converting

val of_jstr : ?base:Jstr.t -> Jstr.t -> (t, Jv.Error.t) result

of_jstr ~base s is a URL from s relative to base (if specified). Note that if s is relative and base is unspecified the function errors.

val to_jstr : t -> Jstr.t

to_jstr u is u as a JavaScript string. The result is percent-encoded.

Percent encoding

val encode : Jstr.t -> (Jstr.t, Jv.Error.t) result

encode s percent-encodes an UTF-8 representation of s. See encodeURI.

Warning. This encodes according to RFC2396 not according to RFC3986 which reserves a few more characters.

val decode : Jstr.t -> (Jstr.t, Jv.Error.t) result

decode s percent-decodes a UTF-8 representation of s. See decodeURI.

val encode_component : Jstr.t -> (Jstr.t, Jv.Error.t) result

encode s percent-encodes a UTF-8 representation of s. See encodeURIComponent.

val decode_component : Jstr.t -> (Jstr.t, Jv.Error.t) result

decode s percent-descodes a UTF-8 representation of s. See decodeURIComponent. Note that this has the same effect as decode.

OCaml

Innovation. Community. Security.