Introduction

Bienvenue sur le livre d’introduction au langage de programmation dédié Catala !

À qui s’adresse Catala

Équipes pluridisciplinaires

Catala est conçu pour être utilisé par des équipes mêlant expertises juridique et informatique. En effet, automatiser l’application d’une loi ou d’un règlement nécessite de combler le fossé de l’ambiguïté entre le texte juridique et un programme informatique qui doit savoir quoi faire dans toutes les situations possibles. Combler cette ambiguïté est l’une des missions des juristes, formés à l’interprétation des textes juridiques et à la recherche juridique pour aboutir à une décision justifiée dans le cadre de l’État de droit.

Si les juristes doivent décider de ce que fait le programme, ils ne sont pas formés aux concepts et abstractions de la programmation, ni à l’écriture de milliers de lignes de code de manière propre et maintenable. Ainsi, le rôle de l’informaticien est de s’assurer que le programme automatisant l’application d’une loi ou d’un règlement est propre, concis, et doté d’abstractions correctement définies qui évitent la duplication de code et facilitent la maintenance et les changements futurs. De plus, l’informaticien est également responsable du déploiement du programme dans un système informatique plus vaste qui pourrait briser ses hypothèses ou mettre à l’épreuve ses performances.

En réutilisant les techniques et outils existants du génie logiciel, tout en présentant des concepts accessibles aux juristes en surface, Catala permet aux juristes et aux informaticiens de collaborer de manière véritablement agile, dépassant la séparation entre les équipes de développement et d’assurance qualité qui ne communiquent que via des cas de test et des documents de spécification.

Agences gouvernementales et organismes de service public

Automatiser l’application d’une loi ou d’un règlement par un programme informatique n’est pas une mince affaire. Pour s’assurer que tous sont traités équitablement en vertu de l’État de droit, votre programme doit prendre en compte de manière exhaustive chaque situation décrite par la loi ou le règlement. Bien qu’automatiser uniquement la situation la plus simple correspondant à une majorité d’utilisateurs puisse être acceptable dans certaines situations, cela ne peut constituer la base d’un service public prêt pour la production. En effet, créer une différence entre un “parcours simple” automatisé et un traitement non automatisé des situations complexes creuse la fracture numérique et accroît la confusion tant pour les usagers que pour les agents.

Catala brille lorsque l’objectif est d’automatiser de manière exhaustive et fiable une loi ou un règlement donné, et de maintenir cette automatisation dans le temps. Le langage et l’outillage vous aideront à gérer la complexité croissante, la maintenance face aux changements juridiques, les cas limites et le déploiement en production au sein d’un système informatique existant. Si vous recherchez un outil pour créer un chatbot d’aide aux utilisateurs de premier niveau qui ne répond qu’aux questions de base, ou un modèle simplifié d’une loi pour une étude économique, vous devriez envisager d’utiliser d’autres outils. En revanche, si vous faites partie d’une organisation responsable de l’exécution d’un service public comme les impôts ou les prestations sociales, vous devriez avoir les moyens de concevoir correctement le programme informatique responsable de l’automatisation, et utiliser Catala pour vous y aider.

Parce que Catala se compile vers des langages de programmation grand public comme Python ou C, il produit des bibliothèques de code source portables qui sont intégrables dans pratiquement n’importe quel système informatique, ancien ou moderne. Plus particulièrement, les programmes Catala peuvent être déployés derrière une API Web ou embarqués dans une application de bureau, permettant d’écrire une fois pour utiliser partout (“write once, use anywhere”). Ainsi, Catala est particulièrement adapté aux agences gouvernementales historiques qui exploitent leurs systèmes informatiques depuis des décennies et continueront de le faire pour les décennies à venir.

Étudiants et universitaires en informatique et/ou en droit

La formalisation du droit, terme plus général pour désigner la traduction du droit en code informatique exécutable, fait l’objet d’une attention académique depuis très longtemps. Le domaine “IA & Droit” a historiquement été la communauté faîtière pour cette ligne de travail, avec trois tendances séquentielles : la programmation logique, les ontologies, et maintenant l’apprentissage automatique et en particulier le traitement du langage naturel. Bien que ces tendances aient mis au jour des résultats importants pour la formalisation du droit, de grandes questions de recherche demeurent. Comment modéliser des dispositions juridiques complexes couvrant de vastes corpus ? La formalisation du droit peut-elle être automatisée ? La rédaction juridique peut-elle être augmentée technologiquement ? Comment détecter les incohérences ou les failles par analyse statique ou dynamique ?

Avec de fortes racines dans la communauté de recherche, son engagement envers l’open source, sa sémantique formalisée et son compilateur extensible, Catala en tant que langage de programmation est une opportunité pour l’apprentissage des étudiants et les projets de recherche. Alors que les enseignants et les étudiants peuvent utiliser Catala pour explorer de manière pratique le droit fiscal et social, les chercheurs peuvent utiliser les programmes Catala comme jeux de données ou programmer une nouvelle analyse qui peut être facilement déployée auprès des utilisateurs de Catala.

Si vous êtes étudiant, professeur, ou qui que ce soit d’autre d’ailleurs, vous êtes invité à utiliser Catala gratuitement et à y contribuer en signalant des problèmes, en proposant des “pull requests”, ou en développant des plugins et des outils autour du langage.

À qui s’adresse ce livre

Ce livre s’adresse principalement aux programmeurs qui souhaitent apprendre Catala, mettre en place un projet l’utilisant pour traduire un texte juridique en code exécutable, et être guidés tout au long du processus. Le livre suppose une connaissance de base des idiomes de la programmation fonctionnelle et, plus généralement, une expérience en génie logiciel avec un autre langage de programmation grand public.

Si vous, programmeur, travaillez dans une équipe pluridisciplinaire avec un ou plusieurs juristes, c’est à vous de leur expliquer ce qu’est Catala et comment travailler avec. Ce guide couvrira donc également divers sujets autour de la collaboration entre juristes et programmeurs.

Si vous êtes juriste et tombez sur ce livre, vous êtes également invité à le lire, bien que certaines parties ne soient pas pertinentes pour vous. Vous pourriez consulter à la place des articles introductifs qui posent le contexte autour du code informatique, de la traduction du droit en code informatique et présentent les spécificités de Catala :

Comment utiliser ce livre

Le livre est organisé en deux parties : le guide utilisateur et le guide de référence. Alors que le guide utilisateur est destiné à être lu de manière linéaire et vise les nouveaux utilisateurs, le guide de référence est le point de chute pour vérifier des éléments concernant le langage et l’outillage Catala au fur et à mesure de votre utilisation, que vous soyez un utilisateur débutant ou expérimenté.

Le guide utilisateur commence par le Chapitre 1 et l’équivalent Catala du programme “Hello, world!”. Le Chapitre 2 explique les concepts fondamentaux de Catala avec un tutoriel pratique centré sur l’automatisation d’un système fiscal fictif de base. Passant aux choses sérieuses, le Chapitre 3 plonge dans la mise en place d’un projet Catala réel avec contrôle de version, suivi des évolutions juridiques, tests, intégration continue, déploiement automatisé, etc. Enfin, le Chapitre 4 accélère votre apprentissage en répondant à (presque) toutes les questions sur lesquelles vous tomberez normalement en codant la loi avec Catala.

Dans le guide de référence, le Chapitre 5 détaille toutes les fonctionnalités disponibles dans le langage Catala, tandis que le Chapitre 6 se concentre sur les interfaces en ligne de commande et les fonctionnalités de l’outil avec lequel vous travaillerez : clerk.

Prise en main

Bienvenue dans le chapitre de prise en main ! Ce chapitre a pour but de vous préparer au début de votre voyage dans l’univers de Catala. Tout d’abord, vous devrez installer Catala sur votre machine, car Catala n’est pas un logiciel en tant que service (SaaS) mais bien une chaîne d’outils de langage de programmation à part entière. Ensuite, vous devrez vérifier que tout fonctionne correctement en créant et exécutant votre premier programme Catala, équivalent du célèbre “Hello, world!”.

Vous découvrirez :

• le système de construction de Catala, clerk ;
• l’outillage de l’IDE Catala (plugin de langage et outil de mise en forme).

Installer Catala sur votre machine

Catala est un langage de programmation principalement conçu pour être installé sur votre machine et exécuté localement dans votre environnement de développement préféré. Concrètement, Catala est composé de plusieurs exécutables qui forment ensemble l’outillage du langage de programmation :

• le compilateur Catala catala, accompagné du système de construction clerk ;
• le serveur de protocole de langage (LSP) Catala catala-lsp ;
• l’outil de formatage automatique Catala catala-format ;
• le plugin Catala pour votre éditeur de texte ou IDE.

En coulisses, la plupart de ces exécutables sont produits à l’aide de la chaîne d’outils logicielle OCaml, le processus d’installation commence donc avec opam, le gestionnaire de paquets et système de construction pour OCaml.

Les instructions d’installation supposent toutes une maîtrise de la ligne de commande et des connaissances de base sur le système de fichiers et le processus général de construction d’exécutables à partir des sources à l’aide d’un gestionnaire de paquets.

Les instructions d’installation diffèrent selon que vous êtes sur un système compatible Unix (Linux, MacOS, sous-système Windows pour Linux), ou sur Windows classique. Veuillez choisir le guide approprié à votre situation.

Linux/Mac/WSL

Sauf indication contraire, l’installation de l’outillage Catala s’effectue sur un terminal en ligne de commande classique.

Obtenir opam

Installez la dernière version d’opam (version >= 2.2), via les instructions d’installation officielles que nous répétons ici pour plus de commodité.

Avec aptitude (distributions linux de type debian) :

$ sudo apt update
$ sudo apt install opam

Sans aptitude :

$ bash -c "sh <(curl -fsSL https://opam.ocaml.org/install.sh)"

À ce stade, opam devrait être initialisé sur votre machine. Mais ce n’est pas fini, car opam doit créer un switch avec une version spécifique d’OCaml, où tous les paquets que nous installerons plus tard seront compilés et stockés. Pour initialiser opam et créer ce premier switch, entrez ce qui suit :

$ opam init -c 4.14.2
$ eval $(opam env)

$ opam switch create 4.14.2

Obtenir Catala

Exécutez les commandes suivantes pour installer la dernière version de Catala via opam :

$ opam update && opam install catala.1.0.0

Une fois terminé, le système de construction Catala devrait être installé. Vous devriez pouvoir appeler avec succès $ clerk --version dans votre terminal. Si ce n’est pas le cas, essayez d’invoquer $ eval $(opam env) avant.

Mettre à jour Catala

À tout moment, vous pouvez récupérer la dernière version de Catala en utilisant ces commandes simples :

$ opam update
$ opam upgrade catala

Cette méthode fonctionne également pour les autres paquets opam présentés ci-dessous : remplacez simplement upgrade catala par upgrade catala-lsp, etc.

$ opam pin catala.dev --dev-repo
$ opam pin catala-lsp.dev --dev-repo
$ opam pin catala-format.dev --dev-repo

$ opam unpin catala.dev
$ opam unpin catala-lsp.dev
$ opam unpin catala-format.dev

$ opam reinstall catala
$ opam reinstall catala-lsp
$ opam reinstall catala-format

Obtenir le serveur LSP (nécessaire pour l’extension VSCode)

L’extension VSCode nécessite que le protocole de serveur de langage (LSP) de Catala soit installé. Cela peut être fait en exécutant :

$ opam install catala-lsp.1.0.0

Obtenir l’extension VSCode

Installez VSCode et ouvrez-le. Parcourez le marché des extensions et installez l’extension Catala.

Obtenir l’outil de mise en forme de code Catala

Exécutez la commande suivante :

$ opam install catala-format.1.0.0

Une fois installé, vous pouvez rafraîchir votre environnement VSCode (F1, puis Developer: Reload Window) ce qui notifiera l’extension Catala que l’outil de mise en forme est maintenant disponible. Vous pouvez invoquer l’outil de mise en forme en utilisant F1, puis Format Document ou par un raccourci clavier défini par l’utilisateur.

Windows

Installateur binaire

Vous pouvez télécharger et installer Catala en utilisant cet installateur binaire - vous pourriez avoir besoin des privilèges d’administrateur :

• Installateur binaire Windows Catala x86_64

Une fois ce fichier d’installation Catala installé, vous devrez peut-être redémarrer VS Code s’il était déjà lancé. Pour vous assurer que tout a été correctement installé, vous pouvez ouvrir un terminal VS Code et taper $ catala --version. Si cela n’affiche pas d’erreur, tout devrait être correctement configuré.

Pour installer l’extension VS Code Catala, veuillez vous référer à cette section.

Installation depuis les sources

Obtenir Opam

Ouvrez un PowerShell et installez opam en invoquant

$ Invoke-Expression "& { $(Invoke-RestMethod https://opam.ocaml.org/install.ps1) }"

Ensuite, initialisez opam :

$ opam init -c 4.14.2

Obtenir Catala

Actuellement, le paquet opam Catala n’est pas directement compilable sur Windows. Cependant, le serveur lsp de Catala intègre un sous-ensemble de Catala qui est suffisant. Cela peut être installé avec la commande suivante

$ opam install catala.1.0.0 catala-lsp.1.0.0

Configurer le serveur LSP Catala

Après l’étape précédente, le serveur LSP Catala devrait être construit dans le répertoire des binaires d’opam. Pour que VS Code puisse l’obtenir, ce répertoire doit être ajouté à la variable d’environnement PATH de Windows.

Pour modifier la variable d’environnement PATH, suivez ces instructions.

Obtenir l’extension VS Code

Installez VS Code et ouvrez-le. Parcourez le marché des extensions et installez l’extension Catala.

Obtenir l’outil de mise en forme de code Catala

Actuellement, l’outil de mise en forme de code n’est pas encore disponible sur Windows.

Créer votre premier programme Catala

Maintenant que vous avez installé l’outillage Catala, vous pouvez tester sa bonne exécution avec l’équivalent d’un programme Hello, world!.

Les programmes Catala sont de simples fichiers texte qui peuvent être manipulés par n’importe quel éditeur de texte ou IDE. Ainsi, pour démarrer votre développement Catala, l’équipe Catala vous recommande d’ouvrir votre éditeur de texte favori.

Dans votre éditeur de texte/IDE, créez un nouveau dossier pour vos développements Catala (par exemple nommé catala) et à l’intérieur, un fichier texte vide (par exemple nommé bonjour_monde.catala_fr).

Écrire des spécifications dans un fichier Catala

Copiez-collez le texte suivant dans votre fichier :

# Tutoriel Catala

## Bonjour tout le monde !

Votre premier programme Catala devrait afficher l'entier `42` comme
Réponse à la Grande Question sur la Vie, l'Univers et le Reste.

À ce stade, votre fichier ressemble à un fichier Markdown classique et ne contient aucun code source Catala per se. En effet, comme Catala utilise la programmation littéraire, tout texte à l’intérieur de votre fichier est considéré par défaut comme une spécification Markdown. Voyons maintenant comment écrire réellement du code !

Écrire votre premier bloc de code Catala

Sous le paragraphe ## Bonjour, monde !, ouvrez un bloc de code Markdown indiquant le langage catala :

```catala
# <Insérez votre code Catala ici !>
```

Ces blocs de code Catala peuvent être placés n’importe où au milieu du Markdown classique de votre fichier source. En fait, si vous suivez la méthodologie Catala pour traduire la loi en code, votre fichier source ressemblera principalement à un gros document Markdown parsemé de nombreux petits blocs de code Catala.

Maintenant, à l’intérieur du bloc de code Catala, copiez-collez ce qui suit :

déclaration champ d'application BonjourMonde:
  résultat réponse_univers contenu entier

champ d'application BonjourMonde:
  définition réponse_univers égal à 42

Il n’est pas important de comprendre ce que fait ce code pour l’instant. Vous l’apprendrez plus tard dans le tutoriel.

Vérification des types et exécution du programme Catala

Puisque Catala est un langage fortement typé, vous pouvez vérifier les types de votre programme sans l’exécuter pour voir s’il y a des erreurs de syntaxe ou de typage. Cela se fait via la commande clerk typecheck :

$ clerk typecheck bonjour_monde.catala_fr

Le résultat de cette commande devrait être :

┌─[RESULT]─
│ Typechecking successful!
└─

Si le programme passe la vérification des types, nous pouvons l’exécuter via l’interpréteur contenu dans le compilateur catala. Cela se fait avec la commande suivante, en indiquant que nous voulons exécuter le champ d’application (--scope) nommé BonjourMonde à l’intérieur du fichier bonjour_monde.catala_fr :

$ clerk run bonjour_monde.catala_fr --scope=BonjourMonde

Le résultat de cette commande devrait être, comme il est de coutume :

┌─[RESULT]─
│ réponse_univers = 42
└─

Vous devriez maintenant être prêt à poursuivre votre voyage Catala à travers le tutoriel !

Tutoriel : calculer vos impôts

Bienvenue dans ce tutoriel, dont l’objectif est de vous guider à travers les fonctionnalités du langage Catala et de vous apprendre à annoter un texte législatif simple en utilisant le langage, pour obtenir un programme exécutable qui calcule vos impôts !

Ce tutoriel ne couvre pas l’installation de Catala. Pour plus d’informations à ce sujet, veuillez vous référer à la section d’installation. Si vous souhaitez suivre ce tutoriel localement, lisez la section sur la création de votre premier programme et copiez-collez simplement les extraits de code du tutoriel dans votre fichier de programme Catala.

Le tutoriel comporte trois sections, conçues pour être complétées dans l’ordre car elles couvrent des fonctionnalités de plus en plus difficiles et avancées du langage :

• la première section concerne les éléments de base des programmes du langage avec un flux de données simple ;
• la deuxième section porte sur ce qui rend Catala unique : sa gestion de premier ordre des définitions conditionnelles et des exceptions ;
• la troisième section traite de la montée en charge de la base de code avec des listes d’éléments et de multiples champs d’application ;
• la quatrième section termine avec les états de variables et l’appel dynamique de champs d’application.

Vous devriez être prêt à commencer maintenant. Bonne chance !

Éléments de base d’un programme Catala

Dans cette section, le tutoriel présente les éléments de base d’un programme Catala : la différence entre la loi et le code, les structures de données, les champs d’application, les variables et les formules. À la fin de la section, vous devriez être capable d’écrire un programme Catala simple équivalent à une seule fonction avec des variables locales dont les définitions peuvent se référer les unes aux autres.

“Tisser” la loi et le code

Catala est un langage conçu autour du concept de programmation littéraire, c’est-à-dire le mélange (ou tissage – de l’anglais weaving) entre le code informatique et sa spécification dans un seul document. Pourquoi la programmation littéraire ? Parce qu’elle permet une correspondance fine entre la spécification et le code. Chaque fois que la spécification est mise à jour, savoir où mettre à jour le code est trivial avec la programmation littéraire. C’est absolument crucial pour permettre la maintenance à long terme de programmes complexes et de haute assurance comme le calcul des impôts ou des prestations sociales.

Ainsi, un fichier de code source Catala ressemble à un document Markdown classique, avec la spécification écrite et formatée comme du texte Markdown, et le code Catala présent uniquement dans des blocs de code Catala bien délimités introduits par une ligne avec ```catala et terminés par une ligne avec ```.

Avant d’écrire du code Catala, nous devons introduire la spécification du code pour ce tutoriel. Cette spécification sera basée sur un Code des Impôts fictif définissant un impôt sur le revenu simple. Mais en général, n’importe quoi peut être utilisé comme spécification pour un programme Catala : lois, décrets, motivations de décisions de justice, doctrine juridique, instructions internes, spécifications techniques, etc. Ces sources peuvent être mélangées pour former un programme Catala complet qui s’appuie sur ces multiples sources. Concrètement, incorporer une source juridique de spécification dans le programme Catala revient à copier-coller le texte et à le formater en syntaxe Markdown à l’intérieur du fichier de code source.

Voici le premier paragraphe de spécification pour notre impôt sur le revenu fictif, l’article 1 du CITC (Code des Impôts du Tutoriel Catala) :

## Article 1

L'impôt sur le revenu pour un individu est défini comme un pourcentage fixe du
revenu de l'individu sur une année.

L’esprit de l’écriture de code en Catala est de coller à la spécification à tout moment afin de placer les extraits de code là où ils doivent être. Par conséquent, nous introduirons ci-dessous les extraits de code Catala qui traduisent l’article 1, qui doivent être placés juste en dessous de l’article 1 dans le fichier de code source Catala.

Ces extraits de code doivent décrire le programme qui calcule l’impôt sur le revenu, et contenir la règle le définissant comme une multiplication du revenu par un taux. Il est temps de plonger dans Catala en tant que langage de programmation.

# Nous apprendrons bientôt quoi écrire ici pour traduire le sens de l'article 1
# en code Catala.

# Pour créer un bloc de code Catala dans votre fichier, délimitez-le avec les
# balises de style Markdown "```catala" et "```". Vous pouvez écrire des
# commentaires dans les blocs de code Catala en préfixant les lignes par "#"

Mettre en place les structures de données

Le contenu de l’article 1 suppose beaucoup de contexte implicite : il existe un individu avec un revenu, ainsi qu’un impôt sur le revenu que l’individu doit payer chaque année. Même si ce contexte implicite n’est pas verbatim dans la loi, nous devons l’expliciter dans le code informatique, sous la forme de structures de données et de signatures de fonctions.

Catala est un langage fortement typé et compilé statiquement, donc toutes les structures de données et signatures de fonctions doivent être explicitement déclarées. Nous commençons donc par déclarer les informations de type pour l’individu, le contribuable qui sera le sujet du calcul de l’impôt. Cet individu a un revenu et un nombre d’enfants, deux informations qui seront nécessaires à des fins fiscales :

# Les déclarations de structures de données et généralement toute déclaration
# en Catala ne correspondent souvent à aucun article de loi spécifique. Ainsi,
# vous pouvez mettre toutes les déclarations en haut de votre fichier
# tutoriel.catala_fr, avant l'article 1.

# Le nom de la structure, "Individu", doit commencer par une majuscule :
# c'est la convention CamelCase.
déclaration structure Individu:
  # Dans cette ligne, "revenu" est le nom du champ de la structure et
  # "argent" est le type de ce qui est stocké dans ce champ.
  # Les types disponibles incluent : "entier", "décimal", "argent", "date",
  # "durée", et toute autre structure ou énumération que vous déclarez.
  donnée revenu contenu argent
  # Les noms de champs "revenu" et "nombre_enfants" commencent par une
  # minuscule, ils suivent la convention snake_case.
  donnée nombre_enfants contenu entier

Cette structure contient deux champs de données, revenu et nombre_enfants. Les structures sont utiles pour regrouper des données qui vont ensemble. Généralement, vous obtenez une structure par objet concret sur lequel la loi s’applique (comme l’individu). C’est à vous de décider comment regrouper les données, mais nous vous conseillons de viser l’optimisation de la lisibilité du code.

# Le nom "CréditImpôt" est également écrit en CamelCase.
déclaration énumération CréditImpôt:
  # La ligne ci-dessous dit que "CréditImpôt" peut être une situation
  # "PasDeCréditImpôt".
  -- PasDeCréditImpôt
  # La ligne ci-dessous dit qu'alternativement, "CréditImpôt" peut être une
  # situation "CréditImpôtEnfants". Cette situation porte un contenu de type
  # entier correspondant au nombre d'enfants concernés par le crédit d'impôt.
  # Cela signifie que si vous êtes dans la situation "CréditImpôtEnfants",
  # vous aurez également accès à ce nombre d'enfants.
  -- CréditImpôtEnfants contenu entier

Notez que ces structures de données que nous avons déclarées ne peuvent pas toujours être rattachées naturellement à un morceau particulier du texte de spécification. Alors, où mettre ces déclarations dans votre fichier de programmation littéraire ? Puisque vous reviendrez souvent à ces déclarations de structures de données pendant la programmation, nous vous conseillons de les regrouper dans une sorte de prélude dans votre fichier de code source. Concrètement, cette section de prélude contenant la déclaration des structures de données sera votre point de référence unique pour essayer de comprendre les données manipulées par les règles ailleurs dans le fichier de code source.

Les champs d’application comme blocs de calcul de base

Nous avons défini et typé les données que le programme manipulera. Maintenant, nous devons définir le contexte logique dans lequel ces données évolueront. Parce que Catala est un langage de programmation fonctionnelle, tout code existe au sein d’une fonction. Et l’équivalent d’une fonction en Catala est appelé un champ d’application (scope). Un champ d’application est composé de :

• un nom,
• des variables d’entrée (similaires aux arguments de fonction),
• des variables internes (similaires aux variables locales),
• des variables de résultat (qui forment ensemble le type de retour de la fonction).

Par exemple, l’article 1 déclare un champ d’application pour calculer l’impôt sur le revenu :

# Les noms de champs d'application utilisent la convention de nommage CamelCase,
# comme les noms de structures ou d'énums. Les variables de champ d'application,
# en revanche, utilisent la convention de nommage snake_case, comme les champs
# de structure.
déclaration champ d'application CalculImpôtRevenu:
  # La ligne suivante déclare une variable d'entrée du champ d'application,
  # ce qui s'apparente à un paramètre de fonction en termes informatiques.
  # C'est la donnée sur laquelle le champ d'application va opérer.
  entrée individu contenu Individu
  interne taux_imposition contenu décimal
  résultat impôt_revenu contenu argent

Le champ d’application est l’unité d’abstraction de base dans les programmes Catala, et les champs d’application peuvent être composés. Puisqu’une fonction peut appeler d’autres fonctions, les champs d’application peuvent aussi appeler d’autres champs d’application. Nous verrons plus tard comment faire cela, mais concentrons-nous d’abord sur les entrées et les sorties des champs d’application.

La déclaration du champ d’application s’apparente à une signature de fonction : elle contient une liste de tous les arguments avec leurs types. Mais en Catala, les variables de champ d’application peuvent être entrée, interne ou résultat. entrée signifie que la variable doit être fournie chaque fois que le champ d’application est appelé, et ne peut pas être définie à l’intérieur du champ d’application. interne signifie que la variable est définie à l’intérieur du champ d’application et ne peut pas être vue de l’extérieur ; elle ne fait pas partie de la valeur de retour du champ d’application. résultat signifie qu’un appelant peut récupérer la valeur calculée de la variable. Notez qu’une variable peut être simultanément une entrée et un résultat du champ d’application, dans ce cas elle doit être annotée avec entrée résultat.

Une fois le champ d’application déclaré, nous pouvons l’utiliser pour définir nos règles de calcul et enfin coder l’article 1 !

Définir des variables et des formules

L’article 1 donne en fait la formule pour définir la variable impôt_revenu du champ d’application CalculImpôtRevenu, ce qui se traduit par le code Catala suivant :

champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    individu.revenu * taux_imposition

Décortiquons le code ci-dessus. Chaque définition d’une variable (ici, impôt_revenu) est rattachée à un champ d’application qui la déclare (ici, CalculImpôtRevenu). Après égal à, nous avons l’expression réelle pour la variable : individu.revenu * taux_imposition. La syntaxe des formules utilise les opérateurs arithmétiques classiques. Ici, * signifie multiplier un montant d’argent par un décimal, renvoyant un nouveau montant d’argent. Le comportement exact de chaque opérateur dépend des types de valeurs sur lesquels il est appliqué. Par exemple, ici, parce qu’une valeur de type argent est toujours un nombre entier de centimes, * arrondit le résultat de la multiplication au centime le plus proche pour fournir la valeur finale de type argent (voir la FAQ pour plus d’informations sur l’arrondi en Catala). Concernant individu.revenu, nous voyons que la notation . nous permet d’accéder au champ revenu de individu, qui est en fait une structure de type Individu.

selon crédit_impôt sous forme
-- PasDeCréditImpôt: 0 €
-- CréditImpôtEnfants contenu nombre_enfants_éligibles:
  10 000 € * nombre_enfants_éligibles

Maintenant, revenons à notre champ d’application CalculImpôtRevenu. À ce stade, il nous manque encore la définition de taux_imposition. C’est un schéma courant lors du codage de la loi : les définitions des différentes variables sont dispersées dans différents articles. Heureusement, le compilateur Catala collecte automatiquement toutes les définitions pour chaque champ d’application et les met dans le bon ordre. Ici, même si nous définissons taux_imposition après impôt_revenu dans notre code source, le compilateur Catala inversera l’ordre des définitions en interne car taux_imposition est utilisé dans la définition de impôt_revenu. Plus généralement, l’ordre des définitions et déclarations de haut niveau dans les fichiers de code source Catala n’a pas d’importance, et vous pouvez remanier le code librement sans avoir à vous soucier de l’ordre des dépendances.

Dans ce tutoriel, nous supposerons que notre spécification CITC fictive définit le pourcentage dans l’article suivant. Le code Catala ci-dessous ne devrait pas vous surprendre à ce stade.

champ d'application CalculImpôtRevenu:
  # Écrire 20% est juste une alternative pour le décimal "0,20".
  définition taux_imposition égal à 20 %

Types de base et calculs en Catala

Jusqu’à présent, nous avons vu des valeurs qui ont des types comme décimal, argent, entier. On pourrait objecter qu’il n’y a pas lieu de distinguer ces trois concepts, car ce ne sont que des nombres. Cependant, la philosophie de Catala est de rendre explicite chaque choix qui affecte le résultat du calcul, et la représentation des nombres affecte le résultat du calcul. En effet, les calculs financiers varient selon que l’on considère un montant d’argent comme un nombre exact de centimes, ou que l’on stocke des chiffres fractionnaires supplémentaires après le centime. Puisque le type de programmes pour lesquels Catala est conçu implique de lourdes conséquences pour de nombreux utilisateurs, le langage est assez strict sur la façon dont les nombres sont représentés. La règle générale est que, en Catala, les nombres se comportent exactement selon la sémantique mathématique commune que l’on peut associer aux calculs arithmétiques de base (+, -, *, /).

En particulier, cela signifie que les valeurs entier sont illimitées et ne peuvent jamais déborder. De même, les valeurs décimal peuvent être arbitrairement précises (bien qu’elles soient toujours rationnelles, appartenant à ℚ) et ne souffrent pas des imprécisions de la virgule flottante. Pour argent, le langage prend une décision arrêtée : une valeur de type argent est toujours un nombre entier de centimes.

Ces choix ont plusieurs conséquences :

• entier divisé par entier donne un décimal ;
• argent ne peut pas être multiplié par argent (multipliez plutôt argent par décimal) ;
• argent multiplié (ou divisé) par décimal arrondit le résultat au centime le plus proche ;
• argent divisé par argent donne un décimal (qui n’est absolument pas arrondi).

10  / 3   = 3,333333333... et
10 € / 3,0 = 3,33 € et
20 € / 3,0 = 6,67 € et
10 € / 3 €  = 3,33333333...

Le compilateur Catala vous guidera pour utiliser explicitement les opérations correctes, en signalant des erreurs de compilation lorsque ce n’est pas le cas.

┌─[ERROR]─
│
│  I don't know how to apply operator + on types integer and decimal
│
├─➤ tutoriel_fr.catala_fr
│    │
│    │   définition x égal à 1 + 2,0
│    │                       ‾‾‾‾‾‾‾
│
│ Type integer coming from expression:
├─➤ tutoriel_fr.catala_fr
│    │
│    │   définition x égal à 1 + 2,0
│    │                       ‾
│
│ Type decimal coming from expression:
├─➤ tutoriel_fr.catala_fr
│    │
│    │   définition x égal à 1 + 2,0
│    │                           ‾‾‾
└─

Catala possède également des types intégrés date et durée avec les opérations associées courantes (ajouter une durée à une date, soustraire deux dates pour obtenir une durée, etc.). Pour un aperçu plus approfondi des calculs de dates (qui sont très délicats !), consultez la référence du langage.

Tester le code

Maintenant que nous avons implémenté quelques articles en Catala, il est temps de tester notre code pour vérifier qu’il se comporte correctement. Nous vous encourageons à tester votre code souvent, le plus tôt possible, et à vérifier le résultat du test dans un système d’intégration continue pour éviter les régressions.

Le test du code Catala se fait avec l’interpréteur à l’intérieur du compilateur, accessible avec la commande interpret et l’option --scope qui spécifie le champ d’application à interpréter.

$ clerk run tutoriel.catala_fr --scope=CalculImpôtRevenu
┌─[ERROR]─
│
│  Invalid scope for execution or testing: it defines input variables. If
│  necessary, a wrapper scope with explicit inputs to this one can be defined.
│
├─➤ tutoriel.catala_fr:41.9-41.19:
│    │
│ 41 │   entrée individu contenu Individu
│    │          ‾‾‾‾‾‾‾‾
└─

Le modèle de test utilise des concepts qui seront vus plus tard dans le tutoriel, il est donc acceptable de considérer une partie de ce qui suit comme une syntaxe mystérieuse qui fait ce que nous voulons. Fondamentalement, nous allons créer pour notre cas de test un nouveau test qui passera des arguments spécifiques à CalculImpôtRevenu qui est testé :

déclaration champ d'application Test:
  # La ligne suivante est mystérieuse pour l'instant
  résultat calcul contenu CalculImpôtRevenu

champ d'application Test:
  définition calcul égal à
    # La ligne suivante est mystérieuse pour l'instant
    résultat de CalculImpôtRevenu avec {
      # Ci-dessous, nous passons les variables d'entrée pour "CalculImpôtRevenu"
      -- individu:
        # "individu" a un type structure, nous devons donc construire la
        # structure "Individu" avec la syntaxe suivante
        Individu {
          # "revenu" et "nombre_enfants" sont les champs de la structure ;
          # nous leur donnons les valeurs que nous voulons pour notre test
          -- revenu: 20 000 €
          -- nombre_enfants: 0
        }
    }

Ce test peut maintenant être exécuté via l’interpréteur Catala :

$ clerk run tutoriel.catala_fr --scope=Test
┌─[RESULT]─
│ calcul = CalculImpôtRevenu { -- impôt_revenu: 4 000,00 € }
└─

Nous pouvons maintenant vérifier que 4 000 € = 20 000 € * 20% ; le résultat est correct.

$ clerk typecheck tutoriel.catala_fr
┌─[RESULT]─
│ Typechecking successful!
└─

Récapitulons

Ceci conclut la première section du tutoriel. En mettant en place des structures de données comme structure et énumération, en représentant les types des variables de champ d'application, et la définition de formules pour ces variables, vous devriez maintenant être capable de coder en Catala l’équivalent de programmes à fonction unique qui effectuent des opérations arithmétiques courantes et définissent des variables locales.

# Corrigé du tutoriel

## Article 1

L'impôt sur le revenu pour un individu est défini comme un pourcentage fixe du
revenu de l'individu sur une année.

```catala
déclaration structure Individu:
  donnée revenu contenu argent
  donnée nombre_enfants contenu entier

déclaration champ d'application CalculImpôtRevenu:
  entrée individu contenu Individu
  interne taux_imposition contenu décimal
  résultat impôt_revenu contenu argent

champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    individu.revenu * taux_imposition
```

## Article 2

Le pourcentage fixe mentionné à l'article 1 est égal à 20 %.

```catala
champ d'application CalculImpôtRevenu:
  définition taux_imposition égal à 20%
```

## Test

```catala
déclaration champ d'application Test:
  résultat calcul contenu CalculImpôtRevenu

champ d'application Test:
  définition calcul égal à
    résultat de CalculImpôtRevenu avec {
      -- individu:
        Individu {
          -- revenu: 20 000 €
          -- nombre_enfants: 0
        }
    }
```

Exercice pratique : “Rien n’est certain sauf la mort et les impôts”

Dans cette section, nous présentons un exercice pratique visant à familiariser avec l’écriture de programmes Catala et la compréhension de ses concepts de base. Nous vous invitons fortement à configurer un environnement Catala fonctionnel, à ouvrir un éditeur (tel que vscode) et à copier-coller le modèle d’exercice suivant dans un fichier catala ; vous pouvez le nommer exercice-2-1-1.catala_fr.

# Livre Catala : Exercice 2-1-1

```catala
déclaration structure Individu:
  donnée date_naissance contenu date
  donnée date_décès contenu DateDécès

déclaration énumération DateDécès:
  -- Décédé contenu date
  -- ToujoursVivant
```

# Question 1

En vous basant sur la déclaration `test_personne1`, déclarez une `test_personne2`
née le 21 décembre 1977 qui est toujours vivante.

```catala
# Déclaration et définition d'une valeur constante nommée test_personne1
déclaration test_personne1 contenu Individu égal à
  Individu {
    -- date_naissance: |1981-10-05|
      # Le format de date est |AAAA-MM-JJ|
    -- date_décès: Décédé contenu |2012-05-12|
  }

déclaration test_personne2 contenu Individu égal à
  test_personne1 # <= Supprimez cette ligne et remplacez-la par votre réponse
```

```catala
déclaration champ d'application TuerPersonne:
  entrée date_fatidique contenu date
  entrée victime contenu Individu
  résultat individu_tué contenu Individu
```

# Question 2

Étant donné la déclaration du champ d'application `TuerPersonne`, définissez une
variable de résultat `individu_tué` du champ d'application `TuerPersonne` qui
utilise les variables d'entrée `date_fatidique` et `victime` pour créer un nouvel
Individu qui est une copie de l'entrée `victime` mais avec sa `date_décès` mise
à jour. Par souci de simplicité, nous ne vérifierons pas si nous tuons un
individu déjà décédé.

Vous pouvez tester votre solution en invoquant le champ d'application Catala
TestTuerPersonne : `clerk run exercice-2-1-1.catala_fr --scope TestTuerPersonne`.

```catala
déclaration champ d'application TestTuerPersonne:
  résultat calcul contenu TuerPersonne

champ d'application TestTuerPersonne:
  définition calcul égal à
    résultat de TuerPersonne avec {
      -- date_fatidique: |2025-01-20|
      -- victime: test_personne2
    }

# Définissez votre champ d'application TuerPersonne ici

# champ d'application TuerPersonne:
#   ...
```

```catala
déclaration structure Couple:
  donnée revenu_annuel_foyer contenu argent
  donnée personne_1 contenu Individu
  donnée personne_2 contenu Individu

# Définissez votre définition test_couple ici

# déclaration test_couple contenu Couple égal à
#   ...
```

```catala
déclaration champ d'application CalculImpôt:
  entrée date_traitement contenu date
  entrée couple contenu Couple

  interne personne1_décédée_avant_date_traitement contenu booléen
  interne personne2_décédée_avant_date_traitement contenu booléen

  résultat montant_impôt contenu argent

champ d'application CalculImpôt:
  définition montant_impôt égal à
    si personne1_décédée_avant_date_traitement
      ou personne2_décédée_avant_date_traitement alors
     0 €
   sinon
     couple.revenu_annuel_foyer * 15%
```

## Question 4

Définissez une autre définition de champ d'application `CalculImpôt` qui définit
les deux variables booléennes internes `personne1_décédée_avant_date_traitement`
et `personne2_décédée_avant_date_traitement`.

```catala
# Définissez votre nouveau champ d'application CalculImpôt ici

# champ d'application CalculImpôt:
#   ...
```

## Question 5

Enfin, nous devons définir un test pour notre calcul. En vous basant sur les
tests définis précédemment, écrivez une définition du champ d'application de test
`TestCalculImpôt`. Ensuite, ajustez les valeurs de test données pour vous assurer
que votre implémentation est correcte.

```catala
déclaration champ d'application TestCalculImpôt:
  résultat test_calcul_impôt contenu CalculImpôt

# Définissez votre champ d'application TestCalculImpôt ici

# champ d'application TestCalculImpôt:
#   ...
```

Dans cet exercice, nous voulons définir (encore un autre !) calcul d’impôt. Cette fois, le montant de l’impôt qu’un foyer doit payer dépend de si les individus sont toujours vivants ou non. Afin de modéliser un tel mécanisme, nous introduisons les structures Catala suivantes représentant les individus.

Un individu est référencé en utilisant seulement deux informations : sa date de naissance et sa possible date de décès. Si un individu est toujours vivant, il n’a pas de date de décès. Exprimer cette possibilité peut se faire en utilisant une énumération : si l’individu est toujours vivant, son entrée date_décès sera ToujoursVivant sinon ce sera Décédé qui doit être accompagné d’une valeur de date comme spécifié dans la déclaration suivante.

déclaration structure Individu:
  donnée date_naissance contenu date
  donnée date_décès contenu DateDécès

déclaration énumération DateDécès:
  -- Décédé contenu date
  -- ToujoursVivant

# Déclaration et définition d'une valeur constante nommée test_personne1
déclaration test_personne1 contenu Individu égal à
  Individu {
    -- date_naissance: |1981-10-05|
      # Le format de date est |AAAA-MM-JJ|
    -- date_décès: Décédé contenu |2012-05-12|
  }

Question 1

En vous basant sur la déclaration test_personne1, essayez de définir une test_personne2 née le 21 décembre 1977 qui est toujours vivante.

déclaration test_personne2 contenu Individu égal à
  Individu {
    -- date_naissance: |1977-12-21|
    -- date_décès: ToujoursVivant
  }

Nous voulons maintenant un moyen de mettre à jour le statut d’une personne de vivant à décédé. Nous le faisons via un champ d’application dédié TuerPersonne dont la déclaration est :

déclaration champ d'application TuerPersonne:
  entrée date_fatidique contenu date
  entrée victime contenu Individu
  résultat individu_tué contenu Individu

Question 2

Étant donné la déclaration du champ d’application TuerPersonne, définissez une variable de résultat individu_tué du champ d’application TuerPersonne qui utilise les variables d’entrée date_fatidique et victime pour créer un nouvel Individu qui est une copie de l’entrée victime mais avec sa date_décès mise à jour. Par souci de simplicité, nous ne vérifierons pas si nous tuons un individu déjà décédé.

Vous pouvez tester votre solution en utilisant le champ d’application TestTuerPersonne suivant en invoquant cette commande dans une console :

clerk run exercice-2-1-1.catala_fr --scope TestTuerPersonne

déclaration champ d'application TestTuerPersonne:
  résultat calcul contenu TuerPersonne

champ d'application TestTuerPersonne:
  définition calcul égal à
    résultat de TuerPersonne avec {
      -- date_fatidique: |2025-01-20|
      -- victime: test_personne2
    }

champ d'application TuerPersonne:
  définition individu_tué égal à
    Individu {
      -- date_naissance: victime.date_naissance
      -- date_décès: Décédé contenu date_fatidique
    }

champ d'application TuerPersonne:
  définition individu_tué égal à
    victime mais en remplaçant { -- date_décès: Décédé contenu date_fatidique }

Nous définissons maintenant une structure Couple qui représente un foyer simple. Cette structure a trois entrées différentes :

• Deux individus : personne_1 et personne_2 ;
• Et leur revenu_annuel_foyer combiné.

déclaration structure Couple:
  donnée personne_1 contenu Individu
  donnée personne_2 contenu Individu
  donnée revenu_annuel_foyer contenu argent

Question 3

Encore une fois, définissez une valeur de test nommée test_couple qui réutilise les individus précédemment définis (à savoir test_personne_1 et test_personne_2) et fixe leur revenu_annuel_foyer à 80 000 €.

déclaration test_couple contenu Couple égal à
  Couple {
    -- revenu_annuel_foyer: 80 000 €
    -- personne_1: test_personne1
    -- personne_2: test_personne2
  }

Considérons maintenant un article de loi sur le calcul de l’impôt avec une définition très simple :

Cela se traduit par le code Catala suivant :

déclaration champ d'application CalculImpôt:
  entrée date_traitement contenu date
  entrée couple contenu Couple

  interne personne1_décédée_avant_date_traitement contenu booléen
  interne personne2_décédée_avant_date_traitement contenu booléen

  résultat montant_impôt contenu argent

champ d'application CalculImpôt:
  définition montant_impôt égal à
    si
      personne1_décédée_avant_date_traitement
      ou personne2_décédée_avant_date_traitement
    alors 0 €
    sinon couple.revenu_annuel_foyer * 15%

Afin de banaliser la définition de montant_impôt, nous avons introduit deux variables de champ d’application interne qui représentent des valeurs booléennes (vrai ou faux). Cependant, même si nous avons fourni la définition de la variable de résultat montant_impôt, ces variables internes restent à définir sinon nous ne pourrons pas effectuer le calcul efficacement.

Question 4

En Catala, les définitions de champ d’application peuvent être dispersées dans tout le fichier. Ce faisant, cela permet d’implémenter localement la logique définie par un article de loi sans introduire de code passe-partout qui gênerait un processus de révision.

Définissez une autre définition de champ d’application CalculImpôt qui définit les deux variables booléennes internes personne1_décédée_avant_date_traitement et personne2_décédée_avant_date_traitement.

champ d'application CalculImpôt:
  définition âge_individu égal à
    selon individu.date_décès sous forme
    -- ToujoursVivant: date_courante - individu.date_naissance
    -- Décédé contenu date_décès: date_décès - individu.date_naissance

champ d'application CalculImpôt:
  définition personne1_décédée_avant_date_traitement égal à
    selon couple.personne_1.date_décès sous forme
    -- ToujoursVivant: faux
    -- Décédé contenu d: d < date_traitement

  définition personne2_décédée_avant_date_traitement égal à
    # Une autre syntaxe possible pour tester les motifs
    couple.personne_2.date_décès sous forme
      Décédé contenu d et d < date_traitement

Question 5

Enfin, nous devons définir un test pour notre calcul. En vous basant sur les tests définis précédemment, écrivez une définition du champ d’application de test TestCalculImpôt. Ensuite, ajustez les valeurs de test données pour vous assurer que votre implémentation est correcte.

déclaration champ d'application TestCalculImpôt:
  résultat test_calcul_impôt contenu CalculImpôt

Comme précédemment, vous pouvez utiliser une commande similaire pour exécuter votre test :

$ clerk run exercice-2-1-1.catala_fr --scope TestCalculImpôt

champ d'application TestCalculImpôt:
  définition test_calcul_impôt égal à
    résultat de CalculImpôt avec {
      # La date de traitement est une semaine avant le décès de test_personne1 :
      -- date_traitement: |2012-05-01|
      # La date de traitement est une semaine avant le décès de test_personne2 :
      # -- date_traitement: |2012-05-20|
      -- couple: test_couple
    }

Définitions conditionnelles et exceptions

Dans cette section, le tutoriel présente la fonctionnalité phare de Catala pour coder la loi : les exceptions dans les définitions de variables. À la fin de la section, vous devriez comprendre le comportement des calculs impliquant des exceptions, et être capable de structurer des groupes de définitions de variables selon leur statut exceptionnel et leur priorité relative.

# Corrigé du tutoriel

## Article 1

L'impôt sur le revenu pour un individu est défini comme un pourcentage fixe du
revenu de l'individu sur une année.

```catala
déclaration structure Individu:
  donnée revenu contenu argent
  donnée nombre_enfants contenu entier

déclaration champ d'application CalculImpôtRevenu:
  entrée individu contenu Individu
  interne taux_imposition contenu décimal
  résultat impôt_revenu contenu argent

champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    individu.revenu * taux_imposition
```

## Article 2

Le pourcentage fixe mentionné à l'article 1 est égal à 20 %.

```catala
champ d'application CalculImpôtRevenu:
  définition taux_imposition égal à 20%
```

## Test

```catala
déclaration champ d'application Test:
  résultat calcul contenu CalculImpôtRevenu

champ d'application Test:
  définition calcul égal à
    résultat de CalculImpôtRevenu avec {
      -- individu:
        Individu {
          -- revenu: 20 000 €
          -- nombre_enfants: 0
        }
    }
```

Définitions conditionnelles et exceptions

Les spécifications provenant de textes juridiques ne divisent pas toujours proprement chaque définition de variable dans son propre article. Parfois, et c’est un schéma très courant, un article ultérieur redéfinit une variable déjà définie précédemment, mais avec une particularité dans une certaine situation exceptionnelle. Par exemple, l’article 3 du CITC :

Cet article donne en fait une autre définition pour le pourcentage fixe, qui était déjà défini à l’article 2. Cependant, l’article 3 définit le pourcentage conditionnellement au fait que l’individu ait plus de 2 enfants. Comment redéfinir taux_imposition ? Catala vous permet précisément de redéfinir une variable sous une condition avec la syntaxe sous condition ... conséquence entre le nom de la variable définie et le mot-clé égal à :

champ d'application CalculImpôtRevenu:
  définition taux_imposition
  sous condition individu.nombre_enfants >= 2
  conséquence égal à 15 %

Qu’est-ce que cela signifie ? Si l’individu a plus de deux enfants, alors taux_imposition sera de 15 %. Les définitions conditionnelles vous permettent de définir vos variables par morceaux, un cas à la fois ; le compilateur Catala assemble le tout pour l’exécution. Plus précisément, à l’exécution, nous regardons les conditions de toutes les définitions par morceaux pour une même variable, et choisissons celle qui est valide.

champ d'application Test:
  définition calcul égal à
    résultat de CalculImpôtRevenu avec {
      -- individu:
        Individu {
          -- revenu: 20 000 €
          -- nombre_enfants: 3
        }
    }

$ clerk run tutoriel.catala_fr --scope=Test
┌─[ERROR]─
│
│  During evaluation: conflict between multiple valid consequences for assigning the same variable.
│
├─➤ tutoriel_fr.catala_fr
│     │
│     │   définition taux_imposition égal à 20 %
│     │                              ‾‾‾‾‾‾
├─ Article 2
│
├─➤ tutoriel_fr.catala_fr
│     │
│     │   conséquence égal à 15 %
│     │                      ‾‾‾‾
└─ Article 3

Si la spécification est correctement rédigée, alors ces situations d’erreur ne devraient pas se produire, car une et une seule définition conditionnelle devrait être valide à tout moment. Ici, cependant, notre définition de taux_imposition entre en conflit avec la définition plus générale que nous avons donnée ci-dessus. Pour modéliser correctement des situations comme celle-ci, Catala nous permet de définir la priorité d’une définition conditionnelle sur une autre. C’est aussi simple que d’ajouter exception avant la définition. Par exemple, voici une version plus correcte du code pour l’article 3 :

champ d'application CalculImpôtRevenu:
  exception définition taux_imposition
  sous condition individu.nombre_enfants >= 2
  conséquence égal à 15 %

Avec exception, la définition conditionnelle de l’article 3 sera choisie par rapport au cas de base de l’article 1 lorsque l’individu a deux enfants ou plus. Ce mécanisme d’exception est calqué sur la logique de la rédaction juridique : c’est le mécanisme clé qui nous permet de diviser notre définition de variables pour correspondre à la structure de la spécification. Sans exception, il n’est pas possible d’utiliser le style de programmation littéraire. C’est précisément pourquoi écrire et maintenir des programmes informatiques pour les impôts ou les prestations sociales est très difficile avec les langages de programmation grand public. Alors, allez-y et utilisez exception autant que possible, car c’est un concept Catala très idiomatique.

Comme décrit ci-dessus, mettre exception dans un programme Catala modifie le comportement du programme, en fournissant une priorité entre les définitions conditionnelles d’une variable que Catala peut utiliser au moment de l’exécution lorsqu’il hésite entre plusieurs définitions qui s’appliquent en même temps. Jusqu’à présent, nous avons vu une situation très simple avec une définition de base (à l’article 2) et une seule exception (à l’article 3). Mais le mécanisme d’exception peut être beaucoup plus large et aider à définir différentes lignes de priorité parmi des dizaines de définitions conditionnelles différentes pour une même variable. Explorons ce mécanisme sur un exemple plus complexe.

Gérer plusieurs exceptions

Il est fréquent dans les textes juridiques qu’un article établissant une règle générale soit suivi de plusieurs articles définissant des exceptions à la règle de base. En plus de l’article 3 et du taux d’imposition réduit pour les familles nombreuses, le CITC (Code des Impôts du Tutoriel Catala) définit en effet une exonération fiscale pour les individus à faible revenu, que nous pouvons coder comme une autre exception à la définition du taux d’imposition de l’article 2 :

champ d'application CalculImpôtRevenu:
  exception définition taux_imposition
  sous condition individu.revenu <= 10 000 €
  # Notez le <= au-dessus, la formulation de l'article 4 suggère d'utiliser <
  # mais nous prenons toujours l'interprétation la plus favorable au
  # contribuable !
  conséquence égal à 0 %

Mais alors, que se passe-t-il lors du test du code avec un individu qui gagne moins de 10 000 € et a plus de 2 enfants ?

champ d'application Test:
  définition calcul égal à
    résultat de CalculImpôtRevenu avec {
      -- individu:
        Individu {
          -- revenu: 5 000 €
          -- nombre_enfants: 3
        }
    }

$ clerk run tutoriel.catala_fr --scope=Test
┌─[ERROR]─
│
│  During evaluation: conflict between multiple valid consequences for assigning the same variable.
│
├─➤ tutoriel_fr.catala_fr
│     │
│     │   conséquence égal à 15 %
│     │                      ‾‾‾‾
├─ Article 3
│
├─➤ tutoriel_fr.catala_fr
│     │
│     │   conséquence égal à 0 %
│     │                      ‾‾‾
└─ Article 4

