package catala

  1. Overview
  2. Docs
package catala
Legend:
Library
Module
Module type
Parameter
Class
Class type

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 duration = Dates_calc.Dates.period
type date_rounding = Dates_calc.Dates.date_rounding
type source_position = {
  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 Eoption : 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.

val yojson_of_io_input : io_input -> Ppx_yojson_conv_lib.Yojson.Safe.t
type io_log = {
  1. io_input : io_input;
  2. io_output : bool;
    (*

    true if the variable is an output

    *)
}
val yojson_of_io_log : io_log -> Ppx_yojson_conv_lib.Yojson.Safe.t

Exceptions

exception EmptyError
exception AssertionFailed of source_position
exception ConflictError of source_position
exception UncomparableDurations
exception IndivisibleDurations
exception ImpossibleDate
exception NoValueProvided of source_position

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 list * string * runtime_value
  9. | Struct of string list * (string * runtime_value) list
  10. | Array of runtime_value Stdlib.Array.t
  11. | Unembeddable
val yojson_of_runtime_value : runtime_value -> Ppx_yojson_conv_lib.Yojson.Safe.t
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:

  • 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

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.
val yojson_of_information : information -> Ppx_yojson_conv_lib.Yojson.Safe.t

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 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])
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 : source_position 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;
}
val yojson_of_event : event -> Ppx_yojson_conv_lib.Yojson.Safe.t
val yojson_of_var_def : var_def -> Ppx_yojson_conv_lib.Yojson.Safe.t
val yojson_of_fun_call : fun_call -> Ppx_yojson_conv_lib.Yojson.Safe.t

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 : source_position -> bool -> bool

Pretty printers

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_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

val first_day_of_month : date -> date
val last_day_of_month : date -> date

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_default : source_position -> (unit -> 'a) array -> (unit -> bool) -> (unit -> 'a) -> 'a
val handle_default_opt : source_position -> 'a Eoption.t array -> (unit -> bool) -> (unit -> 'a Eoption.t) -> 'a Eoption.t
val no_input : unit -> 'a

Operators

module Oper : sig ... end
include module type of Oper
val o_not : bool -> bool
val o_length : 'a array -> integer
val o_torat_int : integer -> decimal
val o_torat_mon : money -> decimal
val o_tomoney_rat : decimal -> 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_reduce : ('a -> 'a -> 'a) -> '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 -> 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 -> 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_rat : money -> decimal -> money
val o_mult_dur_int : duration -> integer -> duration
val o_div_int_int : integer -> integer -> decimal
val o_div_rat_rat : decimal -> decimal -> decimal
val o_div_mon_mon : money -> money -> decimal
val o_div_mon_rat : money -> decimal -> money
val o_div_dur_dur : 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 : 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 : 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 : 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 : duration -> duration -> bool
val o_gte_dat_dat : date -> date -> 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 : duration -> duration -> bool
val o_eq_dat_dat : date -> date -> bool
val o_fold : ('a -> 'b -> 'a) -> 'a -> 'b array -> '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 -> 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

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

Innovation. Community. Security.

GitHub Discord Twitter Peertube RSS
About
Changelog Releases Industrial Users Academic Users Why OCaml
Ecosystem
Packages Community Events OCaml Planet Jobs
Resources
Install OCaml Get Started Platform Tools Language Manual Standard Library API Books Exercises Papers OCaml Playground Logo
Policies
Carbon Footprint Governance Privacy Code of Conduct