This document describes exactly what that pipeline accepts and executes. Where it disagrees with docs/design.md section 7 (the original spec draft) or with what a Rails developer would expect, the code wins, and this document says so (search for "As built").
What is, and is not, Ruby here
Templates are not Ruby. Spinel (the Matz-Ruby AOT compiler cybertrain targets) has no eval, so "interpret the view's own Ruby at request time" was never on the table (D9 in docs/design.md); what runs instead is a small, closed grammar that only wears ERB/Ruby-looking syntax. There is no arbitrary Ruby inside a tag — only what ExprParser (parser.rb) recognizes as a statement or expression. There is no eval, send, instance_eval, method/class/module definitions, require, exceptions (begin/rescue), ranges, regexes, or multiple assignment. Blocks exist only where this document lists them: each/each_with_index/each_slice loops, a fixed set of Array and Hash methods (map, select, sum, group_by ... — see Blocks), helper calls (form_with(...) do |f| ... end) and the tag builder. Every method call (recv.name) is resolved by hand-written case dispatch tables in interpreter.rb, keyed on the receiver's runtime Ruby class; a name missing from that type's table fails with a RuntimeError — there is no method_missing, no reflection, and (per Interpreter#call_method) Spinel's lack of send is exactly why this is a case, not a metaprogrammed lookup. A template can only do what this document describes.
Where this lives in the sourcethe eight files of the template pipeline
The pipeline lives in cybertrain/template/:
| File | Role |
|---|---|
lexer.rb |
Splits source into <% %>/<%= %>/<%== %>/<%# %> tags vs. plain text |
parser.rb |
TreeBuilder nests tags into an AST; ExprParser parses the expression grammar inside one tag |
ast.rb |
The AST node classes the parser produces |
inode.rb |
Compile flattens the AST into monomorphic INodes (an integer "kind" plus typed slots) for fast interpretation |
interpreter.rb |
Walks INodes against an env (Hash<String, value>); owns every per-type "what methods exist" table |
helpers.rb |
link_to, form_with, render, pluralize, ... — everything a template calls without a receiver |
form_builder.rb |
The f yielded by form_with(...) do |f| ... end |
engine.rb |
Loads .html.erb sources — from disk under a root, or from the embedded gen/views.rb table (Engine.embedded) — parses (and optionally caches) them, renders with a layout |
Tags
| Tag | Meaning |
|---|---|
<% code %> |
Executes a statement; produces no output |
<%= expr %> |
Evaluates expr and prints it, HTML-escaped |
<%== expr %> |
Evaluates expr and prints it without escaping |
<%# comment %> |
Ignored (except the line-1 locals: form below) |
Whitespace control (Lexer.tokenize):
- A
<% %>/<%# %>tag that is the only thing on its line (nothing but spaces/tabs on either side up to the newlines) silently swallows its own indentation and trailing newline, like Rails' ERB trim mode.<%= %>/<%== %>are never auto-trimmed this way, even alone on a line. <%-explicitly strips leading spaces/tabs before the tag, and-%>strips the one newline right after it — for any tag kind. Both are no-ops when something other than whitespace occupies that side of the line.<%%in text is a literal<%;%%>inside a tag is a literal%>that does not close the tag.<% # a Ruby-style comment %>(a code tag whose content starts with#) is ignored like<%# %>. A comment after real code in the same tag is not supported —<% x = 1 # note %>is aSyntaxError.- Unterminated tags raise at lex time:
"posts/show:2: unterminated <% tag".
The strict-locals comment
A comment tag whose content starts with locals: and is the very first tag in the file, on line 1, declares the only locals a template (almost always a partial) accepts:
<%# locals: (post:, comment:) %>
<%= post.title %>
<%# locals: () %>(empty list) means "this partial takes no locals."- Each entry must be a bare, lowercase
name:(Lexer.identifier?accepts only[a-z_][a-z0-9_]*). As built: unlike Rails 7.1, entries cannot carry a default value —<%# locals: (post:, comment: nil) %>, the exact form Rails 7.1 supports, is aSyntaxError:"t:1: bad strict locals entry 'comment: nil' (expected name:)", becausecomment: nildoes not end in:. Every declared local is effectively required. A malformed spec (missing parens) raises"t:1: bad strict locals comment (expected locals: (name:, ...))". - Without this comment, a template declares no local list:
renderpasses through whatever locals it is given, unchecked, and the template may also read anything already present in the caller's environment (see Layouts,yield,content_for, partials). - If anything precedes the comment on an earlier line (even one blank line), it is just an ordinary, inert comment, not a locals declaration.
Expressions
Literals
| Literal | Syntax | Notes |
|---|---|---|
| Integer | 1, 1_000 |
underscores allowed; no hex/octal/binary/exponent |
| Float | 2.5, 12_3.4_5 |
a digit is required on both sides of .; no exponent form |
| String | "...", '...' |
double quotes interpolate and support escapes; single quotes only understand \' and \\ |
| Symbol | :title |
identifier characters only — no :"quoted", no :+-style operator symbols |
nil / true / false |
||
| Array | [1, "a", :b], [] |
elements are full expressions |
| Hash | { a: 1, b: "x" }, {} |
symbol-style keys only, same shape as keyword args; no "key" => value hashrocket |
Double-quoted strings interpolate #{...} (any full expression, nestable) and support \n \t \r \0 \e \s, \", \\; any other escaped character passes through unchanged. A string with no #{} compiles to a plain literal; one with interpolation compiles to a sequence of literal pieces and expressions.
Variables
@ivarreadsenv["ivar"]directly — the@is only surface syntax; per D9, "post is both@postand the localpost" in one environment Hash. A missing ivar is simplynil:[<%= @missing %>]renders[], never an error.- A bare local name (
post,title) also readsenv["name"], but if the key does not exist at all, the interpreter treats it as a zero-argument helper call instead. If the key exists (even bound tonil— an unpassed-but-declared strict local, say), its value is returned with no helper fallback. This is why<%= csrf_meta_tags %>and<%= flash %>work with no parentheses, and why<%= nope %>fails with"undefined helper 'nope'"rather than a "no such local" error. - Locals come from
each/each_with_indexblock params,form_with's block param, a partial's strict locals, and<% name = expr %>.
Method calls
recv.method
recv.method(arg1, key: value)
recv&.method # nil-safe: short-circuits to nil, args not evaluated, if recv is nil
method(arg1, key: value) # a helper call: no receiver
method arg1, key: value # same call, no parentheses ("command" syntax)
- A parenthesis-free ("command") argument list is only opened for the outermost call in an expression:
link_to "Show", post_path(post)works, butlink_to "Show", post_path postis aSyntaxError— inner calls need their own parens. - No space is allowed between a call target and its opening
(:link_to("x")andlink_to "x"both work;link_to ("x")is aSyntaxError. yieldandyield :keyare always parsed as calls (see Layouts,yield,content_for, partials).- A bare capitalized word is rejected outright —
"constants are not supported: 'Time'"— templates cannot reach Ruby constants. - These words are reserved and rejected with a dedicated message (
"'x' is not supported in templates") wherever an expression is expected:and or not do end if unless elsif else then while until def class module begin rescue return.caseandwhenare statements of their own (case); inside an expression (<%= case x %>) they are rejected the same way.
Operators, precedence (low to high)
?: ternary, right-associative on both branches
||
&&
== !=
< > <= >=
+ -
* / %
! - (unary, prefix)
. &. [] (method call / safe-nav / indexing, left-to-right chaining)
&&/|| return the operand, not a coerced boolean (nothing || title evaluates to title, not true). Conditions test truthiness: only nil and false are falsy, as in Ruby — 0, "", and empty arrays/hashes are truthy (<% if 0 %>yes<% end %> prints yes).
Indexing is target[index] with no space before [ (items [0] is a syntax error, items[0] is not), and chains like any postfix: h["k"].first, params[:id].
Statements
A <% %> tag holds exactly one statement: an assignment, or an expression evaluated for its side effect (value discarded). <%= %>/<%== %> only ever hold an expression — <%= x = 1 %> is a SyntaxError.
Conditionals
<% if cond %>...<% elsif other %>...<% else %>...<% end %>
<% unless cond %>...<% else %>...<% end %>
unless/else/elsif follow Ruby's rules; elsif after else, a stray else/elsif/end, or a block never closed by end are all SyntaxErrors naming the opening line.
case
<% case @article.status %>
<% when :draft, :review %>
<span class="badge">unpublished</span>
<% when :published %>
<span class="badge">live</span>
<% else %>
<span class="badge">?</span>
<% end %>
- The subject is evaluated once; each
when's values (one or more, separated by commas) are compared in order with the template's==, and the first branch with an equal value runs. Numbers compare by value (1matches1.0); Strings and Symbols by value and type ("a"does not match:a); records as==does (class andid); Arrays and Hashes as==does (by value, element by element); aSafeStringand aStringwith the same text are equal. There is no===: no ranges, classes or regexes afterwhen. elseruns when no value matched; with noelseand no match nothing is printed.- Only blank text (indentation, newlines) may stand between
caseand its firstwhen; it is dropped. Anything else there is aSyntaxError("text between 'case' and its first 'when'"). whenoutside acase("'when' without 'case'"), acasewith no subject or nowhen, awhenwith no value or afterelse, and acasenever closed byendareSyntaxErrors naming the line.thenstays reserved:<% when :a then x %>is aSyntaxError.- A local first assigned inside a branch follows the block-local rule of the block it sits in, as with
if.
Loops
<% @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_indexare recognized only as a suffix on the block head (x.each do |...|); the collection may be any expression, a block-taking call included (<% items.group_by { |i| i.kind }.each do |kind, list| %>). As built, both require declaring one or two block parameters —xs.each do endis aSyntaxError("takes one or two block parameters"), where plain Ruby allows zero.<% x.each_slice(n) do |slice| %>...<% end %>iterates over the slices ofnitems (the last may be shorter), and also needs one or two parameters; with two a slice is taken apart (do |a, b|), the secondnilwhen the slice is short.- Array + one param: the item. Array + two params: an
Arrayitem is destructured (a, b = item[0], item[1]); otherwise the second isnil. each_with_indexon an Array:item, i. On a Hash: the first param is a[key, value]pair, the second the index.eachon a Hash with two params:key, valuedirectly; with one param: a[key, value]pair.- Iterating
nil, aTime, or any scalar is aRuntimeError("undefined method 'each' for Time") — never a silent no-op. - A block parameter shadows a same-named outer local only for the loop and is removed after (
refute env.key?("item")once the loop ends). A variable that existed before the block is the same variable inside it (visible after the loop too); one first assigned inside the block is block-local —nilat the start of every iteration, gone afterward.
Block calls (helpers)
do ... end is also how a receiverless helper call takes a block (for a call with a receiver, see Blocks):
<%= 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 "" %>
Whether the block's result is printed follows the tag: <%= helper do |x| %> prints it, <% helper do |x| %> discards it. Exactly one block parameter is ever bound; a helper block never gets an index or a second value.
Blocks
A call with a receiver may take a block, { |x| expr } or do |x| ... end, with zero, one or two parameters. Which methods accept one is fixed per type; a block anywhere else is a SyntaxError raised when the call runs ("String#upcase takes no block"), and a method the type does not have is the ordinary "undefined method 'x' for Array", with or without a block.
| Receiver | Methods taking a block | The block's value is used as |
|---|---|---|
Array |
map select reject find any? all? none? count sum sort_by min_by max_by group_by |
the mapped value, the test, the summand, the sort key, the group key |
Hash |
map select reject find any? all? none? count sum sort_by min_by max_by group_by |
the same, the block seeing |key, value| (one parameter gets the [key, value] pair); select/reject answer a Hash, the others what the Array method answers over the pairs |
the tag builder |
every element (tag.div do ... end) |
its output is the element's content (The tag builder) |
<%= @items.map { |i| i.name }.join(", ") %>
<%= @line_items.sum { |li| li.price } %>
<% @items.group_by { |i| i.kind }.each do |kind, list| %>
<h2><%= kind %></h2> <%= list.size %>
<% end %>
<% total = @line_items.sum do |li| %>
<% li.price * li.quantity %>
<% end %>
- Value, not output. For the Array and Hash methods the block's value counts: a
{ }block's expression, or adoblock's last statement, which must be an expression statement (<% x * 2 %>);"map's block must end in a value"otherwise (an assignment, or text). What the earlier statements of adoblock print is discarded. Adoblock on such a method sits on its own tag, assigned (<% total = items.sum do |li| %>) or printed (<%= items.map do |x| %>). - No mutation. Templates have no way to change an accumulator, so
each_with_objectandinjectare not in the table ("undefined method 'each_with_object' for Array"): usemap,select,sumorgroup_by. - Two parameters take an Array item apart, as
eachdoes (pairs.map { |a, b| a }). sumof an empty Array is0; Integers sum to an Integer, a Float anywhere makes it a Float (added with the same compensation as Ruby's, so[0.1, 0.2, 0.3].sumis0.6); Strings are refused ("sum: use join for Strings"), as is anything that is not a number.sort_by,min_by,max_by(and blocklesssort,min,max) compare as<does (numbers, Strings, Times;"comparison of String with Integer failed"otherwise).sort_byis stable: equal keys keep their order.min_by/max_byof an empty Array arenil.group_byanswers a Hash from each key as a String (every template Hash is String-keyed::fruitand"fruit"are one group) to the items with that key, in first-seen order.each,each_with_indexandeach_slicetake their block in a<% %>tag (Loops);items.each { |x| x }is aSyntaxError.- A block on a
FormBuilderorPagemethod is refused the same way ("FormBuilder#label takes no block"), and the blockless Array methods take no arguments (nums.sum(10)is"wrong number of arguments for 'sum'"). - If a block raises, its parameters and locals are restored before the error leaves the call.
- A
{ }block needs a receiver:shout { |x| x }is aSyntaxError(helper calls takedo ... end). - Block parameters shadow outer names during the call and are restored after it; a local first assigned in a
doblock is block-local, as ineach.
Assignment
<% total = 0 %><% total = total + 2 %><%= total %> <%# => 2 %>
Only name = expr for one plain local — no @ivar = ..., no arr[0] = .../h[:k] = ..., no a, b = .... The same block-local rule from each applies to assignments inside if/unless nested in a block.
Per-type method table
nil?, present?, and blank? are checked before per-type dispatch, so they work on every value, including models and helper-returned objects (blank? is false for anything but nil/false/an empty SafeString/String/Array/Hash/Errors/Params). Arithmetic (+ - * / %) and comparison (== != < > <= >=) exist only as infix operators, never .method calls — an operator glyph can never follow a . in this grammar.
| Type | Methods | Example |
|---|---|---|
SafeString |
to_s html_safe? size/length empty? |
raw('<b>').size |
String |
upcase downcase capitalize strip size/length empty? to_s to_i html_safe html_safe? include?(s) start_with?(s) end_with?(s) |
title.strip.upcase |
Integer |
to_s to_i to_f zero? positive? negative? abs |
post.comments.size.zero? |
Float |
to_s to_i to_f zero? positive? negative? abs round round(n) floor ceil |
price.round(2) |
Time |
year month day hour min sec strftime(fmt) to_s to_i |
post.created_at.strftime('%Y-%m-%d') |
Array |
size/length/count empty? any? first last reverse include?(x) join(sep) to_a sum min max sort uniq compact flatten take(n) drop(n) each_slice(n) (an Array of Arrays) zip(other), and the block methods of Blocks |
post.comments.any? |
Hash |
key?(k) fetch(k, default) size/length/count empty? any? keys values to_a (the [key, value] pairs), plus h[key] and the block methods of Blocks |
flash.key?(:notice) |
Errors |
any? empty? count/size full_messages key?(a)/include?(a), plus errors[:attr] |
post.errors.full_messages.join(', ') |
Params |
key?(k) empty?, plus params[key] |
params[:id] |
Page (Relation#page) |
number per row_offset next? prev? next_number prev_number |
@page.next? |
true/false |
to_s |
published.to_s |
nil |
to_s (returns "") |
Indexing (x[key]) is a distinct grammar production (Expressions), not a .[] call: Array/String take an integer index, Hash matches any key by its to_s (h[:k] and h["k"] are the same entry), Errors matches by symbol, Params by to_s.
Printing (<%= %>/interpolation) beyond to_s above: Array prints as an inspect-like list — [1, "a", nil] renders the text [1, "a", nil] (then gets escaped, so quotes become "); Hash falls back to Ruby's own Hash#to_s; a Cybertrain::Model prints as #<Post id: 7> (never its attributes); anything else prints via its own to_s. An unlisted method on any of the above is a RuntimeError ("undefined method 'first' for Time"). Integer division/modulo by zero is "divided by 0"; Float follows IEEE-754 instead (Infinity/NaN, no error).
Models in templates
A Cybertrain::Model subclass (a generated Post, Note, ...) resolves a bare name in this order (Interpreter#model_method):
- Five built-ins, always available:
id,persisted?,new_record?,to_param(id.to_s),errors(anErrors, Per-type method table). read_attribute(:name)— a generated column.read_association(:name)— a generatedhas_many/belongs_to.call_view_method(:name)— a hand-written, argument-lessdefthe model generator found inapp/models/**/*.rb(no arity, ever).
<%= post.title %> <%# read_attribute %>
<% post.comments.each do |c| %>...<% end %> <%# read_association %>
<%= post.summary %> <%# call_view_method %>
<%= post.errors.full_messages.join(", ") %>
If all four answer nil, attribute_or_method?(:name) decides whether that was a legitimate name that just holds nil (returns the nil) or a typo ("undefined method 'bogus' for Post").
Generated models answer it from their schema. spin run gen emits attribute_or_method? in every model as a case over its columns (a renamed column under both names), its associations and its public view methods, so <%= post.titel %> on a generated model is "posts/show:3: undefined method 'titel' for Post", while a column that holds nil renders empty. The base Cybertrain::Model#attribute_or_method? (in model.rb) still returns true: a hand-written Cybertrain::Model subclass that does not override it renders an unknown name as empty. Upgrade note: a template that read a name its model never had rendered blank before this and raises after the next spin run gen (docs/design.md D71).
Two models compare with == by class and id (Model#==), reachable as the ordinary == operator (native equality dispatch, not call_method).
Helpers and the form builder
Every receiverless call goes to Helpers#helper_call (helpers.rb), which matches one of the built-ins below; inside a component's template, then tries that component's view methods; treats a name ending in _path/_url as a generated route helper (via Cybertrain::Views.url_resolver, raising "no routes" until the app installs one); then tries the application's helpers; or raises "undefined helper 'name'".
| Helper | Signature | Notes / example |
|---|---|---|
link_to |
link_to(text, href, class:, id:, data_confirm:, data: {}) |
text escaped unless already SafeString; no method: — raises, telling you to use button_to (no rails-ujs/turbo faking of DELETE links) |
button_to |
button_to(text, action, method: :post, class:, data: {}) |
one-button <form class="button_to">; hidden _method for any verb but get/post, plus the CSRF field when a session exists |
form_with |
form_with(model:, url:, scope:, method:, class:, data:, multipart:, local:) do |f| ... end |
needs a block; model: new → collection route + POST, persisted → member route + PATCH; [parent, child] for a nested route, [:admin, @article] for a namespaced one; url:/method: override the derived action/verb; scope: :q names the fields q[term] (with model: it replaces the model's prefix); data: { turbo_frame: "f" } writes data- attributes; local: is accepted and changes nothing; multipart: true adds enctype="multipart/form-data" (required for f.file_field; it is never guessed from the block, and raises ArgumentError on a GET form) |
select_tag |
select_tag(name, option_tags = nil, include_blank:, prompt:, multiple:) |
select_tag "order", options_for_select([["Newest", "new"], ["Oldest", "old"]], "old") → <select name="order" id="order">...</select>; option_tags that is not a SafeString is escaped; multiple: true names it order[]; other keywords are attributes |
options_for_select |
options_for_select(choices, selected = nil) |
the <option> lines of f.select's choices (below); selected is a value or an Array of them, compared as Strings |
options_from_collection_for_select |
options_from_collection_for_select(records, :id, :name, selected = nil) |
one <option> per record, its value and text read as f.collection_select reads them |
t, translate |
t(key, default:, count:, locale:, name: value) |
the text at key in the request's locale, escaped; t(".title") in posts/index.html.erb reads posts.index.title, in the partial posts/_form.html.erb posts.form.title; a key ending in _html prints its HTML and escapes the values (Internationalization) |
l, localize |
l(time_or_date, format: :short, locale:) |
the locale's time.formats / date.formats, or a strftime pattern with the locale's day and month names (Dates and times) |
label_tag, text_field_tag, hidden_field_tag, submit_tag |
label_tag(name, text = nil), text_field_tag(name, value = nil), hidden_field_tag(name, value = nil), submit_tag(value = "Save changes") |
the form tags without a model: label_tag(:term) → <label for="term">Term</label>; hidden_field_tag writes autocomplete="off"; submit_tag is named commit; other keywords are attributes (id: replaces the id taken from the name) |
check_box_tag |
check_box_tag(name, value = "1", checked = false) |
a checkbox without a model and without a hidden field, so an unchecked box sends nothing: check_box_tag :remember_me → <input type="checkbox" name="remember_me" id="remember_me" value="1">; other keywords are attributes |
render |
render "name" / render "name", k: v / render partial: "name", locals: { k: v } / render partial: "comment", collection: @comments / render @comments / render component: "card", k: v |
see Layouts, yield, content_for, partials, Collections and Components |
h, escape |
h(text) |
escapes; a SafeString passes through unescaped |
raw |
raw(text) |
wraps text in a SafeString (prints unescaped) |
pluralize |
pluralize(count, singular, plural = nil) |
pluralize(1, "comment") → "1 comment"; pluralize(2, "mouse") → "2 mice" (Rails' default English inflections, via Cybertrain::Inflector, in an English page only: in another locale the word is kept; app-defined inflections are not supported); explicit third arg always wins |
truncate |
truncate(text, length: 30, omission: "...") |
truncate("Hello world", length: 8) → "Hello..." |
number_with_delimiter |
number_with_delimiter(n, delimiter: ",", separator: ".") |
1234567 → "1,234,567"; -1000 → "-1,000"; 1234.5 → "1,234.5" |
number_with_precision |
number_with_precision(n, precision: 3, delimiter: "", separator: ".", strip_insignificant_zeros: false) |
111.2345 → "111.235"; precision: 0 → "111" |
number_to_human |
number_to_human(n, precision: 3, units: {}) |
1234 → "1.23 Thousand", 1234567 → "1.23 Million"; units: { thousand: "K" } replaces a unit's name (unit, thousand ... quadrillion) |
number_to_percentage |
number_to_percentage(n, precision: 3) |
100 → "100.000%" |
number_to_currency |
number_to_currency(n, unit: "$", precision: 2, format: "%u%n") |
1234.5 → "$1,234.50"; a negative number writes - before the format |
number_to_human_size |
number_to_human_size(n) |
1234 → "1.21 KB" (base 1024); 1 → "1 Byte" |
time_ago_in_words |
time_ago_in_words(time) |
Rails-style buckets, no seconds precision: "less than a minute" … "about 1 hour" … "3 days" … "about 1 year", from the locale's datetime.distance_in_words (ja "2分") |
content_for / content_for? |
content_for(:key) do...end, content_for(:key, "text"), content_for?(:key) |
see Layouts, yield, content_for, partials |
csrf_meta_tags / csrf_token |
empty / absent with no controller session | |
csp_meta_tag / content_security_policy_nonce |
<meta name="csp-nonce" content="..."> / the nonce alone, this request's Content Security Policy nonce; "" when no policy applies |
|
javascript_tag |
javascript_tag(nonce: true) do ... end, javascript_tag(js) |
the content in a <script> (not escaped, as in Rails: never put request data in it), with the nonce when nonce: true and a policy applies; id:, type:, data: are attributes |
asset_path |
asset_path("logo.svg") |
/assets/logo-1a2b3c4d.svg (see Assets); a URL or a path starting with / comes back as given |
stylesheet_link_tag |
stylesheet_link_tag("application", media:, nonce:) |
<link rel="stylesheet" href="/assets/application-1a2b3c4d.css"> (.css added when missing) |
javascript_include_tag |
javascript_include_tag("legacy", nonce:) |
<script src="/assets/legacy-1a2b3c4d.js"></script> (.js added when missing) |
image_tag |
image_tag(source, alt:, size:, class:) |
<img src="/assets/logo-1a2b3c4d.svg" alt="Logo" width="16" height="16"> for size: "16x16" (or "16"); no alt is made up, alt: "" is written |
javascript_importmap_tags |
javascript_importmap_tags(entry = "application") |
the import map, a modulepreload link per preloaded pin and import "application", each with the nonce when a policy applies (Assets); needs a request |
flash |
Hash-like: flash[:notice] |
|
params |
the current Cybertrain::Params |
|
request_path |
current path, "" with no controller |
|
url_for |
url_for(target, format:, anchor:, k: v) |
String as-is, Model → member route, [parent, child] → nested route, [:admin, record] → namespaced route; the keywords are appended as a path helper appends them (url_for("/x", format: :csv) → /x.csv) |
current_page? |
current_page?(path) |
whether this GET or HEAD request is for path (a trailing slash aside; with a query in path, the query must match too); a record or an Array goes through url_for; false for any other method; needs a request |
paginate |
paginate(page, path) |
page is a Cybertrain::Page (from Relation#page); renders <nav class="pager"> with "Newer" (rel="prev"), <span class="pager-current">Page N</span> and "Older" (rel="next"), a link left out when there is no such page. Each link is path plus the current request's query string with page replaced (dropped for page 1), re-encoded and HTML-escaped; a path with its own ?query uses that instead. A Page also answers number, per, row_offset, next?, prev?, next_number, prev_number in a template (<% if @page.next? %>) |
*_path / *_url |
e.g. post_path(post), posts_path(page: 2, format: :json) |
generated by the app, resolved via Cybertrain::Views.url_resolver; keywords go to the query string, format: adds the extension and anchor: the fragment (Redirects and query strings) |
tag |
tag.div(content, attrs) do ... end |
the tag builder: see The tag builder |
content_tag |
content_tag(name, content = nil, attrs), or with a do block |
content_tag "p", "<i>", class: "n" → <p class="n"><i></p>; the same rules as tag |
safe_join |
safe_join(array, sep = "") (no keyword arguments) |
joins into a SafeString, escaping every item and the separator that is not already a SafeString: safe_join([tag.b("a"), "<"], " ") → <b>a</b> < |
class_names |
class_names(*values) |
Rails' class_names/token_list: the words of Strings and Symbols, of Arrays (nested too) and of each Hash key whose value is truthy, each word once; keyword arguments are one more such Hash: class_names("btn", active: @on, big: false) → "btn active" |
dom_id |
dom_id(record, prefix = "") (the prefix is positional, as in Rails) |
"article_12", "new_article" for an unsaved record, dom_id(@article, "edit") → "edit_article_12" (Cybertrain::Html.dom_id in Ruby) |
turbo_stream_from |
turbo_stream_from(*streams, ws: false) |
one <turbo-stream-source> subscribing the page to the streams (Strings, or records named "articles:12"); ws: true gives a ws:///wss:// URL and needs a request. See Realtime |
signed_stream_name |
signed_stream_name(*streams) |
the signed token alone, for hand-written JavaScript |
stream_source_path |
stream_source_path(*streams, mode: "json") |
the stream endpoint's path with the token and mode=json (or "raw") |
turbo_frame_tag |
turbo_frame_tag(id_or_record, src:, loading:, target:, class:, data:) do ... end |
<turbo-frame id="article_3" src="...">...</turbo-frame>; a record gives its dom_id; each attribute only when given |
turbo_stream |
turbo_stream.replace(target, partial:, locals:), .update(target, html:), .append(target) do ... end, .prepend, .before, .after, .remove(target) |
one <turbo-stream action="..."> element, for a *.turbo_stream.erb template; the target is a DOM id or a record; exactly one of a block, partial: (with locals:) and html: |
time_tag |
time_tag(time, text = nil, format:, class:, id:, title:, data:), or with a block |
<time datetime="2026-11-10T12:00:00Z">Tue, 10 Nov 2026 12:00:00 +0000</time>; a Date gives 2026-11-10; without format: the text is the locale's :default format; format: is a format name (:short, :long, or any other the dictionaries hold), formatted by l in the request's locale, or a strftime String (with English day and month names) (an unknown directive raises, and so does a width or flag strftime would read differently: %6L, use %6N; : only in %:z; no padding flag on %F %T %D %R %r %c %x %X %v; a width on a number replaces its padding, %5e gives " 5") |
Every helper text argument follows one rule: a SafeString passes through unescaped, anything else is escaped — link_to raw('<b>raw</b>'), post prints the bold tag literally, but link_to post.title, post escapes it.
The six number helpers are Cybertrain::NumberHelper's, which Ruby code calls as module functions with the same keywords (Cybertrain::NumberHelper.number_to_currency(price, unit: "€")). They take an Integer, a Float or a numeric String (decimal columns are Floats) and round half up on the digits of its decimal text, so the output is the same on both runtimes; anything else raises ArgumentError ("number_with_delimiter: \"abc\" is not a number"), as does a precision outside 0 to 100. In a template nil renders "" (a nullable decimal column prints as empty, as in Rails); Cybertrain::NumberHelper called from Ruby still raises ArgumentError for nil ("number_with_delimiter: nil is not a number"). In a template the defaults come from the request's locale (number.* in the dictionaries: ja's number_to_currency(1234) is "1,234円"), and a keyword given wins; from Ruby they are the English ones shown above.
The tag builder
tag evaluates to a builder (Cybertrain::Html::TagBuilder); any method called on it is an element, rendered by Cybertrain::Html.tag (also callable from Ruby: Html.tag("a", { href: "/x" }, "Go")):
<%= tag.div(class: "card") do %>
<%= tag.h2 @article.title, id: dom_id(@article) %>
<% end %>
<%= tag.input type: "text", name: "q", disabled: true %> <%# <input type="text" name="q" disabled> %>
<%= tag.path d: "M0 0 L10 10" %> <%# SVG elements work %>
<%= tag.my_widget data: { turbo_frame: "f" } %> <%# <my-widget data-turbo-frame="f"></my-widget> %>
<%= tag %>alone prints nothing.- The element name is the method name with
_turned into-; it must match[a-z][a-z0-9-]*("invalid element name 'Div'"otherwise, fromHtml.tag). - Content is the one positional argument (escaped unless a
SafeString, sotag.script("alert(1)")prints its text escaped) or the block's output (do ... end, or{ expr }whose value is printed escaped); the block wins. With neither,tag.divis<div></div>. - Void elements (
area base br col embed hr img input link meta source track wbr) render without a closing tag; content or a block for one is an error ("br is a void element"). - Attributes are the keyword arguments, in order:
nilandfalsedrop the attribute,truerenders it bare (disabled), an Array joins its non-nilitems with spaces (data: { ids: [1, 2] }givesdata-ids="1 2", not Rails' JSON),class:takes whatclass_namestakes (class: ["btn", { active: @on }]),data:andaria:Hashes nest todata-key="v"/aria-key="v"with underscores turned into dashes (andtrue/falsewritten out there); any other Hash value is an error ("attribute 'title' cannot be a Hash"). Every value is escaped, aSafeStringtoo. Attribute names must match[a-zA-Z_:][-a-zA-Z0-9_:.]*("invalid attribute name 'data-a b'");onclick:and the like are allowed, being the author's.
FormBuilder (f in form_with ... do |f|)
Every method returns a SafeString; an unlisted one is a RuntimeError ("undefined method 'color_wheel' for FormBuilder").
| Method | Renders |
|---|---|
f.label :title / f.label :title, "Text" |
<label for="post_title">Title</label> — default text is the humanized attribute (published_at → "Published at", author_id → "Author"); explicit text is escaped unless a SafeString |
f.text_field :title (also email_field, password_field, number_field, date_field, datetime_local_field, time_field, range_field, color_field, search_field, telephone_field, url_field, hidden_field) |
<input type="..." name="post[title]" id="post_title" value="...">; password_field never emits value=; telephone_field is type="tel"; a Time is written as the browser reads it (2026-11-10, 2026-11-10T12:00:00, 12:00:00.000) |
f.select :status, ["draft", "published"] (also include_blank:, prompt:, selected:, disabled:, multiple:) |
<select name="post[status]" id="post_status"> with one <option> per choice, the current value selected; choices are values, [text, value] pairs, or a Hash or [label, [choices]] groups for <optgroup>; multiple: true names it post[status][] and writes a hidden empty input first |
f.collection_select :author_id, @authors, :id, :name |
a <select> with one <option> per record, its value and text read from the two methods |
f.radio_button :status, "draft" |
<input type="radio" name="post[status]" id="post_status_draft" value="draft">, checked when the value matches (checked: overrides) |
f.file_field :cover (also accept: "image/*", required: true) |
<input type="file" name="post[cover]" id="post_cover"> — never a value=, and the attribute need not be a column; the form must be form_with ..., multipart: true; multiple: true raises ArgumentError (one file per field) |
f.text_area :body |
<textarea name="post[body]" id="post_body">\n...</textarea> (leading \n, as Rails does — browsers eat the first newline) |
f.check_box :published |
hidden value="0" input then the real checkbox, so an unchecked box still submits "0"; include_hidden: false leaves the hidden input out |
f.submit / f.submit "Text" |
default text "Create Post"/"Update Post" (by persisted?), or "Save changes" with no model |
With a model, fields are named post[title]/id="post_title" (Inflector.underscore(model.model_name) as scope); form_with(..., scope: :q) uses q[title]/id="q_title" instead; with form_with(url: ...) and no model or scope, the bare attribute name is used for both. Every attribute value and option text is escaped once (a SafeString as it is). Extra keyword args become HTML attributes in order given: true → attr="attr", false/nil dropped, anything else → attr="value" (escaped), underscores become hyphens (data_confirm: "Sure?" → data-confirm="Sure?"), and class: merges with the automatic field_with_errors class added when model.errors.key?(attr).
Application helpers
A module under app/helpers/ is a helper module, as in Rails: every public method in it can be called from any template, without a receiver.
module PricesHelper
def price(value, unit: "USD", precision: 2)
amount = Cybertrain::Cast.float(value).round(Cybertrain::Cast.int(precision))
Cybertrain::Html.tag("span", { class: "price" }, "#{amount} #{unit}")
end
def panel(title, &block)
Cybertrain::Html.tag("section", { class: "panel" }, Cybertrain::Html.safe_join([Cybertrain::Html.tag("h2", {}, title), yield]))
end
end
<%= price @item.cost %> <%# <span class="price">12.5 USD</span> %>
<%= price @item.cost, unit: "EUR" %>
<%= panel "Totals" do %><p><%= @total %></p><% end %>
- Generated dispatch. Templates cannot
send, sospin run genreadsapp/helpers/**/*.rbas text and writesgen/helpers.rb: anApplicationHelpersclass that includes every module (and the route helpers) and acaseover the helper names. Add or change a helper's signature, and the next build regenerates it (the development server does both).cybertrain generate helper priceswrites an emptyPricesHelperand a test. - What is a helper. Public instance methods of a
module(def self.x, setters and everything afterprivateorprotectedare not), whatever their file. A template passes values by position or keyword, so every parameter is named:*rest,**opts,...are generator errors, as is a required parameter after an optional one. A helper takes at most three optional parameters (the generatedcasehas one arm per combination given, so an omitted keyword gets the method's own default). A wrong call is anArgumentErrorat render time:"wrong number of arguments for 'price' (given 0, expected 1)","unknown keyword 'cur' for 'price' (known: unit, precision)". - Reserved names. A helper may not be named like a framework helper (
link_to,render,tag,dom_id,params,content, ...), like a method ofCybertrain::Template::Helpers(public or private: theincludewould replace it for the framework too),yield, or with a_path/_urlending (the route helpers answer those); the same name in two modules is an error as well.spin run genstops with the file, the line and the reason. - Values. Arguments arrive as the template's values (String, Integer, Float,
nil, a record, an Array, a Hash); narrow them withCybertrain::Cast(Cast.str,Cast.int,Cast.float) before arithmetic. What a helper returns is printed like any value: aStringis escaped, aSafeStringis not, so build HTML withCybertrain::Html.tag(name, attrs, content),Html.safe_join,Html.class_names,Html.dom_id,Html.escape,Cybertrain::SafeString.ofor the Ruby forms of the link helpers,link_to_path(text, path, attrs)andbutton_to_path(text, path, attrs)(method:insideattrs). - Blocks. A helper with a
&blockparameter takes ado ... endblock;yield(no arguments) returns what the block printed, as aSafeString.
Components
A component is a class with keyword arguments and a template beside it, in ViewComponent's shape:
class CardComponent < Cybertrain::Component
def initialize(title:, value: 0, tone: "neutral")
@title = title
@value = value
@tone = tone
end
def value_text = "#{@value} pts"
def tone_class = "card--#{@tone}"
end
<%= tag.div(class: class_names("card", tone_class)) do %>
<h3><%= title %></h3><p><%= value_text %></p><%= content %>
<% end %>
<%= render component: "card", title: "Visitors", value: @count %>
<%= render component: "card", title: "Notes", tone: "warm" do %>
<p><%= @note %></p>
<% end %>
- The template sees the component's instance variables as locals (
title), its public methods without parameters by name (value_text), andcontent, what thedoblock printed (""without one). It renders without a layout, can render partials and other components, and counts towardmax_render_depthlike a partial. A partial it renders does not see the component's methods. A bare partial name in a component template (render "chip") is looked up underapp/components/(app/components/_chip.html.erb); a name with a directory (render "shared/note") underapp/views/as usual. - A component is named by its snake-case name without
_component, as a partial is named by its path:"card"forCardComponent,"admin/user_row"forAdmin::UserRowComponent(app/components/admin/user_row_component.rb). Templates cannot name constants. spin run genwritesgen/components.rbfrom a lexical scan, as for helpers: the class line, the@x =assignments, the parameterlessdefs and theinitializekeywords.initializetakes keywords only (at most three of them optional), and its template must exist; a missing keyword or an unknown one is anArgumentErrorat render time. An unknown component isCybertrain::Component::Unknown:"no component 'crad' (app/components/crad_component.rb, then `spin run gen`)".contentis reserved: aninitializekeyword or an@contentinstance variable of that name would be overwritten by the block's output, sospin run genrefuses it, naming the file and line.app/views/components/stays a view directory like any other (aComponentsController's); onlyapp/views/__components/is reserved, the names component templates are kept under.cybertrain generate component card title value:integerwrites the class, its template and a test that renders it withCybertrain::Test.render_component.
Rendering outside a request
A broadcast, a job or a mail body renders without a request:
html = Cybertrain::Views.render_partial("articles/article", article: article) # app/views/articles/_article.html.erb
card = Cybertrain::Views.render_component(CardComponent.new(title: "Visitors", value: 12))
Both return the HTML as a String, with the application's helpers. Path helpers work (article_path(article)), strict locals are checked, and forms (form_with, button_to) render without the authenticity token (a Turbo page submits the one from csrf_meta_tags). A helper that needs a request raises Cybertrain::Views::OutsideRequest ("csrf_token needs a request"): csrf_token, csrf_meta_tags, params, flash, request_path, current_page?, content_security_policy_nonce (so csp_meta_tag and a tag helper given nonce: true), javascript_importmap_tags, any *_url helper and turbo_stream_from ... ws: true. paginate links carry only the path's own query string. (A bare Cybertrain::Template::Helpers.new(nil), as a unit test might build, answers those with empty values instead.)
Layouts, yield, content_for, partials
Engine#render_with_layout(name, layout, env, helpers) renders name into env["__content"] (a SafeString), then renders layout against the same env:
<title><%= yield :title %></title>
<%= yield %>
yield prints env["__content"]; yield :key prints env["__content_key"], or nothing if unset. yield is special-cased directly in the interpreter and cannot be overridden as a helper. A page fills a slot with content_for, anywhere in its body (order relative to yield does not matter — the page fully renders before the layout does):
<% content_for :title do %>Post: <%= @post.title %><% end %>
<% content_for :title, " (draft)" %> <%# appends: calls accumulate, they don't replace %>
Per-controller layouts
An action renders inside app/views/layouts/application.html.erb (when it
exists) unless its controller, a parent or a concern it includes chooses
another:
class AdminController < ApplicationController
layout "print", only: [:receipt] # app/views/layouts/print.html.erb
layout :choose_layout # a method: a name, false for none, nil for the parent's
private
def choose_layout = request.header("Turbo-Frame").to_s.empty? ? "application" : "frame"
end
layout "admin" alone names one layout for every action. spin run gen
reads the layout lines (a quoted name, false, or a method's Symbol,
with only: / except:) and writes the controller's
controller_layout(action). The declarations are tried in order and the
first that applies wins (Rails lets a later one replace an earlier one);
a concern's lines count at its include. render layout: "x" uses
layouts/x for one call and render layout: false none; a leading layouts/
is accepted (layout "layouts/x" is layouts/x). A layout line or
render layout: that names a layout that does not exist raises
MissingTemplate; only the default application layout is optional (an
action renders bare without it). Only html is
rendered in a layout; another format's template renders without one. Any
other layout argument (nil, a lambda, a constant) is refused by gen.
Partials and render
<%= render "form", post: @post %>
<%= render partial: "form", locals: { post: @post } %>
<%= render "comments/comment", comment: c %>
- A bare name with no
/resolves in the current template's own directory (via an env key the rendering machinery sets,__template_dir):render "form"fromposts/showlooks forposts/_form.html.erb. A name containing/is an explicit path; only its last segment gets the_prefix ("comments/comment"→comments/_comment.html.erb). - The partial gets a duplicate of the caller's entire environment (ivars and any locals already in scope) plus the explicit locals given to
render— it is not sandboxed to only what was passed. Strict locals only validate the names explicitly given to thatrendercall against the declared list; they do not stop the partial from also reading some other name it inherits from the caller's environment. - Only
content_forkeys (__content_*) copy back out of a partial's scope into the caller's; ordinary locals it assigns do not leak back. - Missing/extra locals against a
<%# locals: %>declaration areRuntimeErrors:"missing local 'post' for posts/_form.html.erb","unknown local 'extra' for posts/_form.html.erb".
Collections
<%= render partial: "comment", collection: @comments, as: :comment, spacer_template: "divider" %>
<%= render @comments %> <%# each record's comments/_comment.html.erb %>
<%= render @comment %> <%# one record, no counter %>
<%= render component: "comment", collection: @comments %>
collection:renders the partial once per item of an Array, as the local named byas:(the partial's own name by default), with<as>_countercounting from 0, thelocals:given to each andspacer_template:(a partial) between items; an empty collection renders nothing. A partial with strict locals gets the counter only when it declares it, and the item wins over a local of the same name.render @commentspicks each record's partial from its model,<plural>/_<singular>(admin/notes/_notefor anAdmin::Note), so a list may mix models.- A component whose one required keyword is named after it (
CommentComponentwithcomment:) getsCommentComponent.with_collection(items), andrender component: "comment", collection: @commentsrenders it once per item, passingcomment_counter:wheninitializedeclares it.collection:takes no other keyword (render component: "comment", collection: @comments, extra: 1is an error naming it); the block's content is not passed.
File resolution (engine.rb)
"posts/show" and "posts/show.html.erb" name the same template. Development reads app/views/ from disk with cache: false (a file is re-read and re-parsed whenever its mtime or size changes, and that re-parse writes the engine's cache, so the development server always serves with one worker and ignores SPINEL_WORKERS, saying so in its boot banner); the test environment reads from disk with cache: true (parsed once). A production binary never touches disk: cybertrain build runs spin run gen -- --embed-views, which writes every *.erb under app/views/ (dotfiles and symlinked directories skipped) into gen/views.rb, and Engine.embedded(sources) parses every entry once, when the binary boots (error messages keep the same posts/show.html.erb:12 shape), so a template with a syntax error stops the boot instead of failing its page; a binary whose table is empty refuses to boot in production. A missing template raises Cybertrain::Template::MissingTemplate — "Missing template <full path>" from disk, "Missing template posts/nope.html.erb (embedded)" from the table.
File lookups resolve the view root and template path through symlinks and only load regular files inside that root. Paths that escape it (including through symlinks) raise MissingTemplate; exists? returns false for those paths.
Errors
Two exception classes, both in ast.rb's Cybertrain::Template namespace (distinct from ::SyntaxError/::RuntimeError):
SyntaxError— raised while tokenizing/parsing, before any interpretation. Shape:"<template>:<line>: <what>", e.g."posts/show:2: 'if' without 'end'","posts/show:1: unterminated <% tag","posts/show:1: unexpected ')' in 'foo(1))'". Raised directly byEngine#template(hence#render/#render_with_layout) when a page or layout file fails to parse — never caught or rewrapped by the interpreter.RuntimeError— raised while evaluating, same message shape, but<template>is whichever template is currently rendering (Interpreter#renderswaps@namein and out) — a partial's own error keeps the partial's name and line, never the caller's:"posts/_row:1: undefined method 'bogus' for String".
Any plain StandardError from a helper or FormBuilder/custom-object method call (a bare raise "text", ArgumentError, KeyError, even a Cybertrain::Template::RuntimeError from a nested render) is caught and "relocated": rewritten to "<current template>:<current line>: <original message>", unless it is already exactly the last-relocated message (a nested render already stamped its own, more specific location), in which case it passes through unchanged. A Cybertrain::Template::SyntaxError raised by a helper (a partial that fails to parse, mid-render) is never rewrapped — it keeps its own "<partial>:<line>: ..." message and class, so a broken partial is always reported as a SyntaxError about itself, not a RuntimeError about whoever rendered it.
Cybertrain::Views::OutsideRequest and Cybertrain::Component::Unknown also pass through unwrapped, keeping their class, so a caller of Views.render_partial can rescue them.
MissingTemplate (StandardError, engine.rb) is raised unwrapped, no template:line prefix, from a top-level Engine#template/#render/#render_with_layout call (e.g. a controller rendering a missing action template or layout): "Missing template <path>". The same exception raised inside a template via the render helper's partial lookup goes through relocation instead and comes out a RuntimeError: "posts/inline:1: Missing template test/fixtures/views/posts/_nope.html.erb".
Differences from Rails ERB
| Rails ERB | Cybertrain |
|---|---|
| Compiled to a Ruby method; any Ruby, any object, any method works | Interpreted against fixed per-type dispatch tables; only what the per-type method table lists is callable |
ActiveSupport::SafeBuffer is a String subclass |
SafeString is a separate wrapper class — only to_s/html_safe?/size/length/empty? are callable on it |
Blocks: each, { }, map, any Enumerable method |
{ } and do...end on a fixed list of Array/Hash methods (no each_with_object, inject), each/each_with_index/each_slice loops, helper calls and tag |
xs.each { } — zero block params is fine |
each/each_with_index require declaring 1 or 2 block params |
link_to text, path, method: :delete (JS-driven) |
No method: on link_to — use button_to for a real non-GET form |
Strict locals accept name: default_expr (Rails 7.1) |
Only bare name: (required); a default-value entry is a SyntaxError |
| Undefined ivar/local resolves via Ruby / the view context's methods | @x is a plain, never-failing env lookup; a bare undefined local is an explicit, closed helper-call attempt ("undefined helper" if no match) |
case/when with === (ranges, classes, regexes) |
case/when with == only (numbers by value) |
and/or/not, ranges, regexes, multiple assignment all work |
None exist; the reserved words fail with a specific "not supported in templates" message, not a generic parse error |
| Numeric literals: hex, octal, binary, exponents, rationals | Only decimal integers/floats with optional _ separators |
:"quoted symbol", :+ operator symbols |
Symbols are identifier characters only |
foo (x), foo [x] (space tolerated, sometimes with a warning) |
Both are hard SyntaxErrors — no space before a call's ( or an index's [ |
| Nested unparenthesized calls resolved by Ruby's own parser | Only the outermost call in an expression gets parenthesis-free arguments |
An undeclared/misspelled attribute reliably raises NoMethodError |
A generated model raises "undefined method 'x' for Post" (a Template::RuntimeError) and renders an existing nil attribute empty; a hand-written model that does not override attribute_or_method? renders an unknown name empty |
1 / 0 and 1.0 / 0 both raise ZeroDivisionError |
Integer division/modulo by zero raises "divided by 0"; Float follows IEEE-754 (Infinity/NaN), no error |
distance_of_time_in_words/pluralization support i18n locales |
time_ago_in_words, distance_of_time_in_words, the number helpers and time_tag read the locale's dictionary; pluralize inflects English only (Internationalization) |
Every module in app/helpers is mixed in; any signature; a helper may override a framework one |
Modules are scanned at build time into a generated case: named parameters only, at most three optional, no framework helper name and no _path/_url ending (Application helpers) |
ViewComponent: render CardComponent.new(title: "x"), with_collection, slots |
render component: "card", title: "x" by name, content from the block, collection: for a component named after its one required keyword; no slots (Components, Collections) |
A later layout line replaces an earlier one |
The first layout declaration that applies wins (Per-controller layouts) |