Référence du langage de templates de Cybertrain

01Ce qui est du Ruby ici, et ce qui n’en est pas

Les templates ne sont pas du Ruby. Spinel (le compilateur AOT de Ruby de Matz que vise cybertrain) n’a pas d’eval, donc « interpréter le Ruby propre à la vue au moment de la requête » n’a jamais été envisageable (D9 dans docs/design.md) ; ce qui s’exécute à la place est une petite grammaire fermée qui ne fait qu’emprunter une syntaxe d’allure ERB/Ruby. Il n’y a pas de Ruby arbitraire dans une balise — seulement ce que ExprParser (parser.rb) reconnaît comme instruction ou expression. Il n’y a pas d’eval, de send, d’instance_eval, de définitions de méthodes/classes/modules, de require, d’exceptions (begin/rescue), de case/when, d’intervalles, de regex, ni d’affectation multiple. Les seuls blocs sont each, each_with_index et un appel à un helper (form_with(...) do |f| ... end) — pas de blocs { }, pas de map/select ni d’autre méthode d’Enumerable avec bloc. Chaque appel de méthode (recv.name) est résolu par des tables de dispatch case écrites à la main dans interpreter.rb, indexées par la classe Ruby du receveur à l’exécution ; un nom absent de la table de ce type échoue avec une RuntimeError — il n’y a pas de method_missing, pas de réflexion, et (d’après Interpreter#call_method) c’est précisément l’absence de send dans Spinel qui fait que c’est un case et non une recherche par métaprogrammation. Un template ne peut faire que ce que décrit ce document.

02Balises

Contrôle des espaces (Lexer.tokenize) :

• Une balise <% %>/<%# %> qui est la seule chose sur sa ligne (rien que des espaces/tabulations de part et d’autre jusqu’aux sauts de ligne) avale silencieusement sa propre indentation et son saut de ligne final, comme le mode trim de l’ERB de Rails. <%= %>/<%== %> ne sont jamais rognées automatiquement de cette façon, même seules sur une ligne.
• <%- supprime explicitement les espaces/tabulations qui précèdent la balise, et -%> supprime le saut de ligne qui la suit immédiatement — pour tout type de balise. Les deux sont sans effet quand autre chose que des espaces occupe ce côté de la ligne.
• <%% dans le texte est un <% littéral ; %%> dans une balise est un %> littéral qui ne ferme pas la balise.
• <% # a Ruby-style comment %> (une balise de code dont le contenu commence par #) est ignorée comme <%# %>. Un commentaire après du vrai code dans la même balise n’est pas pris en charge — <% x = 1 # note %> est une SyntaxError.
• Les balises non terminées lèvent une erreur dès l’analyse lexicale : "posts/show:2: unterminated <% tag".

Le commentaire de locals stricts

Une balise de commentaire dont le contenu commence par locals: et qui est la toute première balise du fichier, sur la ligne 1, déclare les seules variables locales qu’accepte un template (presque toujours un partiel) :

<%# locals: (post:, comment:) %>
<%= post.title %>

• <%# locals: () %> (liste vide) signifie « ce partiel ne prend aucune variable locale ».
• Chaque entrée doit être un simple name: en minuscules (Lexer.identifier? n’accepte que [a-z_][a-z0-9_]*). Tel qu’implémenté : contrairement à Rails 7.1, les entrées ne peuvent pas porter de valeur par défaut — <%# locals: (post:, comment: nil) %>, la forme exacte que prend en charge Rails 7.1, est une SyntaxError : "t:1: bad strict locals entry 'comment: nil' (expected name:)", car comment: nil ne se termine pas par :. Chaque variable locale déclarée est de fait obligatoire. Une spécification mal formée (parenthèses manquantes) lève "t:1: bad strict locals comment (expected locals: (name:, ...))".
• Sans ce commentaire, un template ne déclare aucune liste de variables locales : render transmet toutes les variables locales qu’il reçoit, sans vérification, et le template peut aussi lire tout ce qui est déjà présent dans l’environnement de l’appelant (voir Layouts, yield, content_for, partiels).
• Si quoi que ce soit précède le commentaire sur une ligne antérieure (ne serait-ce qu’une ligne vide), ce n’est qu’un commentaire ordinaire et inerte, pas une déclaration de locals.

03Expressions

Littéraux

Les chaînes entre guillemets doubles interpolent #{...} (n’importe quelle expression complète, imbricable) et acceptent \n \t \r \0 \e \s, \", \\ ; tout autre caractère échappé passe tel quel. Une chaîne sans #{} se compile en un littéral simple ; une chaîne avec interpolation se compile en une séquence de morceaux littéraux et d’expressions.

Variables

• @ivar lit directement env["ivar"] — le @ n’est que de la syntaxe de surface ; selon D9, « post est à la fois @post et la variable locale post » dans un seul Hash d’environnement. Une ivar absente vaut simplement nil : [<%= @missing %>] rend [], jamais une erreur.
• Un nom local nu (post, title) lit aussi env["name"], mais si la clé n’existe pas du tout, l’interpréteur le traite plutôt comme un appel de helper sans argument. Si la clé existe (même liée à nil — une variable locale stricte déclarée mais non passée, par exemple), sa valeur est renvoyée sans repli sur un helper. C’est pourquoi <%= csrf_meta_tags %> et <%= flash %> fonctionnent sans parenthèses, et pourquoi <%= nope %> échoue avec "undefined helper 'nope'" plutôt qu’avec une erreur « pas de telle variable locale ».
• Les variables locales viennent des paramètres de bloc de each/each_with_index, du paramètre de bloc de form_with, des locals stricts d’un partiel et de <% name = expr %>.

Appels de méthode

recv.method
recv.method(arg1, key: value)
recv&.method             # sûr face à nil : court-circuite vers nil, arguments non évalués, si recv vaut nil
method(arg1, key: value) # un appel de helper : pas de receveur
method arg1, key: value  # même appel, sans parenthèses (syntaxe « commande »)

• Une liste d’arguments sans parenthèses (« commande ») n’est ouverte que pour l’appel le plus externe d’une expression : link_to "Show", post_path(post) fonctionne, mais link_to "Show", post_path post est une SyntaxError — les appels internes ont besoin de leurs propres parenthèses.
• Aucun espace n’est autorisé entre la cible d’un appel et sa ( ouvrante : link_to("x") et link_to "x" fonctionnent tous deux ; link_to ("x") est une SyntaxError.
• yield et yield :key sont toujours analysés comme des appels (voir Layouts, yield, content_for, partiels).
• Un mot nu commençant par une majuscule est rejeté d’emblée — "constants are not supported: 'Time'" — les templates ne peuvent pas atteindre les constantes Ruby.
• Ces mots sont réservés et rejetés avec un message dédié ("'x' is not supported in templates") : and or not do end if unless elsif else then while until case when def class module begin rescue return.

Opérateurs, priorité (de la plus faible à la plus forte)

?:            ternary, right-associative on both branches
||
&&
==  !=
<  >  <=  >=
+  -
*  /  %
!  -            (unary, prefix)
.  &.  []       (method call / safe-nav / indexing, left-to-right chaining)

&&/|| renvoient l’opérande, pas un booléen converti (nothing || title s’évalue en title, pas en true). Les conditions testent la véracité : seuls nil et false sont faux, comme en Ruby — 0, "" et les tableaux/hashs vides sont vrais (<% if 0 %>yes<% end %> affiche yes).

L’indexation s’écrit target[index] sans espace avant [ (items [0] est une erreur de syntaxe, items[0] non), et s’enchaîne comme tout suffixe : h["k"].first, params[:id].

04Instructions

Une balise <% %> contient exactement une instruction : une affectation, ou une expression évaluée pour son effet de bord (valeur ignorée). <%= %>/<%== %> ne contiennent jamais qu’une expression — <%= x = 1 %> est une SyntaxError.

Conditions

<% if cond %>...<% elsif other %>...<% else %>...<% end %>
<% unless cond %>...<% else %>...<% end %>

unless/else/elsif suivent les règles de Ruby ; un elsif après else, un else/elsif/end isolé, ou un bloc jamais fermé par end sont tous des SyntaxError qui nomment la ligne d’ouverture.

Boucles

<% @posts.each do |post| %>...<% end %>
<% @counts.each do |name, n| %>...<% end %>          <%# Hash: name=key, n=value %>
<% items.each_with_index do |item, i| %>...<% end %>

• each/each_with_index ne sont reconnus que comme suffixe de l’en-tête du bloc (x.each do |...|). Tel qu’implémenté, les deux exigent de déclarer un ou deux paramètres de bloc — xs.each do end est une SyntaxError (« takes one or two block parameters »), là où le Ruby ordinaire en accepte zéro.
• Array + un paramètre : l’élément. Array + deux paramètres : un élément Array est déstructuré (a, b = item[0], item[1]) ; sinon, le second vaut nil.
• each_with_index sur un Array : item, i. Sur un Hash : le premier paramètre est une paire [key, value], le second l’index.
• each sur un Hash avec deux paramètres : directement key, value ; avec un paramètre : une paire [key, value].
• Itérer sur nil, un Time ou n’importe quel scalaire est une RuntimeError ("undefined method 'each' for Time") — jamais une absence d’effet silencieuse.
• Un paramètre de bloc masque une variable locale externe du même nom uniquement pendant la boucle, et est supprimé ensuite (refute env.key?("item") une fois la boucle terminée). Une variable qui existait avant le bloc est la même variable à l’intérieur (visible aussi après la boucle) ; une variable affectée pour la première fois dans le bloc est locale au bloc — nil au début de chaque itération, disparue ensuite.

Appels avec bloc (helpers)

do ... end est aussi la façon dont un appel de helper sans receveur prend un bloc — le seul autre usage légal d’un bloc, et seulement quand il n’y a pas de receveur (f.each do |x| end est refusé : « blocks are only supported on each, each_with_index and helper calls ») :

<%= form_with(model: @post) do |f| %>...<% end %>   <%# printed: form_with returns the <form> HTML %>
<% content_for :title do %>Hi<% end %>              <%# not printed: content_for returns "" %>

L’affichage ou non du résultat du bloc suit la balise : <%= helper do |x| %> l’affiche, <% helper do |x| %> l’ignore. Exactement un paramètre de bloc est lié, toujours ; un bloc de helper ne reçoit jamais d’index ni de seconde valeur.

Affectation

<% total = 0 %><% total = total + 2 %><%= total %>   <%# => 2 %>

Uniquement name = expr pour une seule variable locale simple — pas de @ivar = ..., pas de arr[0] = .../h[:k] = ..., pas de a, b = .... La même règle de localité au bloc que pour each s’applique aux affectations dans des if/unless imbriqués dans un bloc.

05Table des méthodes par type

nil?, present? et blank? sont vérifiés avant le dispatch par type, ils fonctionnent donc sur toutes les valeurs, y compris les modèles et les objets renvoyés par des helpers (blank? vaut false pour tout sauf nil/false/une SafeString/String/Array/Hash/Errors/Params vide). L’arithmétique (+ - * / %) et la comparaison (== != < > <= >=) n’existent que comme opérateurs infixes, jamais comme appels .method — un symbole d’opérateur ne peut jamais suivre un . dans cette grammaire.

L’indexation (x[key]) est une production distincte de la grammaire (Expressions), pas un appel .[] : Array/String prennent un index entier, Hash fait correspondre n’importe quelle clé par son to_s (h[:k] et h["k"] sont la même entrée), Errors par symbole, Params par to_s.

Affichage (<%= %>/interpolation) au-delà du to_s ci-dessus : un Array s’affiche comme une liste à la manière d’inspect — [1, "a", nil] rend le texte [1, "a", nil] (puis est échappé, les guillemets deviennent donc ") ; un Hash se rabat sur le Hash#to_s de Ruby ; un Cybertrain::Model s’affiche #<Post id: 7> (jamais ses attributs) ; tout le reste s’affiche via son propre to_s. Une méthode non listée sur l’un de ces types est une RuntimeError ("undefined method 'first' for Time"). La division/le modulo d’un Integer par zéro donne "divided by 0" ; Float suit plutôt l’IEEE-754 (Infinity/NaN, sans erreur).

06Les modèles dans les templates

Une sous-classe de Cybertrain::Model (un Post, un Note générés, ...) résout un nom nu dans cet ordre (Interpreter#model_method) :

1. Cinq méthodes intégrées, toujours disponibles : id, persisted?, new_record?, to_param (id.to_s), errors (un Errors, Table des méthodes par type).
2. read_attribute(:name) — une colonne générée.
3. read_association(:name) — un has_many/belongs_to généré.
4. call_view_method(:name) — un def sans argument écrit à la main que le générateur de modèles a trouvé dans app/models/**/*.rb (jamais d’arité).

<%= post.title %>            <%# read_attribute %>
<% post.comments.each do |c| %>...<% end %>   <%# read_association %>
<%= post.summary %>          <%# call_view_method %>
<%= post.errors.full_messages.join(", ") %>

Si les quatre répondent nil, attribute_or_method?(:name) décide s’il s’agissait d’un nom légitime qui contient simplement nil (renvoie le nil) ou d’une faute de frappe ("undefined method 'bogus' for Post").

Tel qu’implémenté, une vraie lacune que signale le fichier de l’interpréteur lui-même (voir le commentaire TODO(integrator) au-dessus de class Model dans interpreter.rb) : le Cybertrain::Model#attribute_or_method? de base renvoie toujours true. Seul un modèle généré qui le redéfinit avec un case explicite (comme le font les modèles de test écrits à la main) lève réellement une erreur sur une faute de frappe ; sans cette redéfinition, un attribut ou une méthode mal orthographié s’affiche silencieusement vide au lieu d’échouer. Ne supposez pas que les fautes de frappe sont détectées, sauf si vous savez que le modèle redéfinit ce hook.

Deux modèles se comparent avec == par classe et par id (Model#==), accessible via l’opérateur == ordinaire (dispatch natif de l’égalité, pas call_method).

07Helpers et constructeur de formulaires

Chaque appel sans receveur va à Helpers#helper_call (helpers.rb), qui fait correspondre l’une des méthodes intégrées ci-dessous, traite un nom finissant par _path/_url comme un helper de route généré (via Cybertrain::Views.url_resolver, qui lève "no routes" tant que l’application n’en a pas installé un), ou lève "undefined helper 'name'".

Chaque argument texte d’un helper suit une seule règle : une SafeString passe sans être échappée, tout le reste est échappé — link_to raw('<b>raw</b>'), post affiche la balise gras littéralement, mais link_to post.title, post l’échappe.

FormBuilder (f dans form_with ... do |f|)

Chaque méthode renvoie une SafeString ; une méthode non listée est une RuntimeError ("undefined method 'color_wheel' for FormBuilder").

Avec un modèle, les champs sont nommés post[title]/id="post_title" (avec Inflector.underscore(model.model_name) comme portée) ; avec form_with(url: ...) et sans modèle, le nom d’attribut nu est utilisé pour les deux. Les arguments nommés supplémentaires deviennent des attributs HTML dans l’ordre donné : true → attr="attr", false/nil omis, tout le reste → attr="value" (échappé), les tirets bas deviennent des traits d’union (data_confirm: "Sure?" → data-confirm="Sure?"), et class: est fusionné avec la classe automatique field_with_errors ajoutée quand model.errors.key?(attr).

08Layouts, yield, content_for, partiels

Engine#render_with_layout(name, layout, env, helpers) rend name dans env["__content"] (une SafeString), puis rend layout avec le même env :

<title><%= yield :title %></title>
<%= yield %>

yield affiche env["__content"] ; yield :key affiche env["__content_key"], ou rien s’il n’est pas défini. yield est traité à part directement dans l’interpréteur et ne peut pas être redéfini comme helper. Une page remplit un emplacement avec content_for, n’importe où dans son corps (l’ordre par rapport à yield n’a pas d’importance — la page est entièrement rendue avant le layout) :

<% content_for :title do %>Post: <%= @post.title %><% end %>
<% content_for :title, " (draft)" %>   <%# appends: calls accumulate, they don't replace %>

Partiels et render

<%= render "form", post: @post %>
<%= render partial: "form", locals: { post: @post } %>
<%= render "comments/comment", comment: c %>

• Un nom nu sans / se résout dans le propre répertoire du template courant (via une clé d’env que définit la mécanique de rendu, __template_dir) : render "form" depuis posts/show cherche posts/_form.html.erb. Un nom contenant / est un chemin explicite ; seul son dernier segment reçoit le préfixe _ ("comments/comment" → comments/_comment.html.erb).
• Le partiel reçoit une copie de tout l’environnement de l’appelant (ivars et toutes les variables locales déjà visibles) plus les variables locales explicitement passées à render — il n’est pas cloisonné à ce qui lui a été passé. Les locals stricts ne valident que les noms explicitement passés à cet appel de render par rapport à la liste déclarée ; ils n’empêchent pas le partiel de lire aussi un autre nom qu’il hérite de l’environnement de l’appelant.
• Seules les clés de content_for (__content_*) sont recopiées de la portée d’un partiel vers celle de l’appelant ; les variables locales ordinaires qu’il affecte ne remontent pas.
• Des variables locales manquantes/en trop par rapport à une déclaration <%# locals: %> sont des RuntimeError : "missing local 'post' for posts/_form.html.erb", "unknown local 'extra' for posts/_form.html.erb".

Résolution des fichiers (engine.rb)

"posts/show" et "posts/show.html.erb" désignent le même template. Le développement lit app/views/ depuis le disque avec cache: false (un fichier est relu et réanalysé chaque fois que son mtime ou sa taille change) ; l’environnement de test lit depuis le disque avec cache: true (analysé une fois). Un binaire de production ne touche jamais au disque : cybertrain build lance spin run gen -- --embed-views, qui écrit chaque *.erb de app/views/ (fichiers cachés et répertoires liés symboliquement exclus) dans gen/views.rb, et Engine.embedded(sources) analyse chaque entrée une fois (les messages d’erreur gardent la même forme posts/show.html.erb:12) ; un binaire dont la table est vide refuse de démarrer en production. Un template absent lève Cybertrain::Template::MissingTemplate — "Missing template <full path>" depuis le disque, "Missing template posts/nope.html.erb (embedded)" depuis la table.

Les recherches de fichiers résolvent la racine des vues et le chemin du template à travers les liens symboliques, et ne chargent que des fichiers ordinaires situés dans cette racine. Les chemins qui en sortent (y compris via des liens symboliques) lèvent MissingTemplate ; exists? renvoie false pour ces chemins.

09Erreurs

Deux classes d’exception, toutes deux dans l’espace de noms Cybertrain::Template de ast.rb (distinctes de ::SyntaxError/::RuntimeError) :

• SyntaxError — levée pendant le découpage en lexèmes/l’analyse, avant toute interprétation. Forme : "<template>:<line>: <what>", par ex. "posts/show:2: 'if' without 'end'", "posts/show:1: unterminated <% tag", "posts/show:1: unexpected ')' in 'foo(1))'". Levée directement par Engine#template (et donc par #render/#render_with_layout) quand un fichier de page ou de layout ne s’analyse pas — jamais attrapée ni réemballée par l’interpréteur.
• RuntimeError — levée pendant l’évaluation, même forme de message, mais <template> est le template en cours de rendu (Interpreter#render permute @name à l’entrée et à la sortie) — l’erreur propre à un partiel garde le nom et la ligne du partiel, jamais ceux de l’appelant : "posts/_row:1: undefined method 'bogus' for String".

Toute StandardError ordinaire venant d’un helper ou d’un appel de méthode de FormBuilder/d’objet personnalisé (un simple raise "text", ArgumentError, KeyError, voire une Cybertrain::Template::RuntimeError venant d’un render imbriqué) est attrapée et « relocalisée » : réécrite en "<current template>:<current line>: <original message>", sauf si c’est déjà exactement le dernier message relocalisé (un render imbriqué a déjà apposé sa propre localisation, plus précise), auquel cas elle passe inchangée. Une Cybertrain::Template::SyntaxError levée par un helper (un partiel qui ne s’analyse pas, en plein rendu) n’est jamais réemballée — elle garde son propre message "<partial>:<line>: ..." et sa classe, de sorte qu’un partiel cassé est toujours signalé comme une SyntaxError le concernant, et non comme une RuntimeError concernant celui qui l’a rendu.

MissingTemplate (StandardError, engine.rb) est levée sans emballage, sans préfixe template:line, depuis un appel de premier niveau à Engine#template/#render/#render_with_layout (par ex. un contrôleur qui rend un template d’action ou un layout absent) : "Missing template <path>". La même exception levée à l’intérieur d’un template via la recherche de partiel du helper render passe au contraire par la relocalisation et en ressort comme une RuntimeError : "posts/inline:1: Missing template test/fixtures/views/posts/_nope.html.erb".