Module Url.Builder

Construct URLs.

Path builders

type t

The path builder type

val raw : string -> t

raw s creates a URL path segment from string s without percent-encoding it.

This is useful for including readable unicode graphemes in the URL path. See absolute for examples.

val string : string -> t

string s creates a URL path segment from string s.

Special characters like ?, / or non-ASCII characters will be automatically escaped using percent-encoding. See absolute for examples.

val int : int -> t

int i creates a URL path segment from the integer i.

See absolute for examples.

Query and fragment builders

module Query : sig ... end

Construct queries

module Fragment : sig ... end

Construct fragments

URL builders

type root =
  1. | Absolute
    (*

    A local URL starting with an absolute path.

    *)
  2. | Relative
    (*

    A local URL starting with a relative path (relative to the current location).

    *)
  3. | Cross_origin of string
    (*

    Cross_origin origin is a remote URL where the given origin is different from the current location.

    *)

The type of custom URL we want to construct using custom

val absolute : t list -> Query.t list -> string

absolute path_segments query_parameters constructs a local URL (omitting the scheme and authority parts), containing the given path_segments and query_parameters.

Examples:

    absolute [] []
    (* "/" *)

    absolute [string "blog"; int 2025; int 8; int 7] []
    (* "/blog/2025/8/7" *)

    absolute [string "products"] [Query.string "search" "hat"; Query.int "page" 2]
    (* "/products?search=hat&page=2" *)

    absolute [string "name"; string "Гельмут"] []
    (* "/name/%D0%93%D0%B5%D0%BB%D1%8C%D0%BC%D1%83%D1%82" *)

    absolute [string "name"; raw "Гельмут"] []
    (* "/name/Гельмут" *)

    absolute [] [Query.string "emoji" "😅"]
    (* "?emoji=%F0%9F%98%85" *)

    absolute [] [Query.raw "emoji" "😅"]
    (* "?emoji=😅" *)
val relative : t list -> Query.t list -> string

relative path_segments query_parameters constructs a relative local URL (relative the the current location), containing the given path_segments and query_parameters.

This behaves the same as absolute, but omits the leading slash.

Examples:

    relative [] []
    (* "" *)

    relative [string "blog"; int 2025; int 8; int 7] []
    (* "blog/2025/8/7" *)
val cross_origin : string -> t list -> Query.t list -> string

cross_origin pre_path path_segments query_parameters allows constructing a cross-origin URL, (a URL with a different host than the current location), containing the given path_segments and query_parameters.

pre_path is inserted before the path as-is without further checks or encoding.

Example:

    cross_origin "https://ocaml.org" [string "books"] []
    (* "https://ocaml.org/books" *)
val custom : root -> t list -> Query.t list -> Fragment.t option -> string

custom root path_segments query_parameters fragment allows constructing custom URLs containing the given path_segments, query_parameters and fragment.

Examples:

    custom
        Absolute
        [string "article"; int 42]
        [Query.string "search" "ocaml"]
        [Some Fragment.string "conclusion"]
    (* "/article/42?search=ocaml#conclusion" *)

    custom
        (Cross_origin "https://ocaml.org")
        [string "excercises"]
        []
        (Some Fragment.int 6)
    (* "https://ocaml.org/excercises#6" *)