Écrire des scripts .gl

Les fichiers .gl transforment une chaîne de commandes gapline en un artefact unique, versionnable. C’est le bon outil quand un nettoyage vaut la peine d’être rejoué chaque semaine, d’être livré dans un repo, ou d’être remis à un collègue comme pipeline reproductible.

Ce guide construit un script de correction hebdomadaire depuis zéro : valider, patcher les problèmes connus, revalider, sauvegarder.

Anatomie d’un fichier `.gl`

Un fichier .gl est du texte brut :

# Les commentaires commencent par '#'. Sur une ligne seule ou en fin de ligne.

feed ./data/gtfs.zip          # Première directive — charge le flux en mémoire.

validate --min-severity error # N'importe quelle commande gapline, sans le -f.

save ./data/gtfs-patched.zip  # Écriture atomique. Sans argument, écrase la source.

Trois points à retenir :

feed vient toujours en premier. Il charge l’archive une fois ; chaque commande suivante opère sur cette copie en mémoire.
save est explicite. Rien n’arrive au disque tant que save n’est pas exécuté — si le script plante en cours de route, le flux source est intact.
Stop-on-error. La première commande qui échoue stoppe le script. Combiné au point ci-dessus, cela rend les fichiers .gl sûrs à relancer.

La grammaire complète est sur syntaxe .gl ; la sémantique d’exécution est dans concepts / modèle de session .gl.

Un script de correction hebdomadaire

Objectif : chaque lundi matin, valider le flux de production, appliquer les nettoyages connus, remettre à l’équipe un rapport JSON frais.

# Charge le dernier flux déposé par la synchro de nuit.
feed ./data/gtfs.zip

# Purge la ligne retirée et tout ce qui la référence.
delete trips --where "route_id=OLD_LINE" --confirm
delete routes --where "route_id=OLD_LINE" --confirm

# Normalise les lignes de bus mal encodées.
update routes --where "route_type=700" --set route_type=3 --confirm

# Snapshot du rapport post-nettoyage pour l'équipe.
validate --format json -o ./reports/weekly.json

# Écriture atomique. N'est atteinte que si toutes les étapes ci-dessus ont réussi.
save ./data/gtfs-patched.zip

Lancer :

gapline run weekly-fix.gl

Si une commande échoue, l’exécution s’arrête, save est sauté, et ./data/gtfs.zip sur disque reste intact. Corrigez le problème remonté et relancez.

Flags de commandes dans un script

Tous les flags acceptés par le CLI fonctionnent dans un fichier .gl, avec une exception : -f / --feed est fourni par la directive feed, vous l’omettez sur chaque commande suivante. --output fonctionne toujours si vous voulez écrire un rapport intermédiaire à un autre chemin que celui de save.

feed ./data/gtfs.zip

# Le flag --feed est implicite — validate travaille sur la copie en mémoire.
validate --min-severity warning --format json -o pre-cleanup.json

update stops --where "stop_id=S01" --set stop_name="Gare Centrale" --confirm

validate --min-severity warning --format json -o post-cleanup.json

save

Appeler save sans chemin réécrit le fichier source — ici ./data/gtfs.zip. Passez un chemin pour préserver l’original.

Ce que `.gl` ne peut pas faire

Pas de variables, pas de substitution. Les chemins et valeurs sont littéraux.
Pas de conditions, pas de boucles, pas de try/catch. L’exécution est strictement linéaire.
Pas de run imbriqué. Un .gl ne peut pas appeler un autre .gl.

Si votre workflow a besoin de branchements ou de templating, pilotez gapline depuis un script shell et gardez le .gl compact. .gl est déclaratif par design — lisible d’un coup d’œil, sûr à versionner, pas de control flow caché.

Exécution en CI

- run: gapline run weekly-fix.gl
- uses: actions/upload-artifact@v4
  with: { name: weekly-reports, path: reports/ }
- run: |
    case $? in
      0) ;;  # Script terminé, save réussi.
      1) echo "Une étape a échoué — flux source intact." ; exit 1 ;;
      *) exit 1 ;;
    esac

Les codes de retour reflètent le code de la première sous-commande qui a échoué. Voir concepts / codes de retour.

Voir aussi

gapline run — la référence de la commande.
Référence / syntaxe .gl — grammaire des directives.
Concepts / modèle de session .gl — état en mémoire, sémantique de save.
Guides / Intégration CI.