Universal Values.
This module creates an extensible variant type, that resembles extensible variant types, introduced in 4.02, but even more safe and more extensible, and, what really matters, serializable. Basically you should think of Value.t
as a union type, aka sum type, that can be extended in any place, including your plugin code. Where extending is adding new constructor. To add new constructor, you need to register it, e.g.,
let function_signature = Value.Tag.register (module String)
~name:"function_signature"
~uuid:"2175c28c-08ca-4052-8385-3a01e1c6ab6f"
This is merely equivalent to adding a branch
| Function_signature of string
to existing union type. The main difference is that the name
shouldn't be unique (in fact name
doesn't bear any semantic meaning, it basically for pretty-printing). On the other hand the uuid
parameter must be unique across the universe, space and time. To get the UUID with such properties, you can use uuidgen
program that is usually available on Linux and Mac OS.
name
and uuid
must be strings, known at compile time, in other words it must be string literal, not just an arbitrary string, created dynamically. This is made intentionally, in order to prevent the abuse of the system.
The (module String)
syntax creates a value from the module String
, (so called first-class module). The module should implement Value.S
signature, that requires pretty-printing, comparison function and serialization.
module type S = sig
type t with bin_io, compare, sexp
val pp : Format.formatter -> t -> unit
end
The good news is that, most of the types in Core
and Bap
do conform with the requirements. Usually, one can implement the requirements very easily by using type-driven syntax extensions (although, you still need to implement pretty-printing function yourself):
module Loc = struct
type t = string * int * int
with bin_io, compare, sexp
let pp ppf (file,line,col) =
Format.fprintf ppf "%s:%d:%d" file line col
end
let loc = Value.Tag.register (module Loc)
~name:"loc"
~uuid:"400e190e-ce21-488d-87b1-c101709621a8"
The returned value, is a tag that can be used to constructed values of that branch, and to deconstruct (extract) them. You may think of it as a cipher key, that is used to package data into the value container, and later to unpack it:
# let main_pos = Value.create loc ("test.c", 20, 2);;
val main_pos : value = test.c:20:2
You may see, that OCaml pretty-prints the value. That's neat! Also, you may see, that the returned expression has type value
. That means that it can be used uniformly with other values, for example, you can put them in one container, e.g.,
# let main_t = Value.create function_signature
"void main(int argc, const char *argv[])";;
val main_t : value = void main(int argc, const char *argv[])
# let main = [main_pos; main_t];;
val main : value list = [
test.c:20:2;
void main(int argc, const char *argv[])
]
To extract value you can use Value.get
function:
# Value.get loc main_pos;;
- : Loc.t option = Some ("test.c", 20, 2)
This will require an extra allocation of an option
container, and in a performance critical context it may be unacceptable. For this special case you can use a more efficient:
if Value.is loc then Value.get_exn loc main_pos
.
Underneath the hood, the values of type value
is just a pair of an original value and runtime type information.
The comparison of two values of type value
is actually a multi-method, as it has the following behavior:
1. If both values has the same type, then use compare
function, that was provided for this type. 2. If values are of different types, that are known to the type system, then compare them using RTTI, and ignore the value. 3. If at least one of the values is of the unknown type, (i.e., type wasn't registered in the type system), then use polymorphic compare on a tuple of UUID and binary representation of the values.
The rules above guarantee, that values with different RTTI id are never equal. It also guarantees that the ordering will be preserved between different builds of a program, and even between different versions of the compiler.
Thread safety
The only thread unsafe function is register
, that should be called in the module initialization time. In general programs modules are initialized in a single thread, so this shouldn't be an issue. The implementation by itself doesn't call register
.
Tag constructor of type 'a
module type S = sig ... end
A required interface for the type to be lifted to value.
literal string. Don't look at the right hand side of a type equation, this is just a way to say that a string should be a literal not a value. Compiler will automatically coerce your string literals to this type.
persistent type identifier
val create : 'a tag -> 'a -> t
create cons x
creates a value using constructor cons
and argument x
val is : 'a tag -> t -> bool
is cons v
true if value v
was constructed with constructor cons
, i.e., it is true only when is_cons t (create t x)
val get : 'a tag -> t -> 'a option
get cons
extracts a value associated with a constructor cons
(Essentially, performs a pattern match on the specified variant branch)
val get_exn : 'a tag -> t -> 'a
get_exn t v
extracts value created with t
from the variant. Raises unspecified exception if variant v
wasn't created with t
.
val tagname : t -> string
tagname value
returns a constructor name of the value
typeid value
returns a type identifier of the value
module Match : sig ... end
Persistent type identifiers.
Although values of type value
implements regular interface it is recommended to used dict
data structure instead of those, that are provided by Regular
interface.x
include Regular.Std.Regular.S with type t := t
include Regular.Std.Printable.S with type t := t
val to_string : t -> string
to_string x
returns a human-readable representation of x
val str : unit -> t -> string
str () t
is formatted output function that matches "%a" conversion format specifier in functions, that prints to string, e.g., sprintf
, failwithf
, errorf
and, surprisingly all Lwt
printing function, including Lwt_io.printf
and logging (or any other function with type ('a,unit,string,...) formatN`. Example:
Or_error.errorf "type %a is not valid for %a"
Type.str ty Exp.str exp
val pps : unit -> t -> string
will print to a standard output_channel
, useful for using in printf
, fprintf
, etc.
prints a sequence of values of type t
this will include pp
function from Core
that has type t printer
, and can be used in Format.printf
family of functions
include Core_kernel.Pretty_printer.S with type t := t
include Core_kernel.Comparable.S_binable with type t := t
include Base.Comparable.S with type t := t
include Base.Comparisons.S with type t := t
val equal : t -> t -> bool
val compare : t -> t -> int
compare t1 t2
returns 0 if t1
is equal to t2
, a negative integer if t1
is less than t2
, and a positive integer if t1
is greater than t2
.
val ascending : t -> t -> int
ascending
is identical to compare
. descending x y = ascending y x
. These are intended to be mnemonic when used like List.sort ~compare:ascending
and List.sort
~cmp:descending
, since they cause the list to be sorted in ascending or descending order, respectively.
val descending : t -> t -> int
val between : t -> low:t -> high:t -> bool
between t ~low ~high
means low <= t <= high
val clamp_exn : t -> min:t -> max:t -> t
clamp_exn t ~min ~max
returns t'
, the closest value to t
such that between t' ~low:min ~high:max
is true.
Raises if not (min <= max)
.
include Regular.Std.Data.S with type t := t
type info = string * [ `Ver of string ] * string option
name,Ver v,desc
information attached to a particular reader or writer.
Data representation version. After any change in data representation the version should be increased.
Serializers that are derived from a data representation must have the same version as a version of the data structure, from which it is derived. This kind of serializers can only read and write data of the same version.
Other serializers can actually read and write data independent on its representation version. A serializer, that can't store data of current version simply shouldn't be added to a set of serializers.
It is assumed, that if a reader and a writer has the same name and version, then whatever was written by the writer should be readable by the reader. The round-trip equality is not required, thus it is acceptable if some information is lost.
It is also possible, that a reader and a writer that has the same name are compatible. In that case it is recommended to use semantic versioning.
val size_in_bytes : ?ver:string -> ?fmt:string -> t -> int
size_in_bytes ?ver ?fmt datum
returns the amount of bytes that is needed to represent datum
in the given format and version
of_bytes ?ver ?fmt bytes
deserializes a value from bytes.
to_bytes ?ver ?fmt datum
serializes a datum
to a sequence of bytes.
blit_to_bytes ?ver ?fmt buffer datum offset
copies a serialized representation of datum into a buffer
, starting from the offset
.
of_bigstring ?ver ?fmt buf
deserializes a datum from bigstring
of_bigstring ?ver ?fmt datum
serializes a datum to a sequence of bytes represented as bigstring
blit_to_bigstring ?ver ?fmt buffer datum offset
copies a serialized representation of datum into a buffer
, starting from offset
.
Input/Output functions for the given datum.
module Cache : sig ... end
add_reader ?desc ~ver name reader
registers a new reader
with a provided name
, version ver
and optional description desc
add_writer ?desc ~ver name writer
registers a new writer
with a provided name
, version ver
and optional description desc
val available_readers : unit -> info list
available_reader ()
lists available readers for the data type
val default_reader : unit -> info
default_reader
returns information about default reader
val set_default_reader : ?ver:string -> string -> unit
set_default_reader ?ver name
sets new default reader. If version is not specified then the latest available version is used. Raises an exception if a reader with a given name doesn't exist.
val with_reader : ?ver:string -> string -> (unit -> 'a) -> 'a
with_reader ?ver name operation
temporary sets a default reader to a reader with a specified name and version. The default reader is restored after operation
is finished.
val available_writers : unit -> info list
available_writer ()
lists available writers for the data type
val default_writer : unit -> info
default_writer
returns information about the default writer
val set_default_writer : ?ver:string -> string -> unit
set_default_writer ?ver name
sets new default writer. If version is not specified then the latest available version is used. Raises an exception if a writer with a given name doesn't exist.
val with_writer : ?ver:string -> string -> (unit -> 'a) -> 'a
with_writer ?ver name operation
temporary sets a default writer to a writer with a specified name and version. The default writer is restored after operation
is finished.
val default_printer : unit -> info option
default_writer
optionally returns an information about default printer
val set_default_printer : ?ver:string -> string -> unit
set_default_printer ?ver name
sets new default printer. If version is not specified then the latest available version is used. Raises an exception if a printer with a given name doesn't exist.
val with_printer : ?ver:string -> string -> (unit -> 'a) -> 'a
with_printer ?ver name operation
temporary sets a default printer to a printer with a specified name and version. The default printer is restored after operation
is finished.
Low level access to serializers
find_reader ?ver name
lookups a reader with a given name. If version is not specified, then a reader with maximum version is returned.
find_writer ?ver name
lookups a writer with a given name. If version is not specified, then a writer with maximum version is returned.