Previous  Up  Next

Module Common

module Common: sig .. end
Basic types and definitions required throughout the system.
exception Bug of string
exception Finally of exn * exn
Raised when finalization after an exception failed, too. The first exception argument is the one raised by the initial function, the second exception the one raised by the finalizer.
val unimplemented : string -> 'a Or_error.t
For marking a given value as unimplemented. Typically combined with conditional compilation, where on some platforms the function is defined normally, and on some platforms it is defined as unimplemented. The supplied string should be the name of the function that is unimplemented.
type decimal = float
The decimal type alias provides more readable serializations to s-expressions, at the cost of lower precision. For example: 

    # sexp_of_decimal 3.000000000001;;
    - : Sexp.t = 3
    # sexp_of_float 3.000000000001;;
    - : Sexp.t = 3.0000000000010000889

Also, the decimal sexp-converter will fail when provided with nan or infinity. 

    # float_of_sexp (Sexp.Atom "nan");;
    - : float = nan
    # decimal_of_sexp (Sexp.Atom "nan");;
    Exception:
    (Sexplib.Conv.Of_sexp_error (Failure common.ml.Decimal_nan_or_inf) nan).
    

type read_only
Types for use as markers in phantom types. One should not expose functions for converting between read_only/immutable/read_write because the private types expose the subtyping. Users would say "(db :> read_only Db.t)" to cast. The difference between read-only and immutable is that someone else can change a read-only object, while immutable never changes.
type immutable = private read_only 
type read_write = private read_only 
type never_returns = Never_returns.never_returns
never_returns should be used as the return type of functions that don't return and might block forever, rather than 'a or _. This forces callers of such functions to have a call to never_returns at the call site, which makes it clear to readers what's going on. We do not intend to use this type for functions such as failwithf that always raise an exception.
val never_returns : never_returns -> 'a

Error handling

val protect : f:(unit -> 'a) -> finally:(unit -> unit) -> 'a
See exn.mli
val protectx : f:('b -> 'a) -> 'b -> finally:('b -> unit) -> 'a

Input Output

val fst3 : 'a * 'b * 'c -> 'a
triple handling 

val snd3 : 'b * 'a * 'c -> 'a
val trd3 : 'b * 'c * 'a -> 'a
val uw : 'a option -> 'a
Option handling

val is_none : 'a option -> bool
val is_some : 'a option -> bool
val (|!) : 'a -> ('a -> 'b) -> 'b
Functions from fn.ml

val (|>) : 'a -> ('a -> 'b) -> 'b
val ident : 'a -> 'a
val const : 'a -> 'b -> 'a
val (==>) : bool -> bool -> bool
val (^/) : string -> string -> string
same as Filename.concat
val failwiths : string -> 'a -> ('a -> Sexplib.Sexp.t) -> 'b
val failwithf : ('r, unit, string, unit -> 'a) Pervasives.format4 -> 'r
val invalid_argf : ('r, unit, string, unit -> 'a) Pervasives.format4 -> 'r
val ok_exn : 'a Or_error.t -> 'a
Or_error.ok_exn
val error : string -> 'a -> ('a -> Sexplib.Sexp.t) -> 'b Or_error.t
Or_error.error
type 'a return = private {
   return :'b. 'a -> 'b;
}
with_return f allows for something like the return statement in C within f. There are three ways f can terminate:

1. If f calls r.return x, then x is returned by with_return. 2. If f evaluates to a value x, then x is returned by with_return. 3. If f raises an exception, it escapes with_return.

Here is a typical example: 

   let find l ~f =
     with_return (fun r ->
        List.iter l ~f:(fun x -> if f x then r.return (Some x));
        None
      )

It is only because of a deficiency of ML types that with_return doesn't have type: 

 val with_return : 'a. (('a -> ('b. 'b)) -> 'a) -> 'a

but we can slightly increase the scope of 'b, without changing the meaning of the type and then we get 

   type 'a return = { return : 'b . 'a -> b }
   val with_return : ('a return -> 'a) -> 'a

But the actual reason we chose to use a record type with polymorphic field is that otherwise we would have to clobber the namespace of functions with return and that is undesirable because return would get hidden as soon as we open any monad. We considered names different than return but everything seemed worse than just having return as a record field. We are clobbering the namespace of record fields but that is much more acceptable.

