@catala-lang/catala-explain

Catala Explain from trace

Report Bug • Example

A module for explicability from the trace of a catala program.

Installation

To add this module to your ReScript project, install the following dependencies:

yarn add -D @catala-lang/catala-explain rescript-docx

Then add them to the bs-dependencies of your bsconfig.json:

 {
   ...
   "bs-dependencies": [
+    "@catala-lang/catala-explain"
+    "rescript-docx"
   ]
}

ℹ️ You need to install rescript-docx to manage the generated .docx file.

Usage

This module is meant to be used as a library. It provides a function CatalaExplain.generate that takes the user's input and the trace of a catala program and generates a .docx file containing the explanation of the result of the program.

let doc = CatalaExplain.generate(
    // The trace of the catala program
    ~events=CatalaFrenchLaw.retrieveEventsSerialized()->CatalaRuntime.deserializedEvents,
    // A JSON object containing the user's input used to generate the document
    ~userInputs=formData,
    // The schema of the user inputs form, used for having explicit input form labels.
    ~schema= WebAssets.schema,
    // The options for the document
    ~opts={
        title: "Titre de la décision",
        description: "Description du document",
        creator: "Créateur du document",
        // Key from user inputs to ignore (e.g 'identifiant' in array items), instead
        // of using the 'title' field of the schema.
        keysToIgnore: WebAssets.keysToIgnore,
        // The output to show as the result of the computation
        selectedOutput: WebAssets.selectedOutput,
        // The URL of the exposed Catala program source code (used to redirect
        // the user from the generated document to variable definitions)
        sourceURL: "https:/example.com/sources",
    },
)

// Example of how to save the generated document
// 
// Where `FileSaver` is a minimal wrapper around the `file-saver` package
doc
->Docx.Packer.toBlob
->Promise.thenResolve(blob => {
    FileSaver.saveAs(blob, `explication-decision.docx`)
})
->ignore

ℹ️ You can find a complete example of usage in the catala-dsfr repository.

Sponsors

This library has been developed during a research project funded by the mission logiciels libres et communs numériques of the direction interministérielle du numérique in collaboration with the Catala project.