Module Catala_runtime

The OCaml runtime.

Types

type nonrec unit = unit
type nonrec bool = bool
type money = Z.t

Number of cents

type integer = Z.t
type decimal = Q.t
type date = Dates_calc.date
type duration = Dates_calc.period
type date_rounding = Dates_calc.date_rounding =
  1. | RoundUp
  2. | RoundDown
  3. | AbortOnRound
type code_location = {
  1. filename : string;
  2. start_line : int;
  3. start_column : int;
  4. end_line : int;
  5. end_column : int;
  6. law_headings : string list;
}
module Optional : sig ... end
type io_input =
  1. | NoInput
    (*

    For an internal variable defined only in the scope, and does not appear in the input.

    *)
  2. | OnlyInput
    (*

    For variables that should not be redefined in the scope, because they appear in the input.

    *)
  3. | Reentrant
    (*

    For variables defined in the scope that can also be redefined by the caller as they appear in the input.

    *)

This type characterizes the three levels of visibility for a given scope variable with regards to the scope's input and possible redefinitions inside the scope.

type io_log = {
  1. io_input : io_input;
  2. io_output : bool;
    (*

    true if the variable is an output

    *)
}

Exceptions

type error =
  1. | AssertionFailed
    (*

    An assertion in the program doesn't hold

    *)
  2. | NoValue
    (*

    No computation with valid conditions found

    *)
  3. | Conflict
    (*

    Two different valid computations at that point

    *)
  4. | DivisionByZero
    (*

    The denominator happened to be 0 here

    *)
  5. | ListEmpty
    (*

    Element access on an empty list

    *)
  6. | NotSameLength
    (*

    Traversing multiple lists of different lengths

    *)
  7. | InvalidDate
    (*

    Invalid year/month/day combination

    *)
  8. | UncomparableDurations
    (*

    Comparing durations in different units (e.g. months vs. days)

    *)
  9. | AmbiguousDateRounding
    (*

    ambiguous date computation, and rounding mode was not specified

    *)
  10. | IndivisibleDurations
    (*

    Dividing durations that are not in days

    *)
  11. | Impossible
    (*

    The "impossible" keyword was reached

    *)
val error_to_string : error -> string

Returns the capitalized tag of the error as a string

val error_message : error -> string

Returns a short explanation message about the error

exception Error of error * code_location list
exception Empty

Value Embedding

type runtime_value =
  1. | Unit
  2. | Bool of bool
  3. | Money of money
  4. | Integer of integer
  5. | Decimal of decimal
  6. | Date of date
  7. | Duration of duration
  8. | Enum of string * string * runtime_value
  9. | Struct of string * (string * runtime_value) list
  10. | Array of runtime_value Stdlib.Array.t
  11. | Tuple of runtime_value Stdlib.Array.t
  12. | Unembeddable
