modifs.mineures sans commentaires

src/schema/README.md

@@ -4,67 +4,57 @@ les classes de ce package permettent de 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.
 
-les données dont on peut modéliser le schéma sont de 3 types:
+les données dont on peut modéliser le schéma sont de 3 types: scalaire, tableau
-* scalaire
+associatif ou liste. la nature du schéma (la valeur de la clé `"""`) indique le
-* tableau associatif
+type de donnée modélisée
-* liste (tableau séquentiel ou associatif d'éléments du même type)
+* donnée scalaire
 
-chaque type de données a une syntaxe spécifique pour la définition du schéma.
+  forme courante:
-
+  ~~~php
-## Nature de schéma
+  const SCALAR_SCHEMA = [
-
+    $type, [$default, $title, ...]
-Un schéma se présente sous la forme d'un tableau associatif avec des clés qui
+  ];
-dépendent de la nature du schéma. La nature du schéma est indiquée avec la clé
+  ~~~
-`""` (chaine vide), e.g
+  forme normalisée:
-~~~php
-const SCHEMA = [
-  "" => NATURE,
-];
-~~~
-
-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 = [
     $type, [$default, $title, ...]
     "" => "scalar",
   ];
   ~~~
-  Si le type est "array" ou "?array", on peut préciser le schéma de la donnée
+* tableau associatif
-  ~~~php
+  le tableau modélisé peut avoir des clés numériques ou chaines --> seules les
-  const SCALAR_SCHEMA = [
+  clés décrites par le schéma sont validées
-    "?array", [$default, $title, ...]
+
-    "" => "scalar",
+  forme courante:
-    "schema" => NAKED_SCHEMA,
-  ];
-  ~~~
-* 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 = [
     KEY => VALUE_SCHEMA,
     ...
-    "" => "assoc",
   ];
   ~~~
-  la nature "tableau associatif" est du sucre syntaxique pour une valeur
+  forme normalisée:
-  scalaire de type "?array" dont on précise le schéma
   ~~~php
-  // la valeur ci-dessus est strictement équivalent à
   const ASSOC_SCHEMA = [
-    "?array",
+    "?array", [$default, $title, ...]
-    "" => "scalar",
+    "" => "assoc",
     "schema" => [
       KEY => VALUE_SCHEMA,
       ...
     ],
   ];
   ~~~
+* liste (tableau d'éléments du même type)
+  le tableau modélisé peut avoir des clés numériques ou chaines --> on ne
+  modélise ni le type ni la valeur des clés
 
-* nature liste: modélise une liste de valeurs du même type (le tableau peut
+  forme courante:
-  avoir des clés numériques ou chaines --> on ne modélise ni le type ni la
+  ~~~php
-  valeur des clés)
+  const LIST_SCHEMA = [[
+    ITEM_SCHEMA,
+  ]];
+  ~~~
+  forme normalisée:
   ~~~php
   const LIST_SCHEMA = [
     "?array", [$default, $title, ...]
@@ -84,12 +74,9 @@ const SCALAR_SCHEMA = [
   "title" => "libellé de la valeur, utilisable par exemple dans un formulaire",
   "required" => "la valeur est-elle requise? si oui, elle doit exister",
   "nullable" => "si la valeur existe, peut-elle être nulle?",
-  "allow_null" => "si la valeur existe, peut-elle être nulle?", #XXX
-  "allow_empty" => "si la valeur existe, peut-elle être vide?", #XXX
   "desc" => "description de la valeur",
   "analyzer_func" => "XXX",
   "extractor_func" => "XXX",
-  "checker_func" => "XXX 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",
@@ -124,7 +111,7 @@ nature scalaire si:
 
 `messages` indique les messages à afficher en cas d'erreur d'analyse. les clés
 sont  normalisées et correspondent à différents états de la valeur tels
-qu'analysés par `checker_func`
+qu'analysés par `analyzer_func`
 ~~~php
 const MESSAGE_SCHEMA = [
   "missing" => "message si la valeur n'existe pas dans la source et qu'elle est requise",
@@ -137,23 +124,27 @@ const MESSAGE_SCHEMA = [
 
 ## Schéma d'un tableau associatif
 
-Dans sa forme *non normalisée*, un tableau associatif est généralement modélisé
+Dans la forme courante, on considère que c'est un schéma de nature associative si:
-de cette manière:
-~~~php
-const ASSOC_SCHEMA = [
-  KEY => VALUE_SCHEMA,
-  ...
-  "" => "assoc",
-];
-~~~
-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"]`
 
+La forme normalisée est
+~~~php
+const ASSOC_SCHEMA = [
+  "?array",
+  "" => "assoc",
+  "schema" => [
+    KEY => VALUE_SCHEMA,
+    ...
+  ],
+];
+~~~
+le type "?array" ou "array" indique si la liste est nullable ou non. la valeur
+par défaut est "?array"
+
+chaque occurrence de `KEY => VALUE_SCHEMA` définit le schéma de la valeur dont
+la clé est `KEY`
+
 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
@@ -176,14 +167,11 @@ récursivement, avec cependant l'ajout de quelques clés supplémentaires:
 
 ## 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
+Dans la forme courante, on considère que c'est un schéma de nature liste si:
-manière:
+* c'est un tableau avec un unique élément de type tableau à l'index 0, e.g
-~~~php
+  `[["string", null, "required" => true]]`
-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
+La forme normalisée est
 ~~~php
 const LIST_SCHEMA = [
   "?array",
@@ -194,9 +182,4 @@ const LIST_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

src/schema/TODO.md

@@ -1,8 +1,6 @@
 # nulib\schema
 
 * ScalarSchema::from_property()
-* AssocSchema === ScalarSchema(["array", "" => ["scalar", "subtype" => "assoc"]])
-* ListSchema === ScalarSchema(["array", "" => ["scalar", "subtype" => "list"]])
 * possibilité de spécifier un type via sa classe, e.g
   ~~~php
   Schema::ns($schema, [