Modèle de session .gl

Un script .gl est une séquence de commandes gapline qui partagent un seul flux en mémoire. Plutôt que de relire le ZIP à chaque étape, le runner charge une fois, applique chaque commande à la copie de travail, et ne touche le disque qu’à la directive save. C’est ce qui rend les pipelines de nettoyage multi-étapes rapides et atomiques.

Cycle de vie d’une session

Un script s’exécute en trois phases :

1. Chargement. La première directive feed <path> charge l’archive en mémoire. Les commandes suivantes sautent le flag -f — elles opèrent sur le flux chargé.
2. Mutation. validate, read, create, update, delete tournent sur le flux en mémoire, dans l’ordre. Chaque commande voit l’état laissé par la précédente.
3. Persistance. Une directive save [path] réécrit les fichiers modifiés sur disque de façon atomique. Sans save, le script sort sans toucher au flux original.

Si save est passé sans argument, gapline réécrit au chemin passé à feed. Passer un chemin différent est l’équivalent scripté de --output sur une commande seule : le flux source reste intact.

Stop-on-error

L’exécution est strictement séquentielle et stop-on-error. Dès qu’une commande échoue — erreur de parse, garde de validation refusée, refus FK — le runner s’arrête et le processus sort non nul.

Quand le script s’arrête en cours :

• Tout ce qui est avant l’échec est déjà appliqué en mémoire.
• Rien n’est persisté sauf si un save avait déjà réussi plus tôt dans le script.
• Le flux source sur disque est intact.

C’est un compromis délibéré : cela signifie que les scripts .gl sont sûrs à relancer après correction d’un problème amont, sans risque de ZIP partiellement réécrit.

Pourquoi en mémoire

Faire tourner validate → update → validate → save sans session reparserait le ZIP trois fois (une par commande). C’est gâcher — parser un stop_times.txt de plusieurs millions de lignes domine le coût de chaque étape.

Avec une session :

• Seule la première directive feed paie le coût du parse.
• Les mutations restent en RAM, avec les mêmes structures d’index inverse utilisées pour l’intégrité.
• Le save final sérialise les fichiers modifiés en une seule passe.

Chiffres typiques sur un flux d’opérateur moyen : cinq opérations CRUD plus deux validations en moins d’une seconde ; le même pipeline en sept invocations gapline … indépendantes prend plusieurs secondes.

Ce qu’un script peut et ne peut pas faire

Supporté :

• Toutes les sous-commandes top-level (validate, read, create, update, delete) sans le flag -f.
• Commentaires avec #, sur leur propre ligne ou en fin de ligne de directive.

Non supporté, volontairement :

• Variables, substitution, interpolation.
• Conditions, boucles, branchement.
• run imbriqué (un .gl ne peut pas appeler un autre .gl).

.gl est un format batch déclaratif, pas un langage de script. Pour tout ce qui dépasse un pipeline linéaire, retombez sur un script shell qui orchestre plusieurs appels gapline.

Exemple minimal

minimal.gl

feed ./data/gtfs.zip
validate
save

Charge le flux, le valide, le réécrit à ./data/gtfs.zip. L’écriture est atomique : aucun lecteur concurrent ne voit une archive à moitié écrite.

Voir aussi

• gapline run — la commande qui exécute un script .gl.
• Référence / syntaxe .gl — directives et grammaire.
• Guides / Écrire des scripts .gl — parcours complet.