package catala

  1. Overview
  2. Docs
Compiler and library for the literate programming language for tax code specification

Install 

dune-project
 Dependency

github.com Readme Changelog Edit opam file Versions (14)

Authors

  1. V
    Vincent Botbol
  2. N
    Nicolas Chataing
  3. A
    Alain Delaët-Tixeuil
  4. L
    Louis Gesbert
  5. A
    Aymeric Fromherz
  6. D
    Denis Merigoux
  7. R
    Raphaël Monat
  8. R
    Romain Primet
  9. E
    Emile Rolley

Maintainers

  1. C
    contact@catala-lang.org

Sources

1.3.0.tar.gz
md5=59d0dd01df52c38a4d793b594f067d14
sha512=944b755f8b47cb14920994f03f022cc3ba6cdf5def1ae8ffda00a196fa97dcc5b57baf642a03068b79e949df2a98d5f0218e3358e549be1ff0f1cddda1e5f848

doc/catala.runtime_ocaml/Catala_runtime/index.html

Module Catala_runtimeSource

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 duration = Dates_calc.period
Sourcetype date_rounding = Dates_calc.date_rounding =
  1. | RoundUp
  2. | RoundDown
  3. | AbortOnRound
Sourcetype 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;
}
Sourcetype 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.

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

    true if the variable is an output

    *)
}

Exceptions

Sourcetype 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. | UncomparableValues
    (*

    Equality check or comparison on functions

    *)
  8. | DateError of string
    (*

    Errors related to date and duration computations

    *)
  9. | 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 * string option
Sourceexception Empty

Value Embedding

Runtime type encoding

Sourcemodule Value : sig ... end
Sourceval equal : 'a Value.ty -> code_location -> 'a -> 'a -> bool

Polymorphic, structural equality using runtime type information

Sourceval compare : 'a Value.ty -> code_location -> 'a -> 'a -> int

Polymorphic, structural comparison using runtime type information

Catala types utils

Sourcemodule type CatalaType = sig ... end
Sourcemodule Optional : sig ... end
Sourcemodule type ExternalTypeSpec = sig ... end

This interface must be supplied to extend the Catala runtime with abstract types

Execution traces

The trace construction mechanism is a stateful process (i.e., non-reentrant) that collect traces emitted by the generated trace constructors defined below.

The built trace is organized as a tree where each node represent a trace element (e.g., a variable definition, a branching, etc.) which may have sub-traces. For instance, a function that defines local variable definitions will be represented as a FunCall node with a sub_trace containing these LocalVarDef sub-nodes.

Conceptually, whenever we reach a trace event, we open a scope, evaluate the sub-expression potentially yielding new traces that will be its sub-nodes, close the scope and finalize this trace node with the computed sub-expression value.

Whenever a runtime error is triggered, we insert an Error node as a sub-trace of the currently opened scope and re-raise this error. This is automatically performed by the with_trace wrapper.

The global trace state can be retrieved using the retrieve_trace accessor and cleared using reset_trace.

Traces types

Sourcetype trace_kind =
  1. | ScopeCall of trace_ident_decl
    (*

    Scope call with the scope declaration information

    *)
  2. | ScopeVarDef of {
    1. var : trace_ident_decl;
    2. io : io_log;
    }
    (*

    Scope variable definition with its declaration information and its i/o kind

    *)
  3. | LocalVarDef of string
    (*

    Let-binding of a local variable with its name

    *)
  4. | LocalTupDef of string list
    (*

    Let-binding of a local tuple with the name of each binded variable

    *)
  5. | FunCall of trace_ident_decl
    (*

    Function call with its declaration information

    *)
  6. | BranchingCondition
    (*

    Branching condition for an if-then-else or a pattern matching

    *)
  7. | IfBranching
    (*

    Branch taken of the consequence or alternative of an if-then-else

    *)
  8. | MatchBranching of {
    1. constructor_name : string;
    }
    (*

    Pattern taken of a pattern-matching

    *)
  9. | Assertion
    (*

    Beginning of an assertion

    *)
  10. | Exception of {
    1. label : (string * code_location) option;
      (*

      Exception label and its position in case of named exception

      *)
    2. cons_pos : code_location;
      (*

      Position of the consequence that would be evaluated if this exception gets fulfilled

      *)
    }
    (*

    Scope variable definition exception

    *)
  11. | Error of {
    1. error : error;
      (*

      Runtime error itself

      *)
    2. locs : code_location list;
      (*

      Extra-relevant locations

      *)
    3. message : string option;
      (*

      User-faced error message

      *)
    }
    (*

    Runtime error description

    *)

