package mehari

  1. Overview
  2. Docs

Module Mehari.Path

A slighty modified version of Nightmare service API, many thanks to them! Refer to the original specification if necessary.

A path is a fragment of the URL. For example, in the following URL: "https://foo.bar/a/b/c", a/b/c is the path. In the construction of links or controllers between different services, we generally use path which can introduce constant fragments, or variables.

For example, consider this URL fragment: "user/123e4567-e89b-12d3-a456-426614174000", we can assume that user is constant while the path suffix is a UUID, which can vary depending on the profile we want to display.

This separation between constant fragments and variables allows a bidirectional use of path (being able to produce links, or being able to interpret links, i.e. for a given path, providing a function that extracts the variables parts).

Variables

Combinators to describe variables in a path.

type 'a variable

A variable describes how to serialize and deserialize an arbitrary value to and from a string. It is therefore a function pair: from_string : string -> 'a option and to_string: 'a -> string.

val variable : from_string:(string -> 'a option) -> to_string:('a -> string) -> 'a variable

variable ~from_string ~to_string constructs a value of type 'a variable. In order to be able to construct only valid URLs, it is suggested to avoid constructing variables for type aliases (e.g. to describe a UUID) and to use abstract types to force their validated creation.

Pre-defined variable descriptor

Set of predefined variable descriptors for common and usual types.

val string : string variable

string describes a variable of type string.

val int : int variable

int describes a variable of type int.

val float : float variable

float describes a variable of type float.

val bool : bool variable

bool describes a variable of type bool.

val char : char variable

char describes a variable of type char.

Path

A path is described by a type parameterised by two other types. The first, 'continuation defines the type of continuation generated by the path, and 'witness defines the return type of the continuation (which varies depending on how one decides to use the path). So `handler_continuation always has 'witness as the last type.

Here are some examples of continuations generated for given fragments. (It is assumed that the expressions described by ":type" describe a fragment that is a variable of type type:

  • "/" will have the type 'witness
  • "/foo/bar" will have the type 'witness because the path does not introduce a variable
  • "foo/:string/:int/bar" will have the type string -> int -> 'witness.

It should therefore be borne in mind that the first type parameter 'continuation of a path describes a continuation whose normal form will always, invariably be the second type parameter ('witness) and the latter varies according to usage. If for example the path is used to generate a string, it will be of type string (and the continuation will be of type 'a -> string.

type ('continuation, 'witness) t

A wrapped path is wrapped in a unit -> t function to avoid the value restriction.

type ('continuation, 'witness) wrapped = unit -> ('continuation, 'witness) t

Composing path

val root : ('witness, 'witness) t

root returns the root of a path. Every path starts with a root.

val add_constant : string -> ('continuation, 'witness) t -> ('continuation, 'witness) t

add_constant str path returns a new path with a constant fragment.

val add_variable : 'new_variable variable -> ('continuation, 'new_variable -> 'witness) t -> ('continuation, 'witness) t

add_variable variable path returns a new path with a variable fragment.

Example

For example, let's imagine this URL fragment, which can retrieve the first N messages posted by a user in a certain category: get_messages/:int/by_user/:string/in_category/:string (Yes, it's not a very RESTful fragment). This is how we could describe the corresponding path:

let a_path =
  root
  |> add_constant "get_messages"
  |> add_variable int |> add_constant "by_user" |> add_variable string
  |> add_constant "in_category"
  |> add_variable string

Infix operators

module Infix : sig ... end

As the non-infix way of describing paths is rather verbose, here is a collection of infix operators to describe a path in a rather natural way.

val (~/) : string -> ('witness, 'witness) t

~/str is root |> add_constant str.

val (~/:) : 'new_variable variable -> ('new_variable -> 'witness, 'witness) t

~/:var is root |> add_variable var.

val (/) : ('continuation, 'witness) t -> string -> ('continuation, 'witness) t

path / str is path |> add_constant str. A (flipped) infix version of add_constant.

val (/:) : ('continuation, 'new_variable -> 'witness) t -> 'new_variable variable -> ('continuation, 'witness) t

path /: var is path |> add_variable var. A (flipped) infix version of add_variable.

Example

Let's go back to our previous example (get_messages/:int/by_user/:string/in_category/:string).With infix operators, writing a path that captures these fragments is much shorter:

let a_path =
  ~/"get_message" /: int / "by_user" /: string / "in_category" /: string