Dans cette situation, nous devons prioriser les exceptions entre elles.

Ici, parce que l’article 4 suit l’article 3, et parce qu’il est plus favorable au contribuable de payer 0 € d’impôt plutôt que 15 % de son revenu, nous pouvons prendre la décision juridique de prioriser l’exception de l’article 4 sur l’exception de l’article 3. Maintenant, voyons comment écrire cela avec Catala. Parce que l’article 2 est le cas de base pour l’exception de l’article 3, et l’article 3 est le cas de base pour l’exception de l’article 4, nous devons donner aux définitions de taux_imposition aux articles 2 et 3 une étiquette explicite afin que les mots-clés exception dans les articles 3 et 4 puissent faire référence à ces étiquettes :

champ d'application CalculImpôtRevenu:
  # Le mot-clé "étiquette" introduit le nom de l'étiquette elle-même, ici
  # "article_2".
  étiquette article_2 définition taux_imposition égal à 20 %

champ d'application CalculImpôtRevenu:
  # Cette définition est précédée de deux indications :
  # * elle a sa propre étiquette, "article_3" ;
  # * cette définition est une exception à la définition étiquetée "article_2".
  étiquette article_3 exception article_2
  définition taux_imposition
  sous condition individu.nombre_enfants >= 2
  conséquence égal à 15 %

champ d'application CalculImpôtRevenu:
  étiquette article_4 exception article_3
  définition taux_imposition
  sous condition individu.revenu < 10 000 €
  conséquence égal à 0 %

Grâce aux étiquettes, nous pouvons définir des chaînes d’exceptions, où chaque définition est l’exception à la précédente, et le cas de base pour la suivante. Ce modèle est le plus courant dans les textes juridiques, et son comportement est simple : lorsque plusieurs définitions s’appliquent, choisir celle avec la priorité la plus élevée dans la chaîne. Voici une représentation de la chaîne d’exceptions dans notre exemple jusqu’à présent :

graph LR;
A2["`article_2`"]
A3["`article_3`"]
A4["`article_4`"]
A2-->A3
A3-->A4

Mais parfois, il n’est pas possible d’organiser les exceptions en chaîne, car l’interprétation juridique conduit à différentes branches d’exceptions.

Branches d’exceptions

Il peut être difficile de voir pourquoi certaines situations juridiques peuvent conduire à différentes branches d’exceptions. Donnons un exemple avec un nouvel article du CITC :

champ d'application CalculImpôtRevenu:
  étiquette article_5 exception article_3
  définition taux_imposition
  sous condition individu.revenu > 100 000 €
  conséquence égal à 30 %

Maintenant, l’article 3 a deux exceptions : l’article 4 et l’article 5. Ces deux exceptions ont les conditions suivantes :

• Article 4 : revenu inférieur à 10 000 € ;
• Article 5 : revenu supérieur à 100 000 €.

$ catala exceptions tutoriel.catala_fr --scope=CalculImpôtRevenu --variable=taux_imposition
┌[RESULT]─
│ Printing the tree of exceptions for the definitions of variable "taux_imposition" of scope "CalculImpôtRevenu".
└─
┌─[RESULT]─
│ Definitions with label "article_2":
│
├─➤ tutoriel.catala_fr
│    │
│    │   étiquette article_2 définition taux_imposition égal à 20 %
│    │   ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
└─ Title
   └─ Article 2
┌─[RESULT]─
│ Definitions with label "article_3":
│
├─➤ tutoriel.catala_fr
│    │
│    │   étiquette article_3 exception article_2 définition taux_imposition sous condition
│    │   ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
└─ Title
   └─ Article 3
┌─[RESULT]─
│ Definitions with label "article_4":
│
├─➤ tutoriel.catala_fr
│    │
│    │   étiquette article_4 exception article_3 définition taux_imposition sous condition
│    │   ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
└─ Title
   └─ Article 4
┌─[RESULT]─
│ Definitions with label "article_5":
│
├─➤ tutoriel.catala_fr
│    │
│    │   étiquette article_5 exception article_3 définition taux_imposition sous condition
│    │   ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
└─ Title
   └─ Article 5
┌─[RESULT]─
│ The exception tree structure is as follows:
│
│ "article_2"───"article_3"──┬──"article_5"
│                            │
│                            └──"article_4"
└─

Théoriquement, puisque les exceptions de l’article 4 et de l’article 5 ne sont pas priorisées l’une par rapport à l’autre, elles pourraient toutes deux s’appliquer en même temps et entrer en conflit. Cependant, puisque le revenu ne peut pas être à la fois inférieur à 10 000 € et supérieur à 100 000 €, le conflit ne peut pas se produire en pratique. Par conséquent, il n’est pas nécessaire de prioriser les deux exceptions, car elles vivent dans des branches conditionnelles mutuellement exclusives.

champ d'application Test:
  définition calcul égal à
    résultat de CalculImpôtRevenu avec {
      -- individu:
        Individu {
          -- revenu: 200 000 €
          -- nombre_enfants: 3
        }
    }

$ clerk run tutoriel.catala_fr --scope=Test
┌─[RESULT]─
│ calcul = CalculImpôtRevenu { -- impôt_revenu: 60 000,00 € }
└─

Il est alors possible d’étendre ces branches séparément, par exemple avec un nouvel article du CITC :

Cet article introduit une nouvelle information sur le calcul de l’impôt : sommes-nous dans un territoire d’outre-mer ou non ? Nous pouvons le modéliser avec une nouvelle entrée dans le champ d’application CalculImpôtRevenu, conduisant à une déclaration de champ d’application révisée :

déclaration champ d'application CalculImpôtRevenu:
   entrée individu contenu Individu
   entrée territoires_outre_mer contenu booléen
   interne taux_imposition contenu décimal
   résultat impôt_revenu contenu argent

Avec cette nouvelle variable d’entrée, le code pour l’article 6 est le suivant :

champ d'application CalculImpôtRevenu:
  étiquette article_6 exception article_5
  définition taux_imposition
  sous condition individu.revenu > 100 000 € et territoires_outre_mer
  conséquence égal à 25 %

champ d'application CalculImpôtRevenu:
  étiquette article_6 exception article_5
  définition taux_imposition
  sous condition territoires_outre_mer
  conséquence égal à 25 %

Enfin, nous pouvons récapituler la collection de branches d’exception sous forme d’arbre d’exceptions pour notre exemple :

graph LR;
A2["`article_2`"]
A3["`article_3`"]
A4["`article_4`"]
A5["`article_5`"]
A6["`article_6`"]
A2-->A3
A3-->A4
A3-->A5
A5-->A6

Regrouper les définitions conditionnelles pour les exceptions

Jusqu’à présent, nous avons vu comment définir des chaînes d’exceptions et des branches d’exceptions mutuellement exclusives. Mais il existe un schéma très courant qui introduit encore une autre manigance exceptionnelle. Supposons qu’en l’an 2000, une grande réforme fiscale modifie le taux d’imposition de base de l’article 2 avec une légère augmentation :

Maintenant, il existe plusieurs stratégies pour gérer les mises à jour juridiques dans Catala, qui sont résumées dans la section guide de ce livre. Mais ici, nous supposerons que nous voulons que les deux versions de la loi (avant et après 2000) coexistent dans le même programme Catala. Ce choix nous amène à introduire la date courante comme une nouvelle entrée du champ d’application CalculImpôtRevenu :

déclaration champ d'application CalculImpôtRevenu:
   entrée date_courante contenu date
   entrée individu contenu Individu
   entrée territoires_outre_mer contenu booléen
   interne taux_imposition contenu décimal
   résultat impôt_revenu contenu argent

Cette variable date_courante nous permettra d’introduire des définitions conditionnelles mutuellement exclusives pour les deux versions différentes de l’article 2, chacune s’activant uniquement avant ou après l’an 2000. Notez que si les deux définitions de l’article 2 n’étaient pas mutuellement exclusives, elles pourraient entrer en conflit l’une avec l’autre, vous obligeant à prioriser entre elles et à modifier la forme de l’arbre d’exceptions global en introduisant une autre couche d’exception. Cependant, nous voulons dans ce cas que ces deux définitions de base de l’article 2 soient collectivement le cas de base pour toutes les exceptions ultérieures dans l’arbre d’exceptions de taux_imposition ! En résumé, nous voulons l’arbre d’exceptions suivant :

graph LR;
subgraph article_2
direction TB
A2["`article_2 (avant 2000)`"]
A2bis["`article_2 (après 2000)`"]
end
A3["`article_3`"]
A4["`article_4`"]
A5["`article_5`"]
A6["`article_6`"]
A2~~~A2bis
article_2-->A3
A3-->A4
A3-->A5
A5-->A6

Catala est capable de représenter cet arbre d’exceptions, en regroupant les deux définitions conditionnelles de l’article 2. En effet, puisque l’article 3 est une exception à l’étiquette article_2, il suffit de donner la même étiquette article_2 aux deux définitions conditionnelles des deux versions de article_2 :

champ d'application CalculImpôtRevenu:
  étiquette article_2 définition taux_imposition
  sous condition date_courante < |2000-01-01|
  conséquence égal à 20 %

champ d'application CalculImpôtRevenu:
  # Utilisez simplement la même étiquette "article_2" que la définition précédente pour les regrouper
  étiquette article_2 définition taux_imposition
  sous condition date_courante >= |2000-01-01|
  conséquence égal à 21 %

En utilisant le mécanisme de regroupement de définitions avec les branches d’exception, Catala est capable d’exprimer un large éventail de logique de texte juridique, et aide à garder le code aux côtés de sa spécification.

Récapitulons

Ceci conclut la deuxième section du tutoriel. En Catala, les variables peuvent être définies par morceaux, chaque morceau de définition étant activé par une condition. Lorsque plusieurs conditions s’appliquent, on peut prioriser les définitions conditionnelles en utilisant les mots-clés exception et étiquette pour former des arbres d’exceptions capables de capturer la logique complexe derrière les textes juridiques tout en correspondant à leur structure.

# Corrigé du tutoriel

## Article 1

L'impôt sur le revenu pour un individu est défini comme un pourcentage fixe du
revenu de l'individu sur une année.

```catala
déclaration structure Individu:
  donnée revenu contenu argent
  donnée nombre_enfants contenu entier

déclaration champ d'application CalculImpôtRevenu:
  entrée date_courante contenu date
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  interne taux_imposition contenu décimal
  résultat impôt_revenu contenu argent

champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    individu.revenu * taux_imposition
```

## Article 2

Le pourcentage fixe mentionné à l'article 1 est égal à 20 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_2
  définition taux_imposition
  sous condition date_courante < |2000-01-01|
  conséquence égal à
    20%

  étiquette article_2
  définition taux_imposition
  sous condition date_courante >= |2000-01-01|
  conséquence égal à
    21%
```

## Article 3

Si l'individu a la charge de 2 enfants ou plus, alors le pourcentage fixe
mentionné à l'article 1 est égal à 15 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_3 exception article_2
  définition taux_imposition
  sous condition individu.nombre_enfants >= 2
  conséquence égal à
    15%
```

## Article 4

Les individus gagnant moins de 10 000 € sont exonérés de l'impôt sur le revenu mentionné
à l'article 1.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_4 exception article_3
  définition taux_imposition
  sous condition individu.revenu <= 10 000 €
  conséquence égal à
    0%
```

## Article 5

Les individus gagnant plus de 100 000 € sont soumis à un taux d'imposition de
30%, quel que soit leur nombre d'enfants.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_5 exception article_3
  définition taux_imposition
  sous condition individu.revenu > 100 000 €
  conséquence égal à
    30%
```

## Article 6

Dans les territoires d'outre-mer, le taux d'imposition pour les individus gagnant
plus de 100 000 € spécifié à l'article 5 est réduit à 25 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_6 exception article_5
  définition taux_imposition
  sous condition individu.revenu > 100 000 € et territoires_outre_mer
  conséquence égal à
    25%
```

## Test

```catala
déclaration champ d'application Test:
  résultat calcul contenu CalculImpôtRevenu

champ d'application Test:
  définition calcul égal à
    résultat de CalculImpôtRevenu avec {
      -- individu:
        Individu {
          -- revenu: 200 000 €
          -- nombre_enfants: 3
        }
      -- territoires_outre_mer: faux
      -- date_courante: |1999-01-01|
    }
```

Listes et champs d’application

Dans cette section, le tutoriel aborde un schéma courant qui augmente considérablement la complexité d’une base de code : la nécessité de gérer des listes et des règles s’appliquant à chaque élément de la liste. Ici, nous apprenons comment effectuer des opérations avec des listes et déclarer un nouveau champ d’application pour traiter les règles s’appliquant à chaque élément de la liste.

Les deux dernières sections du tutoriel sont assez difficiles et impliquent une certaine complexité dans l’exemple. Cette complexité est nécessaire pour illustrer comment les fonctionnalités de Catala s’adaptent aux textes juridiques du monde réel qui impliquent des fonctionnalités complexes. Nous encourageons le lecteur à persévérer dans son étude de ces sections, et à poser toute question sur le chat en ligne de la communauté Catala.

# Corrigé du tutoriel

## Article 1

L'impôt sur le revenu pour un individu est défini comme un pourcentage fixe du
revenu de l'individu sur une année.

```catala
déclaration structure Individu:
  donnée revenu contenu argent
  donnée nombre_enfants contenu entier

déclaration champ d'application CalculImpôtRevenu:
  entrée date_courante contenu date
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  interne taux_imposition contenu décimal
  résultat impôt_revenu contenu argent

champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    individu.revenu * taux_imposition
```

## Article 2

Le pourcentage fixe mentionné à l'article 1 est égal à 20 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_2
  définition taux_imposition
  sous condition date_courante < |2000-01-01|
  conséquence égal à
    20%

  étiquette article_2
  définition taux_imposition
  sous condition date_courante >= |2000-01-01|
  conséquence égal à
    21%
```

## Article 3

Si l'individu a la charge de 2 enfants ou plus, alors le pourcentage fixe
mentionné à l'article 1 est égal à 15 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_3 exception article_2
  définition taux_imposition
  sous condition individu.nombre_enfants >= 2
  conséquence égal à
    15%
```

## Article 4

Les individus gagnant moins de 10 000 € sont exonérés de l'impôt sur le revenu mentionné
à l'article 1.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_4 exception article_3
  définition taux_imposition
  sous condition individu.revenu <= 10 000 €
  conséquence égal à
    0%
```

## Article 5

Les individus gagnant plus de 100 000 € sont soumis à un taux d'imposition de
30%, quel que soit leur nombre d'enfants.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_5 exception article_3
  définition taux_imposition
  sous condition individu.revenu > 100 000 €
  conséquence égal à
    30%
```

## Article 6

Dans les territoires d'outre-mer, le taux d'imposition pour les individus gagnant
plus de 100 000 € spécifié à l'article 5 est réduit à 25 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_6 exception article_5
  définition taux_imposition
  sous condition individu.revenu > 100 000 € et territoires_outre_mer
  conséquence égal à
    25%
```

## Test

```catala
déclaration champ d'application Test:
  résultat calcul contenu CalculImpôtRevenu

champ d'application Test:
  définition calcul égal à
    résultat de CalculImpôtRevenu avec {
      -- individu:
        Individu {
          -- revenu: 200 000 €
          -- nombre_enfants: 3
        }
      -- territoires_outre_mer: faux
      -- date_courante: |1999-01-01|
    }
```

Créer un foyer à partir d’une liste d’individus

Précédemment, le Code des Impôts du Tutoriel Catala (CITC) a défini un impôt sur le revenu pour chaque individu et ses enfants. Mais maintenant, le CITC devient plus gourmand car une nouvelle taxe distincte similaire à la tristement célèbre poll tax de Thatcher est introduite. À sa création, l’impôt sur le foyer est tel que chaque individu d’un foyer est taxé d’une somme fixe, avec un taux réduit pour les enfants :

Maintenant, implémenter cela en Catala nécessite d’aller au-delà du champ d’application CalculImpôtRevenu que nous avons utilisé plus tôt. En effet, cette nouvelle taxe nécessite un nouveau champ d’application, CalculImpôtFoyer ! Bien qu’il soit assez évident que le résultat de ce nouveau champ d’application devrait être impôt_foyer, son entrée est la collection d’individus qui composent le foyer.

Heureusement, Catala possède un type intégré pour les collections de choses, appelé liste, même s’il se comporte plus comme un tableau dans le jargon informatique traditionnel.

déclaration champ d'application CalculImpôtFoyer:
  # La syntaxe "liste de <X>" désigne le type dont les valeurs sont des listes d'
  # éléments de type <X>.
  entrée individus contenu liste de Individu
  résultat impôt_foyer contenu argent

Pour définir impôt_foyer, nous devons maintenant :

1. compter le nombre d’individus dans individus ;
2. compter le nombre d’enfants de chaque individu et additionner ces comptes ;
3. multiplier ces comptes par le bon montant d’impôt.

Nous effectuerons chacune de ces étapes dans le corps de la définition de impôt_foyer, dans le champ d’application CalculImpôtFoyer, en utilisant des variables locales.

# La ligne suivante définit la variable locale "x" comme étant égale à 4 * 5
soit x égal à 4 * 5 dans
# Nous pouvons ensuite utiliser "x" après le mot-clé "dans" dans le reste du code
x + 2

Pour l’étape 1, nous avons simplement besoin d’obtenir la longueur de la liste individus, ce qui peut être fait via la syntaxe nombre de individus (la syntaxe pour toutes les opérations sur les listes peut être trouvée dans l’aide-mémoire de la syntaxe ou dans le guide de référence). Pour l’étape 2, nous devons agréger le nombre d’enfants pour tous les individus, ce qui peut être fait via la syntaxe somme entier de transforme chaque individu parmi individus en individu.nombre_enfants. Notez l’indication de type (entier) pour la somme, qui indique que si la liste des individus est vide, alors l’entier 0 doit être renvoyé. Enfin, nous pouvons assembler les étapes 1 et 2 pour l’étape 3 qui calcule le montant de l’impôt :

champ d'application CalculImpôtFoyer:
  définition impôt_foyer égal à
    soit nombre_individus égal à nombre de individus dans
    soit nombre_enfants égal à
      somme entier de
        transforme chaque individu parmi individus en individu.nombre_enfants
    dans
    10 000 €
    * (
      # "nombre_individus" est un entier, mais le résultat de la division
      # est un décimal, et nous ne pouvons pas ajouter un entier et un décimal sans d'abord
      # convertir l'un d'eux
      décimal de nombre_individus + nombre_enfants / 2
    )

Cette implémentation de l’article 7 est assez directe et concise. Elle fonctionne, mais notez un décalage subtil entre le texte de l’article 7 et son implémentation Catala : plutôt que d’agréger séparément la contribution de chaque individu et de ses enfants à l’impôt sur le foyer, nous comptons tous les individus d’un côté, et tous les enfants de l’autre. L’addition est commutative et associative donc ce décalage donne le même résultat. Cependant, ne pas suivre l’esprit de la loi dans l’implémentation pourrait ne pas être pérenne, comme nous le verrons juste en dessous…

déclaration champ d'application TestFoyer:
  résultat calcul contenu CalculImpôtFoyer

champ d'application TestFoyer:
  définition calcul égal à
    résultat de CalculImpôtFoyer avec {
      -- individus:
        # Le champ d'application attend une liste d'individus. En Catala, une liste est construite
        # avec la syntaxe "[<élément 1>; <élément 2>; ...]".
        [ Individu {
            -- revenu: 15 000 €
            -- nombre_enfants: 0
          } ;
          Individu {
            -- revenu: 80 000 €
            -- nombre_enfants: 2
          } ]
    }

$ clerk run tutoriel.catala_fr --scope=TestFoyer
┌─[RESULT]─
│ calcul = CalculImpôtFoyer { -- impôt_foyer: 30 000,00 € }
└─

Refactoriser pour tenir compte de l’évolution des exigences

Traduire des textes juridiques en code exécutable est souvent des montagnes russes émotionnelles, car de nouvelles exigences dans des articles ultérieurs peuvent complètement briser les invariants et la structure de l’implémentation que vous avez utilisée dans les articles précédents. Aujourd’hui, le Code des Impôts du Tutoriel Catala (CITC) sera dur avec nous, avec l’article fatidique suivant :

Maintenant, il existe plusieurs stratégies pour implémenter l’article 8, mais toutes ne sont pas juridiquement correctes. Une stratégie pourrait être de calculer le montant total de l’impôt sur le revenu dû par tous les individus du foyer, et de soustraire ce montant total d’ impôt sur le revenu du montant total de l’impôt sur le foyer pour effectuer la déduction. Cependant, cette stratégie est incorrecte, car la déduction de l’impôt sur le foyer pour un individu est implicitement plafonnée par le montant de l’impôt sur le foyer dû pour cet individu ! Ce plafonnement introduit une non-linéarité dans la formule qui empêche de réorganiser les additions et les soustractions tout en gardant les mêmes résultats dans toutes les configurations.

Nous sommes donc contraints de décomposer explicitement le calcul de l’impôt sur le foyer en deux étapes : d’abord, calculer la part de l’impôt sur le foyer due par chaque individu, puis agréger le résultat de la première étape pour tous les individus du foyer. Naturellement, le champ d’application existant CalculImpôtFoyer est l’endroit où la deuxième étape aura lieu. Mais où mettre la première étape ? Une refactorisation est nécessaire !

Comme cela s’est déjà produit pour l’article 8, les articles suivants sont susceptibles d’introduire des raffinements et des exceptions pour cette part de l’impôt sur le foyer. Dans ce cas, il est préférable d’utiliser un champ d’application à part entière pour représenter cette étape de calcul supplémentaire. Le champ d’application est lisible par les juristes et possède des fonctionnalités pratiques pour ajouter des paramètres d’entrée et de sortie, définir des exceptions pour ses variables locales, etc.

Par conséquent, nous opterons pour la création d’un tout nouveau champ d’application pour calculer la part de l’impôt sur le foyer due par un individu, CalculImpôtFoyerIndividuel.

Le champ d’application manquant : calcul de l’impôt sur le foyer pour l’individu

Le nouveau champ d’application, CalculImpôtFoyerIndividuel, aura comme entrée un individu et renverra comme résultat le montant de l’impôt sur le foyer détenu. Cependant, à cause de l’article 8, le champ d’application devra également calculer le montant de l’impôt sur le revenu dû par l’individu, pour le déduire de l’impôt sur le foyer. Le graphe d’appel entre les champs d’application sera alors le suivant :

%%{init: {"flowchart": {"htmlLabels": true}} }%%
graph TD
    A["`CalculImpôtFoyer`"]
    B["`CalculImpôtFoyerIndividuel`"]
    C["`CalculImpôtRevenu`"]
    A-- appelle plusieurs fois -->B
    B-- appelle une fois -->C

Par conséquent, nous aurons également besoin comme entrée de CalculImpôtFoyerIndividuel des entrées nécessaires pour le champ d’application CalculImpôtRevenu de la section précédente du tutoriel : territoires_outre_mer et date_courante. Cela donne la déclaration de champ d’application suivante :

déclaration champ d'application CalculImpôtFoyerIndividuel:
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date

  résultat impôt_foyer contenu argent

Maintenant, nous savons que nous devrons appeler CalculImpôtRevenu exactement une fois pour calculer la déduction pour impôt_foyer. Il existe une méthode sur mesure conçue pour la lisibilité par les juristes pour faire exactement cela en Catala !

# L'appel unique et statique au sous-champ d'application "CalculImpôtRevenu" doit être
# déclaré dans "CalculImpôtFoyerIndividuel", nous répétons donc la
# déclaration du champ d'application ici avec une nouvelle ligne.
déclaration champ d'application CalculImpôtFoyerIndividuel:
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date

  # La ligne suivante déclare un appel statique et unique au sous-champ d'application
  # "CalculImpôtRevenu" avec le nom "calcul_impôt_revenu".
  calcul_impôt_revenu champ d'application CalculImpôtRevenu

  résultat impôt_foyer contenu argent

champ d'application CalculImpôtFoyerIndividuel:
  # À l'intérieur d'un bloc "champ d'application", nous devons définir les arguments de l'appel au sous-champ d'application
  # "calcul_impôt_revenu" : "individu", "territoires_outre_mer" et
  # "territoires_outre_mer".
  définition calcul_impôt_revenu.individu égal à
    individu
  # L'"individu" donné comme argument à "calcul_impôt_revenu",
  # qui est l'appel à "CalculImpôtRevenu", est le même "individu"
  # qui est l'entrée de "CalculImpôtFoyerIndividuel".
  définition calcul_impôt_revenu.territoires_outre_mer égal à
    territoires_outre_mer
  # Ces lignes peuvent sembler tautologiques mais elles sont essentielles pour connecter
  # les champs d'application aux sous-champs d'application de manière non ambiguë. Il est implicite que nous évaluons
  # l'impôt sur le revenu pour la déduction à la même date que nous évaluons le montant de
  # l'impôt sur le foyer, mais cette ligne le rend explicite. Parfois, vous pourriez vouloir
  # appeler le calcul de l'impôt sur le revenu à une date antérieure (comme "date_courante
  # - 5 an") en raison d'une exigence légale, et c'est là que vous spécifiez
  # cela !
  définition calcul_impôt_revenu.date_courante égal à
    date_courante

À ce stade, il est facile de définir impôt_foyer en un seul passage à l’intérieur de CalculImpôtFoyerIndividuel :

champ d'application CalculImpôtFoyerIndividuel:
  définition impôt_foyer égal à
    soit impôt égal à
      10 000 € * (1,0 + individu.nombre_enfants / 2)
    dans
    soit déduction égal à calcul_impôt_revenu.impôt_revenu dans
    # N'oubliez pas de plafonner la déduction !
    si déduction > impôt alors 0 € sinon impôt - déduction

déclaration champ d'application TestFoyerIndividuel:
  résultat calcul contenu CalculImpôtFoyerIndividuel

champ d'application TestFoyerIndividuel:
  définition calcul égal à
    résultat de CalculImpôtFoyerIndividuel avec {
      -- individu:
        Individu {
          -- revenu: 15 000 €
          -- nombre_enfants: 0
        }
      -- date_courante: |1999-01-01|
      -- territoires_outre_mer: faux
    }

$ clerk run tutoriel.catala_fr --scope=TestFoyerIndividuel
┌─[RESULT]─
│ calcul = CalculImpôtFoyerIndividuel { -- impôt_foyer: 7 000,00 € }
└─

Conclusion