val with_return : ('a return -> 'a) -> 'a
val phys_equal : 'a -> 'a -> bool
We disable == and != and replace them with the longer and more mnemonic phys_equal because they too easily lead to mistakes (for example they don't even work right on Int64 or Float). One can usually use the equal function for a specific type, or use (=) or (<>) for built in types like char, int, float,
val (==) : [ `Consider_using_phys_equal ] ->
       [ `Consider_using_phys_equal ] -> [ `Consider_using_phys_equal ]
val (!=) : [ `Consider_using_phys_equal ] ->
       [ `Consider_using_phys_equal ] -> [ `Consider_using_phys_equal ]
val force : 'a Lazy.t -> 'a
val stage : 'a -> 'a Staged.t
See module : Staged for documentation
val unstage : 'a Staged.t -> 'a
exception C_malloc_exn of int * int
Raised if malloc in C bindings fail (errno * size).

Deprecated operations

The following section contains definitions that hide operations from the standard library that are considered problematic or confusing, or simply redundant.

val seek_out : [ `Deprecated_use_out_channel ] ->
       [ `Deprecated_use_out_channel ] -> [ `Deprecated_use_out_channel ]
val pos_out : [ `Deprecated_use_out_channel ] -> [ `Deprecated_use_out_channel ]
val out_channel_length : [ `Deprecated_use_out_channel ] -> [ `Deprecated_use_out_channel ]
val seek_in : [ `Deprecated_use_in_channel ] ->
       [ `Deprecated_use_in_channel ] -> [ `Deprecated_use_in_channel ]
val pos_in : [ `Deprecated_use_in_channel ] -> [ `Deprecated_use_in_channel ]
val in_channel_length : [ `Deprecated_use_in_channel ] -> [ `Deprecated_use_in_channel ]
val modf : [ `Deprecated_use_float_modf ] -> [ `Deprecated_use_float_modf ]
val truncate : [ `Deprecated_use_float_iround_towards_zero ] ->
       [ `Deprecated_use_float_iround_towards_zero ]
val close_in : [ `Deprecated_use_in_channel ] -> [ `Deprecated_use_in_channel ]
we have our own version of these two, the INRIA version doesn't release the runtime lock.
val close_out : [ `Deprecated_use_out_channel ] -> [ `Deprecated_use_out_channel ]
val (&) : [ `Deprecated_use_two_ampersands ] ->
       [ `Deprecated_use_two_ampersands ] -> [ `Deprecated_use_two_ampersands ]
val max_int : [ `Deprecated_use_int_module ]
val min_int : [ `Deprecated_use_int_module ]
val ceil : [ `Deprecated_use__Float__round_up ] -> [ `Deprecated_use__Float__round_up ]
val floor : [ `Deprecated_use__Float__round_down ] ->
       [ `Deprecated_use__Float__round_down ]
val abs_float : [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
val mod_float : [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
val frexp : [ `Deprecated_use_float_module ] ->
       [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
val ldexp : [ `Deprecated_use_float_module ] ->
       [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
val float_of_int : [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
val max_float : [ `Deprecated_use_float_module ]
val min_float : [ `Deprecated_use_float_module ]
val epsilon_float : [ `Deprecated_use_float_module ]
val classify_float : [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
val string_of_float : [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
val float_of_string : [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
val infinity : [ `Deprecated_use_float_module ]
val neg_infinity : [ `Deprecated_use_float_module ]
val nan : [ `Deprecated_use_float_module ]
val int_of_float : [ `Deprecated_use_float_module ] -> [ `Deprecated_use_float_module ]
type fpclass = [ `Deprecated_use_float_module ] 
val compare_decimal : decimal -> decimal -> int
val decimal_of_sexp : Sexplib.Sexp.t -> decimal
val sexp_of_decimal : decimal -> Sexplib.Sexp.t
val bin_decimal : decimal Bin_prot.Type_class.t
val bin_read_decimal : decimal Bin_prot.Read_ml.reader
val bin_read_decimal_ : decimal Bin_prot.Unsafe_read_c.reader
val bin_read_decimal__ : (int -> decimal) Bin_prot.Unsafe_read_c.reader
val bin_reader_decimal : decimal Bin_prot.Type_class.reader
val bin_size_decimal : decimal Bin_prot.Size.sizer
val bin_write_decimal : decimal Bin_prot.Write_ml.writer
val bin_write_decimal_ : decimal Bin_prot.Unsafe_write_c.writer
val bin_writer_decimal : decimal Bin_prot.Type_class.writer
val compare_read_only : read_only -> read_only -> int
Types for use as markers in phantom types. One should not expose functions for converting between read_only/immutable/read_write because the private types expose the subtyping. Users would say "(db :> read_only Db.t)" to cast. The difference between read-only and immutable is that someone else can change a read-only object, while immutable never changes.
val bin_read_only : read_only Bin_prot.Type_class.t
val bin_read_read_only : read_only Bin_prot.Read_ml.reader
val bin_read_read_only_ : read_only Bin_prot.Unsafe_read_c.reader
val bin_read_read_only__ : (int -> read_only) Bin_prot.Unsafe_read_c.reader
val bin_reader_read_only : read_only Bin_prot.Type_class.reader
val bin_size_read_only : read_only Bin_prot.Size.sizer
val bin_write_read_only : read_only Bin_prot.Write_ml.writer
val bin_write_read_only_ : read_only Bin_prot.Unsafe_write_c.writer
val bin_writer_read_only : read_only Bin_prot.Type_class.writer
val read_only_of_sexp : Sexplib.Sexp.t -> read_only
val sexp_of_read_only : read_only -> Sexplib.Sexp.t
val compare_immutable : immutable -> immutable -> int
val bin_immutable : immutable Bin_prot.Type_class.t
val bin_read_immutable : immutable Bin_prot.Read_ml.reader
val bin_read_immutable_ : immutable Bin_prot.Unsafe_read_c.reader
val bin_read_immutable__ : (int -> immutable) Bin_prot.Unsafe_read_c.reader
val bin_reader_immutable : immutable Bin_prot.Type_class.reader
val bin_size_immutable : immutable Bin_prot.Size.sizer
val bin_write_immutable : immutable Bin_prot.Write_ml.writer
val bin_write_immutable_ : immutable Bin_prot.Unsafe_write_c.writer
val bin_writer_immutable : immutable Bin_prot.Type_class.writer
val immutable_of_sexp : Sexplib.Sexp.t -> immutable
val sexp_of_immutable : immutable -> Sexplib.Sexp.t
val compare_read_write : read_write -> read_write -> int
val bin_read_write : read_write Bin_prot.Type_class.t
val bin_read_read_write : read_write Bin_prot.Read_ml.reader
val bin_read_read_write_ : read_write Bin_prot.Unsafe_read_c.reader
val bin_read_read_write__ : (int -> read_write) Bin_prot.Unsafe_read_c.reader
val bin_reader_read_write : read_write Bin_prot.Type_class.reader
val bin_size_read_write : read_write Bin_prot.Size.sizer
val bin_write_read_write : read_write Bin_prot.Write_ml.writer
val bin_write_read_write_ : read_write Bin_prot.Unsafe_write_c.writer
val bin_writer_read_write : read_write Bin_prot.Type_class.writer
val read_write_of_sexp : Sexplib.Sexp.t -> read_write
val sexp_of_read_write : read_write -> Sexplib.Sexp.t
val sexp_of_never_returns : never_returns -> Sexplib.Sexp.t
never_returns should be used as the return type of functions that don't return and might block forever, rather than 'a or _. This forces callers of such functions to have a call to never_returns at the call site, which makes it clear to readers what's going on. We do not intend to use this type for functions such as failwithf that always raise an exception.

Error handling


See exn.mli

Input Output


triple handling


Option handling


Functions from fn.ml


same as Filename.concat

Or_error.ok_exn

Or_error.error

with_return f allows for something like the return statement in C within f. There are three ways f can terminate:

1. If f calls r.return x, then x is returned by with_return. 2. If f evaluates to a value x, then x is returned by with_return. 3. If f raises an exception, it escapes with_return.

Here is a typical example: 

   let find l ~f =
     with_return (fun r ->
        List.iter l ~f:(fun x -> if f x then r.return (Some x));
        None
      )

It is only because of a deficiency of ML types that with_return doesn't have type: 

 val with_return : 'a. (('a -> ('b. 'b)) -> 'a) -> 'a

but we can slightly increase the scope of 'b, without changing the meaning of the type and then we get 

   type 'a return = { return : 'b . 'a -> b }
   val with_return : ('a return -> 'a) -> 'a

But the actual reason we chose to use a record type with polymorphic field is that otherwise we would have to clobber the namespace of functions with return and that is undesirable because return would get hidden as soon as we open any monad. We considered names different than return but everything seemed worse than just having return as a record field. We are clobbering the namespace of record fields but that is much more acceptable.

We disable == and != and replace them with the longer and more mnemonic phys_equal because they too easily lead to mistakes (for example they don't even work right on Int64 or Float). One can usually use the equal function for a specific type, or use (=) or (<>) for built in types like char, int, float,

See module : Staged for documentation

Raised if malloc in C bindings fail (errno * size).

Deprecated operations

The following section contains definitions that hide operations from the standard library that are considered problematic or confusing, or simply redundant.

we have our own version of these two, the INRIA version doesn't release the runtime lock.