catala/examples/tutoriel_fr/tutoriel_fr.catala_fr

# Tutoriel d'utilisation du langage Catala

Bienvenue dans ce tutoriel, son objectif est de vous accompagner dans les
fonctionnalités du langage Catala et de vous apprendre à annoter des textes
législatifs avec ce langage. Ce document s'adresse principalement à des développeurs
ou des personnes ayant déjà programmé, même si des juristes avec des appétences
en informatique devraient pouvoir s'en sortir.

```catala
# Attention, ce tutoriel en français n'est peut-être pas à jour avec
# les dernières fonctionnalités du langage. En effet, le tutoriel en anglais
# disponible sur https://catala-lang.org/en/examples/tutorial constitue
# la référence pour le langage.
```

## Programmation littéraire

Pour commencer à écrire un programme Catala, vous devez partir du texte
d'une source législative qui va justifier le code que vous écrirez.
Concrètement, cela signifie faire un copier-coller du texte de la loi dans
un fichier de source Catala et le formater afin que Catala puisse le comprendre.
Les fichiers de source Catala ont l'extension ".catala_en" en version anglaise.
Si vous écriviez un programme Catala pour une loi française, vous devrez utiliser
l'extension ".catala_fr".

Vous pouvez écrire n'importe quel texte simple en Catala, cela sera affiché
sans modification dans une sortie PDF ou HTML. Vous pouvez découper votre texte
en de courtes lignes, cela apparaîtra comme un seul paragraphe dans la sortie.
Si vous voulez créer un nouveau paragraphe laisser une ligne vierge dans la source.

Catala vous permet de déclarer des entêtes de section ou de sous-section,
en les précédant et les suivant de deux signes dièze "#". Vous pouvez
diminuer l'importance du titre en augmentant le nombre de "#" après le titre de
l'entête.
Étudions un exemple fictif qui définit un impôt sur le revenu.

### Article 1

L'impôt sur le revenu d'un individu est calculé en tant qu'un pourcentage
fixe des revenus d'une personne pour une année.

```catala
# Bienvenue dans le mode code de Catala.
# Ceci est un commentaire car la ligne débute par le caractère #.
# Nous allons bientôt apprendre ce que l'on doit écrire ici pour traduire
# le sens d'un article de loi en code Catala.
```

Afin de faire cela, nous allons entremêler courts bouts de code et phrases
du texte législatif. Chaque bout de code devra être aussi court que possible
et aussi proche que possible de la phrase qui justifie le code. Ce style
s'appelle programmation littéraire, un paradigme de programmation inventé par le
célèbre informaticien Donald Knuth dans les années 70.

## Définir un impôt sur le revenu fictif

Le contenu de l'article 1 utilise beaucoup d'éléments du contexte implicite :
il existe une personne avec un revenu et en même temps un impôt sur le revenu,
qu'une personne doit acquitter chaque année. Même si ce contexte implicite n'est
pas inscrit en tant que tel dans la loi, nous devons l'expliciter pour le traduire
en code. Concrètement, nous avons besoin d'une section "métadonnées" qui définit
la forme et les types de données contenues dans la loi.

Commençons notre section métadonnées en déclarant l'information sur le type
personne :

```catala-metadata
déclaration structure Personne:
  # Le nom de la structure "Personne", doit commencer
  # par une lettre majuscule: c'est la convention CamelCase.
  donnée revenu contenu argent
  # A cette ligne, revenu est le nom du champ de la structure et
  # "argent" est le type de de données de ce champ.
  # On peut utiliser d'autres types comme : entier, décimal,
  # argent, date, durée ou tout autre structure ou énumération
  # que vous aurez déclaré
  donnée nombre_enfants contenu entier
  # "revenu" and "nombre_enfants" commençent par une lettre minuscule,
  # ils adhèrent à la convention snake_case
```

Cette structure contient deux champs de de données, "revenu" et "nombre_enfants".
Les structures sont utiles pour regrouper des données qui vont ensemble.
Typiquement, vous aurez une structure pour une entité concrète sur laquelle
s'applique la loi (comme une personne). C'est à vous de décider comment regrouper
les données mais vous devrez viser à optimiser la lisibilité du code.

Parfois, la loi donne une énumération de différentes situations. Ces énumérations
sont modélisés en Catala par le type énumération, comme suit :