Dans cette section du tutoriel, nous avons vu qu’en Catala, les listes d’éléments sont représentées comme des valeurs avec leur propre type comme liste de argent ou liste de Individu. Vous pouvez manipuler des listes avec des opérateurs comme longueur, comptage, agrégation, mais aussi transformer, filtrer, etc. Veuillez vous référer au guide de référence pour des informations sur tous les opérateurs de liste disponibles en Catala. De plus, nous avons également vu dans cette section du tutoriel que plutôt que d’programmer toutes les règles pour traiter les éléments dans les listes à l’intérieur des opérateurs de liste, il est préférable de créer un nouveau champ d’application pour écrire toutes les règles qui s’appliquent aux éléments de la liste. Cela nous a permis de voir comment les champs d’application peuvent s’appeler les uns les autres et permettre une base de code modulaire qui peut être refactorisée pour tenir compte de l’évolution des exigences légales.

Cependant, pour l’instant, notre implémentation des articles 7 et 8 n’est pas complète, car il nous manque l’étape où CalculImpôtFoyer appelle CalculImpôtFoyerIndividuel sur chaque individu du foyer pour compléter le calcul de l’impôt sur le foyer avec la déduction correcte. Ce sera le sujet de la prochaine et dernière section du tutoriel.

# Corrigé du tutoriel

## Article 1

L'impôt sur le revenu pour un individu est défini comme un pourcentage fixe du
revenu de l'individu sur une année.

```catala
déclaration structure Individu:
  donnée revenu contenu argent
  donnée nombre_enfants contenu entier

déclaration champ d'application CalculImpôtRevenu:
  entrée date_courante contenu date
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  interne taux_imposition contenu décimal
  résultat impôt_revenu contenu argent

champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    individu.revenu * taux_imposition
```

## Article 2

Le pourcentage fixe mentionné à l'article 1 est égal à 20 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_2
  définition taux_imposition
  sous condition date_courante < |2000-01-01|
  conséquence égal à
    20%

  étiquette article_2
  définition taux_imposition
  sous condition date_courante >= |2000-01-01|
  conséquence égal à
    21%
```

## Article 3

Si l'individu a la charge de 2 enfants ou plus, alors le pourcentage fixe
mentionné à l'article 1 est égal à 15 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_3 exception article_2
  définition taux_imposition
  sous condition individu.nombre_enfants >= 2
  conséquence égal à
    15%
```

## Article 4

Les individus gagnant moins de 10 000 € sont exonérés de l'impôt sur le revenu mentionné
à l'article 1.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_4 exception article_3
  définition taux_imposition
  sous condition individu.revenu <= 10 000 €
  conséquence égal à
    0%
```

## Article 5

Les individus gagnant plus de 100 000 € sont soumis à un taux d'imposition de
30%, quel que soit leur nombre d'enfants.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_5 exception article_3
  définition taux_imposition
  sous condition individu.revenu > 100 000 €
  conséquence égal à
    30%
```

## Article 6

Dans les territoires d'outre-mer, le taux d'imposition pour les individus gagnant
plus de 100 000 € spécifié à l'article 5 est réduit à 25 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_6 exception article_5
  définition taux_imposition
  sous condition individu.revenu > 100 000 € et territoires_outre_mer
  conséquence égal à
    25%
```

## Article 7

Lorsque plusieurs individus vivent ensemble, ils sont collectivement soumis à
l'impôt sur le foyer. L'impôt sur le foyer dû est de 10 000 € par individu du foyer,
et la moitié de ce montant par enfant.

```catala
déclaration champ d'application CalculImpôtFoyer:
  entrée individus contenu liste de Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date
  résultat impôt_foyer contenu argent

champ d'application CalculImpôtFoyer:
  définition impôt_foyer égal à
    somme argent de
      transforme chaque individu parmi individus en
        (
          résultat de CalculImpôtFoyerIndividuel avec {
            -- individu: individu
            -- territoires_outre_mer: territoires_outre_mer
            -- date_courante: date_courante
          }
        ).impôt_foyer
```

## Article 8

Le montant de l'impôt sur le revenu payé par chaque individu peut être déduit de la
part de l'impôt sur le foyer due par cet individu.

```catala
déclaration champ d'application CalculImpôtFoyerIndividuel:
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date

  calcul_impôt_revenu champ d'application CalculImpôtRevenu

  résultat impôt_foyer contenu argent

champ d'application CalculImpôtFoyerIndividuel:
  définition calcul_impôt_revenu.individu égal à
    individu
  définition calcul_impôt_revenu.territoires_outre_mer égal à
    territoires_outre_mer
  définition calcul_impôt_revenu.date_courante égal à
    date_courante

  définition impôt_foyer égal à
    soit impôt égal à
      10 000 € * (1,0 + individu.nombre_enfants / 2)
    dans
    soit déduction égal à calcul_impôt_revenu.impôt_revenu dans
    si déduction > impôt alors 0 € sinon impôt - déduction
```

## Test

```catala
déclaration champ d'application TestFoyerIndividuel:
  résultat calcul contenu CalculImpôtFoyerIndividuel

champ d'application TestFoyerIndividuel:
  définition calcul égal à
    résultat de CalculImpôtFoyerIndividuel avec {
      -- individu:
        Individu {
          -- revenu: 15 000 €
          -- nombre_enfants: 0
        }
      -- date_courante: |1999-01-01|
      -- territoires_outre_mer: faux
    }
```

États de variables et appels dynamiques de champs d’application

Introduction

Dans cette section, le tutoriel reprend là où la section précédente s’est arrêtée, c’est-à-dire l’implémentation du calcul de l’impôt sur le foyer pour un individu. Maintenant, nous devons encore agréger les calculs pour les individus au niveau du foyer pour générer l’impôt total sur le foyer.

Faire cette agrégation nécessitera d’appeler le champ d’application CalculImpôtFoyerIndividuel plusieurs fois pour une agrégation de liste à l’intérieur de CalculImpôtFoyer. Nous couvrirons ce sujet, mais d’abord nous devons régler les affaires inachevées de la dernière section du tutoriel !

# Corrigé du tutoriel

## Article 1

L'impôt sur le revenu pour un individu est défini comme un pourcentage fixe du
revenu de l'individu sur une année.

```catala
déclaration structure Individu:
  donnée revenu contenu argent
  donnée nombre_enfants contenu entier

déclaration champ d'application CalculImpôtRevenu:
  entrée date_courante contenu date
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  interne taux_imposition contenu décimal
  résultat impôt_revenu contenu argent

champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    individu.revenu * taux_imposition
```

## Article 2

Le pourcentage fixe mentionné à l'article 1 est égal à 20 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_2
  définition taux_imposition
  sous condition date_courante < |2000-01-01|
  conséquence égal à
    20%

  étiquette article_2
  définition taux_imposition
  sous condition date_courante >= |2000-01-01|
  conséquence égal à
    21%
```

## Article 3

Si l'individu a la charge de 2 enfants ou plus, alors le pourcentage fixe
mentionné à l'article 1 est égal à 15 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_3 exception article_2
  définition taux_imposition
  sous condition individu.nombre_enfants >= 2
  conséquence égal à
    15%
```

## Article 4

Les individus gagnant moins de 10 000 € sont exonérés de l'impôt sur le revenu mentionné
à l'article 1.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_4 exception article_3
  définition taux_imposition
  sous condition individu.revenu <= 10 000 €
  conséquence égal à
    0%
```

## Article 5

Les individus gagnant plus de 100 000 € sont soumis à un taux d'imposition de
30%, quel que soit leur nombre d'enfants.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_5 exception article_3
  définition taux_imposition
  sous condition individu.revenu > 100 000 €
  conséquence égal à
    30%
```

## Article 6

Dans les territoires d'outre-mer, le taux d'imposition pour les individus gagnant
plus de 100 000 € spécifié à l'article 5 est réduit à 25 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_6 exception article_5
  définition taux_imposition
  sous condition individu.revenu > 100 000 € et territoires_outre_mer
  conséquence égal à
    25%
```

## Article 7

Lorsque plusieurs individus vivent ensemble, ils sont collectivement soumis à
l'impôt sur le foyer. L'impôt sur le foyer dû est de 10 000 € par individu du foyer,
et la moitié de ce montant par enfant.

```catala
déclaration champ d'application CalculImpôtFoyer:
  entrée individus contenu liste de Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date
  résultat impôt_foyer contenu argent

champ d'application CalculImpôtFoyer:
  définition impôt_foyer égal à
    somme argent de
      transforme chaque individu parmi individus en
        (
          résultat de CalculImpôtFoyerIndividuel avec {
            -- individu: individu
            -- territoires_outre_mer: territoires_outre_mer
            -- date_courante: date_courante
          }
        ).impôt_foyer
```

## Article 8

Le montant de l'impôt sur le revenu payé par chaque individu peut être déduit de la
part de l'impôt sur le foyer due par cet individu.

```catala
déclaration champ d'application CalculImpôtFoyerIndividuel:
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date

  calcul_impôt_revenu champ d'application CalculImpôtRevenu

  résultat impôt_foyer contenu argent

champ d'application CalculImpôtFoyerIndividuel:
  définition calcul_impôt_revenu.individu égal à
    individu
  définition calcul_impôt_revenu.territoires_outre_mer égal à
    territoires_outre_mer
  définition calcul_impôt_revenu.date_courante égal à
    date_courante

  définition impôt_foyer égal à
    soit impôt égal à
      10 000 € * (1,0 + individu.nombre_enfants / 2)
    dans
    soit déduction égal à calcul_impôt_revenu.impôt_revenu dans
    si déduction > impôt alors 0 € sinon impôt - déduction
```

## Test

```catala
déclaration champ d'application TestFoyerIndividuel:
  résultat calcul contenu CalculImpôtFoyerIndividuel

champ d'application TestFoyerIndividuel:
  définition calcul égal à
    résultat de CalculImpôtFoyerIndividuel avec {
      -- individu:
        Individu {
          -- revenu: 15 000 €
          -- nombre_enfants: 0
        }
      -- date_courante: |1999-01-01|
      -- territoires_outre_mer: faux
    }
```

États de variables

Rappelez-vous que nous avons défini impôt_foyer en un seul passage à l’intérieur de CalculImpôtFoyerIndividuel :

champ d'application CalculImpôtFoyerIndividuel:
  définition impôt_foyer égal à
    soit impôt égal à
      10 000 € * (1,0 + individu.nombre_enfants / 2)
    dans
    soit déduction égal à calcul_impôt_revenu.impôt_revenu dans
    # N'oubliez pas de plafonner la déduction !
    si déduction > impôt alors 0 € sinon impôt - déduction

Cependant, faire cela fusionne les spécifications de l’article 7 et de l’article 8, ce qui va à l’encontre de l’esprit de Catala de diviser le code dans la même structure que le texte juridique. Donc, au lieu d’utiliser deux variables locales à l’intérieur de la définition de impôt_foyer, nous voulons diviser la formule en deux définition distinctes. Intuitivement, cela implique de créer deux variables de champ d’application dans CalculImpôtFoyerIndividuel, impôt_foyer_base (pour l’article 7) et impôt_foyer_avec_déduction (article 8). Mais en réalité, cela revient à donner deux états consécutifs pour la variable impôt_foyer, et les juristes comprennent mieux le code de cette façon ! Donc Catala a une fonctionnalité pour vous permettre de faire exactement cela :

déclaration champ d'application CalculImpôtFoyerIndividuel:
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date

  calcul_impôt_revenu champ d'application CalculImpôtRevenu

  résultat impôt_foyer contenu argent
    # Les différents états pour la variable "impôt_foyer" sont déclarés ici,
    # dans l'ordre exact où vous vous attendez à ce qu'ils soient calculés !
    état base
    état avec_déduction

champ d'application CalculImpôtFoyerIndividuel:
  définition impôt_foyer état base égal à
    10 000 € * (1,0 + individu.nombre_enfants / 2)

champ d'application CalculImpôtFoyerIndividuel:
  définition impôt_foyer état avec_déduction égal à
    # Ci-dessous, "impôt_foyer" fait référence à la valeur de "impôt_foyer" calculée
    # dans l'état précédent, donc ici l'état "base" qui précède immédiatement
    # l'état "avec_déduction" dans la déclaration.
    si calcul_impôt_revenu.impôt_revenu > impôt_foyer alors 0 €
    sinon
      impôt_foyer - calcul_impôt_revenu.impôt_revenu
    # Il est également possible de faire référence aux états de variables explicitement avec la
    # syntaxe "impôt_foyer état base".

Ceci complète notre implémentation de CalculImpôtFoyerIndividuel ! Sa variable de résultat impôt_foyer contient maintenant la part de l’impôt sur le foyer due par chaque individu du foyer, avec la déduction correcte de l’impôt sur le revenu. Nous pouvons maintenant l’utiliser dans le calcul de l’impôt global sur le foyer dans CalculImpôtFoyer.

Relier les champs d’application ensemble via la transformation de liste

Nous pouvons maintenant finir de coder l’article 7 en additionnant chaque part de l’ impôt sur le foyer détenue par tous les individus du foyer. Nous ferons cela via l’agrégation de liste, comme précédemment, mais les éléments de la liste à agréger sont maintenant le résultat de l’appel de CalculImpôtFoyerIndividuel sur chaque individu. Précédemment, nous avons montré comment appeler un sous-champ d’application statiquement et exactement une fois. Mais ici, ce n’est pas ce que nous voulons : nous voulons appeler le sous-champ d’application autant de fois qu’il y a d’individus dans le foyer. Nous devons alors utiliser une méthode différente pour appeler le sous-champ d’application :

déclaration champ d'application CalculImpôtFoyer:
  entrée individus contenu liste de Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date
  résultat impôt_foyer contenu argent

champ d'application CalculImpôtFoyer:
  définition impôt_foyer égal à
    somme argent de
      transforme chaque individu parmi individus en (
        # Ci-dessous se trouve la syntaxe pour appeler le sous-champ d'application
        # "CalculImpôtFoyerIndividuel" dynamiquement, sur place.
        # après "avec" se trouve la liste des entrées du champ d'application.
        résultat de CalculImpôtFoyerIndividuel avec {
          # Les trois lignes suivantes sont tautologiques dans cet exemple, car
          # les noms des paramètres et les noms des variables de champ d'application
          # sont identiques, mais les valeurs des paramètres d'appel de champ d'application peuvent être
          # arbitrairement complexes !
          -- individu: individu # <- ce dernier "individu" est la variable de transformation
          -- territoires_outre_mer: territoires_outre_mer
          -- date_courante: date_courante
        }
        # La construction "résultat de <X> avec { ... }" renvoie une structure
        # contenant toutes les variables de résultat du champ d'application <X>. Par conséquent, nous accédons
        # à la variable de résultat "impôt_foyer" du champ d'application
        # "CalculImpôtFoyerIndividuel" avec la syntaxe d'accès au champ
        # ".impôt_foyer".
        ).impôt_foyer

C’est tout ! Nous avons fini d’implémenter l’article 7 et l’article 8 de manière propre, extensible et pérenne en utilisant une série de champs d’application qui s’appellent les uns les autres.

Tester et déboguer le calcul

Nous avons écrit un code assez complexe dans cette section du tutoriel, il est grand temps de le tester et de le déboguer. De la même manière que le test présenté dans la première section du tutoriel, nous pouvons déclarer un nouveau champ d’application de test pour le calcul de l’impôt sur le foyer, et l’exécuter :

déclaration champ d'application TestFoyer:
  résultat calcul contenu CalculImpôtFoyer

champ d'application TestFoyer:
  définition calcul égal à
    résultat de CalculImpôtFoyer avec {
      -- individus:
        [ Individu {
            -- revenu: 15 000 €
            -- nombre_enfants: 0
          } ;
          Individu {
            -- revenu: 80 000 €
            -- nombre_enfants: 2
          } ]
      -- territoires_outre_mer: faux
      -- date_courante: |1999-01-01|
    }

$ clerk run tutoriel.catala_fr --scope=TestFoyer
┌─[RESULT]─
│ calcul = CalculImpôtFoyer { -- impôt_foyer: 21 500,00 € }
└─

Le résultat du test est-il correct ? Voyons cela en déroulant le calcul manuellement :

• L’impôt sur le foyer pour deux individus et deux enfants est 2 * 10 000 € + 2 * 5 000 €, soit 30 000 € ;
• Le premier individu gagne plus de 10 000 €, moins de 100 000 €, n’a pas d’enfants et nous sommes avant l’an 2000, donc le taux d’impôt sur le revenu est de 20 % selon l’article 2 et son impôt sur le revenu est de 3 000 € ;
• La part de l’impôt sur le foyer pour le premier individu est de 10 000 €, donc la déduction pour le premier individu est la totalité des 3 000 € ;
• Le deuxième individu gagne plus de 10 000 €, moins de 100 000 €, mais a deux enfants donc le taux d’impôt sur le revenu est de 15 % selon l’article 3 et son impôt sur le revenu est de 12 000 € ;
• La part de l’impôt sur le foyer pour le deuxième individu est de 20 000 €, donc la déduction pour le deuxième individu est la totalité des 12 000 € ;
• La déduction totale est donc de 15 000 €, qui est plafonnée à 8 500 € selon l’article 9 ;
• Appliquer la déduction à l’impôt sur le foyer de base donne 21 500 €.

Jusqu’ici tout va bien, le résultat du test est correct. Mais il aurait pu arriver au bon résultat en prenant les mauvaises étapes intermédiaires, donc nous voudrons les inspecter. Heureusement, l’interpréteur Catala peut imprimer la trace complète du calcul à cette fin. Voici la sortie sur l’interprétation de TestFoyer :

$ clerk run tutoriel.catala_fr --scope=TestFoyer -c--trace
[LOG] ☛ Definition applied:
      ─➤ tutoriel.catala_fr
          │
          │   définition calcul égal à
          │              ‾‾‾‾‾‾
      Test
[LOG] →  CalculImpôtFoyer.direct
[LOG]   ≔  CalculImpôtFoyer.direct.
      entrée: CalculImpôtFoyer_in { -- individus_in: [Individu { -- revenu: 15 000,00 € -- nombre_enfants: 0 }; Individu { -- revenu: 80 000,00 € -- nombre_enfants: 2 }] -- territoires_outre_mer_in: faux -- date_courante_in: 1999-01-01 }
[LOG]   ☛ Definition applied:
        ─➤ tutoriel.catala_fr
            │
            │   définition parts_impôt_foyer égal à
            │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
        Article 7
[LOG]   →  CalculImpôtFoyerIndividuel.direct
[LOG]     ≔  CalculImpôtFoyerIndividuel.direct.
      entrée: CalculImpôtFoyerIndividuel_in { -- individu_in: Individu { -- revenu: 15 000,00 € -- nombre_enfants: 0 } -- territoires_outre_mer_in: faux -- date_courante_in: 1999-01-01 }
[LOG]     ☛ Definition applied:
          ─➤ tutoriel.catala_fr
              │
              │   définition impôt_foyer égal à
              │              ‾‾‾‾‾‾‾‾‾‾‾‾
          Article 7
[LOG]     ≔  CalculImpôtFoyerIndividuel.impôt_foyer: 10 000,00 €
[LOG]     →  CalculImpôtRevenu.direct
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
                │
                │   définition calcul_impôt_revenu.date_courante égal à
                │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 8
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
                │
                │   définition calcul_impôt_revenu.individu égal à
                │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 8
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
                │
                │   définition calcul_impôt_revenu.territoires_outre_mer égal à
                │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 8
[LOG]       ≔  CalculImpôtRevenu.direct.
      entrée: CalculImpôtRevenu_in { -- date_courante_in: 1999-01-01 -- individu_in: Individu { -- revenu: 15 000,00 € -- nombre_enfants: 0 } -- territoires_outre_mer_in: faux }
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
               │
               │     date_courante < |2000-01-01|
               │     ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 2 (ancienne version avant 2000)
[LOG]       ≔  CalculImpôtRevenu.taux_imposition: 0,2
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
               │
               │   définition impôt_revenu égal à
               │              ‾‾‾‾‾‾‾‾‾‾‾‾
            Article 1
[LOG]       ≔  CalculImpôtRevenu.impôt_revenu: 3 000,00 €
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
                │
                │   calcul_impôt_revenu champ d'application CalculImpôtRevenu
                │   ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 7
[LOG]       ≔  CalculImpôtRevenu.direct.
      résultat: CalculImpôtRevenu { -- impôt_revenu: 3 000,00 € }
[LOG]     ←  CalculImpôtRevenu.direct
[LOG]     ≔  CalculImpôtFoyerIndividuel.
      calcul_impôt_revenu: CalculImpôtRevenu { -- impôt_revenu: 3 000,00 € }
[LOG]     ☛ Definition applied:
          ─➤ tutoriel.catala_fr
              │
              │   définition déduction égal à
              │              ‾‾‾‾‾‾‾‾‾
          Article 8
[LOG]     ≔  CalculImpôtFoyerIndividuel.déduction: 3 000,00 €
[LOG]     ☛ Definition applied:
          ─➤ tutoriel.catala_fr
              │
              │       résultat de CalculImpôtFoyerIndividuel avec {
              │       ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
              │         -- individu: individu
              │         ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
              │         -- territoires_outre_mer: territoires_outre_mer
              │         ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
              │         -- date_courante: date_courante
              │         ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
              │       }
              │       ‾
          Article 7
[LOG]     ≔  CalculImpôtFoyerIndividuel.direct.
      résultat: CalculImpôtFoyerIndividuel { -- impôt_foyer: 10 000,00 € -- déduction: 3 000,00 € }
[LOG]   ←  CalculImpôtFoyerIndividuel.direct
[LOG]   →  CalculImpôtFoyerIndividuel.direct
[LOG]     ≔  CalculImpôtFoyerIndividuel.direct.
      entrée: CalculImpôtFoyerIndividuel_in { -- individu_in: Individu { -- revenu: 80 000,00 € -- nombre_enfants: 2 } -- territoires_outre_mer_in: faux -- date_courante_in: 1999-01-01 }
[LOG]     ☛ Definition applied:
          ─➤ tutoriel.catala_fr
              │
              │   définition impôt_foyer égal à
              │              ‾‾‾‾‾‾‾‾‾‾‾‾
          Article 7
[LOG]     ≔  CalculImpôtFoyerIndividuel.impôt_foyer: 20 000,00 €
[LOG]     →  CalculImpôtRevenu.direct
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
                │
                │   définition calcul_impôt_revenu.date_courante égal à
                │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 8
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
                │
                │   définition calcul_impôt_revenu.individu égal à
                │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 8
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
                │
                │   définition calcul_impôt_revenu.territoires_outre_mer égal à
                │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 8
[LOG]       ≔  CalculImpôtRevenu.direct.
      entrée: CalculImpôtRevenu_in { -- date_courante_in: 1999-01-01 -- individu_in: Individu { -- revenu: 80 000,00 € -- nombre_enfants: 2 } -- territoires_outre_mer_in: faux }
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
               │
               │     individu.nombre_enfants >= 2
               │     ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 3
[LOG]       ≔  CalculImpôtRevenu.taux_imposition: 0,15
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
               │
               │   définition impôt_revenu égal à
               │              ‾‾‾‾‾‾‾‾‾‾‾‾
            Article 1
[LOG]       ≔  CalculImpôtRevenu.impôt_revenu: 12 000,00 €
[LOG]       ☛ Definition applied:
            ─➤ tutoriel.catala_fr
                │
                │   calcul_impôt_revenu champ d'application CalculImpôtRevenu
                │   ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            Article 7
[LOG]       ≔  CalculImpôtRevenu.direct.
      résultat: CalculImpôtRevenu { -- impôt_revenu: 12 000,00 € }
[LOG]     ←  CalculImpôtRevenu.direct
[LOG]     ≔  CalculImpôtFoyerIndividuel.
      calcul_impôt_revenu: CalculImpôtRevenu { -- impôt_revenu: 12 000,00 € }
[LOG]     ☛ Definition applied:
          ─➤ tutoriel.catala_fr
              │
              │   définition déduction égal à
              │              ‾‾‾‾‾‾‾‾‾
          Article 8
[LOG]     ≔  CalculImpôtFoyerIndividuel.déduction: 12 000,00 €
[LOG]     ☛ Definition applied:
          ─➤ tutoriel.catala_fr
              │
              │       résultat de CalculImpôtFoyerIndividuel avec {
              │       ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
              │         -- individu: individu
              │         ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
              │         -- territoires_outre_mer: territoires_outre_mer
              │         ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
              │         -- date_courante: date_courante
              │         ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
              │       }
              │       ‾
          Article 7
[LOG]     ≔  CalculImpôtFoyerIndividuel.direct.
      résultat: CalculImpôtFoyerIndividuel { -- impôt_foyer: 20 000,00 € -- déduction: 12 000,00 € }
[LOG]   ←  CalculImpôtFoyerIndividuel.direct
[LOG]   ≔  CalculImpôtFoyer.
      parts_impôt_foyer: [CalculImpôtFoyerIndividuel { -- impôt_foyer: 10 000,00 € -- déduction: 3 000,00 € }; CalculImpôtFoyerIndividuel { -- impôt_foyer: 20 000,00 € -- déduction: 12 000,00 € }]
[LOG]   ☛ Definition applied:
        ─➤ tutoriel.catala_fr
            │
            │   définition impôt_foyer
            │              ‾‾‾‾‾‾‾‾‾‾‾‾
        Article 7
[LOG]   ≔  CalculImpôtFoyer.impôt_foyer#base: 30 000,00 €
[LOG]   ☛ Definition applied:
        ─➤ tutoriel.catala_fr
            │
            │   définition déduction_totale
            │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
        Article 8
[LOG]   ≔  CalculImpôtFoyer.déduction_totale#base: 15 000,00 €
[LOG]   ☛ Definition applied:
        ─➤ tutoriel.catala_fr
            │
            │   définition déduction_totale
            │              ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
        Article 9
[LOG]   ≔  CalculImpôtFoyer.déduction_totale#plafonnée: 8 500,00 €
[LOG]   ☛ Definition applied:
        ─➤ tutoriel.catala_fr
            │
            │   définition impôt_foyer
            │              ‾‾‾‾‾‾‾‾‾‾‾‾
        Article 8
[LOG]   ≔  CalculImpôtFoyer.impôt_foyer#déduction: 21 500,00 €
[LOG]   ☛ Definition applied:
        ─➤ tutoriel.catala_fr
            │
            │     résultat de CalculImpôtFoyer avec {
            │     ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            │       -- individus:
            │       ‾‾‾‾‾‾‾‾‾‾‾‾‾
            │         [ Individu {
            │         ‾‾‾‾‾‾‾‾‾‾‾‾
            │             -- revenu: 15 000 €
            │             ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            │             -- nombre_enfants: 0
            │             ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            │           } ;
            │           ‾‾‾
            │           Individu {
            │           ‾‾‾‾‾‾‾‾‾‾
            │             -- revenu: 80 000 €
            │             ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            │             -- nombre_enfants: 2
            │             ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            │           } ]
            │           ‾‾‾
            │       -- territoires_outre_mer: faux
            │       ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            │       -- date_courante: |1999-01-01|
            │       ‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾‾
            │     }
            │     ‾
        Test
