Module Kurl.Fmt

URL request formatters.


type kurl = t

See Kurl.t.

type t = fmt

See fmt.

val empty : ?disable_rel:bool -> ?use_exts:bool -> ?scheme:string -> ?authority:string -> root:Webs.Http.Path.t -> unit -> fmt

empty ~disable_rel ~use_exts ~scheme ~host ~root () is an empty URL formatter with:

  • scheme, a scheme used for full URL formatting, see req.
  • host, a host used for full URL formatting, see req.
  • root, the root path prepended to all URL request paths.
  • use_exts, appends the extension of bare URLs to formatted URLs, defaults to false and expands directory indexes if requested by kind, see kind.
  • disable_rel turns relative formatting functions into absolute ones (defaults to false). true is faster. The idea is to disable it for serving over the http[s] scheme and enable it for serving over the file scheme.

This empty URL formatter has any bound on the root. This means that untyped URL formatting is readily available. For example via:

let url uf path = Kurl.Url.url uf Kurl.(V (any, Bare.v `GET path))
val with_fmt : ?disable_rel:bool -> ?use_exts:bool -> ?scheme:string -> ?authority:string -> ?root:Webs.Http.Path.t -> fmt -> fmt

with_fmt uf is uf with formatter parameters changed as specified. See Fmt.empty.

val scheme : fmt -> string

scheme uf is the scheme of uf, can be empty.

val authority : fmt -> string

authority uf is the authority of uf, can be empty.

val root : fmt -> Webs.Http.Path.t

root uf is the root path of uf.

val disable_rel : fmt -> bool

disable_rel uf is true if relative formatting is turned into absolute formatting.

val use_exts : fmt -> bool

use_exts uf is true if bare URL extensions are appended to formatted URLs.

Typed formatting


val bind : Webs.Http.Path.t -> 'a kind -> fmt -> fmt

bind p k uf is uf with URL requests of kind k bound to well-formed path p.

Raises Invalid_argument if k is already bound in uf or if p not well-formed.

val bind_tree : 'a tree -> fmt -> fmt

bind_tree t uf is uf with URL request kinds in t bound to their path in t.


val bare : fmt -> kurl -> bare

bare uf (V (k, u)) is k's bare absolute URL request for u. Note that this differs from k's encoding only in the URL path.

Raises Invalid_arg if k is not part of fmt's tree.

val req : ?full:bool -> fmt -> kurl -> Webs.Http.Method.t * string

req is like Fmt.bare' but returns an encoded URL path and query (if any).

If full is true (defaults to false) a complete URL is returned:

  1. scheme: is prepended iff scheme is non empty.
  2. // follows iff both scheme and authority are non empty or if authority is empty and scheme is "file".
  3. authority follows iff authority is non empty.
  4. The URL path and query follow

In general it's better to avoid full URLs if you can, but it can be useful e.g. for sitemap generation.

val url : ?full:bool -> fmt -> kurl -> string

url is req without the method.


val rel_bare : fmt -> src:kurl -> dst:kurl -> bare

rel_bare rf ~src ~dst s is a relative raw request from src to dst. Compared to Fmt.bare this only changes the path of the result which is the relative path from src to dst.

Note this assumes both paths do not have dot or non-final empty segments.

Raises Invalid_arg if root or sub is not part of fmt's tree.

val rel_req : fmt -> src:kurl -> dst:kurl -> Webs.Http.Method.t * string

rel_req is like rel_bare but returns an encoded URL path, including the query (if any).

val rel_url : fmt -> src:kurl -> dst:kurl -> string

rel_url is rel_req without the method.