```catala-metadata
déclaration énumération CréditImpôt:
# Le nom "CréditImpôt" s'écrit aussi en CamelCase
-- AucunCréditImpôt
# Cette ligne indique que "CréditImpôt" peut être en situation
# "AucunCréditImpôt"
-- CréditImpôtEnfants contenu entier
# Cette ligne indique, de manière alternative, que "CréditImpôt" peut aussi
# être une situation "CréditImpôtEnfants". Cette situation porte un contenu
# de type entier qui correspond 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 aussi accès à ce nombre d'enfants.
```

En informatique, une telle énumération est appelée "type somme" ou simplement
énumération. La combinaison de structures et d'énumération permet au programmeur
Catala de déclarer toutes les formes possibles de données, car cette combinaison
est équivalente à la puissante notion de types de données algébriques.

Nous avons défini et typé les données que le programme va manipuler. Maintenant,
nous devons définir un contexte logique dans lequel ces données vont évoluer.
On effectue cela par la notion de "champs d'application" en Catala.
Les champs d'application sont proches des fonctions en termes de programmation
traditionnelle. Les champs d'application doivent avoir été déclarés
préalablement dans les métadonnées, de la manière suivante:

```catala-metadata
déclaration champ d'application CalculImpôtRevenu:
  # Les champs d'application utilisent le CamelCase
  entrée personne contenu Personne
  # Cette ligne déclare un élémént de contexte du champ d'application,
  # cela ressemble à un paramètre de fonction en informatique. C'est la
  # donnée sur laquelle le champ d'application va intervenir
  interne pourcentage_fixe contenu décimal
  sortie impôt_revenu contenu argent
```

Nous avons maintenant tout ce dont nous avons besoin pour annoter le contenu
de l'article 1 qui a été copié ci-dessous.

### Article 1

L'impôt sur le revenu pour une personne est défini comme un pourcentage fixe
des revenus de la personne pour une année.

```catala
champ d'application CalculImpôtRevenu:
  définition impôt_revenu égal à
    personne.revenu *€ pourcentage_fixe
```

Dans le code, nous définissons à l'intérieur de notre champ d'application
le montant d'impôt sur le revenu selon la formule décrit dans l'article.
Quand nous définissons des formules, vous avez accès à tous les opérateurs
arithmétiques habituels : addition "+", soustraction "-", multiplication "*"
et division (barre oblique).

Toutefois, dans le code Catala, vous pouvez voir que nous utilisons "*€"
pour multiplier les revenus d'une personne par le pourcentage fixe. Le
suffixe € inique que nous effectuons une multiplication sur une somme d'argent.
En effet, en Catala, vous devez rester conscient de la donnée manipulée :
est-ce de l'argent ? est-ce un entier ? Utiliser simple "+" ou "*" est ambigu
en termes d'arrondis car l'argent est habituellement arrondi au centime.
Ainsi, afin d'être clair, nous suffixons ces opérations avec quelque chose
qui indique le type de donnée manipulé. Les suffixes sont "€" pour de l'argent,
"." pour les décimales, arobase (comme dans les adresses mail) pour les dates et
le symbole chapeau pour les durées. Si vous oubliez le suffixe, le vérificateur
de types de Catala va afficher une message d'erreur afin de vous aider à le placer
comme il le faut.

Mais dans l'article 1, une question reste sans réponse: quelle est la valeur
de la pourcentage fixe? Souvent, des valeurs précises sont définis ailleurs
dans les sources législatives. Ici, supposons que nous avons:

### Article 2

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

```catala
champ d'application CalculImpôtRevenu:
  définition pourcentage_fixe égal à 20%
  # Ecrire 20% est juste une abbréviation pour 0.20
```

Vous pouvez voir ici que Catala permet des définitions réparties dans toute
l'annotation du texte législatif, afin que chaque définition soit le plus
proche possible de sa localisation dans le texte.

## Définitions conditionnelles

Jusqu'à là tout va bien mais maintenant le texte législatif présente quelques
difficultés. Supposons que le troisième article dispose :

### Article 3

Si l'individu a à sa charge deux ou plus enfants alors
le pourcentage fixe mentionné à l'article 1 vaut 15 %.

```catala
# Comment redéfinir pourcentage_fixe ?
```