[LOG]   ≔  CalculImpôtFoyer.direct.
      résultat: CalculImpôtFoyer { -- impôt_foyer: 21 500,00 € }
[LOG] ←  CalculImpôtFoyer.direct
[LOG] ≔  TestFoyer.calcul: CalculImpôtFoyer { -- impôt_foyer: 21 500,00 € }

L’inspection de la trace révèle la structure du calcul qui correspond étroitement au raisonnement juridique que nous avons fait juste au-dessus pour calculer la sortie du test manuellement. Avec cet outil puissant, il est possible de déboguer et de maintenir des programmes Catala à grande échelle.

Conclusion

Félicitations pour avoir terminé le tutoriel Catala ! Les deux dernières sections n’ont pas présenté de fonctionnalités uniques à Catala, contrairement aux exceptions de la deuxième section. Au contraire, en Catala, nous utilisons les techniques classiques de génie logiciel de la programmation fonctionnelle pour diviser le code en plusieurs fonctions qui s’appellent les unes les autres au bon niveau d’ abstraction, dans le but de garder le code proche de là où il est spécifié dans la loi. Il existe différentes façons d’exprimer quelque chose en Catala, mais la proximité entre le code et la spécification juridique devrait être le critère pour ce qui est la manière idiomatique de faire les choses.

Refactoriser le code Catala en continu à mesure que de nouvelles exigences légales sont ajoutées ou mises à jour est la clé pour maintenir la base de code efficacement sur le long terme, et éviter le code spaghetti qui est courant lors de la traduction de la loi en code. Nous espérons que ce tutoriel vous a mis sur la bonne voie pour votre voyage dans Catala et le monde merveilleux de l’automatisation sûre et fidèle des dispositions légales.

Nous vous encourageons à lire les prochains chapitres de ce livre pour continuer à apprendre comment utiliser Catala, car le tutoriel n’est pas situé dans une configuration de projet de développement logiciel réel, et manque de beaucoup de conseils sur le codage en Catala mais aussi l’interaction avec les juristes.

# Corrigé du tutoriel

## Article 1

L'impôt sur le revenu pour un individu est défini comme un pourcentage fixe du
revenu de l'individu sur une année.

```catala
déclaration structure Individu:
  donnée revenu contenu argent
  donnée nombre_enfants contenu entier

déclaration champ d'application CalculImpôtRevenu:
  entrée date_courante contenu date
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  interne taux_imposition contenu décimal
  résultat impôt_revenu contenu argent

champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    individu.revenu * taux_imposition
```

## Article 2

Le pourcentage fixe mentionné à l'article 1 est égal à 20 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_2
  définition taux_imposition
  sous condition date_courante < |2000-01-01|
  conséquence égal à
    20%

  étiquette article_2
  définition taux_imposition
  sous condition date_courante >= |2000-01-01|
  conséquence égal à
    21%
```

## Article 3

Si l'individu a la charge de 2 enfants ou plus, alors le pourcentage fixe
mentionné à l'article 1 est égal à 15 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_3 exception article_2
  définition taux_imposition
  sous condition individu.nombre_enfants >= 2
  conséquence égal à
    15%
```

## Article 4

Les individus gagnant moins de 10 000 € sont exonérés de l'impôt sur le revenu mentionné
à l'article 1.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_4 exception article_3
  définition taux_imposition
  sous condition individu.revenu <= 10 000 €
  conséquence égal à
    0%
```

## Article 5

Les individus gagnant plus de 100 000 € sont soumis à un taux d'imposition de
30%, quel que soit leur nombre d'enfants.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_5 exception article_3
  définition taux_imposition
  sous condition individu.revenu > 100 000 €
  conséquence égal à
    30%
```

## Article 6

Dans les territoires d'outre-mer, le taux d'imposition pour les individus gagnant
plus de 100 000 € spécifié à l'article 5 est réduit à 25 %.

```catala
champ d'application CalculImpôtRevenu:
  étiquette article_6 exception article_5
  définition taux_imposition
  sous condition individu.revenu > 100 000 € et territoires_outre_mer
  conséquence égal à
    25%
```

## Article 7

Lorsque plusieurs individus vivent ensemble, ils sont collectivement soumis à
l'impôt sur le foyer. L'impôt sur le foyer dû est de 10 000 € par individu du foyer,
et la moitié de ce montant par enfant.

```catala
déclaration champ d'application CalculImpôtFoyer:
  entrée individus contenu liste de Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date

  résultat impôt_foyer contenu argent

champ d'application CalculImpôtFoyerIndividuel:
  définition calcul_impôt_revenu.individu égal à
    individu
  définition calcul_impôt_revenu.territoires_outre_mer égal à
    territoires_outre_mer
  définition calcul_impôt_revenu.date_courante égal à
    date_courante

  définition impôt_foyer égal à
    10 000 € * (1,0 + individu.nombre_enfants / 2)

champ d'application CalculImpôtFoyer:
  définition impôt_foyer
  égal à
    somme argent de
      transforme chaque individu parmi individus en
        (
          résultat de CalculImpôtFoyerIndividuel avec {
            -- individu: individu
            -- territoires_outre_mer: territoires_outre_mer
            -- date_courante: date_courante
          }
        ).impôt_foyer
```

## Article 8

Le montant de l'impôt sur le revenu payé par chaque individu peut être déduit de la
part de l'impôt sur le foyer due par cet individu.

```catala
déclaration champ d'application CalculImpôtFoyerIndividuel:
  entrée individu contenu Individu
  entrée territoires_outre_mer contenu booléen
  entrée date_courante contenu date

  calcul_impôt_revenu champ d'application CalculImpôtRevenu

  résultat impôt_foyer contenu argent
  résultat déduction contenu argent

champ d'application CalculImpôtFoyerIndividuel:
  définition déduction égal à
    si calcul_impôt_revenu.impôt_revenu > impôt_foyer alors impôt_foyer
    sinon calcul_impôt_revenu.impôt_revenu
```

## Test

```catala
déclaration champ d'application TestFoyer:
  résultat calcul contenu CalculImpôtFoyer

champ d'application TestFoyer:
  définition calcul égal à
    résultat de CalculImpôtFoyer avec {
      -- individus:
        [
          Individu {
            -- revenu: 15 000 €
            -- nombre_enfants: 0
          };
          Individu {
            -- revenu: 80 000 €
            -- nombre_enfants: 2
          }
        ]
      -- territoires_outre_mer: faux
      -- date_courante: |1999-01-01|
    }
```

Guide pas à pas : configurer un projet Catala

Bien que le tutoriel Catala vous initie à la programmation en Catala et aux spécificités de la traduction des exigences juridiques dans votre code, il lui manque tous les aspects d’un projet informatique au-delà de la simple écriture du code.

Plus précisément, l’équipe Catala encourage les développeurs Catala à utiliser les standards modernes de génie logiciel en ce qui concerne l’organisation et la gestion de projet. Cette section agit comme un guide pas à pas qui montre principalement comment le système de construction Catala, clerk, facilite les processus de structuration, de test et de déploiement d’un projet informatique utilisant Catala.

Ce guide est structuré séquentiellement pour imiter les différentes étapes de la création d’un nouveau projet Catala et de l’organisation de sa base de code ainsi que du travail autour de celle-ci :

• la première section explique comment organiser les fichiers sources Catala et configurer votre projet pour clerk, le système de construction de Catala ;
• la deuxième section développe la précédente pour ajouter le déploiement automatisé des artefacts générés par Catala en utilisant les différents backends du compilateur ;
• la troisième section concerne la mise en place d’une pile de génie logiciel moderne autour de la base de code, complète avec gestion de versions, tests automatisés et intégration continue (CI) ;

• la quatrième et dernière section est principalement non technique et orthogonale aux sections précédentes, elle concerne l’organisation humaine des projets Catala impliquant des juristes et des programmeurs, ainsi que les choix fondamentaux importants à faire au début du projet.

Bonne lecture !

Structure des répertoires et configuration

La première étape lors de la création de votre projet Catala est de définir la structure des répertoires et des fichiers qui contiendront votre code source. Dans cette section, nous décrirons l’organisation et la configuration d’un projet Catala contenant des fichiers de code source gérés par le système de construction clerk.

Pour commencer, nous vous encourageons vivement à mettre en place un système de gestion de versions tel que git lors de la construction de votre projet ; cette pratique est largement utilisée dans le développement logiciel et aide à suivre et maintenir les contributions à votre code.

Exemple de projet Clerk

Disons que vous avez un projet fictif qui a deux parties principales : une pour calculer les codes fiscaux et une pour les aides au logement. La hiérarchie de fichiers suivante montre un exemple de l’organisation habituelle pour un projet Catala :

mon-projet/
│   clerk.toml
├───src/
│   ├───code_impots/
│   │   │   article_121.catala_fr
│   │   │   article_132.catala_fr
│   │   │   ...
│   │
│   ├───aides_logement/
│   │   │   article_8.catala_fr
│   │   │   ...
│   │
│   └───commun/
│       │   prorata.catala_fr
│       │   foyer.catala_fr
│       │   ...
│
└───tests/
    │   test_impot_revenu.catala_fr
    │   test_aides_logement.catala_fr

Le projet est composé de plusieurs répertoires et d’un fichier de configuration de projet clerk.toml :

• src/ : contient les programmes Catala principaux. Ces programmes peuvent être davantage divisés en sous-répertoires pour séparer correctement votre processus de développement. Le sous-répertoire src/commun/, ici, contient certaines structures de données et utilitaires qui sont partagés par les deux autres composants.
• tests/ : contient les tests dédiés de vos programmes Catala. Afin de ne pas encombrer votre logique avec des tests parasites, il est conseillé de créer des fichiers spécifiques et séparés contenant vos tests pour chaque module source.
• clerk.toml : le fichier de configuration d’un projet clerk.

Avoir un tas de fichiers de code source Catala (correctement déclarés comme modules) stockés dans les sous-répertoires du projet n’est pas encore suffisant pour que clerk trouve ses marques et sache quoi faire. Vous devez le guider avec un fichier de configuration déclaratif, clerk.toml.

Le fichier de configuration clerk.toml

