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: scalaire, tableau associatif ou liste. la nature du schéma (la valeur de la clé """) indique le type de donnée modélisée

donnée scalaire

forme courante:

const SCALAR_SCHEMA = [
  $type, [$default, $title, ...]
];

forme normalisée:

const SCALAR_SCHEMA = [
  $type, [$default, $title, ...]
  "" => "scalar",
];

tableau associatif le tableau modélisé peut avoir des clés numériques ou chaines --> seules les clés décrites par le schéma sont validées

forme courante:

const ASSOC_SCHEMA = [
  KEY => VALUE_SCHEMA,
  ...
];

forme normalisée:

const ASSOC_SCHEMA = [
  "?array", [$default, $title, ...]
  "" => "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

forme courante:
```
const LIST_SCHEMA = [[
  ITEM_SCHEMA,
]];
```
forme normalisée:
```
const LIST_SCHEMA = [
  "?array", [$default, $title, ...]
  "" => "list",
  "schema" => ITEM_SCHEMA,
];
```

Schéma d'une valeur scalaire

Dans sa forme normalisée, une valeur scalaire est généralement modélisée de cette manière:

const SCALAR_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",
  "required" => "la valeur est-elle requise? si oui, elle doit exister",
  "nullable" => "si la valeur existe, peut-elle être nulle?",
  "desc" => "description de la valeur",
  "analyzer_func" => "XXX",
  "extractor_func" => "XXX",
  "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",
  "" => "scalar",
  "schema" => "schéma de la valeur si le type est array ou ?array, null sinon",
];

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:

const SCALAR_SCHEMA1 = [
  "string", null, "une valeur chaine",
];
const SCALAR_SCHEMA2 = [
  "type" => "string",
  "default" => null,
  "title" => "une valeur chaine",
  "" => "scalar",
];

Si la nature du schéma n'est pas spécifiée, on considère que c'est un schéma de nature scalaire si:

c'est une chaine, qui représente alors le type, e.g "string"
c'est un tableau avec un unique élément à l'index 0 de type chaine, qui est aussi le type, e.g ["string"]
c'est un tableau avec un élément à l'index 0, ainsi que d'autres éléments, e.g ["string", null, "required" => true]

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 analyzer_func

const MESSAGE_SCHEMA = [
  "missing" => "message si la valeur n'existe pas dans la source et qu'elle est requise",
  "unavailable" => "message si la valeur vaut false dans la source et qu'elle est requise",
  "null" => "message si la valeur est nulle et qu'elle n'est pas nullable",
  "empty" => "message si la valeur est une chaine vide et que ce n'est pas autorisé",
  "invalid" => "message si la valeur est invalide",
];

Schéma d'un tableau associatif

Dans la forme courante, 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

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

VALUE_SCHEMA = [
  ...
  "name" => "identifiant de la valeur",
  "pkey" => "chemin de clé de la valeur dans le tableau associatif",
];

s'il s'agit d'une valeur scalaire simple autre que array

VALUE_SCHEMA = [
  ...
  "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 la forme courante, 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]]

La forme normalisée est

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"

-- coding: utf-8 mode: markdown -- vim:sw=4:sts=4:et:ai:si:sta:fenc=utf-8:noeol:binary