Module JSON

La chaîne de traitement

Le paquet json est écrit en Vitte et ne déclare pas de dépendance native dans package.toml. Le chemin ordinaire transforme un texte en tokens, construit une valeur Vitte, puis peut réencoder cette valeur :

texte JSON → lexer → tokens → parser → JsonValue → encodeur → texte JSON

Espace	Rôle	Point d’entrée utile
json::core::value	Valeurs, membres, constructeurs, accès, égalité et validation.	JsonValue, JsonValueKind
json::parser::parser	Lexer puis lecture d’un document complet et production de diagnostics.	parse, parse_strict
json::encode::encoder	Sérialisation compacte ou mise en forme lisible.	encode, encode_pretty
json::lexer	Tokens et séquences d’échappement JSON.	lex, decode_escape
json::error	Positions, plages source et modèles de diagnostic.	JsonSpan, human_line
json::runtime::numeric	Validation, conversion et formatage des nombres JSON.	parse_i64, parse_f64

Installer et importer

Depuis la racine du dépôt, les sources du module sont sous modules/json. Pour les compiler avec le compilateur du dépôt, indique le répertoire qui contient le namespace json :

VITTE_MODULE_PATH="$PWD/modules" build/bin/vitte compile application.vit -o application

Une installation du paquet depuis la racine du dépôt se fait avec :

make -C modules/json install PREFIX="$HOME/.local"

Le manifeste modules/json/package.toml nomme le paquet json, indique json.vit comme entrée et définit la syntaxe de chemin de module avec ::. Le manifeste décrit le paquet ; il ne constitue pas un gestionnaire de dépendances Vitte.

Lire, puis vérifier le résultat

Les opérations renvoient des formes de résultat avec un champ ok. Vérifie-le avant de lire value, text ou un autre contenu de sortie. Voici le flux d’usage présenté dans le guide du module :

use json::parser::parser::{JsonParseResult, parse_strict};
use json::encode::encoder::{JsonEncodeResult, encode_pretty};

proc reformater(source: string) {
    let parsed: JsonParseResult = parse_strict(source);
    if !parsed.ok {
        // parsed.diagnostic donne le détail de l’échec.
        give;
    }

    let encoded: JsonEncodeResult = encode_pretty(&parsed.value);
    if !encoded.ok {
        // Ne pas utiliser encoded.text en cas d’échec.
        give;
    }

    // encoded.text contient le JSON mis en forme.
    give;
}

Les valeurs JSON

JsonValue représente null, les booléens, les nombres, les chaînes, les tableaux et les objets. Le module distingue les nombres entiers et flottants avec JsonValueKind.Integer et JsonValueKind.Float. Cette distinction aide à choisir les conversions sans transformer systématiquement tous les nombres en flottants.

let absent: JsonValue = null();
let actif: JsonValue = boolean(true);
let nombre: JsonValue = integer(42);
let mesure: JsonValue = floating(21.5);
let texte: JsonValue = string("Vitte");
let vide: JsonValue = empty_array();

let version: JsonMember = member("version", integer(1));
let paquet: JsonValue = object([version]);

Pour inspecter une valeur, teste son genre avec is_null, is_bool, is_integer, is_float, is_string, is_array ou is_object. Les fonctions array_len, array_get_ref, object_len et object_get_ref donnent accès aux contenus. Vérifie le type et la présence des champs avant de les utiliser dans les règles métier de ton application.

Le modèle conserve l’ordre de lecture des membres d’un objet pour l’encodage, mais l’égalité structurelle des objets ne dépend pas de cet ordre. L’ordre des éléments d’un tableau reste significatif.

Parser et clés dupliquées

parse(source) effectue le lexing et lit un document JSON complet. Il exige une valeur racine et rejette les tokens qui la suivent. parse_strict(source) applique la même grammaire, mais refuse les clés d’objet répétées. Les variantes parse_tokens et parse_tokens_strict prennent une suite de tokens déjà produite par le lexer.

Pour les entrées de configuration ou de réseau, préfère parse_strict : si deux clés portent le même nom, différents consommateurs peuvent sinon retenir des valeurs différentes. JSON ne permet pas les commentaires, les clés non citées, les guillemets simples ou les virgules finales.

Diagnostics et positions

En cas d’échec, JsonParseResult.diagnostic contient entre autres le code, le message, le détail, une suggestion éventuelle, la valeur attendue et trouvée, la clé et un JsonSpan. Les suggestions sont informatives ; elles ne modifient pas automatiquement le document.

Les coordonnées de JsonPosition sont comptées à partir de zéro. Pour afficher une ligne ou une colonne à une personne, utilise human_line et human_column, qui produisent des numéros commençant à un. Les plages source servent à pointer l’erreur ou les occurrences liées dans un éditeur.

Encoder du JSON

encode et encode_compact produisent une sortie compacte ; encode_pretty utilise une indentation de deux espaces. encode_pretty_with_indent(value, indent) choisit l’indentation. Le résultat JsonEncodeResult fournit ok, text et error : n’utilise text qu’après avoir vérifié ok.

L’encodeur vérifie les valeurs, les nombres et les chaînes, refuse les clés dupliquées et impose une profondeur maximale. L’espace json::encode::escape fournit aussi des fonctions pour échapper ou citer une chaîne indépendamment d’un arbre JSON ; ne le confonds pas avec l’encodeur complet.

Unicode, nombres et limites

Le lexer reconnaît les échappements JSON, dont \uXXXX. Les paires de surrogates UTF-16 sont composées en scalaire Unicode ; les surrogates isolés sont refusés. Le runtime numérique expose notamment scan, valid, parse_i64, parse_u64, parse_f64 et les fonctions de formatage correspondantes. Les conversions refusent les dépassements et les résultats flottants non finis.

Les valeurs par défaut inscrites dans parser/parser.vit sont une profondeur maximale de 512, 1 048 576 valeurs, éléments de tableau ou membres d’objet, et une longueur maximale de clé de 16 777 216. Le type JsonParserLimits est exposé, mais les quatre fonctions de parsing exportées utilisent les limites par défaut : le code actuel ne fournit pas d’entrée publique de parsing avec limites personnalisées.

Vérifier le module dans son dépôt

Le Makefile du module propose des cibles pour vérifier les sources, les suites d’encodage, le parser, Unicode, les nombres et l’installation :

make -C modules/json check
make -C modules/json test-encode test-runtime test-invalid test-parse \
    test-roundtrip test-string-concat test-unicode

Cette page documente les cibles déclarées dans modules/json/Makefile ; elle ne signifie pas que ces suites ont été exécutées pour chaque version du compilateur. La matrice d’état du compilateur et les sources du dépôt permettent de vérifier la compatibilité de ta cible.

Documentation complète et éditions PDF

• Guide détaillé dans le dépôt : API, diagnostics, cas d’usage, sécurité et référence rapide.
• README du paquet : imports, installation et compatibilité.
• PDF français joint à l’issue #17 · PDF anglais.
• Issue #17 : autres fichiers PDF et suivi de la documentation.

Le PDF français porte lui-même la mention « édition de travail » et demande de vérifier ses signatures et commandes dans le dépôt. Utilise-le comme document pédagogique complémentaire, pas comme spécification des fonctions exportées.