Ce fichier est utilisé pour configurer comment et ce que l’outil clerk est censé construire et exécuter. Ce fichier de configuration doit être écrit au format de configuration TOML. Voici un exemple de ce à quoi il devrait ressembler pour notre projet fictif (les commentaires sont préfixés par le caractère #) :

[project]
include_dirs = [ "src/commun",              # Quels répertoires inclure
                 "src/code_impots",         # lors de la recherche de modules Catala
                 "src/aides_logement" ]     # et de dépendances.
build_dir    = "_build"    # Définit où sortir les fichiers compilés générés.
target_dir   = "_target"   # Définit où sortir les fichiers finaux des cibles.

# Chaque section [[target]] décrit une cible de construction pour le projet

[[target]]
name     = "code-impots-us"                       # Le nom de la cible
modules  = [ "Article_121", "Article_132", ... ]  # Composants modules
tests    = [ "tests/test_impot_revenu.catala_fr" ] # Test(s) associé(s)
backends = [ "c", "java" ]                        # Backends de langage de sortie

[[target]]
name     = "aides-logement"
modules  = [ "Article_8", ... ]
tests    = [ "tests/test_aides_logement.catala_fr" ]
backends = [ "ocaml", "c", "java" ]

Cet exemple de fichier clerk.toml décrit d’abord deux éléments de configuration à l’échelle du projet (sous la section [project]) :

• dans quels répertoires clerk doit chercher les fichiers sources Catala lorsqu’il essaie de trouver des modules et des dépendances ;
• où sortir les fichiers compilés générés lors de la construction du projet et de ses cibles.

Les options build_dir et target_dir ont déjà pour valeur par défaut "_build" et "_target" lorsqu’elles sont absentes, donc, ici elles peuvent être omises en toute sécurité.

Ensuite, le fichier de configuration définit deux composants [[target]]. Une cible dans un projet Catala est un ensemble de modules Catala qui seront compilés vers un ou plusieurs langages de programmation cibles, créant des bibliothèques sources prêtes à l’emploi que vous pouvez ensuite importer et distribuer à d’autres applications dans votre système informatique.

Par exemple, la première cible est nommée "code-impots-us" (vous pouvez la choisir comme vous le souhaitez) et empaquettera toutes les structures de données déclarées et les champs d’application définis dans les modules donnés et leurs dépendances. Nous associons également des fichiers (ou répertoires) de tests spécifiques liés à cette cible afin que nous puissions les exécuter isolément si nécessaire. Enfin, nous définissons les backends de langage que cette cible doit générer. Dans notre premier exemple, nous avons configuré la cible pour traduire notre code en tant que bibliothèque C et en tant que paquet Java.

Veuillez vous référer à la référence complète de clerk.toml pour une liste exhaustive des options de configuration et de leurs valeurs possibles.

Maintenant que nous avons nos fichiers sources bien disposés dans leurs répertoires appropriés, ainsi qu’un fichier de configuration de projet, nous détaillerons dans la section suivante comment construire et déployer les livrables pour le projet.

Construction et déploiement du projet

Dans la section précédente, nous avons défini un répertoire contenant un projet Catala avec un fichier de configuration clerk.toml qui contenait deux cibles principales (code-impots-us et aides-logement) que nous visons à construire et exporter en tant que bibliothèques sources dans différents langages.

[project]
include_dirs = [ "src/commun",              # Quels répertoires inclure
                 "src/code_impots",         # lors de la recherche de modules Catala
                 "src/aides_logement" ]     # et de dépendances.
build_dir    = "_build"    # Définit où sortir les fichiers compilés générés.
target_dir   = "_target"   # Définit où sortir les fichiers finaux des cibles.

# Chaque section [[target]] décrit une cible de construction pour le projet

[[target]]
name     = "code-impots-us"                       # Le nom de la cible
modules  = [ "Article_121", "Article_132", ... ]  # Composants modules
tests    = [ "tests/test_impot_revenu.catala_fr" ] # Test(s) associé(s)
backends = [ "c", "java" ]                        # Backends de langage de sortie

[[target]]
name     = "aides-logement"
modules  = [ "Article_8", ... ]
tests    = [ "tests/test_aides_logement.catala_fr" ]
backends = [ "ocaml", "c", "java" ]

mon-projet/
│   clerk.toml
├───src/
│   ├───code_impots/
│   │   │   article_121.catala_fr
│   │   │   article_132.catala_fr
│   │   │   ...
│   │
│   ├───aides_logement/
│   │   │   article_8.catala_fr
│   │   │   ...
│   │
│   └───commun/
│       │   prorata.catala_fr
│       │   foyer.catala_fr
│       │   ...
│
└───tests/
    │   test_impot_revenu.catala_fr
    │   test_aides_logement.catala_fr

Construire le projet

Maintenant que vous avez tout configuré, vous pouvez construire le projet, ce qui signifie compiler les fichiers de code source Catala dans les différents langages de programmation cibles. C’est le travail de la commande clerk build :

$ clerk build
┌─[RESULT]─
│ Build successful. The targets can be found in the following files:
│     [code-impots-us] → _targets/code-impots-us
│     [aides-logement] → _targets/aides-logement
└─

La sortie de la commande vous montre où trouver les résultats. Chaque section [[target]] produit un sous-répertoire dans le répertoire _targets/, avec les artefacts de compilation à l’intérieur. Dans notre exemple, cela pourrait ressembler à ceci :

_targets/
├───code-impots-us/
│   ├───c/
│   │   │   Article_121.c
│   │   │   Article_121.h
│   │   │   Article_121.o
│   │   │   ...
│   │
│   ├───java/
│   │   │   Article_121.java
│   │   │   Article_121.class
│   │   │   ...
│   aides-logement/
│   │   ...

Déployer le code généré

Maintenant que tout est correctement construit dans les différents backends, il est temps de les intégrer ! Le but de Catala est de fournir des bibliothèques sources prêtes à l’emploi dans un langage de programmation cible ; Catala ne crée pas une application complète pour vous. Par conséquent, vous prenez généralement ce que Catala construit et l’intégrez dans un autre projet existant.

À partir de ce point, le déploiement nécessite un peu de travail manuel car il dépend des spécificités de vos cas d’utilisation. Fondamentalement, c’est à vous de copier les artefacts dans _targets vers votre autre projet, de les compiler et de les lier à votre base de code existante.

Par exemple, si vous souhaitez intégrer le programme Catala dans le cadre d’une application Java, vous devrez copier les fichiers sources Java générés depuis le répertoire _target/<nom_cible>/java/ vers un sous-répertoire de votre projet Java, et mettre à jour votre configuration Maven pom.xml en conséquence afin que Maven puisse construire les fichiers sources générés par Catala.

Appeler les fonctions générées dans les langages de programmation cibles

Illustrons avec un exemple. Considérez ce programme Catala très simple :

> Module ImpotSimple

```catala
déclaration champ d'application CalculImpotRevenu:
  entrée revenu contenu argent
  résultat impot_revenu contenu argent

champ d'application CalculImpotRevenu:
  définition impot_revenu égal à revenu * 10%
```

Avec sa version compilée en Java :

/* This file has been generated by the Catala compiler, do not edit! */

import catala.runtime.*;
import catala.runtime.exception.*;

public class Test {

    public static class CalculImpotRevenu implements CatalaValue {

        final CatalaMoney impot_revenu;

        CalculImpotRevenu (final CatalaMoney revenu_in) {
            final CatalaMoney revenu = revenu_in;
            final CatalaMoney
                impotRevenu = revenu.multiply
                             (new CatalaDecimal(new CatalaInteger("1"),
                                                new CatalaInteger("5")));
            this.impot_revenu = impotRevenu;
        }

        static class CalculImpotRevenuOut {
            final CatalaMoney impot_revenu;
            CalculImpotRevenuOut (final CatalaMoney impot_revenu) {
                this.impot_revenu = impot_revenu;
            }
        }

        CalculImpotRevenu (CalculImpotRevenuOut result) {
            this.impot_revenu = result.impot_revenu;
        }

        @Override
        public CatalaBool equalsTo(CatalaValue other) {
          if (other instanceof CalculImpotRevenu v) {
              return this.impot_revenu.equalsTo(v.impot_revenu);
          } else { return CatalaBool.FALSE; }
        }

        @Override
        public String toString() {
            return "impot_revenu = " + this.impot_revenu.toString();
        }
    }

}

Si vous inspectez le fichier généré, vous remarquerez que les champs d’application Catala seront traduits en classe Java (et en fonctions en C ou Python). Les calculs de champ d’application sont effectués dans le constructeur de la classe. Par conséquent, pour exécuter le champ d’application, nous devons instancier cette classe et récupérer le résultat.

De plus, pour chaque backend, il existe une version dédiée du runtime Catala. Ce composant est nécessaire pour la compilation et l’exécution des programmes Catala générés. Les runtimes décriront les types et structures de données Catala, les erreurs spécifiques ainsi qu’une API pour les manipuler depuis les langages ciblés. Les fichiers pour le runtime devraient être inclus dans le _targets/<nom-cible> ; vous pouvez également les copier dans votre projet et référencer leurs types et fonctions depuis votre application.

En mettant tout cela ensemble, voici par exemple un programme Java simple qui exécute notre champ d’application :

import catala.runtime.CatalaMoney;

class Main {
    public static void main(String[] args){
        CatalaMoney revenu_entree = CatalaMoney.ofCents(50000*100);
        CalculImpotRevenu resultat = new CalculImpotRevenu(revenu_entree);
        CatalaMoney impot_resultat = resultat.impot_revenu;
        System.out.println("Impôt sur le revenu : " + impot_resultat);
    }
}

Comme mentionné, les runtimes Catala offrent une API pour construire les valeurs spécifiques à Catala, par exemple, la méthode statique java CatalaMoney.ofCents qui construit une valeur CatalaMoney équivalente à une valeur de type argent. Seul le ciel est la limite ensuite quant à ce que vous pouvez construire !

Dans cette section, nous avons vu comment construire un projet, l’exporter et l’intégrer dans une application existante. Dans la section suivante, nous plongerons dans les tests de Catala et la mise en place de l’intégration continue.

Processus de test et d’intégration continue

Dans la section précédente, nous avons défini un répertoire contenant un projet Catala avec un fichier de configuration clerk.toml qui contenait deux cibles principales (code-impots-us et aides-logement), que nous avons appris à compiler et déployer en C et Java. Maintenant, assurons-nous que le code déployé est correct et pratiquons un peu de développement piloté par les tests !

[project]
include_dirs = [ "src/commun",              # Quels répertoires inclure
                 "src/code_impots",         # lors de la recherche de modules Catala
                 "src/aides_logement" ]     # et de dépendances.
build_dir    = "_build"    # Définit où sortir les fichiers compilés générés.
target_dir   = "_target"   # Définit où sortir les fichiers finaux des cibles.

# Chaque section [[target]] décrit une cible de construction pour le projet

[[target]]
name     = "code-impots-us"                       # Le nom de la cible
modules  = [ "Article_121", "Article_132", ... ]  # Composants modules
tests    = [ "tests/test_impot_revenu.catala_fr" ] # Test(s) associé(s)
backends = [ "c", "java" ]                        # Backends de langage de sortie

[[target]]
name     = "aides-logement"
modules  = [ "Article_8", ... ]
tests    = [ "tests/test_aides_logement.catala_fr" ]
backends = [ "ocaml", "c", "java" ]

mon-projet/
│   clerk.toml
├───src/
│   ├───code_impots/
│   │   │   article_121.catala_fr
│   │   │   article_132.catala_fr
│   │   │   ...
│   │
│   ├───aides_logement/
│   │   │   article_8.catala_fr
│   │   │   ...
│   │
│   └───commun/
│       │   prorata.catala_fr
│       │   foyer.catala_fr
│       │   ...
│
└───tests/
    │   test_impot_revenu.catala_fr
    │   test_aides_logement.catala_fr

Mise en place des tests

Nous encourageons les développeurs Catala à écrire beaucoup de tests dans leurs projets ! Bien que vous puissiez écrire des tests n’importe où dans vos fichiers de code source Catala, nous vous conseillons de les regrouper dans un dossier tests à la racine de votre projet, avec des fichiers spécifiques remplis de tests pour un module spécifique dans src, par exemple.

Qu’est-ce qu’un test ?

En Catala, un test est un champ d’application sans variables d’entrée, qui appelle le champ d’application ou la fonction que vous voulez tester avec des entrées codées en dur. Par exemple, imaginez que l’un de vos fichiers src, src/impot_revenu.catala_fr, contient la déclaration de champ d’application suivante (adaptée et étendue de plus tôt)

> Module Impot_revenu

```catala
déclaration énumération Declaration:
  -- Individuelle
  -- Conjointe contenu date

déclaration champ d'application CalculImpotRevenu:
  entrée revenu contenu argent
  entrée nombre_enfants contenu entier
  entrée declaration contenu Declaration

  résultat impot_revenu contenu argent
```

Ensuite, dans le fichier tests/tests_impot_revenu.catala_fr, vous pouvez écrire un test pour le champ d’application CalculImpotRevenu. Bien qu’il n’y ait pas de format contraint pour les tests en Catala, nous recommandons que vous suiviez ce modèle :

> Usage de Impot_revenu

```catala
# D'abord, déclarez votre test
déclaration champ d'application TestImpotRevenu1: # Vous pouvez choisir n'importe quel nom pour votre test
  résultat calcul contenu Impot_revenu.CalculImpotRevenu # Mettez ici le champ d'application que vous voulez tester

# Ensuite, remplissez les entrées de votre test
champ d'application TestImpotRevenu1:
  définition calcul égal à
    résultat de Impot_revenu.CalculImpotRevenu avec {
      # Les entrées de ce test pour CalculImpotRevenu sont ci-dessous :
      -- revenu: 20 000 €
      -- nombre_enfants: 2
      -- declaration: Conjointe contenu |1998-04-03|
    }
```

Ce test est maintenant un programme valide. Vous pouvez l’exécuter avec :

$ clerk run tests/tests_impot_revenu.catala_fr --scope=TestImpotRevenu1
┌─[RESULT]─ TestImpotRevenu1 ─
│ calcul =
│   Impot_revenu.CalculImpotRevenu {
│     -- impot_revenu: 5 000,00 €
│   }
└─

Maintenant, ce test devrait indiquer quelles sont les sorties attendues, à comparer avec les sorties calculées. Il y a des façons de le faire avec Catala, selon ce qui convient le mieux à votre cas d’utilisation. Le point de départ pour les deux méthodes est exactement ce que nous avons décrit juste au-dessus. Les deux méthodes sont supportées par le système de test de Catala, accessible via la commande clerk test.

Test par assertion

Une façon de vérifier le résultat calculé est d’affirmer qu’il doit être égal à une valeur attendue, en utilisant les assertions de Catala. Pour enregistrer un test par assertion dans clerk test, mettez simplement l’attribut #[test] à la déclaration du champ d’application de test. Par exemple, voici notre exemple de test configuré comme un test par assertion :

#[test]
déclaration champ d'application TestImpotRevenu1:
  résultat calcul contenu CalculImpotRevenu

champ d'application TestImpotRevenu1:
  définition calcul égal à
    résultat de CalculImpotRevenu avec {
      # Les entrées de ce test pour CalculImpotRevenu sont ci-dessous :
      -- revenu: 20 000 €
      -- nombre_enfants: 2
      -- declaration: Conjointe contenu |1998-04-03|
    }
  assertion (calcul.impot_revenu = 5 000 €)

Bien sûr, l’assertion peut être aussi complexe que vous le souhaitez. Vous pouvez vérifier le résultat de manière exhaustive ou partielle, vérifier si une propriété dépendant de l’entrée est satisfaite, etc. Au moment du test, clerk test vérifiera seulement si toutes les assertions que vous avez définies sont valides.

Test Cram

La deuxième façon de vérifier le résultat attendu d’un calcul est simplement de vérifier la sortie textuelle de l’exécution de la commande dans le terminal. C’est appelé test cram. Pour activer les tests cram dans Catala, vous devez spécifier :

1. quelle est la commande que vous voulez tester ;
2. quelle devrait être la sortie attendue du terminal.

Les tests Cram sont directement intégrés dans les fichiers de code source Catala, sous la forme d’un bloc de code Markdown ```catala-test-cli. À l’intérieur, vous spécifiez quelle commande tester après l’invite $ catala .... Par exemple, la commande interpret --scope=TestImpotRevenu1 est équivalente à l’exécution de clerk run --scope=TestImpotRevenu1. Ensuite suit un verbatim du résultat attendu tel qu’il est craché par l’exécution de la commande sur le terminal.

Par exemple, voici comment créer un test cram à partir de notre exemple CalculImpotRevenu ci-dessus :

```catala
déclaration champ d'application TestImpotRevenu1:
  résultat calcul contenu CalculImpotRevenu

champ d'application TestImpotRevenu1:
  définition calcul égal à
    résultat de CalculImpotRevenu avec {
      # Les entrées de ce test pour CalculImpotRevenu sont ci-dessous :
      -- revenu: 20 000 €
      -- nombre_enfants: 2
      -- declaration: Conjointe contenu |1998-04-03|
    }
```

```catala-test-cli
$ catala interpret --scope=TestImpotRevenu1
┌─[RESULT]─ TestImpotRevenu1 ─
│ calcul =
│   Impot_revenu.CalculImpotRevenu {
│     -- impot_revenu: 5 000,00 €
│   }
└─
```

clerk test récupérera les blocs ```catala-test-cli , exécutera la commande à l’intérieur, et comparera la sortie avec la sortie attendue.

Rappelez-vous qu’au-delà de interpret, vous pouvez mettre n’importe quelle commande Catala acceptable sur un test cram. Voir la référence pour plus de détails.

Exécuter les tests et obtenir des rapports

Simple : exécutez simplement clerk test ! Par défaut, il scannera tout votre projet à la recherche de #[test] ou ```catala-test-cli dans vos fichiers, exécutera le test, vérifiera la sortie attendue. Si tout est bon, vous obtiendrez dans votre terminal un rapport comme :

┏━━━━━━━━━━━━━━━━━━━━━━━━━  ALL TESTS PASSED  ━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃                                                                       ┃
┃             FAILED     PASSED      TOTAL                              ┃
┃   files          0         34         34                              ┃
┃   tests          0        245        245                              ┃
┃                                                                       ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛

Bien sûr, les nombres dépendent du nombre de tests et de fichiers de test qu’il y a dans votre projet (ne vous inquiétez pas s’ils sont plus bas pour vous).

Si un #[test] basé sur une assertion échoue, vous obtiendrez un rapport supplémentaire imprimant pourquoi l’assertion a échoué, avec la commande exacte que vous pouvez exécuter pour reproduire l’ échec :

■ scope Test TestImpotRevenu1
  $ catala interpret -I code_impots --scope=TestImpotRevenu1
    tests/tests_impot_revenu.catala_fr:34 Assertion failed: 5 000,00 € = 4 500,00 €

Les tests cram échoués produiront également un rapport détaillé avec un diff entre la sortie attendue et calculée du terminal.

Pipelines CI

Maintenant que vous avez appris à déclarer vos tests, à les exécuter et à lire les rapports, vous êtes prêt pour le développement piloté par les tests en local. Mais le génie logiciel moderne nécessite une vérification par un tiers des tests avant que le code ne soit fusionné dans la base de code principale. C’est l’un des objectifs des configurations d’intégration continue, et nous discuterons ici de la façon de les mettre en place avec Catala.

Images Docker

Une configuration d’intégration continue commence généralement par le déploiement d’une machine virtuelle ou d’un conteneur basé sur le cloud équipé de toutes les dépendances nécessaires pour construire votre code et exécuter vos tests.

$ docker pull registry.gitlab.inria.fr/catala/ci-images:latest

Workflow d’intégration continue

Maintenant, cette étape dépend de ce que vous utilisez comme forge de développement logiciel. De nos jours, toutes ont un moyen de déclarer des pipelines déclenchés lors de certains événements (commits sur une branche, sur une PR, sur une fusion, etc). Ces pipelines lancent des exécuteurs qui exécutent certaines commandes, généralement pour exécuter le test ou construire un artefact.

Ce guide ne vous apprendra pas comment écrire ces fichiers de pipeline, veuillez vous référer à la documentation de votre forge logicielle. Cependant, pour vous donner une idée rapide, voici un exemple de fichier de workflow GitHub Actions pour les projets hébergés sur Github pour notre exemple de projet Catala :

name: CI

on:
  push:

jobs:
  tests:
    name: Test suite and build
    container:
      image: registry.gitlab.inria.fr/catala/ci-images:latest-c
      options: --user root
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Run test suite with the Catala interpreter and backends
        run: opam exec -- clerk ci

Le opam exec est important car clerk est installé via opam et la chaîne d’outils logicielle OCaml dans les images CI.

Récupérer les artefacts et les déployer

À l’intérieur de votre pipeline CI, après une exécution de clerk ci ou clerk build, vous devriez trouver le code source généré pour chaque backend de chaque cible à l’intérieur du dossier _targets (rappelez-vous la section précédente du guide). À partir de là, vous pouvez personnaliser votre fichier de pipeline pour récupérer l’artefact, l’empaqueter comme vous le souhaitez, le transférer vers un autre dépôt, construire une application plus grande qui l’intègre, etc.

Conclusion

Merci d’avoir suivi ce guide ! Nous espérons qu’il vous met sur la voie d’un projet Catala réussi. Veuillez lire la référence clerk pour plus d’informations sur ce que notre système de construction peut faire pour vous aider.

Développement agile avec juristes et programmeurs

À ce stade du guide, vous devriez avoir configuré l’environnement technique du projet et être prêt à commencer à développer en Catala. Mais même si ce n’est pas le cas, et avant de commencer à traduire votre premier texte juridique en code, vous devriez également mettre en place une organisation et une méthodologie appropriées pour vous assurer que vos efforts de traduction sont aussi productifs que possible, et conduisent au code avec le moins de bugs possible du premier coup. Cette section fournit des conseils et des justifications pour certaines des décisions de projet les plus importantes que vous aurez à prendre. De plus, elle donne des indications pratiques sur la façon d’ adapter la méthodologie agile de programmation à la tâche de traduire la loi en code, ce qui nécessite une culture de sécurité avant tout et un environnement organisationnel.

Pourquoi vous devriez éviter d’écrire des documents de spécification intermédiaires

Un trope courant des grandes organisations chargées d’automatiser la prise de décision basée sur des spécifications juridiques est de produire divers documents textuels servant de “spécifications” qui se situent entre les textes juridiques sources et le code exécutable automatisant les décisions.

Maintenant, chaque document s’appuie sur le précédent en allant plus en détail et en prenant de plus en plus de micro-décisions sur la façon dont la prestation doit être calculée. Ces micro-décisions sont cruciales et elles doivent être prises à chaque niveau avec le bon niveau de responsabilité quant aux effets de ces décisions sur les futurs bénéficiaires de la prestation.

Mais chaque étape de production d’un nouveau document à partir du précédent, et son envoi à une nouvelle équipe de personnes, augmente le risque d’erreurs et de malentendus, dans un véritable jeu de téléphone arabe administratif. Généralement, ces erreurs et malentendus sont constamment résolus par de longs appels téléphoniques entre les différentes équipes de votre agence au sujet des documents qu’ils viennent d’envoyer. Ces appels téléphoniques conduisent à beaucoup de prises de décision qui ne laissent souvent aucune trace écrite. Accumulée au fil du temps, cette méthodologie de travail conduit à des spécifications dont les règles ne peuvent pas être retracées à une base légale dans la loi et le décret, et qui risquent de diverger ou même de contredire les instructions du département juridique de votre propre agence. Cela nuit à l’efficacité interne et rend impossible la satisfaction du cadre juridique pour la prise de décision automatisée qui impose des normes de transparence strictes.

Plus globalement, la complexité des processus requis pour traduire les exigences légales en code exécutable pour la prise de décision automatisée est la cible du mouvement “Rules as Code” promu par l’ OCDE. Le but ultime de “Rules as Code” est de réduire toutes les étapes du processus décrit ci-dessus et de publier directement la loi et les décrets sous forme de code exécutable. Bien que l’on puisse penser que Catala permet directement cet objectif ultime, l’équipe Catala ne pense pas que ce soit souhaitable, étant donné les impacts considérables que cela aurait sur l’État de Droit.

Au lieu de cela, l’équipe Catala recommande d’utiliser Catala pour fusionner les deux dernières étapes du processus et fusionner dans le fichier de code source Catala à la fois le code exécutable, et tous les textes qui fournissent la base légale pour votre agence. Le reste de cette page expliquera plus concrètement comment y parvenir.

Pourquoi vous devriez choisir les textes juridiques pour la programmation littéraire en Catala

Comme expliqué ci-dessus, généralement les programmeurs ne se réfèrent qu’aux spécifications lorsqu’ils écrivent leur code, et non aux textes juridiques dont les spécifications ont été dérivées. Par conséquent, il serait logique à première vue d’utiliser simplement les spécifications comme point de départ de la programmation littéraire. Bien que ce soit techniquement possible, l’équipe Catala ne le recommanderait pas car cela empêche l’effort de réécriture vers Catala de reconstruire la chaîne de justifications des micro-choix du texte juridique au code exécutable.

En effet, tout l’intérêt de la programmation littéraire est de fusionner dans un seul document à la fois le code et l’explication de pourquoi le code fonctionne de cette façon. Appliqué à Catala, la programmation littéraire signifie que l’explication de pourquoi le code fonctionne de cette façon doit contenir la base légale de son comportement, donc les textes juridiques.

De plus, utiliser les textes juridiques dans la programmation littéraire au lieu des spécifications accélère considérablement la maintenance du code. En effet, chaque fois qu’il y a une mise à jour dans les textes juridiques, il suffit de propager la mise à jour à la copie du texte juridique dans le fichier Catala (un processus qui peut être automatisatisé), et ensuite de mettre à jour (manuellement) les extraits de code qui se trouvent juste en dessous des textes juridiques mis à jour. La connaissance de quel morceau de code correspond à quelle partie du texte juridique est explicite, ce qui le rend plus robuste au changement de personnel ou à la perte de mémoire institutionnelle. Comparez cela avec le processus traditionnel de mise à jour de la spécification, puis de mise à jour du code : le rédacteur de la spécification et le rédacteur du code (généralement deux personnes différentes) doivent se rappeler quelle partie du document qu’ils écrivent correspond aux parties mises à jour du document qu’ils reçoivent.

Globalement, utiliser les textes juridiques pour la programmation littéraire Catala assure la cohérence de la documentation pour les choix interprétatifs, ainsi que la robustesse et l’efficacité des futures mises à jour du code.

champ d'application RevenuBrutVersNetIndividuel:
  # Une lecture littérale de l'article 364 impliquerait de mettre 10 000 € ici. Mais
  # en fait, l'instruction de l'agence N°1045-58 publiée le 28/04/2023 précise
  # que le plafond est estimé au niveau du foyer et non au niveau individuel.
  # Pour concilier avec la vue individuelle de l'article 364, le plafond ici devrait
  # être un prorata du plafond du foyer par rapport au revenu de chaque
  # individu. Nous supposons que ce prorata est fourni comme variable d'entrée
  # "plafond_deduction_prorata" du champ d'application "RevenuBrutVersNetIndividuel".
  définition deduction_revenu état plafonnement égal à
    plafond_deduction_prorata

# Maintenant nous devons calculer "plafond_deduction_prorata" du champ d'application
# "RevenuBrutVersNetIndividuel", au niveau du foyer. Mais en fait, un mémo interne
# envoyé par le département juridique au département informatique le 05/09/2023 précise
# en outre que le plafond au niveau du foyer ne devrait être proratisé que si la somme
# des revenus des individus dans le foyer est supérieure au plafond.
# Sinon, chaque individu devrait voir comme son plafond individuel le plafond de
# tout le foyer. C'est équivalent car si la somme des revenus est inférieure au
# plafond, alors l'opération de plafonnement n'aura aucun effet.
champ d'application RevenuBrutVersNetFoyer:
  # ...

Recruter une équipe mêlant programmation et connaissances du domaine

Pour cette raison, l’équipe Catala conseille d’avoir un mélange équilibré entre des personnes qui peuvent écrire du bon code (généralement des ingénieurs logiciels) et des personnes qui peuvent comprendre ce que la loi signifie et l’interpréter (généralement des juristes mais pas toujours, comme nous le verrons) au sein de votre équipe pluridisciplinaire. Ce mélange égal implique que vous pouvez organiser l’équipe en paires de personnes : un juriste et un programmeur. Vous pouvez augmenter l’effort de développement en augmentant le nombre de paires dans votre équipe qui peuvent être affectées à des parties indépendantes du calcul.

Nous verrons ci-dessous comment les programmeurs et les juristes passent leur temps au cours d’une semaine typique. Mais d’abord, parlons de quel type de “juristes” nous parlons dans nos équipes pluridisciplinaires. Le mot “juristes” fait généralement référence aux avocats, c’est-à-dire aux personnes défendant des individus et des entreprises devant les tribunaux lors d’un procès. Mais les agences administratives emploient très peu de ce type de juristes, et ces personnes ne sont dévouées qu’à la gestion des procès dans lesquels l’agence est impliquée. Au lieu de cela, les agences administratives emploient généralement un bon nombre de personnes formellement formées en Droit à l’université dans leur département juridique central, chargées d’identifier et de surveiller tous les textes juridiques auxquels l’ agence doit se conformer. Ces “juristes” rédigent ensuite généralement les instructions officielles de l’agence qui paraphrasent le texte juridique, tout en prenant en compte les décisions de justice passées et la doctrine officielle de l’agence. Cela correspond à l’étape 3. du processus en V décrit plus haut dans cette page.

Ensuite, l’étape 4. du processus implique encore d’autres interprétations de la loi. Mais cette fois, c’est souvent fait par des personnes qui n’ont pas de formation universitaire formelle en droit, et qui ne s’appellent pas “juristes”. Cependant, ces personnes ont une connaissance étendue et spécialisée du contenu juridique en question, basée sur des décennies d’expérience antérieure dans leurs postes, ou en tant que travailleurs sociaux de terrain au sein de l’agence. Parfois, ces personnes n’ont jamais vu les textes juridiques pour la prestation ou l’impôt dans lequel elles sont spécialisées, elles n’ont jamais lu que les instructions officielles de l’agence rédigées par le département juridique interne. L’équipe Catala appelle ces personnes les “experts du domaine”, et ils sont aussi cruciaux que les “juristes” pour s’assurer que la chaîne entre la base légale et le code exécutable est pleinement justifiée dans un fichier de code source Catala.

Par conséquent, l’équipe Catala recommande d’inclure un mélange d’“experts du domaine” et de “juristes” de type département juridique au sein de votre équipe aux côtés des ingénieurs logiciels. C’est la combinaison du point de vue de la théorie juridique avec l’expérience de la pratique de cette loi dans l’agence qui est la clé pour atteindre la cohérence du logiciel écrit en Catala avec à la fois les systèmes existants qu’il est censé remplacer et la doctrine juridique officielle de l’agence à laquelle il est censé se conformer.

Emploi du temps hebdomadaire : sessions de programmation en binôme et devoirs

Une fois que vous avez assemblé votre équipe selon les principes énoncés ci-dessus, vous devrez définir des tâches pour chacune de vos paires juriste-programmeur. Pour chaque morceau de travail (que ce soit l’implémentation d’une certaine section d’un statut ou d’un certain champ d’application prédéterminé comme important dans le calcul), le travail doit suivre une boucle itérative composée des étapes suivantes :

1. Identifier les sources juridiques et les instructions et mémos de l’agence justifiant le morceau de calcul ;
2. Les copier-coller dans un fichier de code source Catala et échafauder la structure de données et les déclarations de champ d’application ;
3. Travailler linéairement à travers les sources juridiques, en s’assurant de mettre le code Catala aussi près que possible de la source juridique qui le justifie ;
4. Pendant le travail d’implémentation, des tâches de refactorisation de code et des questions de recherche juridique surviendront inévitablement ;
5. Les traiter en itérant vers les étapes précédentes de cette boucle ;
6. Vous avez terminé quand plus aucune nouvelle tâche de refactorisation ou question de recherche juridique ne survient !

En suivant les boucles précédentes, le programmeur et le juriste de la paire seront occupés à temps plein pendant une semaine typique. L’organisation de la semaine pour les deux devrait être centrée autour d’une session hebdomadaire de programmation en binôme de 2 à 3 heures, avec le schéma suivant :

• avant la session de programmation en binôme, le juriste doit envoyer au programmeur les listes de textes juridiques à prendre en compte pour le morceau de travail actuel ;
• sur cette base, le programmeur doit écrire un échafaudage initial de structure de données et de déclarations de champ d’application à utiliser pendant la session de programmation en binôme ;
• le juriste doit également rechercher préventivement les décisions de justice pertinentes et les documents de doctrine de l’agence avant la session de programmation en binôme ;
• un ordre du jour est communément fixé par le juriste et le programmeur pour la session de programmation en binôme à venir, priorisant les tâches à accomplir ;
• pendant la session de programmation en binôme, le juriste et le programmeur doivent discuter du texte de loi et essayer d’esquisser ou d’implémenter entièrement des extraits de code Catala (généralement des définitions de variables de champ d’application) ;
• ils doivent également noter dûment toute tâche de refactorisation ou question de recherche juridique qui survient pendant la session comme tâches à faire ;
• ces tâches à faire doivent occuper à la fois le juriste et le programmeur après la session de programmation en binôme et avant la suivante ;
• de plus, le juriste doit préparer de manière asynchrone des cas de test que le programmeur (ou le juriste) peut implémenter et ajouter à la base de tests pour l’intégration continue ;
• une fois terminé, le morceau de travail est matérialisé sous forme de proposition de fusion (merge request) complète avec implémentation et tests, à examiner à la fois juridiquement et informatiquement par une autre paire juriste-programmeur.

Si tout cela ne remplit pas la semaine de travail, le programmeur peut travailler en plus sur des tâches de programmation liées au déploiement du projet tandis que le juriste peut travailler à la rédaction de mémos internes documentant l’avancement du projet et comment les décisions qu’ils ont prises en programmant sont conformes à la doctrine de l’ agence.

Suivi des progrès et planification du travail

Globalement, vous savez que vous réimplémenterez un certain calcul d’impôt ou de prestation, mais comment diviser le travail en tâches et les distribuer aux paires ?

Pour la gestion de projet au jour le jour, l’équipe Catala vous conseille de faire plein usage des plateformes de génie logiciel comme Github, Gitlab ou Jira. Non seulement les tâches de codage peuvent être modélisées et suivies comme des tickets et des pull requests sur ces plateformes, mais les tâches juridiques peuvent également être modélisées et suivies comme des tickets. En particulier, l’équipe Catala a noté qu’il est très utile de mettre toutes les tâches à faire collectées à la fin d’une session de programmation en binôme sous la forme de tickets dans la plateforme. Ensuite, l’avancement du projet peut être suivi avec des tableaux de tickets, des listes et une estimation du temps comme un projet logiciel standard.

Vous pouvez également utiliser des étiquettes de tickets pour marquer les questions juridiques qui ont été recherchées ou validées par le département juridique de l’agence. Étiqueter les tickets facilite la planification de l’ordre du jour de la prochaine session de programmation en binôme et le tri entre les tâches qui nécessitent encore des recherches ou une validation supplémentaires, et celles qui peuvent être implémentées en code Catala tout de suite.

FAQ: Comment coder la loi?

Après avoir installé Catala, suivi le tutoriel et configuré votre projet, vous devriez être prêt à lancer votre projet de transformation de la loi en code. Cependant, il se peut que vous ayez encore des questions. Ce chapitre vise à répondre aux questions fréquentes que se posent les utilisateurs, à la fois en général et spécifiques à Catala.

Questions générales

Qu’est-ce que la programmation en binôme pour coder la loi ?

Comme l’explique l’introduction de ce livre, Catala est conçu pour être utilisé par des équipes possédant à la fois une expertise juridique et informatique. La programmation en binôme fait généralement référence à deux programmeurs travaillant ensemble côte à côte sur le même ordinateur pour écrire du code informatique. La programmation en binôme pour coder la loi n’implique pas deux programmeurs ayant des compétences similaires, mais plutôt un programmeur et un juriste, des personnes ayant des domaines d’expertise différents, travaillant côte à côte pour écrire un code informatique qui capture aussi précisément que possible le sens de la loi. La programmation en binôme avec un juriste et un programmeur permet d’encoder la loi sans qu’une seule personne ait besoin d’être experte à la fois en droit fiscal et en codage. La programmation en binôme améliore également la qualité du code car elle exige que le juriste explique la loi très clairement, si clairement qu’un programmeur puisse la comprendre, et elle exige que le programmeur soit capable d’articuler exactement comment le code informatique correspond à la loi, améliorant ainsi la précision et l’attention aux détails tant pour la loi que pour le code.

Qu’est-ce que la programmation littéraire pour coder la loi ?

La programmation littéraire est l’idée, avancée pour la première fois par Donald Knuth, qu’un programme informatique ne communique pas seulement à un ordinateur ce qu’il doit faire, mais communique aussi aux humains lisant le programme ce que le programme veut que l’ordinateur fasse. Concrètement, les programmes qui suivent l’approche de la programmation littéraire incluent beaucoup de commentaires. La programmation littéraire est particulièrement importante pour coder la loi, car elle augmente la transparence et montre clairement comment le code correspond (ou ne correspond pas) à la loi. Comme expliqué dans la première section du tutoriel, la programmation littéraire pour la loi en Catala signifie que le code Catala inclut non seulement le code qui dit à l’ordinateur quoi faire, mais aussi le langage législatif ou réglementaire réel qui se rapporte au code pour l’ordinateur. Cela facilite la mise à jour du code informatique lorsque la loi change. Les commentaires incluent également le raisonnement derrière les décisions de l’équipe de codage, y compris le support statutaire extra-légal pour les décisions. Et les commentaires peuvent également expliciter les ambiguïtés trouvées par l’équipe de codage, et comment et pourquoi l’équipe a choisi de résoudre ces ambiguïtés.

Pourquoi ne devrais-je pas utiliser n’importe quel langage de programmation que j’aime pour coder la loi ?

La question de savoir quel langage de programmation utiliser pour coder la loi est, bien sûr, une question pragmatique. Le fait que Catala puisse être compilé vers d’autres langages, tels que Python, démontre que l’on pourrait coder la loi et capturer avec précision son sens, dans une certaine mesure, dans de nombreux langages différents. Mais Catala présente plusieurs avantages pour coder la loi, en particulier la loi qui est organisée comme des règles générales suivies d’exceptions, comme le sont de nombreuses lois.

Premièrement, un programme en Catala imite la structure de la pensée juridique en listant d’abord les parties, structures et variables pertinentes. Les éléments sont nommés avant d’être utilisés, ce qui permet aux humains regardant le code informatique d’identifier les concepts pertinents avant de les appliquer. Deuxièmement, Catala permet au programmeur de définir facilement un champ d’application sur lequel diverses règles et définitions s’appliquent, en accord avec l’approche de la loi d’avoir des dispositions qui s’appliquent uniquement à “ce chapitre”, “cette section”, et ainsi de suite.

De plus, et c’est le plus important, comme décrit dans la deuxième section du tutoriel, la sémantique de Catala est basée sur une logique de règles générales et d’exceptions (“logique par défaut priorisée”). La structure des programmes Catala peut donc suivre de près la structure de la loi elle-même, si la loi est organisée comme des règles générales suivies d’exceptions. Cela rend plus facile le codage de la loi ; parce que la logique sous-jacente suit le statut, la traduction en logique par défaut peut simplement suivre le statut lui-même. Et si le statut change, il sera plus facile de changer le code Catala qu’il ne le serait de changer un code qui ne suivrait pas la structure du statut. Parce que Catala permet des exceptions qui l’emportent sur des règles plus générales, la formalisation en Catala permet aux sections et sous-sections distinctes de la loi de rester séparées. La rédaction est plus modulaire et permet aux codeurs d’échanger plus facilement la nouvelle loi et l’ancienne loi.

Enfin, les programmes Catala peuvent être formellement vérifiés car Catala a une sémantique formelle bien définie.

Peut-on utiliser de grands modèles de langage (LLM) pour traduire la loi en code ?

Savoir si les grands modèles de langage (LLM) peuvent être utilisés pour traduire la loi en code est une question de recherche ouverte que diverses personnes ont poursuivie, sans grand succès à ce stade. Le langage juridique est complexe et ne ressemble pas au langage “ordinaire”. Même au-delà de cela, coder la loi est plus que simplement “traduire” directement le langage statutaire en code informatique. La loi englobe plus que le simple langage d’un statut. Coder la loi peut, par exemple, nécessiter de résoudre des ambiguïtés présentes dans le texte statutaire, ou d’incorporer des règlements ou des pratiques en dehors du statut. Traduire la loi en code nécessite également précision, exactitude et responsabilité, qui sont toutes, au moment de cette rédaction, en tension avec l’utilisation des LLM.

Toute loi peut-elle être formalisée ?

Dans un certain sens pas particulièrement intéressant, toute loi peut être formalisée. Mais au moins lorsqu’il s’agit de formaliser la loi avec Catala, toute loi n’est pas utilement formalisée. Les lois où l’effort de formalisation porte ses fruits concrètement ont tendance à être des lois lourdes en règles, complexes, impliquant peut-être de nombreux calculs numériques, et, pour vraiment profiter de tout ce que Catala a à offrir, structurées comme des règles générales suivies d’exceptions.

Formaliser la loi a également un impact sur la façon dont elle est appliquée, et sur l’État de droit en général. Voir les travaux du groupe de recherche COHUBICOL pour plus de détails.

Questions spécifiques à Catala

Quand choisir condition, règle plutôt que des booléens ?

Vous avez peut‑être remarqué les mots‑clés condition et règle dans les champs d’application Catala, par exemple :

déclaration champ d'application Foo:
  entrée i contenu entier
  résultat x condition

champ d'application Foo:
  règle x sous condition i = 42 conséquence rempli

Le programme ci‑dessus est strictement équivalent à celui‑ci :

déclaration champ d'application Foo:
  entrée i contenu entier
  résultat x contenu booléen

champ d'application Foo:
  définition x égal à faux

  exception définition x sous condition i = 42 conséquence égal à vrai

Comme l’exemple le montre, condition est un sucre syntaxique pour déclarer une variable booléenne dont la valeur par défaut est faux. Dans le corps du champ d’application, on utilise règle au lieu de définition pour préciser sous quelles conditions la condition doit être rempli (vrai) ou non rempli (faux). Il est possible d’utiliser exception et étiquette sur des règles comme sur des définitions, mais toutes les règle sont implicitement des exceptions d’un cas de base où la condition vaut faux.

Ce comportement pour condition et rule correspond à l’intuition juridique et rend cette syntaxe plus lisible pour des morceaux de programme où l’on construit une valeur booléenne selon des cas.

Pourquoi faut‑il faire des conversions de type ?

Certains langages, comme Javascript, ne distinguent pas entiers et décimaux (type unique Number). D’autres, comme Python, masquent la distinction car l’interpréteur insère des conversions implicites quand un entier est utilisé là où un décimal est attendu. Cette approche facilite le codage, car on se soucie moins de la représentation en mémoire : “ça marche”.

Mais cela a un inconvénient : puisque le langage décide pour vous de la représentation en mémoire, vous perdez le contrôle sur la précision des calculs et sur la manière dont les valeurs sont converties. Par exemple, convertir un décimal en entier fait perdre de la précision (arrondi/troncature) ; il y a plusieurs façons de convertir un nombre de mois en nombre de jours selon la finalité du calcul.

La philosophie de Catala est de vous donner le contrôle, au prix d’exiger des conversions explicites. Ainsi, les types de base de Catala (booléen, entier, décimal, argent, date, durée) sont strictement distincts et nécessitent des conversions explicites entre eux. Utiliser un décimal là où un entier est attendu produira une erreur de typage comme :

┌─[ERROR]─
│
│  I don't know how to apply operator + on types integer and decimal
│
├─➤ example.catala_en:
│    │
│ 13 │   1 + 2.0
│    │   ‾‾‾‾‾‾‾
│
│ Type integer coming from expression:
├─➤ example.catala_en:
│    │
│ 13 │  1 + 2.0
│    │  ‾
│
│ Type decimal coming from expression:
├─➤ example.catala_en:
│    │
│ 13 │   1 + 2.0
│    │       ‾‾‾
└─

On corrige en remplaçant 2.0 par entier de 2.0. Voir la section correspondante de la référence du langage pour les détails.

Pourquoi un type argent distinct ?

Effectuer correctement des calculs financiers est difficile. Les règles de précision/arrondi varient selon les applications et doivent être conciliées avec la performance.

C’est pourquoi Catala sépare strictement argent des entier/décimal. Utiliser argent avec des conversions explicites (cf. ci‑dessus) permet au compilateur d’avertir lorsqu’on mélange argent et non‑argent. L’argent et son unité deviennent comme une unité dimensionnelle dans une formule physique.

Une fois ce type distinct, il faut lui donner un comportement cohérent avec la philosophie du langage. Les valeurs argent en Catala sont un nombre entier de centimes. Multiplier un argent par un décimal peut donner un résultat non entier en centimes ; Catala arrondit alors au centime le plus proche.

Si vous avez besoin de plus de précision pour des montants d’argent, représentez‑les en décimal et convertissez vers/depuis argent quand nécessaire.

Comment arrondir un montant à une précision donnée ?

En Catala, argent est un entier de centimes (voir ci‑dessus). Un calcul avec argent est arrondi au centime à chaque étape. Il faut donc penser l’arrondi à chaque valeur intermédiaire ; cela facilite la relecture par des experts métier.

• Pour arrondir à l’unité monétaire la plus proche, utilisez arrondi de.
• Pour arrondir à un multiple arbitraire du centime, utilisez les fonctions utilitaires de la bibliothèque standard (section 5‑7).

Exemples:

• Money.round_by_excess of $4.13 donne $5
• Money.round_by_default of $4.13 donne $4
• Money.round_to_decimal of $123.45, 1 = $123.5 (arrondi au 10e de l’unité)
• Money.round_to_decimal of $123.45, -2 = $100.0 (arrondi à la centaine)

Des fonctions analogues existent pour décimal dans le module dédié.

Pourquoi des entiers/décimaux mathématiques plutôt que des entiers/flottants machine ?

Pour la précision. Les entiers machine débordent. Les flottants ne représentent pas tous les intervalles et accumulent des erreurs. En général, c’est acceptable ; pas pour des calculs financiers qui pilotent des décisions administratives.

Catala utilise la bibliothèque GMP pour des entiers et décimaux mathématiquement sains dont la représentation grandit avec la précision requise. Cela a un coût de performance, mais GMP propose des optimisations bas niveau pour limiter cet impact.

En pratique, les décimal de Catala sont des rationnels GMP (fractions irréductibles de deux entiers GMP).

Comment créer des dates et des durées à partir d’entiers ?

Pour obtenir une durée, multipliez l’unité voulue par l’entier/décimal :

# 1 mois * 24 = 24 mois

déclaration durée_de_jours contenu durée
  dépend de nombre_de_jours contenu entier
  égal à
    1 jour * nombre_de_jours

En revanche, on ne construit pas une date YYYY-MM-DD en concaténant des entiers. Utilisez la fonction Date.of_year_month_day.

Pourquoi pas de chaînes de caractères ?

L’absence de chaînes est volontaire. Catala cible des calculs décrits par des textes juridiques. Si vous trouvez un texte légal nécessitant des opérations de chaînes, dites‑le nous !

• Les opérations “texte” des lois sont souvent mieux modélisées par des énumérations (avec contenu) et un filtrage par motif exhaustif.
• Les opérations bas niveau non décrites par la loi mais utilisées dans un programme Catala devraient être faites hors de Catala, en fournissant le résultat comme entrée d’un champ d’application, ou via un module externe (référence).
• Ajouter un runtime de chaînes alourdirait fortement la taille/complexité, avec des regex identiques sur tous les backends supportés. Coût important à la mise en œuvre et en maintenance.

Comment ajouter une exception depuis l’extérieur d’un champ d’application ?

La loi peut être tordue. Par exemple, l’article 1731 bis du CGI spécifie des amendes où l’on doit neutraliser certaines déductions à l’intérieur d’un calcul fiscal existant. En Catala, vous auriez deux champs d’application FinesComputation et IncomeTaxComputation ; le premier doit appeler le second tout en modifiant certaines règles à l’intérieur du second.

Ce motif revient à déclarer une exception à une variable de IncomeTaxComputation, depuis l’extérieur de IncomeTaxComputation. Catala offre une fonctionnalité dédiée : les variables de contexte, qui étendent proprement les exceptions entre champs d’application. Voir la référence.

Dois‑je répéter tous les champs d’une struct si je n’en change qu’un seul ?

Non ! Voir “Mise à jour des structures” dans la référence.

Comment sont gérées les dates et durées ?

Quel est le résultat de 31 janv + 1 mois ? 28 fév, 29 fév, 1er mars ? Ces ambiguïtés ont un impact sur les décisions automatisées. Nous avons conçu une bibliothèque dédiée de calcul de dates permettant de choisir la stratégie d’arrondi des dates ambiguës, motivée dans un article scientifique.

Sinon, les dates sont des dates grégoriennes au jour près. Les durées combinent jours/mois/années. Voir la référence.

Quels langages cibles pour Catala ?

Le compilateur Catala cible nativement :

• C (C89) ;
• Python ;
• Java ;
• OCaml.

Depuis le backend OCaml, Javascript peut être ciblé via js_of_ocaml.

Les runtimes ont deux dépendances hors bibliothèques standard : GMP pour l’arithmétique multi‑précision et la bibliothèque de dates.

Pourquoi ne peut‑on pas découper les déclarations de champ d’application comme les définitions ?

En Catala, on peut avoir plusieurs définition pour la même variable, ce qui permet d’aligner le code sur des fragments de texte légal dispersés. On pourrait vouloir faire pareil avec les déclarations de structures et de champs d’application.

Nous avons choisi de ne pas le permettre. Empiriquement, contrairement aux definitions à justifier par le texte légal, l’agencement des structures et prototypes relève surtout de choix de programmation. Nous recommandons de mettre toutes les déclarations de structures et de champs d’application dans un “prologue” distinct des sources légales, plutôt que de les disperser.

De plus, centraliser ces déclarations facilite la navigation. Des outils avancés (“Aller à la déclaration”) peuvent pallier ce besoin, mais ils ne sont pas toujours disponibles pour des lecteurs externes à l’équipe de développement.

Le langage Catala

Bienvenue dans la référence du langage Catala ! L’objectif de ce chapitre est de présenter, point par point, chaque fonctionnalité du langage, avec des exemples et des conseils.

Dans cette référence, une fonctionnalité de langage correspond souvent à un élément de syntaxe comme dans l’aide‑mémoire de la syntaxe. Mais, contrairement à l’aide‑mémoire, cette référence contextualise les fonctionnalités, motive les choix de conception et donne des exemples d’utilisation.

À l’inverse du tutoriel Catala, ce guide de référence n’a pas vocation à vous apprendre Catala pas à pas : les fonctionnalités sont présentées de façon taxonomique et chaque explication ne s’appuie pas toujours sur les précédentes.

Le but de cette référence est donc de vous permettre de retrouver rapidement une fonctionnalité précise lorsque vous en avez besoin, après une première phase d’apprentissage via le tutoriel.

Programmation littéraire et syntaxe de base

Programmation littéraire

Tissage et extraction

La programmation littéraire mélange le code source et sa documentation dans le même document. Un fichier source Catala contient donc à la fois du code Catala et le texte de la spécification juridique pour ce code.

Pour exécuter le code ou le compiler vers un langage de programmation cible, le compilateur Catala ignore simplement tout le texte de spécification juridique du fichier source et ne prend que le code source. C’est ce qu’on appelle l’extraction (ou tangling).

Mais vous pourriez aussi vouloir produire un document complet lisible par un humain (ou même par un juriste) sur le programme et sa spécification. Le compilateur Catala et le système de construction vous permettent également de le faire, voir la référence du système de construction pour plus d’informations. C’est ce qu’on appelle le tissage (ou weaving).

Texte libre et paragraphes

Si vous mettez simplement du texte dans votre fichier de code source Catala, il sera interprété comme du texte libre et ignoré en tant que code source Catala. Ce mode texte libre est conçu pour que vous puissiez copier-coller les spécifications juridiques de votre programme Catala. Ces spécifications seront la base de votre programme, car vous les annoterez avec des blocs de code Catala.

Le texte libre suit la syntaxe Markdown classique : vous devez laisser une ligne vide pour introduire un nouveau paragraphe.

Ceci est un premier paragraphe de texte libre.
Cette phrase sera rendue sur la même ligne que la précédente.

Cette phrase commence un nouveau paragraphe après un saut de ligne.

Titres

Un document Markdown est organisé grâce à une hiérarchie de titres, chacun introduit par #. Plus un titre a de #, plus il est profond dans le plan du document. Utilisez ces titres pour répliquer la structure hiérarchique des documents juridiques (sections, articles, etc.) ; chaque paragraphe de la spécification juridique devrait avoir un titre spécifiant son intitulé.

# Titre du document

## Première section

### Article 1

...

## Deuxième section

### Article 2

...

### Article 3

...

En effet, le compilateur Catala gardera une trace de ces titres pour enrichir les positions du code source utilisées dans les messages d’erreur, le débogage et les interfaces d’explications.

Autres fonctionnalités Markdown

Pour le style (gras, italique), les tableaux, les liens, etc., vous pouvez utiliser toutes les fonctionnalités Markdown supportées par Pandoc.

Extension de fichier Markdown

Il est possible de suffixer les fichiers Catala avec l’extension .md: foo.catala_en sera équivalent à foo.catala_en.md. En particulier, cela permet à des outils externes d’interpréter les fichiers Catala comme des fichiers Markdown. Cela permet, par exemple, d’afficher proprement les fichiers Catala dans des visualisateurs web.

Principes de syntaxe de base

Blocs de code Catala

Tout le code source Catala doit être contenu à l’intérieur d’un bloc de code Catala. Un bloc de code Catala ressemble à ceci à l’intérieur de votre fichier source :

```catala
<votre code va ici>
```

En général, le code source Catala ne se soucie pas des sauts de ligne, des tabulations et des espaces ; vous pouvez organiser votre code comme vous le souhaitez. Cependant, cette syntaxe pour ouvrir et fermer les blocs de code Catala est très stricte et doit être strictement respectée.

Commentaires à l’intérieur des blocs de code Catala

À l’intérieur d’un bloc de code Catala, vous pouvez commenter votre code en préfixant les lignes par #. Les commentaires seront ignorés par le compilateur à l’exécution mais tissés dans la documentation comme des spécifications juridiques en mode texte libre.

Mots-clés réservés

Certains mots sont réservés en Catala pour les mots-clés et ne peuvent donc pas être utilisés comme noms de variables. Si vous essayez, vous obtiendrez une erreur de syntaxe confuse car Catala croira que vous avez essayé d’utiliser le mot-clé au lieu du nom de variable.

Les mots-clés réservés en Catala sont :

champ d'application conséquence donnée dépend de déclaration contexte de liste de contient énumération entier argent décimal date durée booléen somme rempli définition état étiquette exception égal à selon n'importe quel sous forme sous condition si alors sinon condition contenu structure assertion avec pour tout on a règle soit existe dans parmi combine transforme chaque en tel que et ou ou bien non maximum minimum est ou si liste vide alors mais en remplaçant initialement nombre an mois jour vrai faux entrée résultat interne arrondi

Inclusion textuelle

Bien qu’un module Catala doive être contenu dans un seul fichier, parfois les spécifications juridiques sont très volumineuses et il est impossible de les décomposer en modules logiquement indépendants : la loi est une grosse boule de code spaghetti. Dans ce cas, il serait injuste de vous forcer à avoir des fichiers sources Catala gigantesques pour représenter un module.

Par conséquent, Catala dispose d’une fonctionnalité d’inclusion textuelle. Elle fonctionne comme ceci. Si, à l’intérieur de foo.catala_fr, vous mettez (en mode texte libre, pas à l’intérieur d’un bloc de code Catala) :

> Inclusion: bar.catala_fr

Alors, le tissage et l’extraction fonctionneront comme si vous aviez copié-collé le contenu de bar.catala_fr à l’intérieur de foo.catala_fr à l’endroit où se trouve le > Inclusion.

# Calcul de la taxe

> Inclusion: loi.catala_fr
> Inclusion: reglement.catala_fr
> Inclusion: jurisprudence.catala_fr

Types, valeurs et opérations

Types de base

Les types et valeurs suivants sont intégrés à Catala, s’appuyant sur des mots-clés du langage.

Booléens

Le type booléen n’a que deux valeurs, vrai et faux.

Opérations booléennes

Comparaisons

Opérations sur les entiers

Le type entier représente les entiers mathématiques, comme 564 614 ou -2. Notez que vous pouvez optionnellement utiliser le séparateur de nombres (espace) pour rendre les grands entiers plus lisibles.

Voir aussi le module Entier de la bibliothèque standard pour plus d’opérations.

Décimaux

Le type décimal représente les nombres décimaux mathématiques (ou rationnels), comme 0,21 ou -988 453,6842541. Notez que vous pouvez optionnellement utiliser le séparateur de nombres (espace) pour rendre les grands décimaux plus lisibles. Les nombres décimaux sont stockés avec une précision infinie en Catala, mais vous pouvez les arrondir à volonté.

Opérations sur les décimaux

Voir aussi le module Décimal de la bibliothèque standard pour plus d’opérations.

Argent

Le type argent représente un montant d’argent, positif ou négatif, dans une unité monétaire (dans la version française de Catala, le symbole monétaire € est utilisé), avec une précision au centime et pas en dessous. Les valeurs monétaires sont notées comme des valeurs décimales avec au maximum deux chiffres fractionnaires et le symbole monétaire, comme 12,36 € ou -871 84,1 €.

Opérations sur l’argent

Voir aussi le module Argent de la bibliothèque standard pour plus d’opérations.

Dates

Le type date représente des dates dans le calendrier grégorien. Ce type ne peut pas représenter de dates invalides comme 2025-02-31. Les valeurs de ce type sont notées suivant la notation ISO8601 (AAAA-MM-JJ) entourée de barres verticales, comme |1930-09-11| ou |2012-02-03|.

Sémantique de l’addition de dates

L’addition de dates en Catala consiste à ajouter une durée à une date, donnant une nouvelle date dans le passé ou dans le futur selon que la durée est négative ou positive. La valeur de cette nouvelle date dépend du contenu de la durée :

• si la durée est un nombre de jours, alors Catala ajoutera ou soustraira simplement ce nombre de jours au jour de la date originale, en passant aux mois précédents ou suivants si nécessaire ;
• si la durée est un nombre d’années (disons, x), alors Catala se comportera comme si la durée était de 12 * x mois ;
• si la durée est un nombre de mois, Catala ajoutera ou soustraira simplement ce nombre de mois au mois de la date originale, en passant à l’année précédente ou suivante si nécessaire ; mais cette opération pourrait donner une date invalide (comme 31 janv. + 1 mois -> 31 fév.), qui doit être arrondie.

Il existe trois modes d’arrondi en Catala, dont la description est ci-dessous :

Par défaut, Catala est en mode “Pas d’arrondi”. Pour définir le mode d’arrondi vers le haut ou vers le bas, pour toutes les opérations de date à l’intérieur d’un champ d’application entier, voir la section de référence pertinente.

Enfin, si la durée à ajouter est composée de plusieurs unités (comme 2 mois + 21 jour), alors Catala commencera par ajouter la composante avec la plus grande unité (ici, mois), puis la composante avec la plus petite unité (ici, jour).

Opérations sur les dates

Voir aussi le module Date de la bibliothèque standard pour plus d’opérations.

Durées

Le type durée représente des durées en termes de jours, mois et/ou années, comme 254 jour, 4 mois ou 1 an. Les durées peuvent être négatives et combiner un nombre de jours et de mois ensemble, comme 1 mois + 15 jour.

Opérations sur les durées

Conversion des types numériques de base

La conversion entre les types de base est explicite ; la syntaxe est <nom du type désiré> de <argument>.

Types déclarés par l’utilisateur

Les types déclarés par l’utilisateur doivent être déclarés avant d’être utilisés dans le reste du programme. Cependant, la déclaration n’a pas besoin d’être placée avant l’utilisation dans l’ordre textuel.

Structures

Les structures combinent plusieurs éléments de données ensemble dans un seul type. Chaque élément de données est un “champ” de la structure. Si vous avez une structure, vous pouvez accéder à chacun de ses champs, mais vous avez besoin de tous les champs pour construire la valeur de la structure.

Les types de structure sont déclarés par l’utilisateur, et chaque type de structure a un nom choisi par l’utilisateur. Les noms de structure commencent par une majuscule et doivent suivre la convention de nommage CamelCase. Un exemple de déclaration de structure est :

déclaration structure Individu:
  donnée date_naissance contenu date
  donnée revenu contenu argent
  donnée nombre_enfants contenu entier

Le type de chaque champ de la structure est obligatoire et introduit par contenu. Il est possible d’imbriquer des structures (déclarer le type d’un champ d’une structure comme une autre structure ou énumération), mais pas récursivement.

Les valeurs de structure sont construites avec la syntaxe suivante :

Individu {
  -- date_naissance: |1930-09-11|
  -- revenu: 100 000 €
  -- nombre_enfants: 2
}

Pour accéder au champ d’une structure, utilisez simplement la syntaxe <valeur struct>.<nom champ>, comme individu.revenu.

Énumérations

Les énumérations représentent une alternative entre différents choix, chacun encapsulant un modèle spécifique de données. En ce sens, les énumérations sont des “types somme” à part entière comme dans les langages de programmation fonctionnelle, et plus puissantes que les énumérations de type C qui listent juste des codes alternatifs qu’une valeur peut avoir. Chaque choix ou alternative de l’énumération est appelé un “cas” ou une “variante”.

Les types d’énumération sont déclarés par l’utilisateur, et chaque type d’énumération a un nom choisi par l’utilisateur. Les noms d’énumération commencent par une majuscule et doivent suivre la convention de nommage CamelCase. Un exemple de déclaration d’énumération est :

déclaration énumération PasDeCreditImpot:
  -- PasDeCreditImpot
  -- CreditImpotPourIndividu contenu Individu
  -- CreditImpotApresDate contenu date

Le type de chaque cas de l’énumération est obligatoire et introduit par contenu. Il est possible d’imbriquer des énumérations (déclarer le type d’un champ d’une énumération comme une autre énumération ou structure), mais pas récursivement.

Les valeurs d’énumération sont construites avec la syntaxe suivante :

# Premier cas
PasDeCreditImpot,
# Deuxième cas
CreditImpotPourIndividu contenu Individu {
    -- date_naissance: |1930-09-11|
    -- revenu: 100 000 €
    -- nombre_enfants: 2
},
# Troisième cas
CreditImpotApresDate contenu |2000-01-01|

Pour inspecter les valeurs d’énumération, voir dans quel cas vous êtes et utiliser les données associées, utilisez le filtrage par motif.

Listes

Le type liste de <autre type> représente un tableau de taille fixe d’un autre type. Par exemple, liste de entier représente un tableau de taille fixe d’entiers.

Vous pouvez construire des valeurs de liste en utilisant la syntaxe suivante :

[1; 6; -4; 846645; 0]

Opérations sur les listes

transforme chaque (x, y) parmi (lst1, lst2) en x + y

N-uplets

Le type (<type 1>, <type 2>) représente une paire d’éléments, le premier étant de type 1, le second étant type 2. Il est possible d’étendre le type paire en un type triplet, ou même un n-uplet pour un nombre arbitraire n en répétant les éléments après ,.

Vous pouvez construire des valeurs de n-uplet avec la syntaxe suivante :

(|2024-04-01|, 30 €, 1%) # Cette valeur a le type (date, argent, décimal)

Vous pouvez accéder au n-ième élément d’un n-uplet, commençant à 1, avec la syntaxe <n-uplet>.n.

Valeurs optionnelles

Le type optionnel de <type> peut être utilisé pour contenir une valeur de <type> qui pourrait être absente. Par exemple, optionnel de entier est équivalent à l’énumération :

déclaration énumération EntierOptionnel:
  -- Absent
  -- Présent contenu entier

Mais l’avantage de optionnel de entier par rapport à un tel EntierOptionnel est qu’il n’a pas besoin d’être déclaré pour chaque type avec lequel il est utilisé. Comme une énumération, les valeurs de type optionnel peuvent être créées en utilisant Présent contenu <expr>, et utilisées dans les formes selon <expr> sous forme et <expr> sous forme <constr>, par ex.

si foo sous forme Présent de bar et bar > 3 alors ...

Fonctions

Les types de fonction représentent des valeurs de fonction, c’est-à-dire des valeurs qui nécessitent d’être appelées avec des arguments pour produire un résultat. Les fonctions sont des valeurs de première classe car Catala est un langage de programmation fonctionnelle.

La syntaxe générale pour décrire un type de fonction est :

<type du résultat> dépend de
  <nom de l'argument 1> contenu <type de l'argument 1>,
  <nom de l'argument 2> contenu <type de l'argument 2>,
  ...

Par exemple, argent dépend de revenu contenu argent, nombre_enfants contenu entier peut être le type d’une fonction de calcul d’impôt.

Cependant, contrairement à la plupart des langages de programmation, il n’est pas possible de construire directement une fonction comme une valeur ; les fonctions sont créées et passées avec d’autres mécanismes du langage.

Fonctions polymorphes

Une fonctionnalité clé d’un langage de programmation est sa capacité à éviter la duplication de code ; le programmeur devrait réutiliser autant de code que possible à travers des abstractions, telles que des fonctions et des modules. De plus, une fonctionnalité standard du génie logiciel moderne est le polymorphisme, c’est-à-dire écrire des morceaux de code qui peuvent opérer sur plusieurs types de valeurs à la fois, évitant au programmeur la nécessité de dupliquer le même code plusieurs fois selon le type des arguments.

Concrètement, lors de la définition d’une fonction en Catala, vous pouvez donner le type n'importe quel à un argument ou au type de retour. Cela signifie que lorsque vous appelez la fonction, vous pouvez l’appeler avec un argument qui a n’importe lequel des types possibles. Nous pouvons appeler un tel argument “générique”, ou dire qu’il a un type “joker”. Par exemple, il est pratique de pouvoir écrire la fonction est_vide une fois pour des listes d’ éléments de n’importe quel type :

déclaration est_vide contenu booléen
  dépend de argument contenu liste de n'importe quel
  égal à (nombre de argument = 0)

Bien que les arguments génériques soient puissants, ils ont aussi l’inconvénient que vous ne pouvez pas vraiment “faire” grand-chose avec une valeur qui a le type n'importe quel puisque vous ne savez pas quel type elle a. En particulier, il est impossible d’utiliser les opérateurs comme +, *, -, /, <=, etc. puisque ces opérateurs ne fonctionnent que pour les types de base (entier, décimal, etc.) et pas tous les autres types qui peuvent être définis par l’utilisateur (structures, énumérations, etc.).

Parfois, il y a plusieurs arguments génériques ou types de retour dans la même fonction mais vous voulez qu’ils partagent le même type générique. Par exemple, si une fonction inverse les éléments d’une liste, le type des éléments de la liste sera le même à l’entrée et à la sortie de la fonction. Les types n'importe quel peuvent être nommés à cette fin, en utilisant n'importe quel de type <nom>. Par exemple :

déclaration inverser contenu liste de n'importe quel de type type_element
  dépend de argument contenu liste de n'importe quel de type type_element

Si vous ne nommez pas le type n'importe quel explicitement, il sera supposé que chaque n'importe quel est un n'importe quel frais et indépendant des autres n'importe quel. Cela peut conduire à des messages d’erreur complexes du compilateur, alors rappelez-vous de donner le même nom aux types n'importe quel que vous savez devoir être liés ensemble.

Les signatures de fonctions polymorphes peuvent être vraiment utiles lors de la définition d’interfaces pour des modules implémentés en externe.

Champs d’application, fonctions et constantes

Déclarations de champ d’application

Un champ d’application est une fonction dont le prototype (c’est-à-dire la signature) est explicitement déclaré, et dont le corps peut être dispersé en petits morceaux à travers la base de code de programmation littéraire.

Vous devez déclarer (déclaration champ d'application Foo ...) une fois à un endroit dans le code ; ensuite vous pouvez utiliser ce champ d’application (champ d'application Foo) pour ajouter des définitions de variables plusieurs fois et n’importe où ailleurs dans votre base de code.

Les sections de référence suivantes vous indiquent comment écrire la déclaration de champ d’application. Comme divulgâchage, voici un exemple complet pour un champ d’application minimal nommé Min avec deux variables, a et b :

déclaration champ d'application Min:
  entrée a contenu entier
  résultat b contenu décimal

Nom du champ d’application

Les déclarations de champ d’application commencent par la déclaration du nom du champ d’application. Les noms de champ d’application commencent par une majuscule et suivent la convention CamelCase. Une déclaration de champ d’application est un élément de haut niveau à l’intérieur d’un bloc de code Catala. Par exemple, si vous voulez nommer votre champ d’application Foo, alors sa déclaration commence par :

déclaration champ d'application Foo:
   ...

Le contenu de la déclaration de champ d’application (à l’intérieur des ...) est composé de :

• déclarations de variables de champ d’application ;
• sous-champs d’application appelés dans le champ d’application.

Ces deux éléments sont décrits ci-dessous.

Déclarations de variables de champ d’application

Après le nom du champ d’application viennent les variables de champ d’application dans la déclaration de champ d’application. Les variables de champ d’application sont similaires aux variables locales dans une fonction. Leur déclaration comporte :

• leur statut entrée/résultat ;
• leur nom ;
• leur type ;
• optionnellement, une liste d’états pour la variable.

Les noms de variables commencent par une minuscule et suivent la convention snake_case. La syntaxe pour la déclaration de la variable bar est :

<statut entrée/résultat> bar contenu <type> [<liste d'états de variable>]

déclaration champ d'application Foo:
  entrée baz contenu booléen
  interne fizz contenu date
    état avant
    état après
  entrée résultat buzz contenu décimal
    dépend de arg contenu date

Les explications pour le statut entrée/résultat, les types de variables et les états de variables suivent ci-dessous.

Qualificateurs d’entrée/résultat

Il existe six types de qualificateurs d’entrée/résultat :

• entrée
• résultat
• interne
• contexte
• entrée résultat
• contexte résultat

Variables d’entrée

Les variables d’entrée nécessitent qu’une valeur soit fournie lorsque le champ d’application est appelé, comme un argument de fonction. Elles ne peuvent pas être redéfinies à l’intérieur du champ d’application.

Variables de résultat

Les variables de résultat sont définies à l’intérieur du champ d’application, et leur valeur est renvoyée comme partie du résultat de l’appel du champ d’application.

Variables internes

Lorsqu’une variable n’est ni une entrée ni un résultat du champ d’application, elle doit être qualifiée d’interne.

Variables de contexte

Les variables de contexte sont essentiellement des entrées optionnelles au champ d’application avec une valeur par défaut définie à l’intérieur du champ d’application. Supposons que le champ d’application Foo a une variable de contexte bar. Si vous fournissez une valeur x pour bar lors de l’appel de Foo, le calcul de Foo considérera que bar = x. Mais si vous ne fournissez pas de valeur pour bar lors de l’appel de Foo, Foo prendra comme valeur bar la définition existante de bar à l’intérieur de Foo.

Variables d’entrée et de résultat

Parfois, on veut que l’entrée d’un champ d’application soit copiée et transmise comme partie du résultat de l’appel du champ d’application. C’est-à-dire qu’une telle variable serait à la fois entrée et résultat, c’est pourquoi la syntaxe pour cela est entrée résultat. Dans ce cas, la variable ne peut pas être définie à l’intérieur du champ d’application (car c’est une entrée). Cela fonctionne aussi en remplaçant entrée par contexte.

Types de variables et fonctions

Le type de la variable suivant le mot-clé contenu peut être n’importe quel identifiant de type décrit dans la référence des types, y compris les types de fonction.

Variables de champ d’application condition

Une syntaxe spéciale existe pour le cas spécifique d’une variable de champ d’application booléenne dont la valeur par défaut est faux. Ce cas correspond directement à une condition juridique, il est donc nommé condition en Catala. La syntaxe pour déclarer une variable de champ d’application condition (ici nommée bar, avec un qualificateur interne) est :

déclaration champ d'application Foo:
  interne bar condition

Les variables condition ont également une syntaxe spéciale pour les définitions (voir la section de référence pertinente).

Déclarations d’états de variable

Comme mentionné dans le tutoriel, il est possible de distinguer plusieurs états pendant le calcul de la valeur finale de la variable. Les états se comportent comme une chaîne de variables, la suivante utilisant la valeur de la précédente pour son calcul.

La liste ordonnée des états que la variable prend pendant le calcul est déclarée aux côtés de la variable. Par exemple, si la variable entière interne foo a les états a, b et c dans cet ordre, alors foo doit être déclarée avec :

déclaration champ d'application Foo:
  interne foo contenu entier
    état a
    état b
    état c

L’ordre des clauses état dans la déclaration détermine l’ordre de calcul entre les états pour la variable. Vous pouvez écrire foo état a pour la valeur de la variable foo pendant l’état a. Avec cet ordre entre a, b et c, foo état b peut dépendre de foo état a et foo état c peut dépendre de foo état b, mais pas l’inverse.

Structure de résultat du champ d’application

Toutes les variables qualifiées de résultat dans un champ d’application feront partie du résultat de l’appel du champ d’application. Ce résultat est matérialisé comme une structure, avec chaque variable de résultat correspondant à un champ de la structure. Cette structure de résultat du champ d’application est utilisable comme n’importe quel autre type de structure déclaré par l’utilisateur.

Par exemple, si j’ai la déclaration de champ d’application :

déclaration champ d'application Foo:
  résultat bar contenu entier
  résultat baz contenu décimal

  interne fizz contenu booléen
  entrée buzz contenu date

Alors implicitement, une structure de résultat également nommée Foo sera utilisable comme si elle avait la déclaration suivante :

déclaration structure Foo:
  donnée bar contenu entier
  donnée baz contenu décimal

Cette déclaration implicite de structure de résultat est utile pour transporter le résultat d’un appel de champ d’application dans une autre variable et les réutiliser plus tard dans le code.

Déclarations de sous-champs d’application

Les champs d’application sont des fonctions, et en tant que tels, ils peuvent être appelés comme des fonctions. Appeler un champ d’application peut être fait à l’intérieur de n’importe quelle expression en fournissant simplement les variables d’entrée comme arguments.

Mais parfois, on sait que l’on effectuera toujours un seul appel statique de sous-champ d’application depuis un champ d’application appelant. Pour cette situation, Catala a une syntaxe déclarative spéciale rendant plus facile pour les juristes de comprendre ce qui se passe.

Les sous-champs d’application sont déclarés dans la déclaration de champ d’application comme des variables de champ d’application. Par exemple, si à l’intérieur du champ d’application Foo vous appelez le champ d’application Bar exactement une fois, alors vous écrirez :

déclaration champ d'application Foo:
  appel_bar champ d'application Bar

appel_bar est le nom (de votre choix) qui désignera cette instance spécifique d’appel de Bar à l’intérieur de Foo. Vous pouvez avoir plusieurs appels statiques au même champ d’application comme :

déclaration champ d'application Foo:
  premier_appel_bar champ d'application Bar
  second_appel_bar champ d'application Bar

Vous pouvez également préfixer par résultat la ligne appel_bar champ d'application Bar, assurant que la structure de résultat de l’appel à Bar sera présente comme champ appel_bar de la structure de résultat de l’appel à Foo.

Comme avec les structures et les énumérations, il n’est pas possible pour ces appels de champ d’application d’être récursifs.

Voir appel de sous-champ d’application pour savoir comment fournir des arguments à l’appel de sous-champ d’application et récupérer les résultats.

Déclarations et définitions de constantes et fonctions globales

Bien que les champs d’application soient le cheval de bataille des implémentations Catala, il y a parfois de petites choses qui n’ont pas besoin d’être à l’intérieur d’un champ d’application à part entière. Par exemple, déclarer de petites fonctions utilitaires comme exces_de qui calcule l’excès du premier argument par rapport au second, ou déclarer une constante pour le nombre de secondes dans une journée.

Pour cela, Catala permet la déclaration de constantes et fonctions globales, qui ne sont pas liées à un champ d’application particulier.

Constantes

Pour déclarer et définir globalement une constante foo de type <type> (n’importe quel élément dans la référence des types) avec la valeur <expr> (n’importe quelle expression de type <type>), utilisez la syntaxe suivante :

déclaration foo contenu <type> égal à <expr>

Par exemple :

déclaration foo contenu booléen égal à vrai
déclaration bar contenu entier égal à 4643 * 876 - 524

Fonctions

Si le type de la constante que vous déclarez et définissez est un type de fonction, alors la constante devient une fonction globale gratuitement. Par exemple :

déclaration foo contenu est_rond contenu booléen
  dépend de x contenu décimal
  égal à
    arrondi de x = x

déclaration exces_de contenu argent
  dépend de
    arg contenu argent,
    seuil contenu argent
  égal à
    si arg >= seuil
    alors arg - seuil
    sinon 0 €

Définitions et exceptions

Alors que la section de référence précédente couvrait la déclaration des champs d’application (introduite par déclaration champ d'application Foo) qui doit être faite une fois pour chaque champ d’application dans la base de code, cette section couvre la définition des variables de champ d’application dispersées à travers la base de code de programmation littéraire (introduite par champ d'application Foo).

La syntaxe complète de ce qui sera couvert dans cette section est :

champ d'application <nom_champ_application>:
  [étiquette <nom_étiquette>]
  [exception <nom_étiquette>]
  définition <nom_variable_champ_application>
    [de <paramètres>] [état <nom_état>]
    [sous condition <expression> conséquence]
    égal à <expression>

  assertion <expression>

Définitions de variables de champ d’application

Les définitions de variables de champ d’application sont l’endroit où vivra la majeure partie du code Catala. Définir une variable bar à l’intérieur du champ d’application Foo comme la valeur 42 est aussi simple que :

champ d'application Foo:
  définition bar égal à 42

Bien sûr, vous pouvez remplacer 42 par n’importe quelle expression tant qu’elle a le type correct par rapport à la déclaration de la variable de champ d’application.

Variables de champ d’application qui sont des fonctions

Si la variable de champ d’application que vous définissez est une variable de fonction, par exemple si foo est une fonction du champ d’application Foo avec les arguments x et y, alors la syntaxe pour définir la variable est :

champ d'application Foo:
  définition foo de x, y égal à x + y

Variables de champ d’application avec plusieurs états

Si la variable de champ d’application a plusieurs états, par exemple si bar a les états debut, milieu et fin, alors la syntaxe pour définir l’état milieu de la variable est :

champ d'application Foo:
  définition bar état milieu égal à bar * 2
  # "bar" ci-dessus fait référence à la valeur de bar dans l'état précédent,
  # ici "debut"

Les états de variables et les fonctions se mélangent de cette façon :

champ d'application Foo:
  définition foo de x, y état milieu égal à (foo de x, y) * 2 + x + y

Variables de champ d’application qui sont condition

Les variables de champ d’application condition (variables de champ d’application booléennes avec une valeur par défaut de faux) ont une syntaxe différente, adaptée aux juristes, pour les définitions : définition est remplacé par règle et égal à <expression> est remplacé par rempli ou non rempli :

champ d'application Foo:
  # Les règles viennent généralement toujours sous la forme de définitions conditionnelles, voir ci-dessous
  règle bar sous condition [...] conséquence non rempli

Définitions conditionnelles

La principale fonctionnalité de Catala est de pouvoir décomposer les définitions de variables de champ d’application en plusieurs morceaux. En effet, les textes juridiques définissent souvent les choses par morceaux dans plusieurs articles, chaque article traitant d’une situation spécifique donnant une définition spécifique pour une quantité. Ce modèle est reflété dans Catala sous la forme de définitions conditionnelles.

Les conditions sont introduites dans les définitions de variables de champ d’application juste avant le mot-clé égal à avec la syntaxe suivante :

champ d'application Foo:
  définition bar sous condition fizz >= 0 conséquence égal à 42

Suivez la section pertinente du tutoriel pour plus d’informations sur la façon d’utiliser les définitions conditionnelles pour encoder des dispositions juridiques.

champ d'application Foo:
  définition bar sous condition date_courante >= |2025-01-01|
  conséquence égal à [...]

  définition baz sous condition date_courante >= |2025-01-01|
  conséquence égal à [...]

champ d'application Foo sous condition date_courante >= |2025-01-01|:
  définition bar égal à [...]

  définition baz égal à [...]

Exceptions et priorités

Lorsqu’il y a plusieurs définitions conditionnelles ou non conditionnelles pour une variable de champ d’application donnée, il est parfois nécessaire de désambiguïser laquelle va prévaloir lorsque les conditions pour 2 définitions ou plus se déclenchent en même temps. Cela se fait en définissant une structure d’exceptions entre les multiples définitions de la même variable de champ d’application. Cette structure d’exceptions est en fait un arbre, car vous pouvez avoir des exceptions d’exceptions.

Suivez la section pertinente du tutoriel pour plus d’informations sur la façon d’utiliser les exceptions pour encoder des dispositions juridiques.

Déclarer une définition exceptionnelle à une seule définition de cas de base

Commençons par le cas le plus basique. Chaque nœud de l’arbre des exceptions pour une variable de champ d’application donnée commence par une définition conditionnelle ou non conditionnelle. Vous pouvez donner une étiquette à ce nœud de l’arbre avec la syntaxe étiquette :

champ d'application Foo:
  étiquette cas_base définition bar égal à 42

Ensuite, plus tard dans la base de code, si vous voulez ajouter une exception à ce cas_base de la définition de bar, vous le ferez avec la syntaxe :

champ d'application Foo:
  # La ligne ci-dessous signifie que la définition actuelle est une exception *à*
  # l'autre définition avec l'étiquette "cas_base".
  exception cas_base
  définition bar
  sous condition fizz = 0
  conséquence égal à
    0

champ d'application Foo:
  définition bar égal à 42

...

champ d'application Foo:
  exception définition bar
  sous condition fizz = 0
  conséquence égal à
    0

Déclarer plusieurs définitions comme une exception à une seule définition

Dans l’exemple précédent, bar était défini exceptionnellement à 0 si fizz = 0. Et si vous voulez étendre ce comportement avec deux autres définitions exceptionnelles qui définissent bar à 1 et -1 respectivement lorsque fizz > 0 et fizz < 0 ? Ces trois définitions exceptionnelles ne peuvent pas entrer en conflit les unes avec les autres car fizz est soit positif, négatif ou 0. Donc, ces trois définitions exceptionnelles se comportent comme une grande exception au cas de base (où bar est défini à 42).

Pour regrouper les trois définitions exceptionnelles ensemble en Catala et les définir comme une exception au cas de base, il suffit de donner aux trois définitions exceptionnelles la même étiquette fizz_exn (vous pouvez choisir le nom de l’étiquette) et l’indication d’exception :

champ d'application Foo:
  étiquette cas_base définition bar égal à 42

...

champ d'application Foo:
  étiquette fizz_exn
  exception cas_base
  définition bar
  sous condition fizz = 0
  conséquence égal à
    0

...

champ d'application Foo:
  étiquette fizz_exn
  exception cas_base
  définition bar
  sous condition fizz > 0
  conséquence égal à
    1

...

champ d'application Foo:
  étiquette fizz_exn
  exception cas_base
  définition bar
  sous condition fizz < 0
  conséquence égal à
    -1

champ d'application Foo:
  définition bar égal à 42

...

champ d'application Foo:
  exception définition bar
  sous condition fizz = 0
  conséquence égal à
    0

...

champ d'application Foo:
  exception définition bar
  sous condition fizz > 0
  conséquence égal à
    1

...

champ d'application Foo:
  exception définition bar
  sous condition fizz < 0
  conséquence égal à
    -1

Déclarer plusieurs définitions comme une exception à un groupe de définitions

Pour construire sur notre exemple fil rouge, imaginez maintenant que la valeur de bar dans le cas de base dérive avec le temps : 42 avant 2025 mais 43 après. Alors, vous avez besoin de deux définitions conditionnelles dans le cas de base (ces deux définitions regroupées sont toujours mutuellement exclusives). Cela est réalisé en Catala simplement en donnant la même étiquette cas_base aux deux définitions de cas de base :

champ d'application Foo:
  étiquette cas_base définition bar
  sous condition date_courante < |2025-01-01|
  conséquence égal à
    42

...

champ d'application Foo:
  étiquette cas_base définition bar
  sous condition date_courante >= |2025-01-01|
  conséquence égal à
    43

...

champ d'application Foo:
  étiquette fizz_exn
  exception cas_base
  définition bar
  sous condition fizz = 0
  conséquence égal à
    0

...

champ d'application Foo:
  étiquette fizz_exn
  exception cas_base
  définition bar
  sous condition fizz > 0
  conséquence égal à
    1

...

champ d'application Foo:
  étiquette fizz_exn
  exception cas_base
  définition bar
  sous condition fizz < 0
  conséquence égal à
    -1

Empiler les exceptions, et plus encore

Les exemples précédents montrent comment utiliser la syntaxe étiquette et exception pour regrouper des définitions ensemble et déclarer des priorités exceptionnelles. Cette syntaxe est tout ce dont vous avez besoin ! En particulier, vous pouvez empiler les exceptions en définissant des chaînes et des branches de relation exception, etc. Cela est couvert de manière extensive dans la section pertinente du tutoriel.

Appel de sous-champ d’application

Une fois que vous avez déclaré un sous-champ d’application, vous devrez définir ses arguments en définissant les variables d’entrée du sous-champ d’application dans le champ d’application. Par exemple, si le champ d’application Foo a un sous-champ d’application bar appelant le champ d’application Bar qui a des variables d’entrée fizz et buzz, vous devrez définir bar.fizz et bar.fuzz avec cette syntaxe :

champ d'application Foo:
  définition bar.fizz égal à [...]

  définition bar.fuzz égal à [...]

Bien sûr, vous pouvez utiliser des exceptions et des définitions conditionnelles pour ces définitions de variables d’entrée de sous-champ d’application.

Une fois que vous avez défini toutes les variables d’entrée du champ d’application (ainsi que certaines variables de contexte si nécessaire), vous pouvez simplement faire référence aux variables de résultat du sous-champ d’application dans des expressions ultérieures. Par exemple, si Bar a une variable de résultat fizzbuzz, alors vous pouvez faire référence à bar.fizzbuzz comme le résultat de fizzbuzz lors de l’appel de Bar avec les arguments bar.fizz et bar.fuzz.

Assertions

Les assertions en Catala sont des expressions attachées aux champs d’application (elles peuvent dépendre des variables de champ d’application) qui doivent toujours être vraies. Elles peuvent être utilisées pour :

• la validation des entrées et les préconditions de champ d’application ;
• vérifier des invariants logiques ;
• tester une sortie attendue.

Leur syntaxe est aussi simple que :

champ d'application Foo:
  assertion bar + 2 = fizz * 4

Il est possible d’attacher un attribut #[error.message] à une assertion afin d’y ajouter un message qui sera affiché en cas d’échec.

Mode d’arrondi des dates

Pour définir le mode d’arrondi du calcul de date vers le haut ou vers le bas (voir la section de référence pertinente), pour toutes les opérations de date à l’intérieur d’un champ d’application entier, utilisez cette syntaxe :

# Supposons que vous vouliez définir le mode d'arrondi pour les opérations de date
# à l'intérieur du champ d'application Foo déclaré ailleurs
champ d'application Foo:
  date arrondi supérieur # arrondi à la date suivante
  # ou
  date arrondi inf # arrondi à la date précédente

Expressions

Les expressions en Catala représentent le cœur des règles de calcul, qui apparaissent dans les définitions de variables de champ d’application ou dans les définitions de constantes globales.

<expr> ::=
  | (<expr 1>, <expr 2>, ...)                         # N-uplet
  | <expr>.<nom champ>                                # Accès champ structure
  | <expr>.<entier>                                   # Accès composant n-uplet
  | [<expr 1>; <expr 2>; ...]                         # Liste
  | <structure> { -- <nom champ 1>: <expr 1> -- ...}  # Valeur structure
  | <variante énum> contenu <expr>                    # Valeur énum
  | <expr 1> de <expr 2>, <expr 3>, ...               # Appel fonction
  | résultat de <nom champ d'application> avec        # Appel direct champ d'application
      {  -- <variable 1>: <expr 1> -- ... }
  | selon <expr> sous forme                           # Filtrage par motif
    -- <variante énum 1>: <expr 1>
    -- <variante énum 2> contenu <variable>: <expr 2>
  | <expr> sous forme <variante énum>                 # Test variante motif
  | <expr> sous forme <variante énum> contenu <variable> # Idem avec liaison contenu
      et <expr>                                       #   et test sur la variable
  | <expr> mais en remplaçant                         # Mises à jour partielles structure
      {  -- <variable 1>: <expr 1> -- ... }
  | - <expr>                                          # Négation
  | <expr>
    < + - * / et ou non ou bien > < >= <= == != > <expr> # Opérations binaires
  | si <expr 1> alors <expr 2> sinon <expr 3>         # Conditionnelles
  | soit <variable> égal à <expr 1> dans <expr 2>     # Liaison locale
  | assertion <expr 1> dans <expr 2>                  # Assertion locale
  | ...                                               # Variable, littéraux,
                                                      # opérateurs de liste, ...

Références à d’autres variables

À l’intérieur d’une expression, vous pouvez faire référence au nom d’autres variables du même champ d’application, ou à des constantes et fonctions de haut niveau.

Pour référencer une variable d’un autre module, utilisez la syntaxe <nom du module>.<nom de la variable>.

Valeurs et opérations

Toutes les valeurs et opérations présentées précédemment sont des expressions à part entière.

Parenthèses

Vous pouvez utiliser des parenthèses (...) autour de n’importe quelle partie ou sous-partie d’une expression pour vous assurer que le compilateur comprendra correctement ce que vous tapez.

Variables locales et liaisons let

À l’intérieur d’une définition complexe d’une variable de champ d’application, il est souvent utile de donner un nom à une quantité intermédiaire pour promouvoir sa réutilisation, ou simplement pour rendre le code plus lisible. Bien qu’il soit toujours possible d’introduire une nouvelle variable de champ d’application à cet effet, vous pouvez également utiliser une variable locale plus légère qui n’affecte que l’expression courante. La syntaxe pour celles-ci est soit foo égal à ... dans .... Par exemple :

champ d'application Bar:
  définition baz égal à
    soit foo égal à [4; 6; 5; 1] dans
    somme entier de foo - maximum de foo

soit (y, z) = x dans
si z alors y sinon 0

Conditionnelles

Vous êtes encouragé à utiliser des exceptions aux définitions de variables de champ d’application pour encoder la logique cas de base/exception des textes juridiques. Seules les exceptions et les définitions conditionnelles de variables de champ d’application vous permettent de diviser votre code Catala en petits morceaux, chacun attaché au morceau de texte juridique qu’il encode.

Cependant, parfois, il est tout simplement logique d’utiliser une conditionnelle classique à l’intérieur d’une expression pour distinguer entre deux cas. Dans ce cas, utilisez le traditionnel si ... alors ... sinon .... Notez que vous devez inclure le sinon à chaque fois car cette conditionnelle est une expression produisant toujours une valeur et non une instruction qui met à jour conditionnellement une cellule mémoire.

Structures

Comme expliqué précédemment, les valeurs de structure sont construites avec la syntaxe suivante :

Individu {
  -- date_naissance: |1930-09-11|
  -- revenu: 100 000 €
  -- nombre_enfants: 2
}

Pour accéder au champ d’une structure, utilisez simplement la syntaxe ., comme individu.revenu.

Bar {
  -- baz: 42
  -- fizz: foo.fizz
  -- ...
}

foo mais en remplaçant { -- baz: 42 }

Énumérations

Comme expliqué précédemment, le type de chaque cas de l’énumération est obligatoire et introduit par contenu. Il est possible d’imbriquer des énumérations (déclarer le type d’un champ d’une énumération comme une autre énumération ou structure), mais pas récursivement.

Les valeurs d’énumération sont construites avec la syntaxe suivante :

# Premier cas
PasDeCreditImpot,
# Deuxième cas
CreditImpotPourIndividu contenu Individu {
    -- date_naissance: |1930-09-11|
    -- revenu: 100 000 €
    -- nombre_enfants: 2
},
# Troisième cas
CreditImpotApresDate contenu |2000-01-01|

Filtrage par motif

Le filtrage par motif est une fonctionnalité populaire des langages de programmation qui vient de la programmation fonctionnelle, introduite dans le grand public par Rust, mais suivie par d’autres langages comme Java ou Python. En Catala, le filtrage par motif fonctionne sur les valeurs d’énumération dont le type a été déclaré par l’utilisateur. Supposons que vous ayez déclaré le type

déclaration énumération PasDeCreditImpot:
  -- PasDeCreditImpot
  -- CreditImpotPourIndividu contenu Individu
  -- CreditImpotApresDate contenu date

et vous avez une valeur foo de type PasDeCreditImpot. foo est soit une instance de PasDeCreditImpot, soit CreditImpotPourIndividu, soit CreditImpotApresDate. Si vous voulez utiliser foo, vous devez fournir des instructions pour ce qu’il faut faire dans chacun des trois cas, puisque vous ne savez pas à l’avance lequel ce sera. C’est le but du filtrage par motif ; dans chacun des cas, fournir une expression produisant ce qui devrait être le résultat dans ce cas. Ces expressions de cas peuvent également utiliser le contenu stocké à l’intérieur du cas des énumérations, rendant le filtrage par motif un moyen puissant et intuitif d’“inspecter” le contenu imbriqué. Par exemple, voici la syntaxe de filtrage par motif pour calculer le crédit d’impôt dans notre exemple :

selon foo sous forme
-- PasDeCreditImpot: 0 €
-- CreditImpotPourIndividu contenu individu: individu.revenu * 10%
-- CreditImpotApresDate contenu date: si date_courante >= date alors 1000 € sinon 0 €

Dans CreditImpotPourIndividu contenu individu, alors que CreditImpotPourIndividu est le nom du cas d’énumération inspecté, individu est un nom de variable choisi par l’utilisateur représentant le contenu de ce cas d’énumération. En d’autres termes : vous pouvez choisir votre propre nom pour la variable dans la syntaxe à cet endroit !

Il est important de noter que le filtrage par motif vous aide également à éviter d’oublier de gérer des cas. En effet, si vous déclarez un cas dans le type mais l’oubliez dans le filtrage par motif, vous obtiendrez une erreur du compilateur.

selon foo sous forme
-- PasDeCreditImpot: vrai
-- n'importe quel: faux

selon foo sous forme
-- CreditImpotPourIndividu contenu individu: vrai
-- n'importe quel: faux

foo sous forme CreditImpotPourIndividu

selon foo sous forme
-- CreditImpotPourIndividu contenu individu: individu.revenu >= 10 000 €
-- n'importe quel: faux

foo sous forme CreditImpotPourIndividu contenu individu et individu.revenu >= 10 000 €

N-uplets

Comme expliqué précédemment, vous pouvez construire des valeurs de n-uplet avec la syntaxe suivante :

(|2024-04-01|, 30 €, 1%) # Cette valeur a le type (date, argent, décimal)

Vous pouvez également accéder au n-ième élément d’un n-uplet, commençant à 1, avec la syntaxe <n-uplet>.n.

Listes

Vous pouvez construire des valeurs de liste en utilisant la syntaxe suivante :

[1; 6; -4; 846645; 0]

Toutes les opérations disponibles pour les listes sont disponibles sur la page de référence pertinente.