Cet article donne en réalité une autre définition pour le pourcentage fixe,
préalablement défini à l'article 2. Toutefois, si l'article 3 définit le pourcentage
de manière conditionnelle pour la personne ayant plus de deux enfants.
Catala permet de redéfinir précisément une variable sous une condition :

```catala
champ d'application CalculImpôtRevenu:
  définition pourcentage_fixe sous condition
    personne.nombre_enfants >= 2
  conséquence égal à 15%
  # Ecrire 15% est juste une abbréviation pour 0.15
```

Quand le programme Catala va s'exécuter, la juste définition sera choisie
dynamiquement en déterminant laquelle des condition est vraie dans le contexte.
Une source législative rédigée correctement doit toujours garantir qu'au maximum
une seule condition soit vraie à tout moment. Toutefois, si ce n'est pas le cas,
Catala vous permettra de définir un ordre des priorités sur les conditions,
qui doit être justifié par un raisonnement juridique.

## Fonctions

Catala vous permet de définir des fonctions partout dans vos données. Voici
à quoi cela ressemble dans la définition des métadonnées quand nous voulons
définir un calcul de l'impôt sur le revenu à deux tranches :

```catala-metadata
déclaration structure DeuxTranches:
  donnée seuil contenu argent
  donnée taux1 contenu décimal
  donnée taux2 contenu décimal

déclaration champ d'application CalculImpôtDeuxTranches :
  entrée tranches contenu DeuxTranches
  sortie formule_imposition contenu argent dépend de argent
```

Et dans le code :

### Article4

Le montant d'impôt pour le calcul à deux tranches
est égal au montant d'impôt dans chaque tranche multiplié
par le taux de chaque branche.

```catala
champ d'application CalculImpôtDeuxTranches :
  définition formule_imposition de revenu égal à
    si revenu <=€ tranches.seuil alors
      revenu *€ tranches.taux1
    sinon (
      tranches.seuil *€ tranches.taux1 +€
      (revenu -€ tranches.seuil) *€ tranches.taux2
    )
```

## Inclusion de champ d'application

Maintenant que nous avons défini notre champ d'application utilitaire pour
calculer un impôt à deux tranches, nous voulons l'utiliser dans notre champ
d'application principal de calcul de l'impôt.

### Article 5

Pour les individus dont le revenu est supérieur à 100 000€,
l'impôt sur le revenu de l'article 1 est de 40% du revenu au-dessus de
100 000€. En dessous de 100 000€, l'impôt sur le revenu est de 20% du revenu.

```catala
déclaration champ d'application NouveauCalculImpôtRevenu:
  deux_tranches champ d'application CalculImpôtDeuxTranches
  # Cette ligne indique que nous ajoutons l'élément deux_tranches au contexte.
  # Toutefois, les mots clé "champ d'application" indique que l'élément n'est
  # pas une donnée mais plutôt un sous-champ d'application qui peut être
  # utilisé pour calculer des choses.
  entrée personne contenu Personne
  sortie impôt_revenu contenu argent

champ d'application NouveauCalculImpôtRevenu :
  définition deux_tranches.tranches égal à DeuxTranches {
    -- seuil: 100 000€
    -- taux1: 20%
    -- taux2: 40%
  }
  définition impôt_revenu égal à
    deux_tranches.formule_imposition de personne.revenu
```

### Article 6

Les personnes ayant moins de 10 000€ de revenus sont exemptés de l'impôt
sur le revenu prévu à l'article 1.

```catala
champ d'application NouveauCalculImpôtRevenu:
  définition impôt_revenu sous condition
    personne.revenu <=€ 10 000€
  conséquence égal à 0€
```

Et voilà ! Nous avons défini un calcul d'impôt à deux tranches en annotant
tout simplement un texte législatif par des bouts de code Catala.
Cependant, les lecteurs attentifs auront vu quelque chose de curieux dans les
articles 5 et 6. Que se passe-t-il si le revenu d'une personne se situe entre
10 000€ et 100 000€ ?

La loi ne le précise pas; nos articles sont clairement mal rédigés.
Mais Catala vous aide à trouver ce genre d'erreur par de simples tests ou
même la vérification formelle. Commençons par les tests.

## Tester les programmes Catala