val unembeddable : 'a -> runtime_value
val embed_unit : unit -> runtime_value
val embed_bool : bool -> runtime_value
val embed_money : money -> runtime_value
val embed_integer : integer -> runtime_value
val embed_decimal : decimal -> runtime_value
val embed_date : date -> runtime_value
val embed_duration : duration -> runtime_value
val embed_array : ('a -> runtime_value) -> 'a Stdlib.Array.t -> runtime_value

Logging

Global process

The logging is constituted of two phases:

Data structures

type information = string list

Represents information about a name in the code -- i.e. variable name, subscope name, etc...

It's a list of strings with a length varying from 2 to 3, where:

  • the first string is the name of the current scope -- starting with a capitalized letter Scope_name,
  • the second string is either: the name of a scope variable or, the name of a subscope input variable -- a_subscope_var.input_var
  • the third string is either: a subscope name (starting with a capitalized letter Subscope_name or, the input (resp. output) string -- which corresponds to the input (resp. the output) of a function.

The raw events

type raw_event =
  1. | BeginCall of information
    (*

    Subscope or function call.

    *)
  2. | EndCall of information
    (*

    End of a subscope or a function call.

    *)
  3. | VariableDefinition of information * io_log * runtime_value
    (*

    Definition of a variable or a function argument.

    *)
  4. | DecisionTaken of code_location
    (*

    Source code position of an event.

    *)

The structured events

The corresponding grammar of the event type, is the following:

<event> := <fun_call>
         | <subscope_call>
         | <var_def>
         | <var_def_with_fun>
         | VariableDefinition

<fun_call> :=
    VariableDefinition                      (function input)
    <fun_call_beg>
        <event>*
        (<var_def> | <var_def_with_fun>)    (function output)
    EndCall

<var_def_with_fun> :=
       /-- DecisionTaken
pos of |   <fun_call>+                      (function calls needed to compute the variable value)
       \-> VariableDefinition

<subscope_call> :=
    <sub_var_def>*          (sub-scope attributes def)
    <sub_call_beg>
        <event>+
    EndCall

<var_def> := DecisionTaken VariableDefinition(info, _)
  (when info.length = 2 && info[1] == "id")

<sub_var_def> := DecisionTaken VariableDefinition(info, _)
  (when info.length = 3)

<fun_call_beg> := BeginCall(info)
  (when info.length = 2)

<sub_call_beg> := BeginCall(info)
  (when info.length = 2 and '.' in info[1])
type event =
  1. | VarComputation of var_def
  2. | FunCall of fun_call
  3. | SubScopeCall of {
    1. name : information;
    2. inputs : var_def list;
    3. body : event list;
    }
and var_def = {
  1. pos : code_location option;
  2. name : information;
  3. io : io_log;
  4. value : runtime_value;
  5. fun_calls : fun_call list option;
}
and fun_call = {
  1. fun_name : information;
  2. fun_inputs : var_def list;
  3. body : event list;
  4. output : var_def;
}

Parsing

val retrieve_log : unit -> raw_event list

retrieve_log () returns the current list of collected raw_event.

module EventParser : sig ... end

Helping functions

Logging instruments

val reset_log : unit -> unit
val log_begin_call : string list -> 'a -> 'a
val log_end_call : string list -> 'a -> 'a
val log_variable_definition : string list -> io_log -> ('a -> runtime_value) -> 'a -> 'a
val log_decision_taken : code_location -> bool -> bool

Pretty printers

module Json : sig ... end
val pp_events : ?is_first_call:bool -> Stdlib.Format.formatter -> event list -> unit

pp_events ~is_first_call ppf events pretty prints in ppf the string representation of events.

If is_first_call is set to true, the formatter will be flush at the end. By default, is_first_call is set to false.

Constructors and conversions

Rounding

val round : Q.t -> Z.t

This helper function rounds a rational to the nearest integer. Tie-breaker is the "half away from zero" rule: 0.5 is rounded to 1.0 and -0.5 is rounded to -1.0. This function shall be used anytime rounding is necessary.

Money

val money_of_cents_string : string -> money
val money_of_units_int : int -> money
val money_of_decimal : decimal -> money

Warning: rounds to nearest cent, using round.

val money_of_cents_integer : integer -> money
val money_to_float : money -> float
val money_to_string : money -> string
val money_to_cents : money -> integer
val money_round : money -> money

Rounds to the nearest currency unit using round.

Decimals

val decimal_of_string : string -> decimal
val decimal_to_string : max_prec_digits:int -> decimal -> string
val decimal_of_integer : integer -> decimal
val decimal_of_float : float -> decimal
val decimal_to_float : decimal -> float
val decimal_round : decimal -> decimal

Rounds to the nearest integer using round.

val decimal_of_money : money -> decimal

Integers

val integer_of_string : string -> integer
val integer_to_string : integer -> string
val integer_to_int : integer -> int
val integer_of_int : int -> integer
val integer_of_decimal : decimal -> integer
val integer_log2 : integer -> int
val integer_exponentiation : integer -> int -> integer

Dates

val day_of_month_of_date : date -> integer
val month_number_of_date : date -> integer
val is_leap_year : integer -> bool
val year_of_date : date -> integer
val date_to_string : date -> string
val date_of_numbers : int -> int -> int -> date

Usage: date_of_numbers year month day.

Raises Failure on invalid inputs

val first_day_of_month : date -> date
val last_day_of_month : date -> date
val date_to_years_months_days : date -> int * int * int

Durations

val duration_of_numbers : int -> int -> int -> duration

Usage : duration_of_numbers year mounth day.

val duration_to_years_months_days : duration -> int * int * int

Times

val duration_to_string : duration -> string

Defaults

val handle_exceptions : ('a * code_location) Optional.t array -> ('a * code_location) Optional.t

Operators

module Oper : sig ... end
include module type of Oper
val o_not : bool -> bool
val o_length : 'a array -> integer
val o_toint_rat : decimal -> integer
val o_toint_mon : money -> integer
val o_torat_int : integer -> decimal
val o_torat_mon : money -> decimal
val o_tomoney_rat : decimal -> money
val o_tomoney_int : integer -> money
val o_getDay : date -> integer
val o_getMonth : date -> integer
val o_getYear : date -> integer
val o_firstDayOfMonth : date -> date
val o_lastDayOfMonth : date -> date
val o_round_mon : money -> money
val o_round_rat : decimal -> decimal
val o_minus_int : integer -> integer
val o_minus_rat : decimal -> decimal
val o_minus_mon : money -> money
val o_minus_dur : duration -> duration
val o_and : bool -> bool -> bool
val o_or : bool -> bool -> bool
val o_xor : bool -> bool -> bool
val o_eq : 'a -> 'a -> bool
val o_map : ('a -> 'b) -> 'a array -> 'b array
val o_map2 : code_location -> ('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c array
  • raises Runtime.NotSameLength
val o_reduce : ('a -> 'a -> 'a) -> (unit -> 'a) -> 'a array -> 'a
val o_concat : 'a array -> 'a array -> 'a array
val o_filter : ('a -> bool) -> 'a array -> 'a array
val o_add_int_int : integer -> integer -> integer
val o_add_rat_rat : decimal -> decimal -> decimal
val o_add_mon_mon : money -> money -> money
val o_add_dat_dur : date_rounding -> code_location -> date -> duration -> date
val o_add_dur_dur : duration -> duration -> duration
val o_sub_int_int : integer -> integer -> integer
val o_sub_rat_rat : decimal -> decimal -> decimal
val o_sub_mon_mon : money -> money -> money
val o_sub_dat_dat : date -> date -> duration
val o_sub_dat_dur : date_rounding -> code_location -> date -> duration -> date
val o_sub_dur_dur : duration -> duration -> duration
val o_mult_int_int : integer -> integer -> integer
val o_mult_rat_rat : decimal -> decimal -> decimal
val o_mult_mon_int : money -> integer -> money
val o_mult_mon_rat : money -> decimal -> money
val o_mult_dur_int : duration -> integer -> duration
val o_div_int_int : code_location -> integer -> integer -> decimal
val o_div_rat_rat : code_location -> decimal -> decimal -> decimal
val o_div_mon_mon : code_location -> money -> money -> decimal
val o_div_mon_int : code_location -> money -> integer -> money
val o_div_mon_rat : code_location -> money -> decimal -> money
val o_div_dur_dur : code_location -> duration -> duration -> decimal
val o_lt_int_int : integer -> integer -> bool
val o_lt_rat_rat : decimal -> decimal -> bool
val o_lt_mon_mon : money -> money -> bool
val o_lt_dur_dur : code_location -> duration -> duration -> bool
val o_lt_dat_dat : date -> date -> bool
val o_lte_int_int : integer -> integer -> bool
val o_lte_rat_rat : decimal -> decimal -> bool
val o_lte_mon_mon : money -> money -> bool
val o_lte_dur_dur : code_location -> duration -> duration -> bool
val o_lte_dat_dat : date -> date -> bool
val o_gt_int_int : integer -> integer -> bool
val o_gt_rat_rat : decimal -> decimal -> bool
val o_gt_mon_mon : money -> money -> bool
val o_gt_dur_dur : code_location -> duration -> duration -> bool
val o_gt_dat_dat : date -> date -> bool
val o_gte_int_int : integer -> integer -> bool
val o_gte_rat_rat : decimal -> decimal -> bool
val o_gte_mon_mon : money -> money -> bool
val o_gte_dur_dur : code_location -> duration -> duration -> bool
val o_gte_dat_dat : date -> date -> bool
val o_eq_boo_boo : bool -> bool -> bool
val o_eq_int_int : integer -> integer -> bool
val o_eq_rat_rat : decimal -> decimal -> bool
val o_eq_mon_mon : money -> money -> bool
val o_eq_dur_dur : code_location -> duration -> duration -> bool
val o_eq_dat_dat : date -> date -> bool
val o_fold : ('a -> 'b -> 'a) -> 'a -> 'b array -> 'a
val o_toclosureenv : 'a -> Stdlib.Obj.t
val o_fromclosureenv : Stdlib.Obj.t -> 'a

Modules API

type hash = string
val register_module : string -> (string * Stdlib.Obj.t) list -> hash -> unit

Registers a module by the given name defining the given bindings. Required for evaluation to be able to access the given values. The last argument is expected to be a hash of the source file and the Catala version, and will in time be used to ensure that the module and the interface are in sync

val check_module : string -> hash -> (unit, hash) Stdlib.result

Returns Ok if it has been registered with the correct hash, Error h if there is a hash mismatch.

Raises Not_found if the module does not exist at all

val lookup_value : (string list * string) -> Stdlib.Obj.t