Skip to content
Find file
Fetching contributors…
Cannot retrieve contributors at this time
216 lines (154 sloc) 6.2 KB
(* Ohm is © 2011 Victor Nicollet *)
(** Unique 11-character string identifiers. *)
(** The type of identifiers.
For all practical purposes, this is a string, but it's of an abstract type so that
conversions are explicit, thus avoiding an entire category of subtle mistakes.
*)
type t
val compare : t -> t -> int
(** Convert a JSON value to an identifier.
The code below displays {v 00xFv012cFH v}:
{[
let json : Json_type.t = Json_type.Build.string "00xFv012cFH" in
let id : Id.t = Id.of_json json in
print_endline (Id.str id)
]}
@raise Json_type.Json_error for JSON values that are not a string.
*)
val of_json : Json_type.t -> t
(** Convert a JSON value to an identifier, without exceptions.
Equivalent to {!of_json} but returns [None] instead of raising an exception.
*)
val of_json_safe : Json_type.t -> t option
(** Convert a JSON string to an identifier, without exceptions.
Parses the provided string as a JSON value, then applies {!on_json_safe}.
The code below displays {v 00xFv012cFH v}:
{[
let json_string = "\"00xFv012cFH\"" in
let id_opt : Id.t option = Id.of_json_string_safe json in
let Some id = id_opt in
print_endline (Id.str id)
]}
*)
val of_json_string_safe : string -> t option
(** Convert an identifier to a JSON string.
Applies {!to_json} and serializes the resulting JSON value.
The code below displays {v "00xFv012cFH" v}:
{[
let id : Id.t = Id.of_string "00xFv012cFH" in
print_endline (Id.to_json_string id)
]}
*)
val to_json_string : t -> string
(** Convert an identifier to a JSON value.
The code below displays a fresh unique identifier:
{[
let id : Id.t = Id.gen () in
let json : Json_type.t = Id.to_json id in
print_endline (Json_type.Browse.string json)
]}
*)
val to_json : t -> Json_type.t
(** Identity, useful when you need to use a CouchDB table without defining a specific
identifier type.
*)
val to_id : t -> t
(** Identity, useful when you need to use a CouchDB table without defining a specific
identifier type.
*)
val of_id : t -> t
(** Convert a string to an identifier.
This is purely a type-casting operation, so that the following is true:
{[ id == Id.of_string (Id.to_string id) ]}
It is not necessary for the string to be 11 characters long, but it
is nonetheless advised.
*)
val of_string : string -> t
(** Convert an identifier to a string.
This is purely a type-casting operation, so that the following is true:
{[ str = Id.to_string (Id.of_string id) ]}
*)
val to_string : t -> string
(** Alias for {!Id.to_string}. *)
val str : t -> string
(** Create the CSS/jQuery selector for an identifier.
This feature is useful when generating unique element IDs for an HTML document. This function
prepends a hash (#) character to the identifier, which is the CSS and jQuery syntax for a
selector that selects that identifier.
The code below displays {v #my-identifier v}:
{[
let id : Id.t = Id.of_string "my-identifier" in
print_endline (Id.sel id)
]}
*)
val sel : t -> string
(** Create a new unique identifier using {!Util.uniq}.
The identifier matches the regular expression {v [a-zA-Z0-9]\{11\} v}. If two identifiers [a] and [b]
are generated by the same process in that order, then [a < b]. If they were generated by two different
processes, [a < b] if [a] was generated at least one second before [b].
There is no risk of collision between identifiers, unless two processes with the same PID each generate
one identifier at the same second {i and} they have generated the same number of identifiers since they
started running.
The generation function uses [Unix.gettimeofday ()] and [Unix.getpid ()] to compute the current time
and the PID.
*)
val gen : unit -> t
(** The JSON formatter for identifiers. See module {!Fmt} for more information about JSON formatters. *)
val fmt : t Fmt.t
(** The length of identifiers generated by {!Id.gen}. *)
val length : int
(** The smallest possible ID. Use this for range queries in, for example, CouchDB. *)
val smallest : t
(** The largest possible 11-character ID, as constructed by {!Id.gen}. Use this for range queries in,
for example, CouchDB. Do not use if you are building your own identifiers instead of relying
on {!Id.gen}.
*)
val largest : t
val next : t -> t
val arg : (t -> string) * (string -> t option)
val seg : (t -> string) * (string -> t)
(** The type of a strongly typed identifier module. These modules define a new identifier type tagged
with a type parameter that carries additional information about the identifier. The new identifier
type has a special type [t] which is an abbreviation for [[`Unknown] id]: a bottom type.
This module type is intended to be the public interface of all strongly typed identifier modules.
For implementation, [include] module {!Id.Phantom} below in your module to define
all the functions in this module type, then add all other necessary functions.
*)
module type PHANTOM = sig
(** The phantom type. *)
type 'relation id
val compare : 'relation id -> 'relation id -> int
(** Construct a strongly typed identifier from a normal {!Id.t}. *)
val of_id : t -> [`Unknown] id
(** Any strongly typed identifier can be converted back to an identifier. *)
val to_id : 'any id -> t
include Fmt.FMT with type t = [`Unknown] id
val fmt : 'a id Fmt.t
val gen : unit -> t
val smallest : t
val largest : t
val next : 'a id -> 'a id
val to_string : 'any id -> string
val of_string : string -> t
(** Any identifier can be converted to the bottom type identifier. *)
val decay : 'any id -> t
val arg : (t -> string) * (string -> t option)
val seg : (t -> string) * (string -> t)
end
module Phantom : sig
type 'relation id = t
val compare : 'relation id -> 'relation id -> int
include Fmt.FMT with type t = [`Unknown] id
val fmt : 'a id Fmt.t
val of_id : t -> [`Unknown] id
val to_id : 'any id -> t
val gen : unit -> t
val smallest : t
val largest : t
val next : 'a id -> 'a id
val decay : 'any id -> t
val to_string : 'any id -> string
val of_string : string -> t
val arg : (t -> string) * (string -> t option)
val seg : (t -> string) * (string -> t)
end
Jump to Line
Something went wrong with that request. Please try again.