Runtime (p.catala.0.10.0.doc.catala.runtime_ocaml.Runtime

Types

Sourcetype nonrec unit = unit

Sourcetype nonrec bool = bool

Sourcetype money = Z.t

Number of cents

Sourcetype integer = Z.t

Sourcetype decimal = Q.t

Sourcetype date = Dates_calc.Dates.date

Sourcetype duration = Dates_calc.Dates.period

Sourcetype date_rounding = Dates_calc.Dates.date_rounding =

| RoundUp
| RoundDown
| AbortOnRound

Sourcetype source_position = {

filename : string;
start_line : int;
start_column : int;
end_line : int;
end_column : int;
law_headings : string list;

}

Sourcemodule Eoption : sig ... end

Sourcetype io_input =

| NoInput
(*
For an internal variable defined only in the scope, and does not appear in the input.
*)
| OnlyInput
(*
For variables that should not be redefined in the scope, because they appear in the input.
*)
| 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.

Sourcetype io_log = {

io_input : io_input;
io_output : bool;
(*
true if the variable is an output
*)

}

Exceptions

Sourcetype error =

| AssertionFailed
(*
An assertion in the program doesn't hold
*)
| NoValue
(*
No computation with valid conditions found
*)
| Conflict
(*
Two different valid computations at that point
*)
| DivisionByZero
(*
The denominator happened to be 0 here
*)
| NotSameLength
(*
Traversing multiple lists of different lengths
*)
| UncomparableDurations
(*
Comparing durations in different units (e.g. months vs. days)
*)
| IndivisibleDurations
(*
Dividing durations that are not in days
*)

Sourceval error_to_string : error -> string

Returns the capitalized tag of the error as a string

Sourceval error_message : error -> string

Returns a short explanation message about the error

Sourceexception Error of error * source_position list

Sourceexception Empty

Value Embedding

Sourcetype runtime_value =

| Unit
| Bool of bool
| Money of money
| Integer of integer
| Decimal of decimal
| Date of date
| Duration of duration
| Enum of string * string * runtime_value
| Struct of string * (string * runtime_value) list
| Array of runtime_value Array.t
| Unembeddable

Sourceval unembeddable : 'a -> runtime_value

Sourceval embed_unit : unit -> runtime_value

Sourceval embed_bool : bool -> runtime_value

Sourceval embed_money : money -> runtime_value

Sourceval embed_integer : integer -> runtime_value

Sourceval embed_decimal : decimal -> runtime_value

Sourceval embed_date : date -> runtime_value

Sourceval embed_duration : duration -> runtime_value

Sourceval embed_array : ('a -> runtime_value) -> 'a Array.t -> runtime_value

Logging

Global process

The logging is constituted of two phases:

The first one consists of collecting raw events (see raw_event) during the program execution (see retrieve_log) throught Logging instruments.
The second one consists in parsing the collected raw events into structured ones (see event).

Data structures

Sourcetype 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

Sourcetype raw_event =

| BeginCall of information
(*
Subscope or function call.
*)
| EndCall of information
(*
End of a subscope or a function call.
*)
| VariableDefinition of information * io_log * runtime_value
(*
Definition of a variable or a function argument.
*)
| DecisionTaken of source_position
(*
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])

Sourcetype event =

| VarComputation of var_def
| FunCall of fun_call
| SubScopeCall of {
1. name : information;
2. inputs : var_def list;
3. body : event list;
}

Sourceand var_def = {

pos : source_position option;
name : information;
io : io_log;
value : runtime_value;
fun_calls : fun_call list option;

}

Sourceand fun_call = {

fun_name : information;
fun_inputs : var_def list;
body : event list;
output : var_def;

}

Parsing

Sourceval retrieve_log : unit -> raw_event list

retrieve_log () returns the current list of collected raw_event.

Sourcemodule EventParser : sig ... end

Helping functions

Logging instruments

Sourceval reset_log : unit -> unit

Sourceval log_begin_call : string list -> 'a -> 'a

Sourceval log_end_call : string list -> 'a -> 'a

Source

val log_variable_definition : 
  string list ->
  io_log ->
  ('a -> runtime_value) ->
  'a ->
  'a

Sourceval log_decision_taken : source_position -> bool -> bool

Pretty printers

Sourcemodule Json : sig ... end

Sourceval pp_events : ?is_first_call:bool -> 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

Sourceval 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

Sourceval money_of_cents_string : string -> money

Sourceval money_of_units_int : int -> money

Sourceval money_of_decimal : decimal -> money

Warning: rounds to nearest cent, using round.

Sourceval money_of_cents_integer : integer -> money

Sourceval money_to_float : money -> float

Sourceval money_to_string : money -> string

Sourceval money_to_cents : money -> integer

Sourceval money_round : money -> money

Rounds to the nearest currency unit using round.

Decimals

Sourceval decimal_of_string : string -> decimal

Sourceval decimal_to_string : max_prec_digits:int -> decimal -> string

Sourceval decimal_of_integer : integer -> decimal

Sourceval decimal_of_float : float -> decimal

Sourceval decimal_to_float : decimal -> float

Sourceval decimal_round : decimal -> decimal

Rounds to the nearest integer using round.

Sourceval decimal_of_money : money -> decimal

Integers

Sourceval integer_of_string : string -> integer

Sourceval integer_to_string : integer -> string

Sourceval integer_to_int : integer -> int

Sourceval integer_of_int : int -> integer

Sourceval integer_log2 : integer -> int

Sourceval integer_exponentiation : integer -> int -> integer

Dates

Sourceval day_of_month_of_date : date -> integer

Sourceval month_number_of_date : date -> integer

Sourceval is_leap_year : integer -> bool

Sourceval year_of_date : date -> integer

Sourceval date_to_string : date -> string

Sourceval date_of_numbers : int -> int -> int -> date

Usage: date_of_numbers year month day.

raises Failure
on invalid inputs

Sourceval first_day_of_month : date -> date

Sourceval last_day_of_month : date -> date

Sourceval date_to_years_months_days : date -> int * int * int

Durations

Sourceval duration_of_numbers : int -> int -> int -> duration

Usage : duration_of_numbers year mounth day.

Sourceval duration_to_years_months_days : duration -> int * int * int

Times

Sourceval duration_to_string : duration -> string

Defaults

Source

val handle_default : 
  source_position array ->
  (unit -> 'a) array ->
  (unit -> bool) ->
  (unit -> 'a) ->
  'a

raises Empty

raises Error
Conflict

Source

val handle_default_opt : 
  source_position array ->
  'a Eoption.t array ->
  (unit -> bool) ->
  (unit -> 'a Eoption.t) ->
  'a Eoption.t

raises Error
Conflict

Operators

Sourcemodule Oper : sig ... end

include module type of Oper

Sourceval o_not : bool -> bool

Sourceval o_length : 'a array -> integer

Sourceval o_torat_int : integer -> decimal

Sourceval o_torat_mon : money -> decimal

Sourceval o_tomoney_rat : decimal -> money

Sourceval o_getDay : date -> integer

Sourceval o_getMonth : date -> integer

Sourceval o_getYear : date -> integer

Sourceval o_firstDayOfMonth : date -> date

Sourceval o_lastDayOfMonth : date -> date

Sourceval o_round_mon : money -> money

Sourceval o_round_rat : decimal -> decimal

Sourceval o_minus_int : integer -> integer

Sourceval o_minus_rat : decimal -> decimal

Sourceval o_minus_mon : money -> money

Sourceval o_minus_dur : duration -> duration

Sourceval o_and : bool -> bool -> bool

Sourceval o_or : bool -> bool -> bool

Sourceval o_xor : bool -> bool -> bool

Sourceval o_eq : 'a -> 'a -> bool

Sourceval o_map : ('a -> 'b) -> 'a array -> 'b array

Source

val o_map2 : 
  source_position ->
  ('a -> 'b -> 'c) ->
  'a array ->
  'b array ->
  'c array

raises [NotSameLength]

Sourceval o_reduce : ('a -> 'a -> 'a) -> 'a -> 'a array -> 'a

Sourceval o_concat : 'a array -> 'a array -> 'a array

Sourceval o_filter : ('a -> bool) -> 'a array -> 'a array

Sourceval o_add_int_int : integer -> integer -> integer

Sourceval o_add_rat_rat : decimal -> decimal -> decimal

Sourceval o_add_mon_mon : money -> money -> money

Sourceval o_add_dat_dur : date_rounding -> date -> duration -> date

Sourceval o_add_dur_dur : duration -> duration -> duration

Sourceval o_sub_int_int : integer -> integer -> integer

Sourceval o_sub_rat_rat : decimal -> decimal -> decimal

Sourceval o_sub_mon_mon : money -> money -> money

Sourceval o_sub_dat_dat : date -> date -> duration

Sourceval o_sub_dat_dur : date -> duration -> date

Sourceval o_sub_dur_dur : duration -> duration -> duration

Sourceval o_mult_int_int : integer -> integer -> integer

Sourceval o_mult_rat_rat : decimal -> decimal -> decimal

Sourceval o_mult_mon_rat : money -> decimal -> money

Sourceval o_mult_dur_int : duration -> integer -> duration

Sourceval o_div_int_int : source_position -> integer -> integer -> decimal

Sourceval o_div_rat_rat : source_position -> decimal -> decimal -> decimal

Sourceval o_div_mon_mon : source_position -> money -> money -> decimal

Sourceval o_div_mon_rat : source_position -> money -> decimal -> money

Sourceval o_div_dur_dur : source_position -> duration -> duration -> decimal

Sourceval o_lt_int_int : integer -> integer -> bool

Sourceval o_lt_rat_rat : decimal -> decimal -> bool

Sourceval o_lt_mon_mon : money -> money -> bool

Sourceval o_lt_dur_dur : source_position -> duration -> duration -> bool

Sourceval o_lt_dat_dat : date -> date -> bool

Sourceval o_lte_int_int : integer -> integer -> bool

Sourceval o_lte_rat_rat : decimal -> decimal -> bool

Sourceval o_lte_mon_mon : money -> money -> bool

Sourceval o_lte_dur_dur : source_position -> duration -> duration -> bool

Sourceval o_lte_dat_dat : date -> date -> bool

Sourceval o_gt_int_int : integer -> integer -> bool

Sourceval o_gt_rat_rat : decimal -> decimal -> bool

Sourceval o_gt_mon_mon : money -> money -> bool

Sourceval o_gt_dur_dur : source_position -> duration -> duration -> bool

Sourceval o_gt_dat_dat : date -> date -> bool

Sourceval o_gte_int_int : integer -> integer -> bool

Sourceval o_gte_rat_rat : decimal -> decimal -> bool

Sourceval o_gte_mon_mon : money -> money -> bool

Sourceval o_gte_dur_dur : source_position -> duration -> duration -> bool

Sourceval o_gte_dat_dat : date -> date -> bool

Sourceval o_eq_int_int : integer -> integer -> bool

Sourceval o_eq_rat_rat : decimal -> decimal -> bool

Sourceval o_eq_mon_mon : money -> money -> bool

Sourceval o_eq_dur_dur : source_position -> duration -> duration -> bool

Sourceval o_eq_dat_dat : date -> date -> bool

Sourceval o_fold : ('a -> 'b -> 'a) -> 'a -> 'b array -> 'a

Modules API

Sourcetype hash = string

Sourceval register_module : string -> (string * 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

Sourceval check_module : string -> hash -> bool

Returns true if it has been registered with the correct hash, false if there is a hash mismatch.

raises Not_found
if the module does not exist at all

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