Package Reference

HypertextLiteral

The HypertextLiteral module exports the @htl macro which implements interpolation aware of hypertext escape context. It also provides for escaping of JavaScript within the <script> tag.

julia> v = "<1 Brown \"M&M's\"!";

julia> @htl "<span>$v</span>"
<span>&lt;1 Brown &quot;M&amp;M&apos;s&quot;!</span>

julia> @htl "<script>console.log($v)</script>"
<script>console.log("<1 Brown \"M&M's\"!")</script>

This escaping of Julia values to JavaScript values is done with js function, which is not exported by default.

julia> v = "<1 Brown \"M&M's\"!";

julia> @htl "<div onclick='alert($(HypertextLiteral.js(v)))'>"
<div onclick='alert(&quot;&lt;1 Brown \&quot;M&amp;M&apos;s\&quot;!&quot;)'>

There is also a non-standard string literal, @htl_str that is not exported. It can be used with dynamically constructed templates.

See also: @htl, HypertextLiteral.@htl_str

EscapeProxy(io) - wrap an `io` to perform HTML escaping

This is a transparent proxy that performs HTML escaping so that objects that are printed are properly converted into valid HTML values. As a special case, objects wrapped with Bypass are not escaped, and bypass the proxy.

Examples

julia> ep = EscapeProxy(stdout);
julia> print(ep, "A&B")
A&B
julia> print(ep, Bypass("<tag/>"))
<tag/>

JavaScript(js) - shows `js` as `"text/javascript"`

Render(data) - printed object shows its text/html

Reprint(fn) - apply the lambda function when printed

Result(fn)

This object wraps a function produced by the @htl macro. This function prints a the evaluated to the given io. This object is also showable via "text/html" so it may be used in an HTML display context.

Script(data)

This object renders Javascript data escaped within an attribute.

ScriptTag(data)

This object prints data unescaped within a <script> tag, wrapped in a ScriptTagProxy that guards against invalid script content.

ScriptTagProxy(io)

This is a transparent proxy that ensures neither <!-- nor </script> occur in the output stream.

Examples

julia> gp = ScriptTagProxy(stdout);
julia> print(gp, "valid");
valid
julia> print(gp, "</script>")
ERROR: "Content within a script tag must not contain `</script>`"

StyleTag(data)

This object prints data unescaped within a <style> tag, wrapped in a StyleTagProxy that guards against invalid style content. Content is treated as if it had occurred within an attribute value, only that amperstand escaping is not used.

StyleTagProxy(io)

This is a transparent proxy that ensures neither <!-- nor </style> occur in the output stream.

Examples

julia> gp = StyleTagProxy(stdout);
julia> print(gp, "valid");
valid
julia> print(gp, "</style>")
ERROR: "Content within a style tag must not contain `</style>`"

attribute_value(x)

This method may be implemented to specify a printed representation suitable for use within a quoted attribute value.

content(x)

This method may be implemented to specify a printed representation suitable for text/html output. AbstractString, Symbol and Number (including Bool) types are printed, with proper escaping.

A default implementation first looks to see if typeof(x) has implemented a way to show themselves as text/html, if so, this is used. Otherwise, the result is printed within a <span> tag, using a class that includes the module and type name. Hence, missing is serialized as: <span class="Base-Missing">missing</span>.

interpolate(args)::Expr

Take an interweaved set of Julia expressions and strings, tokenize the strings according to the HTML specification [1], wrapping the expressions with wrappers based upon the escaping context, and returning an expression that combines the result with an Result wrapper.

For these purposes, a Symbol is treated as an expression to be resolved; while a String is treated as a literal string that won't be escaped. Critically, interpolated strings to be escaped are represented as an Expr with head of :string.

There are tags, "script" and "style" which are rawtext, in these cases there is no escaping, and instead raise an exception if the appropriate ending tag is in substituted content.

[1] https://html.spec.whatwg.org/multipage/parsing.html#tokenization

js(x)

This method may be implemented to specify a printed representation suitable for use within a quoted attribute value starting with on.

normalize_attribute_name(name)

For String names, this simply verifies that they pass the attribute name production, but are otherwise untouched.

For Symbol names, this converts snake_case Symbol objects to their kebab-case equivalent. So that keywords, such as for could be used, we strip leading underscores.

print_script(io, value)

Show value as "text/javascript" to the given io, this provides some baseline functionality for built-in data types.

- `nothing` becomes `undefined`
- `missing` becomes `null`
- `Bool` values are printed as `true` or `false`
- `AbstractString` and `Symbol` become a double-quoted string
- `AbstractVector` and `Tuple` become an array
- `Dict` and `NamedTuple` become a Javascript object, with
   keys converted to string values
- `AbstractFloat` and `Integer` are printed directly, where
  `NaN` remains `NaN` but `Inf` is printed as `Infinity`

The fallback behavior of print_script is to show the object as "text/javascript". The Javascript wrapper will take any string and let it be printed in this way.

print_script_hook(io, value)

Provides a hook to override print_script for custom Javascript runtimes, such as Pluto.jl, to provide their own value marshalling.

print_value(io, value)

This is the default translation of interpolated values within rawtext tags, such as <style> and attribute values.

• The elements of a Tuple or AbstractArray object are printed, with a space between each item.

• The Pair, NamedTuple, and Dict objects are treated as if they are CSS style elements, with a colon between key and value, each pair delimited by a semi-colon.

• The Nothing object is treated as an empty string.

Otherwise, this method simply uses the standard print representation for the given object.

rewrite_inside_tag(expr)

Attempt to speed up serialization of inside_tag by exploring the expression tree at macro expansion time.

@htl string-expression

Create a Result object with string interpolation ($) that uses context-sensitive hypertext escaping. Before Julia 1.6, interpolated string literals, e.g. $("Strunk & White"), are treated as errors since they cannot be reliably detected (see Julia issue #38501).

@htl_str -> Result

Create a Result object with string interpolation ($) that uses context-sensitive hypertext escaping. Unlike the @htl macro, this string literal does not include escaping feature [1]. To include $ within user content one must write $. Observe that " and any other HTML ampersand escape sequence can be used as appropriate.

In this syntax, interpolation is extended beyond regular Julia strings to handle three additional cases: tuples, named tuples (for attributes), and generators. See Julia #38734 for the feature request so that this could also work within the @htl macro syntax.

[1] There are also a few edge cases, see @raw_str documentation and Julia #22926 for more detail.