From 08d5327afa318c344308f01ef3b0eed7487aa1b6 Mon Sep 17 00:00:00 2001 From: Jephte Clain Date: Mon, 10 Mar 2025 04:31:35 +0400 Subject: [PATCH] modifs.mineures sans commentaires --- src/schema/README.md | 121 +++++++++++++++++++------------------------ src/schema/TODO.md | 2 - 2 files changed, 52 insertions(+), 71 deletions(-) diff --git a/src/schema/README.md b/src/schema/README.md index 499ce69..200cee4 100644 --- a/src/schema/README.md +++ b/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: -* scalaire -* tableau associatif -* liste (tableau séquentiel ou associatif d'éléments du même type) +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 -chaque type de données a une syntaxe spécifique pour la définition du schéma. - -## Nature de schéma - -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 -~~~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 + forme courante: + ~~~php + const SCALAR_SCHEMA = [ + $type, [$default, $title, ...] + ]; + ~~~ + forme normalisée: ~~~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 - ~~~php - const SCALAR_SCHEMA = [ - "?array", [$default, $title, ...] - "" => "scalar", - "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) +* 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: ~~~php const ASSOC_SCHEMA = [ 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 + forme normalisée: ~~~php - // la valeur ci-dessus est strictement équivalent à const ASSOC_SCHEMA = [ - "?array", - "" => "scalar", + "?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 -* 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) + forme courante: + ~~~php + 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é -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: +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 +~~~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 -manière: -~~~php -const LIST_SCHEMA = [ITEM_SCHEMA]; -~~~ -où ITEM_SCHEMA est le schéma des éléments de la liste +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]]` -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 \ No newline at end of file diff --git a/src/schema/TODO.md b/src/schema/TODO.md index bbd1432..92fcbc0 100644 --- a/src/schema/TODO.md +++ b/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, [