Module Fmlib_browser.Url

Construct and parse URLs.

Basics

type protocol =
  1. | Http
  2. | Https

The protocol (a.k.a. scheme) of the URL. Only web-related protocols are supported.

type t = {
  1. protocol : protocol;
  2. host : string;
  3. port : int option;
  4. path : string;
  5. query : string option;
  6. fragment : string option;
}

The parts of a URL.

The URL spec defines the parts like this:

      https://example.com:8042/over/there?name=ferret#nose
      \___/   \______________/\_________/ \_________/ \__/
        |            |            |            |        |
      scheme     authority       path        query   fragment

The strings in this type are not transformed in any way yet. The Parser module has functions for that, e.g. splitting the path into segments, accessing specific query parameters and decoding the results into custom data types.

Other parts of this library like Command.http_request require URLs as strings. Those should be constructed directly using functions from the Builder module, e.g Builder.absolute or Builder.custom.

NOTE: Not all URL features from the URL spec are supported. For example, the userinfo segment as part of the authority is not supported.

val of_string : string -> t option

of_string s tries to split s into its URL parts.

Examples:

    of_string "http://example.com:443"
    =
    Some
        {
            protocol = Http;
            host = "example.com";
            port = Some 443;
            path = "/";
            query = None;
            fragment = None;
        }

    of_string "https://example.com/hats?q=top%20hat"
    =
    Some
        {
            protocol = Https;
            host: "example.com";
            port = None;
            path = "/hats";
            query = Some "q=top%20hat";
            fragment = None;
        }

    of_string "example.com:443" = None (* no protocol *)

    of_string "http://tom@example.com" = None (* userinfo not allowed *)

    of_string "http://#cats" = None (* no host *)
val to_string : t -> string

to_string url serializes the given url into a string.

This is useful, when we have a Url.t and need to pass it on as string to Command.push_url or debug. For constructing URL strings from scratch, it is more convenient to use functions from the Builder module, e.g Builder.absolute or Builder.custom.

Percent-encoding

val percent_encode_part : string -> string

percent_encode_part s encodes a part of a URL by escaping special characters like ?, / or non-ASCII characters. This uses Javascript's encodeURIComponent internally.

Normally the Builder module should be used for constructing URLs. This function is here for exceptional cases that require more control.

val percent_decode_part : string -> string option

percent_decode-part s decodes a part of a URL recovering special characters like ?, / or non-ASCII characters. This uses Javascript's decodeURIComponent internally.

Normally the Parser module should be used for decoding URLs. This function is here for exceptional cases that require more control.

Builders and parsers

module Builder : sig ... end

Construct URLs.

module Parser : sig ... end

Parse URLs.