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_escape
import 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)]))
end
Output
<h1>a&lt;b</h1>
<ul>
  <li>x&amp;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>"))
end
Output
<p>a&lt;b: <em>ok</em></p>
  • <%= code %> inserts the value of code as "#{code}" does (to_s). The output is raw, as ERB’s is: nothing is escaped, so write EAG.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: function is a value of type Fn[String, String], such as &EAG.html_escape, and every <%= code %> then inserts function.call("#{code}"), so HTML is escaped by default and <%== is the way out. A function of another type is CHECK-TYPE-MISMATCH at the function; escape is the only directive word, and a directive with another word, with no function, not on the first line or given twice is PARSE-EAG-DIRECTIVE. Any Fn[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 %> is CHECK-CAPTURED-ASSIGNMENT, so write <% for i in items %> (Ruby’s each do habit 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’s trim_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 \n or 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-at and refs at a position inside a tag do not work yet (QUERY-NO-EXPRESSION); refs by name finds the names a tag uses.

html_escape replaces &, <, >, " and ' with &amp;, &lt;, &gt;, &quot; and &#39;, 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.