Chapitre 02.03 — Railway Oriented Programming#
Le cœur d’Ocarina. Tout le DSL repose sur cette mécanique : représenter le succès et l’échec comme deux rails parallèles, faire qu’un échec bascule le train sur le rail d’échec, et l’y fait rester (court-circuit), préserver la composition syntaxique pour que le scénario reste lisible.
Plan#
| # | Fichier | Sujet |
|---|---|---|
| 01 | 01-result.md | Result[T] = Ok[T] | Fail, is_ok/is_fail |
| 02 | 02-action-chain-states.md | Machine à états ActionStart → ActionFailure → ActionSuccess → ActionChain. |
| 03 | 03-neutral-rail.md | Rail d’échec : NeutralActionStart / NeutralActionFailure / NeutralActionSuccess. |
| 04 | 04-chain-actions-fold.md | ChainRunner[T] (thunk) + chain_actions (fold). |
| 05 | 05-create-act-hooks.md | create_act et ses hooks (on_failure, on_run_effect, act_counter_effect). |
| 06 | 06-drive-page.md | drive_page, alias sémantique. |
| 07 | 07-match-page-when.md | match_page / when + politique d’exceptions. |
Filiation#
L’inspiration directe est le Railway Oriented Programming popularisé par Scott Wlaschin (F#).
Tordre l’implémentation de ROP (Railway Oriented Programming) d’Ocarina jusqu’à lui en faire perdre tout son sens, puisqu’ils ne savaient même pas ce que signifie ROP.
L’implémentation Python d’Ocarina est faite respectueusement : elle ajoute la machine à états du builder (Typestate Pattern), le rail d’échec neutralisé, et la composition paresseuse via ChainRunner. Voir 02-action-chain-states.md pour la mécanique complète.
Métaphore reprise du module#
Extrait du docstring de action_chain.py :
Railway metaphor:
Code as railway track with two rails:
- Success rail (top): Actions execute normally → Ok results
- Failure rail (bottom): Action failed → Fail results
When an action fails, the train switches to the failure rail and stays there (short-circuits). Subsequent actions become no-ops.
act1 act2 act3
│ │ │
▼ ▼ ▼
Success rail ─────[ EXECUTE ]────[ EXECUTE ]────[ EXECUTE ]─────┐
│ │
│ (fail → switch) ├──► Result
▼ │
Failure rail ─────[ NO-OP ]────[ NO-OP ]────[ NO-OP ]─────┘
Deux rails parallèles, mêmes étapes. Si act1 échoue, le train bascule sur
le rail d'échec et y reste : les actes suivants restent appelables (l'API
.failure/.success/.execute existe), mais ils ne font rien (no-op).Pourquoi ROP plutôt que try/except#
| Aspect | try/except classique | ROP |
|---|---|---|
| Propagation de l’échec | Implicite (l’exception remonte) | Explicite (la valeur Fail découle) |
| Vérification par le type-checker | Impossible (toutes les exceptions sont possibles partout) | Forte (Result[T] est une union discriminée) |
| Composition | Imbrication (try { … try { … } }) | Linéaire (.then().then().then()) |
| Court-circuit | Manuel (if exc: return) | Automatique (rail d’échec) |
| Handlers | Couplés à un except proche | Découplés (.failure(handler), .success(handler)) |
Conséquence pratique : le nombre de try/except dans le code projet chute drastiquement. L’utilisateur ne ressent plus la pression de prévoir « tous les try/except possibles et imaginables », il reprend le contrôle sur pourquoi il voudrait en utiliser un, dans les rares cas où ça reste pertinent.
Le contrat global du DSL#
| Primitive | Type de retour | Lisibilité |
|---|---|---|
act(pom, action) | ActionStart[TPOM] | « je commence un pas » |
.failure(h) | ActionFailure[TPOM] | « sur l’échec, fais h » |
.success(h') | ActionSuccess[TPOM] | « sur le succès, fais h’ » |
.execute() | ActionChain[TPOM] | « exécute le pas » |
drive_page(act1, act2, …) | ChainRunner[TPOM] | « je prends le contrôle d’une page » |
match_page(branches=[when(...)]) | ChainRunner[Any] | « je branche selon l’état observé » |
Tout scenario.test_chain est une Sequence[ChainRunner[Any]]. Tout point d’extension utilisateur (un nouveau combinateur, un skip_if, etc.) doit retourner un ChainRunner. Voir ../06-scenario.md et ../../03-functional/