Tester les programmes Catala peut se faire directement en Catala. En effet,
écrire des cas de tests pour chaque champ d'application Catala que vous
définissez est une bonne pratique appelée "tests unitaires" dans la
communauté du génie logicielle. Les cas de test sont définis dans des
champ d'application :

### Tester NouveauCalculImpotRevenu

```catala
déclaration champ d'application Test1:
  calcul_impôt champ d'application NouveauCalculImpôtRevenu
  sortie impôt_revenu contenu argent

champ d'application Test1:
  définition
    calcul_impôt.personne
    # L'on définit le paramètre au sous-champ d'application
  égal à
    # Les quatre lignes ci-dessous définissent une structure entière
    # en valorisant chacun des champs
    Personne {
      -- revenu: 230 000€
      -- nombre_enfants: 0
    }

  définition impôt_revenu égal à calcul_impôt.impôt_revenu
  # Ensuite, nous récupérons le montant d'impôt, calculé par
  # sous-champ d'application et nous assertons qu'il vaut bien
  # la valeur attendue :
  # (230 000€ - 100 000€) * 40% + 100 000€ * 20% = 72 000€
  assertion impôt_revenu = 72 000€
```

Ce test devrait être bon. Maintenant étudions un test en échec :

```catala
déclaration champ d'application Test2:
  calcul_impôt champ d'application NouveauCalculImpôtRevenu
  sortie impôt_revenu contenu argent

champ d'application Test2:
  définition calcul_impôt.personne égal à Personne {
    -- revenu: 4 000€
    -- nombre_enfants: 0
  }

  définition impôt_revenu égal à calcul_impôt.impôt_revenu
  assertion impôt_revenu = 0€
```

Ce cas de test devrait calculer un impôt sur le revenu de 0€,
en raison de l'article 6. Mais au lieu de cela, l'exécution produira
une erreur car il y a un conflit entre les règles.

## Définir des exceptions à des règles

En effet, la définition d'un impôt sur le revenu à l'article 6 entre en
conflit avec la définition de l'article 5. Mais en réalité, l'article 6
est une simple exception à l'article 5. Dans la loi, il est implicite que
si l'article 6 est applicable, alors son application est prioritaire
sur l'article 5.

### Régler correctement le calcul

Cette priorité implicite doit être explicitement déclaré en Catala. Voici une
version correcte du champ d'application NouveauCalculImpotRevenu :

```catala
déclaration champ d'application NouveauCalculImpôtRevenuCorrect:
  deux_tranches champ d'application CalculImpôtDeuxTranches
  entrée personne contenu Personne
  sortie impôt_revenu contenu argent

champ d'application NouveauCalculImpôtRevenuCorrect :
  définition deux_tranches.tranches égal à DeuxTranches {
    -- seuil: 100 000€
    -- taux1: 20%
    -- taux2: 40%
  }


  # Pour définir une exception à une règle, vous devez d'abord étiquetter
  # la règle à laquelle vous voulez attacher l'exception. Vous pouvez mettre
  # n'importe quel identifiant en snake_case pour l'étiquette.
  étiquette article_5
  définition impôt_revenu égal à
    deux_tranches.formule_imposition de personne.revenu

  # Puis, vous pouvez déclarez l'exception par référence à l'étiquette
  exception article_5
  définition impôt_revenu sous condition
    personne.revenu <=€ 10 000€
  conséquence égal à 0€
```

Le test devrait désormais fonctionner :

```catala
déclaration champ d'application Test3:
  calcul_impôt champ d'application NouveauCalculImpôtRevenuCorrect
  sortie impôt_revenu contenu argent

champ d'application Test3:
  définition calcul_impôt.personne égal à Personne {
    -- revenu: 4 000€
    -- nombre_enfants: 0
  }
  définition impôt_revenu égal à calcul_impôt.impôt_revenu
  assertion impôt_revenu = 0€
```

## Conclusion

Ce tutoriel présente les concepts de base et la syntaxe des fonctionnalités
du langage Catala. C'est à vous de les utiliser pour annoter du texte
législatif avec leur traduction algorithmique.

Il n'y pas une seule bonne façon d'écrire des programmes Catala car le style de
programmation doit être adapté au texte de loi annoté. Cependant, Catala est un
langage basé sur la programmation fonctionnelle, donc suivre les
patrons de conception habituels de la programmation fonctionnelle
devrait aider à obtenir du code concis et lisible.