Module `Catala_runtime`Source

The 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 code_location = {

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

}

Sourcemodule Optional : 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
*)
| ListEmpty
(*
Element access on an empty list
*)
| NotSameLength
(*
Traversing multiple lists of different lengths
*)
| UncomparableDurations
(*
Comparing durations in different units (e.g. months vs. days)
*)
| AmbiguousDateRounding
(*
ambiguous date computation, and rounding mode was not specified
*)
| IndivisibleDurations
(*
Dividing durations that are not in days
*)
| Impossible
(*
The "impossible" keyword was reached
*)

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 * code_location 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
| Tuple 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 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])

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 : code_location 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 : code_location -> 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_of_decimal : decimal -> 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_exceptions : 
  ('a * code_location) Optional.t array ->
  ('a * code_location) Optional.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_toint_rat : decimal -> 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 : 
  code_location ->
  ('a -> 'b -> 'c) ->
  'a array ->
  'b array ->
  'c array

raises Runtime.NotSameLength

Sourceval o_reduce : ('a -> 'a -> 'a) -> (unit -> '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 -> code_location -> 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_rounding -> code_location -> 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_int : money -> integer -> money

Sourceval o_mult_mon_rat : money -> decimal -> money

Sourceval o_mult_dur_int : duration -> integer -> duration

Sourceval o_div_int_int : code_location -> integer -> integer -> decimal

Sourceval o_div_rat_rat : code_location -> decimal -> decimal -> decimal

Sourceval o_div_mon_mon : code_location -> money -> money -> decimal

Sourceval o_div_mon_int : code_location -> money -> integer -> money

Sourceval o_div_mon_rat : code_location -> money -> decimal -> money

Sourceval o_div_dur_dur : code_location -> 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 : code_location -> 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 : code_location -> 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 : code_location -> 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 : code_location -> duration -> duration -> bool

Sourceval o_gte_dat_dat : date -> date -> bool

Sourceval o_eq_boo_boo : bool -> bool -> 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 : code_location -> duration -> duration -> bool

Sourceval o_eq_dat_dat : date -> date -> bool

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

Sourceval o_toclosureenv : 'a -> Obj.t

Sourceval o_fromclosureenv : Obj.t -> '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 -> (unit, hash) 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

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

Install

dune-project
Dependency

Authors

Maintainers

Sources

doc/catala.runtime_ocaml/Catala_runtime/index.html

Module `Catala_runtime`Source

Types

Exceptions

Value Embedding

Logging

Global process

Data structures

The raw events

The structured events

Parsing

Helping functions

Logging instruments

Pretty printers

Constructors and conversions

Rounding

Money

Decimals

Integers

Dates

Durations

Times

Defaults

Operators

package catala

Install

dune-project Dependency

Authors

Maintainers

Sources

doc/catala.runtime_ocaml/Catala_runtime/index.html

Module Catala_runtimeSource

Types

Exceptions

Value Embedding

Logging

Global process

Data structures

The raw events

The structured events

Parsing

Helping functions

Logging instruments

Pretty printers

Constructors and conversions

Rounding

Money

Decimals

Integers

Dates

Durations

Times

Defaults

Operators

dune-project
Dependency

Module `Catala_runtime`Source