EAG templates (std)
EAG (“Embedded AGentica”) is Agentica’s ERB: a template is a heredoc <<~EAG whose text has the tags of Ruby’s ERB. A template is code of the file that holds it: the checker types every tag, there is no eval, and the result is a String. The file must import EAG from "std/eag" (any import form; CHECK-EAG-IMPORT without it), as Ruby needs require "erb". This is the one name that is not Ruby’s: Ruby has no heredoc form of ERB.
EAG.html_escape(value: String) -> String # ERB::Util.html_escapeimport EAG from "std/eag"
struct Item
title: String
visible: Bool
end
def page(name: String, items: List[Item]) -> String
<<~EAG
<h1><%= EAG.html_escape(name) %></h1>
<ul>
<% for item in items %>
<% if item.visible %>
<li><%= EAG.html_escape(item.title) -%>
</li>
<% end %>
<% end %>
</ul>
EAG
end
def main() -> Void
puts(page("a<b", [Item(title: "x&y", visible: true), Item(title: "z", visible: false)]))
endOutput
<h1>a<b</h1>
<ul>
<li>x&y </li>
</ul>A template with an escaper escapes what <%= %> inserts and leaves <%== alone:
import EAG from "std/eag"
def card(name: String, note: String) -> String
<<~EAG
<%@ escape &EAG.html_escape %>
<p><%= name %>: <%== note %></p>
EAG
end
def main() -> Void
puts(card("a<b", "<em>ok</em>"))
endOutput
<p>a<b: <em>ok</em></p><%= code %>inserts the value ofcodeas"#{code}"does (to_s). The output is raw, as ERB’s is: nothing is escaped, so writeEAG.html_escape(...)for HTML, or give the template an escaper (below).<%== code %>inserts the value raw, with or without an escaper (unlike Erubi, where<%==escapes when<%=does not).<%@ escape function %>alone on the first line of the template gives it an escaper:functionis a value of typeFn[String, String], such as&EAG.html_escape, and every<%= code %>then insertsfunction.call("#{code}"), so HTML is escaped by default and<%==is the way out. A function of another type isCHECK-TYPE-MISMATCHat the function;escapeis the only directive word, and a directive with another word, with no function, not on the first line or given twice isPARSE-EAG-DIRECTIVE. AnyFn[String, String]works, so a library can offer its own escaper.<% code %>is a statement:if,elsif,else,for,while,case,end, or any other. The tags of a template must close their own blocks (PARSE-EAG-BLOCK). A template is a block of its function, so a tag cannot assign a variable of the function (CHECK-CAPTURED-ASSIGNMENT); a variable made in a tag lives in the template. For the same reason a block inside a tag cannot write output:<% items.each do |i| %><%= i %><% end %>isCHECK-CAPTURED-ASSIGNMENT, so write<% for i in items %>(Ruby’seach dohabit does not work here).<%# note %>is dropped.<%%is the text<%.-%>removes the line break after the tag, and<%-removes the spaces before the tag when only spaces come before it on its line (Ruby’strim_mode: "-").- One rule is not Ruby’s
trim_mode: "-": a line that holds only one<% %>or<%# %>tag and spaces is removed whole, so a loop leaves no blank lines. - The body is raw text: no
\nor other escape and no#{}. The common indentation is removed, as for any<<~heredoc, and a body may be one line. A tag ends on its line, at the first%>(PARSE-EAG-UNTERMINATED-TAG). - A template is an expression, so it can be returned, assigned, passed as an argument or followed by a method (
<<~EAG.length). An error in a tag has the place of the tag in the template.agentica type-atandrefsat a position inside a tag do not work yet (QUERY-NO-EXPRESSION);refsby name finds the names a tag uses.
html_escape replaces &, <, >, " and ' with &, <, >, " and ', as ERB::Util.html_escape does. It takes a String; call to_s on another value first. Ruby’s alias h does not exist here.