Typed Literals
A typed literal is a type name followed by a string, such as
Date"2026-06-15" from Dates & Times. The type’s own
code turns the string into a value. This is ordinary Nomi code, and you can
write it for your own types.
The shape
Section titled “The shape”A typed literal starts with a type name: Html"...", Date"...",
Box"...", or Regex`\d+`. The string can use double quotes, triple
quotes, or backticks. The type in front decides what value you get.
To make a type usable this way, implement the
Literal interface for it. Its one
function is from_fragments.
When Nomi sees Html"...", it calls Html’s from_fragments. This is an
ordinary interface call, so the usual rules about who may implement an
interface for a type apply.
import
std::io
std::literals.{Fragment, Literal}
end
type Html String
// The text with HTML's special characters written as entities.
fn escape(text: String) -> String
text
|> String.replace("&", "&")
|> String.replace("<", "<")
|> String.replace(">", ">")
|> String.replace("\"", """)
end
impl Literal for Html
fn from_fragments(fragments: List<Fragment<String>>) -> Html
fragments
|> Iter.map(fn frag ->
case frag
.Static(s) -> s
.Dynamic(v) -> escape(v)
end
end)
|> String.join()
|> Html()
end
end
fn main()
name = "Tom & <Jerry>"
Html(text) = Html"<p>Hello, ${name}</p>"
io.print(text)
end<p>Hello, Tom & <Jerry></p>
Nomi splits the string into a list of
fragments. Plain text becomes a
Static(text) fragment. Each ${...} becomes a Dynamic(value) fragment.
from_fragments turns each fragment into text and joins them. This one
escapes each dynamic value, so a name holding < can’t add markup to the
page.
std::sql’s Sql literal works the same way, but
keeps each value apart from the SQL as a query parameter, so a value can
never change what a query does. The Databases
chapter shows it.
Fine print
- The impl chooses what a
${...}slot must hold.Fragment<String>takes onlyStringvalues; a slot of another type is an error at the slot. An interface such asDisplaytakes any implementor. - A backtick body has no slots: it is one
Staticfragment holding the text as written. - A triple-quoted typed literal drops its shared indentation, as a triple-quoted string does.
- A prefix that is not a type in scope, or a type with no
impl Literal, is an error that names what to write. LiteralandFragmentare not in the prelude. Only a handler’s author imports them.
Spec: Typed literals, Desugaring, Typed literal forms.
Any type can be the prefix
Section titled “Any type can be the prefix”The prefix can be any type, so you have two choices:
- A new distinct type, like
type Html Stringabove. It names the literal and holds the value it builds. - A type you already have. Then the literal reads like a constructor.
Box"x"builds aBox, the same asBox{contents: "x"}:
import std::literals.{Fragment, Literal}
struct Box
contents: String
end
impl Literal for Box
fn from_fragments(fragments: List<Fragment<String>>) -> Box
contents =
fragments
|> Iter.map(fn frag ->
case frag
.Static(s) -> s
.Dynamic(v) -> v
end
end)
|> String.join()
Box{contents:}
end
end
fn main()
dbg Box"hello"
dbg Box{contents: "world"}
enddbg line 24: Box"hello" = Box{contents: "hello"}
dbg line 25: Box{contents: "world"} = Box{contents: "world"}
Both lines build a Box.
A literal without slots is checked at compile time
Section titled “A literal without slots is checked at compile time”A literal with no ${...} slot has the same text every time, whichever
quotes it uses. So Nomi runs the type’s from_fragments while it checks
your program. If from_fragments can fail (it returns a Result), as it can
for Regex from std::regex:
- If it returns
Ok(v), the literal is the value itself.Regex`\d+`is aRegex, not aResult. It needs no?, and you can use it anywhere, including in a top-levelonce. - If it returns
Err(e), the literal is a compile error with that error’s message.nomi check,nomi runand your editor all reportRegex"["astyped literal Regex"[" is invalid: error parsing regexp: missing closing ]: `[`.
A literal with a slot is built when the program runs, so it stays a
Result. Use one when the pattern comes from a value, and unwrap it with
? or case:
import std::regex.Regex
once digits = Regex`\d+`
fn main() -> Result<Unit, String>
word = "floor"
floor = Regex"${word} \\d+"?
text = "room 42, floor 7"
dbg String.find_all(text, digits)
dbg String.find(text, floor)
Ok(Unit)
enddbg line 10: String.find_all(text, digits) = ["42", "7"]
dbg line 11: String.find(text, floor) = Some("floor 7")
This works for every type whose from_fragments can fail, including the
calendar types. Date"2026-06-15" is a Date, and Date"2026-13-01"
does not compile. The quotes only change how the text is read: a backtick
body keeps every backslash, which suits a regex, and double quotes suit the
rest.
The run must work out its result from the text alone. If from_fragments
prints, reads a file or the clock, or never finishes, a literal of that type
without slots is a compile error. To build such a value from text, call one
of the type’s functions instead, such as Date.parse(text). When the
program runs, a literal without slots is built once, the first time it is
reached, so a literal in a function that runs many times is built only once.
If from_fragments cannot fail, as with Html and Box above, the compiler
still runs it, to make sure it can, and the literal is the value
from_fragments returns.
Fine print
- A
?after a literal without slots is an error, since the literal is the value, not aResult. The hint says to remove the?. - The compile error shows the
Errthrough itsDisplay, or itsDebugwhen it has none. - A handler that doesn’t finish within the compiler’s step limit, or traps, is refused the same way as one with effects.
- A
Regexliteral’s type depends on its text. One with${...}can’t know its groups, so its captures come back as a list.
Scalars & Strings shows what
you can do with a Regex: find, split, replace and read capture groups.
Bits from std::bits is checked the same way:
Bits"10aa_aaaa" is a bit pattern whose letter names a field, where an x
would match any bit, and Bits"10z2" does not compile.
Checked literals
Section titled “Checked literals”A type can also check a literal that has ${...} slots, by implementing
CheckedLiteral instead
of Literal. Its check reads the text around the slots while Nomi checks
your program, and its build fills the slots when the program runs and
cannot fail. So the literal is the value, not a Result, whichever quotes
it uses.
Url works this way. Url"https://api.example.com/greet/${name}" is a
Url, with name escaped as a path segment. A slot takes any Display
value, so an Int or a Uuid id goes in as it is. Url"https://${host}/"
is a compile error at the slot, since no escaping makes a value safe as a
host. Toml does too: in Toml"name = ${name}" the slot is written as the
value’s TOML, so a String is quoted and escaped, and a slot inside a TOML
string is a compile error. Spec:
Checked literals.
Where the type is already known, as a dot-variant’s enum is, the tag can
be left out. u: Url = "https://example.com/${id}" and
http.get("https://example.com/") are Url literals, checked the same
way. Only a literal converts: a String value where a Url is expected
is still an error. Spec:
Literals typed by their position.
std::html’s Html, which HTTP uses for pages, is not the Html
this page declares. The compiler checks its literals itself, as HTML
templates.
Modules & Imports is next. It covers how a program is split across files.