This type describes all the different trace kind generated throughout execution

Sourceand trace_ident_decl = {
  1. name : string;
  2. decl_pos : code_location;
}

Variable-kind declaration info, i.e., name and declaration position

Sourcetype trace = trace_element list
Sourceand trace_element = {
  1. kind : trace_kind;
    (*

    The kind of trace

    *)
  2. pos : code_location;
    (*

    The expression pos responsible for this trace

    *)
  3. value : Value.t option;
    (*

    The resulting evaluated value. No value present on error.

    *)
  4. sub_trace : trace;
    (*

    Sub elements of the trace. E.g., a ScopeCall trace will contain ScopeVarDef traces in its sub-trace.

    *)
}

Trace node

Trace constructors

Sourceval begin_trace : trace_kind -> code_location -> unit

Begins a trace scope given a trace_kind and its code_location.

Sourceval end_trace : ?value:Value.t -> unit -> unit

Ends the currently opened trace scope and register the value.

Sourceval single_trace : trace_kind -> code_location -> unit

Equivalent to a sequence of begin_trace then end_trace. Used for error reporting.

Sourceval with_trace : embed:('a -> Value.t) -> trace_kind -> code_location -> (unit -> 'a) -> 'a

Wrapper that takes a function f and insert a begin_trace before f () and a end_trace afterwards. It also retrieves and embeds the computed value.

It also catches runtime's errors and insert a single_trace before re-raising it. When it occurs, a flag is also set so that callers do not catch it again.

Trace accessors

Sourceval retrieve_trace : unit -> trace

Finalize the global trace state and returns the immutable trace value.

Sourceval reset_trace : unit -> unit

Resets the global trace state.

Pretty printers

Sourcemodule Print : sig ... end

This module is for setting options and internals, use Value.format to print values

JSON printers

Sourcemodule Json : sig ... end

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

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

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_toint_mon : money -> integer
Sourceval o_torat_int : integer -> decimal
Sourceval o_torat_mon : money -> decimal
Sourceval o_tomoney_rat : decimal -> money
Sourceval o_tomoney_int : integer -> 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 Value.ty -> code_location -> 'a -> 'a -> bool
Sourceval o_lt : 'a Value.ty -> code_location -> 'a -> 'a -> bool
Sourceval o_lte : 'a Value.ty -> code_location -> 'a -> 'a -> bool
Sourceval o_gt : 'a Value.ty -> code_location -> 'a -> 'a -> bool
Sourceval o_gte : 'a Value.ty -> code_location -> 'a -> 'a -> bool
Sourceval o_map : ('a -> 'b) -> 'a array -> 'b array
Sourceval o_map2 : code_location -> ('a -> 'b -> 'c) -> 'a array -> 'b array -> 'c array
  • raises Runtime.NotSameLength
Sourceval o_reduce : ('a -> 'a -> 'a) -> 'a array -> 'a Optional.t
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_fold : ('a -> 'b -> 'a) -> 'a -> 'b array -> 'a
Sourceval o_find : ('a -> bool) -> 'a array -> 'a Optional.t
Sourceval o_sort_asc : 'b Value.ty -> code_location -> ('a -> 'b) -> 'a array -> 'a array
Sourceval o_sort_desc : 'b Value.ty -> code_location -> ('a -> 'b) -> 'a array -> 'a array
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 -> ?types:(string * (module CatalaType)) 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 * string) -> Obj.t
Sourceval lookup_type : (string * string) -> (module CatalaType)