Merge branch 'master' of https://git.univ-reunion.fr/sda-php/nur-sery

src/schema/README.md

@@ -2,14 +2,12 @@
 
 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.
+formulaire web, résultat d'une requête SQL, flux CSV, etc.
 
 les données dont on peut modéliser le schéma sont de 3 types:
 * scalaire
-* liste (tableau séquentiel)
 * tableau associatif
+* liste (tableau séquentiel ou associatif d'éléments du même type)
 
 chaque type de données a une syntaxe spécifique pour la définition du schéma.
 
@@ -28,41 +26,57 @@ La nature indique le type de données représenté par le schéma.
 * nature scalaire: modélise une donnée scalaire
   ~~~php
   const SCALAR_SCHEMA = [
-    "" => ["scalar"],
-    ...
+    $type, [$default, $title, ...]
+    "" => "scalar",
   ];
   ~~~
-* nature liste: modélise une liste de valeurs du même type
+  Si le type est "array" ou "?array", on peut préciser le schéma de la donnée
   ~~~php
-  const LIST_SCHEMA = [
-    "" => ["list",
-      "title" => "libellé de la valeur",
-      "required" => false,
-      "nullable" => true,
-      "desc" => "description de la valeur",
-      "name" => "identifiant de la valeur",
-    ],
-    ITEM_SCHEMA,
+  const SCALAR_SCHEMA = [
+    "?array", [$default, $title, ...]
+    "" => "scalar",
+    "schema" => NAKED_SCHEMA,
   ];
   ~~~
-* nature tableau associatif: modélise un tableau associatif
+* nature tableau associatif: modélise un tableau associatif (le tableau peut
+  avoir des clés numériques ou chaines --> seules les clés décrites par le
+  schéma sont validées)
   ~~~php
   const ASSOC_SCHEMA = [
-    "" => ["assoc",
-      "title" => "libellé de la valeur",
-      "required" => false,
-      "nullable" => true,
-      "desc" => "description de la valeur",
-      "name" => "identifiant de la valeur",
-    ],
     KEY => VALUE_SCHEMA,
     ...
+    "" => "assoc",
+  ];
+  ~~~
+  la nature "tableau associatif" est du sucre syntaxique pour une valeur
+  scalaire de type "?array" dont on précise le schéma
+  ~~~php
+  // la valeur ci-dessus est strictement équivalent à
+  const ASSOC_SCHEMA = [
+    "?array",
+    "" => "scalar",
+    "schema" => [
+      KEY => VALUE_SCHEMA,
+      ...
+    ],
+  ];
+  ~~~
+
+* nature liste: modélise une liste de valeurs du même type (le tableau peut
+  avoir des clés numériques ou chaines --> on ne modélise ni le type ni la
+  valeur des clés)
+  ~~~php
+  const LIST_SCHEMA = [
+    "?array", [$default, $title, ...]
+    "" => "list",
+    "schema" => ITEM_SCHEMA,
   ];
   ~~~
 
 ## Schéma d'une valeur scalaire
 
-Une valeur scalaire est modélisée de cette manière:
+Dans sa forme normalisée, une valeur scalaire est généralement modélisée de
+cette manière:
 ~~~php
 const SCALAR_SCHEMA = [
   "type" => "types autorisés de la valeur",
@@ -76,13 +90,14 @@ const SCALAR_SCHEMA = [
   "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",
-  "" => ["scalar"],
-  "name" => "identifiant de la valeur",
+  "" => "scalar",
+  "schema" => "schéma de la valeur si le type est array ou ?array, null sinon",
 ];
 ~~~
 
-L'ordre des clés du schéma indique la clé associé à une valeur si elle fournie
-dans un tableau séquentiel. Par exemple, les deux schéma suivants sont équivalents:
+L'ordre des clés du schéma ci-dessus indique la clé associé à une valeur si elle
+est fournie dans un tableau séquentiel. Par exemple, les deux schéma suivants
+sont équivalents:
 ~~~php
 const SCALAR_SCHEMA1 = [
   "string", null, "une valeur chaine",
@@ -91,7 +106,7 @@ const SCALAR_SCHEMA2 = [
   "type" => "string",
   "default" => null,
   "title" => "une valeur chaine",
-  "" => ["scalar"],
+  "" => "scalar",
 ];
 ~~~
 
@@ -116,71 +131,67 @@ const MESSAGE_SCHEMA = [
 ];
 ~~~
 
-## Schéma d'une liste (tableau séquentiel)
-
-Une liste est modélisée de cette manière:
-~~~php
-const LIST_SCHEMA = [
-  ITEM_SCHEMA,
-  "" => ["list"],
-];
-~~~
-où ITEM_SCHEMA est le schéma des éléments de la liste
-
-Si la nature du schéma n'est pas spécifiée, on considère que c'est un schéma de
-nature liste si:
-* c'est un tableau avec un unique élément de type tableau à l'index 0, e.g
-  `[["string", null, "required" => true]]`
-
 ## Schéma d'un tableau associatif
 
-Un tableau associatif est modélisée de cette manière:
+Dans sa forme *non normalisée*, un tableau associatif est généralement modélisé
+de cette manière:
 ~~~php
 const ASSOC_SCHEMA = [
   KEY => VALUE_SCHEMA,
   ...
-  "" => ["assoc"],
+  "" => "assoc",
 ];
 ~~~
-où l'ensemble des occurrences de `KEY => VALUE_SCHEMA` définit le schéma de la
-valeur dont la clé est `KEY`
+où chaque occurrence de `KEY => VALUE_SCHEMA` définit le schéma de la valeur
+dont la clé est `KEY`
 
 Si la nature du schéma n'est pas spécifiée, on considère que c'est un schéma de
 nature associative si:
 * c'est un tableau uniquement associatif avec aucun élément séquentiel, e.g
   `["name" => "string", "age" => "int"]`
 
-VALUE_SCHEMA peut-être un schéma de nature scalaire, liste ou associative.
-
-S'il s'agit d'une valeur scalaire, il y a quelques clés de définitions
-supplémentaires:
-~~~php
-const VALUE_SCHEMA = [
-  ...
-  "pkey" => "chemin de clé de la valeur dans le tableau associatif",
-  "header" => "nom de l'en-tête s'il faut présenter cette donnée dans un tableau",
-  "composite" => "ce champ fait-il partie d'une valeur composite?",
-];
-~~~
-
-Pour une liste, il y a quelques clés de définitions supplémentaires:
-~~~php
-const VALUE_SCHEMA = [
-  "" => ["list",
+VALUE_SCHEMA peut-être n'importe quel schéma valide, qui sera analysé
+récursivement, avec cependant l'ajout de quelques clés supplémentaires:
+* description de la valeur dans le contexte du tableau
+  ~~~php
+  VALUE_SCHEMA = [
     ...
+    "name" => "identifiant de la valeur",
     "pkey" => "chemin de clé de la valeur dans le tableau associatif",
-  ],
-];
-~~~
-
-Pour une tableau associatif, il y a quelques clés de définitions supplémentaires:
-~~~php
-const VALUE_SCHEMA = [
-  "" => ["assoc",
+  ];
+  ~~~
+* s'il s'agit d'une valeur scalaire simple autre que array
+  ~~~php
+  VALUE_SCHEMA = [
     ...
-    "pkey" => "chemin de clé de la valeur dans le tableau associatif",
-  ],
+    "header" => "nom de l'en-tête s'il faut présenter cette donnée dans un tableau",
+    "composite" => "ce champ fait-il partie d'une valeur composite?",
+  ];
+  ~~~
+
+## Schéma d'une liste (tableau séquentiel ou associatif d'éléments du même type)
+
+Dans sa forme *non normalisée*, une liste est généralement modélisée de cette
+manière:
+~~~php
+const LIST_SCHEMA = [ITEM_SCHEMA];
+~~~
+où ITEM_SCHEMA est le schéma des éléments de la liste
+
+Pour information, la forme normalisée est plutôt de la forme
+~~~php
+const LIST_SCHEMA = [
+  "?array",
+  "" => "list",
+  "schema" => ITEM_SCHEMA,
 ];
 ~~~
+le type "?array" ou "array" indique si la liste est nullable ou non. la valeur
+par défaut est "?array"
+
+Si la nature du schéma n'est pas spécifiée, on considère que c'est un schéma de
+nature liste si:
+* c'est un tableau avec un unique élément de type tableau à l'index 0, e.g
+  `[["string", null, "required" => true]]`
 
 -*- coding: utf-8 mode: markdown -*- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary