How catalalang/catala works
Project Type and Purpose
• Catala is a domain-specific language (DSL) compiler designed for translating legislatively annotated texts into executable, “faithful‐by‐construction” algorithms. In addition to the core compiler, it includes a build system (“clerk”), testing framework, plugin backends, and runtime components for several target languages.
• The README clearly highlights that Catala’s purpose is to allow legal texts to be directly “compiled” into certified code (producing lawyer‐readable outputs) by following a literate programming approach. The project is research-oriented and involves formal semantics and verification.
File Structure
• Top-level folders include:
• build_system: Contains the “Clerk” build tool used for testing and orchestration.
• compiler: The core of the Catala compiler, with several subdirectories (such as dcalc, desugared, lcalc, scalc, scopelang, shared_ast, surface, etc.) each representing different stages or representations in the compilation pipeline.
• runtimes: Contains runtime implementations for various target languages (C, OCaml, Python, JavaScript through jsoo, rescript) that the compiler can produce.
• tests: A comprehensive test suite organized by language constructs – helpful for understanding both unit and regression testing.
• syntax_highlighting and doc: Provide auxiliary tools and developer documentation.
• There are also configuration files (e.g., Dockerfile, Makefile, opam files) and build scripts that point to a development-oriented, multi-target, modular design.
A. Compiler Subsystem:
• Frontend:
• The Surface layer (compiler/surface) where the source “legislative text” (annotated with code intentions) is read.
• Lexers, parsers, and token processing (files such as lexer.cppo.ml, parser.mly).
• Transformation Pipeline:
• Desugaring (compiler/desugared): Converting surface code to an intermediate “desugared” form.
• Intermediate representations (modules like dcalc, lcalc, scalc, scopelang) which represent the evolving internal state of the program.
• Shared AST and utility modules (compiler/shared_ast, catala_utils): Common functionality across phases.
• Backend & Plugin Architecture:
• Code generation to target languages (see files in “to_ocaml.ml,” “to_c.ml,” “to_python.ml” in corresponding directories).
• Plugin support (compiler/plugins): Enables dynamic linking and extension of available backends without modifying the core.
• Driver and Orchestration:
• The main compiler driver (compiler/driver.ml) which coordinates these stages.
B. Build System (Clerk Subsystem):
• The build_system directory contains components (clerk.ml, clerk_report.ml, clerk_config) to validate the code, run tests, and generate reports.
• Its design supports executing a series of tasks such as scanning, testing, and running rules to ensure compiler correctness.
C. Runtimes and Integration Points:
• Runtimes provide the execution environments for compiled outputs targeted at languages such as C, OCaml, Python, Rescript, and JavaScript. These are separate modules that plug into the overall system.
• They integrate with the generated code coming out of the compiler (transformation outputs from the backend modules).
D. Testing and Documentation:
• Extensive tests (organized under tests) cover various language features (arithmetic, arrays, exceptions, modules, etc.).
• Documentation and formal proofs (doc/) outline the formal semantics and expected behaviors.
• Auxiliary directories like syntax_highlighting support tooling for editors and developer experience.