Compile errors

lttr.Compile checks everything about a template that doesn't depend on data: the Comark source, the frontmatter, every module and its attributes, every merge tag and binding against your Go type, and the family rules. It reports every problem it finds at once, each with the template name, line and column.

Read an error

Each error is one line: name:line:col: message. Lines and columns start at 1, and columns count bytes. When there are several, Compile joins them with errors.Join, so printing the error prints one per line:

auth.reset:7:15: unknown name "cod"
auth.reset:11:1: notice: tone must be "warn"

A few things decide what you see:

• A parse error stops early. If the Comark itself can't be parsed (an unclosed frontmatter, an invalid attribute list, bad props YAML, invalid UTF-8), you get that one error, the earliest in the file.
• Template errors come before family errors. The family rules (from, issue, legal, footer.*, forbidden modules) run only once the template compiles on its own. Fix the first batch and the family errors appear on the next compile (D28).
• Module errors point at the module. An unknown attribute or a wrong count is reported at the first : of the component, not at the attribute.
• Exact duplicates are dropped.

Handle errors in Go

Every positioned error is an *ir.Error:

type Error struct {
    Name string // template (or copy) name
    Pos  Pos    // Pos{Line, Col}, 1-based
    Msg  string
}

errors.As finds the first one. To walk all of them, unwrap the joined error:

package main

import (
    "errors"
    "fmt"
    "net/mail"

    "github.com/sulv-io/lttr"
    "github.com/sulv-io/lttr/ir"
)

type Reset struct {
    Code      string `json:"code"`
    ExpiresIn string `json:"expires_in"`
}

var families = lttr.NewRegistry(lttr.Family{
    Name:   "security",
    From:   mail.Address{Name: "Acme Security", Address: "security@acme.example"},
    Stream: lttr.Security,
    Header: lttr.H1,
    Footer: lttr.F2,
})

const src = `---
template: auth.reset
family: security
subject: Your reset code
---

::code{value="{{cod}}"}
It expires in {{expires_in}}.
::

::notice{tone="red"}
Didn't ask for this? You can ignore this email.
::
`

func main() {
    _, err := lttr.Compile[Reset](families, "auth.reset", []byte(src))
    if err == nil {
        return
    }

    // The whole error: one "name:line:col: message" per line.
    fmt.Println(err)

    // Each joined error is an *ir.Error with its own position.
    errs := []error{err}
    if j, ok := err.(interface{ Unwrap() []error }); ok {
        errs = j.Unwrap()
    }
    for _, e := range errs {
        var ce *ir.Error
        if errors.As(e, &ce) {
            fmt.Printf("line %d, col %d: %s\n", ce.Pos.Line, ce.Pos.Col, ce.Msg)
        }
    }
}

auth.reset:7:15: unknown name "cod"
auth.reset:11:1: notice: tone must be "warn"
line 7, col 15: unknown name "cod"
line 11, col 1: notice: tone must be "warn"

Two errors have no position, because they are about the call rather than the template: lttr: template data must be a struct, got string when T is not a struct, and lttr: nil registry.

MustCompile panics with the same joined error. Use it for package-level templates, so a broken template stops the service at startup, and Compile when the source comes from somewhere you don't control.

Read warnings

Warnings never fail a compile. They are on the compiled template, formatted name:line:col: warning: message, and are also copied into every rendered Message.Warnings:

func TestTemplatesHaveNoWarnings(t *testing.T) {
    for _, w := range orderShipped.Meta().Warnings {
        t.Error(w) // e.g. order.shipped:1:1: warning: frontmatter: no preheader
    }
}

Warnings are produced only when the template compiles. A template with errors reports the errors alone.

Fix common errors

The messages below are copied from the compiler; quoted names and numbers change with your template.

Syntax

Frontmatter

Modules

Merge tags and bindings

Families

Errors that depend on data happen at render time instead: a tag with no value and no fallback (no value for {{order_id}}), a merge value in a URL host that isn't a single DNS label preceded by // or . and followed by . (merge value {{shop}} cannot form part of a url host — a missing optional value there is the same error, not dropped), an invalid URL, an empty subject. They are *ir.Error values in the same format; see Config and the renderer.

Lint from the command line

lttr lint compiles template files and prints errors as file:line:col: message and warnings as file:line:col: warning: message. It exits 1 when any file has an error. For example, a copy of 03-password-reset.md with a typo in a merge tag, a bad tone and no preheader:

go run ./cmd/lttr lint 03-password-reset.md

03-password-reset.md:13:15: unknown name "otp_cod"
03-password-reset.md:17:1: notice: tone must be "warn"

With the two errors fixed, the same file compiles and lint prints the warning, exiting 0:

03-password-reset.md:1:1: warning: frontmatter: no preheader

Next steps

• Comark syntax for the rules behind the syntax errors.
• Merge tags and bindings for path resolution.
• Live preview, which shows compile errors in the browser as you edit.