Rat docs

Parser errors

The parser flags common dialect gotchas with a one-line did-you-mean hint, so a misleading unexpected token message points you straight at the documented fix. Errors carry a byte-precise column inside the failing expression and a hint suffix in the form — hint: ….

Multi-line object literals

Collapse to one line, or use the indent-nested form

Multi-line braced object literals are not supported — the dialect line parser handles one logical line per declaration. Either keep the object on one line or use the indent-nested name: form with deeper-indented children, which the pre-pass collapses for you.

# bad — parser fails with: expected object key, got "end of input"
> server
person: { first: 'Grace', last: 'Hopper' }

# good — one line
> server
person: { first: 'Grace', last: 'Hopper' }

# also good — indent-nested
> server
person: { first: 'Grace', last: 'Hopper' }

Unclosed bracket in a string

Escape literal brackets so the interpolation splitter ignores them

Inside a string literal, [expr] is evaluated and substituted. A bare [ without a matching ] trips the interpolation splitter. Escape with \\[ when you need a literal bracket — for example, a code snippet that includes [name] in its output. 

> server snippet: 'see [name' > server snippet: 'see [name' 
Multi-line tag attributes
Keep every attribute on the same line as its opening tag
Tag attributes have to fit on one line. The dialect does not parse attr[ on one line with the value on the next — the tag folder produces a single composite line and the parser fails to balance the bracket. Either inline the value or route it through a server field and interpolate with [name]. 
<a href[ '/posts/getting-started'> Read post Read post > server post_href: '/posts/getting-started' > page Read post 
Markdown emphasis in expression position
Escape the asterisk, or route the maths through a derived field
A stray \* in body prose gets rewritten by the renderer's markdown pass into an em tag. If the rewriter pulls the marker into an expression — for example a bare-line expression that ends with n \* 2 — the parser sees an inline HTML tag where it expected an operand and fails with unexpected token "<". Escape the marker with \\\*, route the maths through a derived field, or use × for the multiply sign. 
> page 
n  2 = 0 > server n: 5 double >> n  2 > page 
n × 2 =  
Bare regex escapes in strings
Double the backslash so the regex engine sees it
Rat string literals only recognise \\n, \\t, and \\r as escapes — every other backslash sequence silently drops the backslash. That's the wrong default for a regex pattern body, so '\\d+' reaches the regex engine as 'd+' and never matches. Double the backslash so the literal \\d survives. 
> server digits >> regex.find_all(text, '\d+') > server digits >> regex.find_all(text, '\\d+') 
Want a hint added for a pattern that bit you? The catalog lives in internal/parser/diagnostic.go and is a flat list of (predicate, hint) pairs. Add a signature, add a failure test, and the next time the parser fails with that shape your hint comes along for free.