From 932da9e00bb0489ae1e0a71b3b667449ed604395 Mon Sep 17 00:00:00 2001
From: Jephte Clain <Jephte.Clain@univ-reunion.fr>
Date: Mon, 20 Nov 2023 23:14:11 +0400
Subject: [PATCH] modifs.mineures sans commentaires

---
 doc/schema.md | 91 +++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 91 insertions(+)
 create mode 100644 doc/schema.md

diff --git a/doc/schema.md b/doc/schema.md
new file mode 100644
index 0000000..7a42a81
--- /dev/null
+++ b/doc/schema.md
@@ -0,0 +1,91 @@
+# nulib\schema
+
+objet: s'assurer que des données soit dans un type particulier, en les
+convertissant si nécessaire. la source de ces données peut-être diverse:
+formulaire web, résultat d'une requête SQL, flux CSV, etc. mais en définitive,
+les données qui sont traitées par du code PHP sont du bon type et au bon
+format, ou une erreur est levée.
+
+## Schéma d'une valeur simple
+
+Une valeur scalaire est modélisée de cette manière:
+~~~php
+const SIMPLE_SCHEMA = [
+    "type" => "types autorisés de la valeur",
+    "default" => "valeur par défaut si la valeur n'existe pas",
+    "title" => "libellé de la valeur, utilisable par exemple dans un formulaire",
+    "desc" => "description de la valeur",
+    "required" => "la valeur est-elle requise? si oui, elle doit exister",
+    "nullable" => "si la valeur existe, peut-elle être nulle?",
+    "checker_func" => "une fonction qui vérifie une valeur et la classifie",
+    "parser_func" => "une fonction qui analyse une chaine pour produire la valeur",
+    "messages" => "messages à afficher en cas d'erreur d'analyse",
+    "formatter_func" => "une fonction qui formatte la valeur pour affichage",
+    "format" => "format à utiliser pour l'affichage",
+    "" => "nature du schéma: scalar",
+];
+~~~
+
+Le schéma d'une valeur simple peut avoir les formes suivantes:
+- la forme normalisée contient la nature de schéma qui vaut `scalar` et toutes
+  les autres clés spécifiées ci-dessus
+- la forme habituelle qui a au moins une valeur de type chaine et d'index 0 pour le type
+
+par exemple, les deux schémas suivants sont équivalents:
+~~~php
+const NORMALIZED = [
+    "" => ["scalar"],
+    "type" => "string",
+    "default" => null,
+    "title" => "valeur chaine",
+    "desc" => "une description plus longue",
+    "required" => false,
+    "nullable" => true,
+    ...
+];
+const SIMPLE = [
+    "?string", null, "valeur chaine",
+    "desc" => "une valeur chaine quelconque",
+    ...
+];
+~~~
+
+## Schéma d'une liste séquentielle
+
+Une liste séquentielle est modélisée de cette manière:
+~~~php
+const LIST_SCHEMA = [SIMPLE_SCHEMA];
+~~~
+
+Ce schéma a un unique élément d'index 0, qui représente le schéma de chaque
+élément de la liste
+
+~~~php
+const NORMALIZED = [
+    "" => ["list",
+      "title" => "liste de valeurs chaines",
+      "desc" => "une description plus longue",
+      "required" => false,
+      "nullable" => true,
+    ],
+    ITEM_SCHEMA,
+];
+~~~
+
+## Schéma d'un tableau associatif
+
+
+~~~php
+const NORMALIZED = [
+    "" => ["assoc",
+      "title" => "liste de valeurs chaines",
+      "desc" => "une description plus longue",
+      "required" => false,
+      "nullable" => true,
+    ],
+    KEY => VALUE_SCHEMA,
+    ...
+];
+~~~
+
+-*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary
\ No newline at end of file