A small and fast precompiled template engine for MoonBit.

template

html

rendering

escaping

filters

moon add justjavac/template@0.1.1

Download zip

Author

justjavac

Version

0.1.1

License

MIT

Repository

github.com/justjavac/moonbit-template

Last updated

2 months ago

Downloads

README

#justjavac/template

justjavac/template is a precompiled template engine for MoonBit.

#Quick Start

Then define data in ordinary MoonBit source:

///|
#tplpath("templates/profile_card.mtpl")
pub(all) struct ProfileCard {
  name : String
  bio : @template.SafeHtml
}

Write the template:

<article>
  <h1><%= name |> trim |> upper %></h1>
  <%- bio %>
</article>

Generate the renderer:

moon install justjavac/template_codegen

For normal package builds, wire the same command into pre-build:

options(
  "pre-build": [
    {
      "input": [
        "main.mbt",
        "templates/profile_card.mtpl",
        "templates/partials/footer.mtpl",
      ],
      "output": "tpl.generated.mbt",
      "command": "template_codegen --scan $input -o $output",
    },
  ],
)

The generated source implements @template.Render for ProfileCard, so callers use the method form:

///|
let page = ProfileCard::{
  name: " justjavac ",
  bio: @template.safe_html("<p>Trusted HTML</p>"),
}

///|
let html = try! page.render()

#
Render

source

pub(open) trait Render {
  fn render(Self) -> String raise
}

Values that can render themselves to HTML strings.

Generated template implementations use this trait so callers can render pages with page.render(). The method allows raise because template code can call ordinary MoonBit functions that use checked errors. User-defined page structs normally receive their implementation from template_codegen.

#
RenderError

source

pub(all) suberror RenderError {
  Message(String)
  InvalidInclude(String)
} derive(Eq, @moonbitlang/core/debug.Debug
Debug)

Error values reserved for render-time failures.

The current generator mostly reports parse and codegen problems before rendering, but this error type gives runtime integrations a stable place for checked failures such as invalid dynamic includes.

#
SafeHtml

source

pub struct SafeHtml {
  value : String
}

HTML that has already been validated by the caller.

SafeHtml is the trust boundary for raw output. Generated templates escape ordinary values by default; wrapping a string in this type documents that the caller intentionally wants the markup written without escaping.

impl Show for SafeHtml

#
SafeHtml::new

source

fn SafeHtml::new(value : String) -> SafeHtml

Wraps trusted HTML so it can be passed through raw template output.

Prefer constructing this value near the code that validates or produces the markup, so the trust decision remains visible at the call site.

#
SafeHtml::to_string

source

fn SafeHtml::to_string(self : SafeHtml) -> String

Returns the trusted HTML payload without escaping it.

This is useful when adapting SafeHtml to another renderer or writing tests that need to inspect the exact trusted markup.

#
default

source

fn default(value : String, fallback~ : String) -> String

Returns fallback when value is empty.

Non-empty strings are returned unchanged, which makes this a small display helper rather than a general Option replacement.

#
escape_html

source

fn escape_html(value : String) -> String

Escapes the HTML-sensitive characters &, <, >, ", and '.

The returned string is safe to place in normal HTML text positions produced by templates. Raw output must be requested explicitly through template syntax or by rendering trusted SafeHtml.

#
lower

source

fn lower(value : String) -> String

Converts a string to lowercase using MoonBit's string casing rules.

The result can be composed with other filters in a template pipeline.

#
render_value

source

fn[T : Show] render_value(value : T) -> String

Formats a value the same way MoonBit string interpolation does.

Generated templates call this for expression output before applying the escaped or raw write path, so any type with a Show implementation can be rendered consistently.

#
replace

source

fn replace(value : String, old~ : String, new~ : String) -> String

Replaces every occurrence of old with new.

The named arguments make generated pipeline calls readable, for example value |> replace(old=" ", new="-").

#
safe_html

source

fn safe_html(value : String) -> SafeHtml

Creates a trusted HTML wrapper.

This convenience constructor is equivalent to SafeHtml::new(value) and is exported for template-facing code that prefers function-style helpers.

#
trim

source

fn trim(value : String) -> String

Removes leading and trailing Unicode whitespace.

This filter is intended for pipeline use in templates and mirrors String::trim.

#
trim_end

source

fn trim_end(value : String) -> String

Removes trailing Unicode whitespace.

This filter is intended for pipeline use in templates and mirrors String::trim_end.

#
trim_start

source

fn trim_start(value : String) -> String

Removes leading Unicode whitespace.

This filter is intended for pipeline use in templates and mirrors String::trim_start.

#
upper

source

fn upper(value : String) -> String

Converts a string to uppercase using MoonBit's string casing rules.

The result can be composed with other filters in a template pipeline.

#
write_escaped

source

fn write_escaped(out : StringBuilder, value : String) -> Unit

Escapes text and writes it into a template output buffer.

This is the default output path for generated escaped expressions such as <%= value %>.

#
write_raw

source

fn write_raw(out : StringBuilder, value : String) -> Unit

Writes raw text into a template output buffer without escaping it.

Generated renderers use this path for trusted content and raw template expressions. Prefer write_escaped for ordinary user-provided strings.

Source Files

Site source Report issue Packages Build queue Skills Statistics

template

#justjavac/template

#Quick Start

#Render

#RenderError

#SafeHtml

#SafeHtml::new

#SafeHtml::to_string

#default

#escape_html

#lower

#render_value

#replace

#safe_html

#trim

#trim_end

#trim_start

#upper

#write_escaped

#write_raw

Source Files

#
Render

#
RenderError

#
SafeHtml

#
SafeHtml::new

#
SafeHtml::to_string

#
default

#
escape_html

#
lower

#
render_value

#
replace

#
safe_html

#
trim

#
trim_end

#
trim_start

#
upper

#
write_escaped

#
write_raw