index.mld

{0 Routes}

{1 Introduction}

Routes is a routing library for OCaml that allows defining type safe routes, to dispatch a request to a
matching handler, based on path parameters in the input URI target.
Type safe in this context, refers to processing the input URI in a manner that assigns
concrete types to the values extracted from the path parameters.

The library has no external dependencies aside from the OCaml standard library, and it
can be used in both native (via ocamlopt) and javascript usecases (via js_of_ocaml).
It isn't tied to any particular framework, with the intention for frameworks to provide
a higher level wrapper around it.

{2 Installation}

Routes is published on the opam repository. If using opam, install it via

stable version:
{[ opam install routes ]}

development version:
{[ opam pin add routes.dev git+https://github.com/anuragsoni/routes.git ]}

If using esy, add the dependency [@opam/routes] to [package.json/esy.json].
Or you can use [esy add @opam/routes] to add it to the manifest file automatically.

{2 Usage }

{[

let greet_user (name : string) (id : int) =
  Printf.sprintf "Hello, %s [%d]" name id

let add_user (name : string) (id : int) (is_admin : bool) =
  Printf.sprintf "Added user %s with id %d. IsAdmin? %b" name id is_admin

let greet_user_route () = Routes.(s "user" / str / int /? nil)
let add_user_route () = Routes.(s "user" / str / int / bool / s "add" /? nil)

let router = Routes.one_of [ greet_user_route () @--> greet_user
                           ; add_user_route () @--> add_user ]
]}


Routes ships with patterns that match the following types: int, int32, int64, bool, string,
but it is possible to define custom patterns that can be used
to extract path parameters that can be parsed into a user defined type.

{[
module Shape = struct
  type t =
    | Square
    | Circle

  let parse = function
    | "square" -> Some Square
    | "circle" -> Some Circle
    | _ -> None

  let serialize = function
    | Square -> "square"
    | Circle -> "circle"

  let p r = Routes.custom ~serialize ~parse ~label:":shape" r
end

(* Now the shape pattern can be used just like any
   of the built in patterns like int, bool etc *)
let route () = s "shape" / Shape.p / s "create" /? nil
]}

{1 Support}

Routes' git repository is located on {{: https://github.com/anuragsoni/routes} Github}. Use the repository's {{: https://github.com/anuragsoni/routes/issues} issue tracker} to file bug reports and feature requests.

{1 License }

Routes is distributed under the BSD-3-clause license.

{1 API documentation}
{!modules:
Routes
}