resto 0.7 · OCaml Package

Paths describe URIs/URLs: segments separated by slashes (/).

Note that paths can be static (i.e., all the segments of the path are determined in advance) or dynamic (i.e., some segments of the path are actually arguments for the service -- e.g., paths can have the form /user/<user-name> where <user-name> is a string encoding of a user identifier).

type ('prefix, 'params) t

The type for service's paths

A (p, a) path is a path in which some segments encode a value of type a.

Typically a (_, unit) path is a static path. Also typically, a dynamic path has type (_, ((unit * a) * b) * ..) path where different segments encode the different components of the tuple (a, b, etc.). For example the path /entries-by-date/<year>/<month>/<day> may be described as a (_, ((unit * int) * int) * int) path.

type ('prefix, 'params) path = ('prefix, 'params) t

type 'prefix context = ('prefix, 'prefix) path

val root : unit context

root is the basis to build paths upon. It is the "Nil" of path construction.

val open_root : 'a context

val add_suffix : ('prefix, 'params) path -> string -> ('prefix, 'params) path

add_suffix p s is a path in which s has been appended to the sequence of segments described by p.

val (/) : ('prefix, 'params) path -> string -> ('prefix, 'params) path

(/) is an infix operator for add_suffix.

val add_arg : 
  ('prefix, 'params) path ->
  'a Arg.t ->
  ('prefix, 'params * 'a) path

add_arg p a is a path in which a segment representing a value of type a has been appended to the sequence of segments described by p.

This is intended for use by services. Specifically, a service that is parameterized over a value of type ty is attached to a path that includes an argument for a value of type ty. When the service is called, Resto decodes the argument and passes its value to the service.

val (/:) : ('prefix, 'params) path -> 'a Arg.t -> ('prefix, 'params * 'a) path

(/:) is an infix operator for add_arg.

val add_final_args : 
  ('prefix, 'params) path ->
  'a Arg.t ->
  ('prefix, 'params * 'a list) path

add_final_args p a is a path in which an arbitrary sequence of segments representing values of type a has been appended to the sequence of segments described by p.

A similar use to the add_arg is intended, but for a list of values rather than a single value.

Note that, as the name suggests, add_final_args is final: you cannot add further suffixes or arguments to the resulting path. Attempting to do so raises Invalid_arg. Similarly, using the resulting path as a prefix (see below) raises the same exception. This is because paths built with add_final_args consume all the suffix as an unterminated list of arguments, there cannot be further suffixes or arguments.

val (/:*) : 
  ('prefix, 'params) path ->
  'a Arg.t ->
  ('prefix, 'params * 'a list) path

( /:* ) is an infix operator for add_final_args.

val prefix : 
  ('prefix, 'a) path ->
  ('a, 'params) path ->
  ('prefix, 'params) path

prefix p q is a path in which the sequence of segments of p is followed by the sequence of segments of q.

val subst0 : ('p, 'p) path -> ('p2, 'p2) path

val subst1 : ('p, 'p * 'a) path -> ('p2, 'p2 * 'a) path

val subst2 : ('p, ('p * 'a) * 'b) path -> ('p2, ('p2 * 'a) * 'b) path

val subst3 : 
  ('p, (('p * 'a) * 'b) * 'c) path ->
  ('p2, (('p2 * 'a) * 'b) * 'c) path

package resto