Expand description
§lower_lang
Lowers a lossless syntax tree into HIR. A language describes what its
constructs mean as data — a Mapping from node kinds to semantic
archetypes (binders, scopes, declarations, control, expressions,
patterns, types), operator tables with their policies, and hygienic
templates for sugar — and lower-lang builds the HIR, records
where every node came from, and validates the result.
§The lazy path
Build a mapping once, then lower any tree of that language:
use hir_lang::OpKind;
use intern_lang::Interner;
use lower_lang::{lower, Arch, MappingBuilder, OpSpec, Pick, TokenRole};
use syntax_lang::{Element, Node, Span, Token, TokenKind};
#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
enum K { File, Add, Num, Plus, Space }
impl TokenKind for K {
fn is_trivia(&self) -> bool { matches!(self, K::Space) }
}
let mut b = MappingBuilder::new();
b.node(K::File, Arch::Module { name: Pick::Absent, items: Pick::Nodes });
b.node(K::Add, Arch::binary());
b.token(K::Num, TokenRole::Int);
b.binary_op(K::Plus, OpSpec::Op(OpKind::Add));
let mapping = b.build()?;
// `1 + 2`
let tok = |k, s, e| Element::Token(Token::new(k, Span::new(s, e)));
let add = Node::new(K::Add, vec![
tok(K::Num, 0, 1), tok(K::Space, 1, 2), tok(K::Plus, 2, 3),
tok(K::Space, 3, 4), tok(K::Num, 4, 5),
]);
let file = Node::new(K::File, vec![Element::Node(add)]);
let mut names = Interner::new();
let out = lower(&file, "1 + 2", &mapping, &mut names).expect("within budget");
assert!(out.problems.is_empty());
assert!(hir_lang::print(&out.hir, &names).contains("(op add overflow=error"));§Templates as text
Sugar is lowered through hygienic templates, written in HIR’s template syntax and parsed once (never substituted):
use lower_lang::{MappingBuilder, OpSpec};
let mut b = MappingBuilder::<u8>::new();
// PHP's `&&` (a bool), and `++$x` with the place evaluated once.
let and = b.parse_template("bool_and", "if ${lhs} { not(not(${rhs})) } else { false }")?;
let inc = b.parse_template("pre_increment", "let_place p = ${place} in p = add(p, 1)")?;
b.binary_op(1, OpSpec::Template(and));
b.prefix_op(2, OpSpec::Template(inc));
assert!(b.build().is_ok());§What lowering guarantees
- It never panics and always returns valid HIR for any tree, including
trees full of syntax errors, unmapped kinds, missing parts, and spans
outside the source: each broken construct becomes an HIR error form and a
Problemwith its source span, and hir-lang’s lenient validation repairs and reports everything else. Only an exhaustedBudget(or exhausted interner or arena space) stops it. - Every HIR node has an origin inside the source: its own syntax span, or, for template output, the span of the node that invoked the template, with the template’s expansion recorded.
- Templates are hygienic: names a template introduces carry its expansion’s mark and are resolved by construction, so they never capture or shadow user names.
- It is deterministic and iterative: the same input lowers to the same HIR, at any tree depth.
§no_std
The crate needs only alloc. The default std feature is additive.
Modules§
- templates
- Ready-made lowering templates for the sugar most languages share.
Structs§
- Args
Hole - An argument-list hole.
- Budget
- Limits on what one lowering may do. Untrusted trees and templates cannot exceed them; exceeding one is a reported problem or error, never a hang.
- Expr
Hole - An expression hole.
- Label
Hole - A label hole.
- Lang
Policy - Language-wide lowering policies.
- Literals
- How number literals are spelled and decoded: the literal decoding table.
- Lowered
- The result of lowering: a valid HIR unit and every problem found.
- Lowerer
- Lowers syntax trees with one mapping: the configured path, for a budget, a compilation unit other than 0, or host-provided field labels.
- Mapping
- A language’s semantics as data: what each node kind means, what each token is, which operators map to what, and the templates for sugar.
- Mapping
Builder - Builds a
Mapping. Every method records;buildchecks everything and sorts the tables. - NameRef
- A host or intrinsic name stored in a mapping, from
MappingBuilder::name. - PatHole
- A pattern hole.
- Problem
- One problem, at the source span it is about.
- Span
- A half-open byte range
start..endinto a single source. - Stmts
Hole - A statement-list hole.
- TBinder
- A binder the template introduces (fresh and hygienic per instantiation).
- TExpr
- An expression node of a template under construction.
- TLabel
- A loop or block label the template introduces.
- TPat
- A pattern node of a template under construction.
- TStmt
- A statement node of a template under construction.
- TTy
- A type node of a template under construction.
- Template
- A finished, checked lowering template.
- Template
Builder - Builds a
Templatebottom-up, like hir-lang’sBuilderbuilds HIR. - Template
Id - A template registered in a mapping, from
MappingBuilder::template. - Template
Use - A use of a registered template as a node’s archetype, made by
MappingBuilder::template_node. - TyHole
- A type hole.
Enums§
- Arch
- A semantic archetype: what a syntax node means, and where its parts are.
- Break
Levels - What the label of a
breakorcontinueis (LangPolicy::break_levels; LSF2break_levels). - Context
- The context a construct was lowered in, for problem messages.
- Effect
Mode - How a function’s effects are decided.
- Escapes
- How a string or character literal’s escapes are decoded.
- Fixity
- Operator positions, for the tables and errors.
- Hoist
Blocker - Why a binding could not be hoisted to its function.
- Hole
Kind - What a hole is filled with, and where it may be used.
- Ident
Patterns - How a bare identifier in a
matcharm pattern is lowered. - Join
- How the pieces of an interpolated string become one string.
- Label
Ref - The label of a loop or block a template creates, or a jump’s target.
- Legacy
Octal - What a leading
0followed by more digits means (0777). - Lower
Error - Why lowering stopped without a result. Problems in the code never stop it; only exhausted resources do.
- Mapping
Error - Why a mapping was refused.
- Modifier
- A keyword or symbol that sets a flag on the construct it appears in.
- OpSpec
- What an operator token lowers to.
- Pick
- Where a field of an archetype is found among a node’s children.
- Place
Args - Which call arguments are passed as places, so a by-reference parameter can alias them.
- Problem
Kind - What is wrong with one construct.
- Record
Shape - How a record or variant’s field layout is decided.
- Separators
- Where
_may separate the digits of a number. - Syntax
Error - What is wrong with a template text. Carried by
TemplateError::Syntaxtogether with the byte range it is about. - TArg
- An argument of
TemplateBuilder::apply: what fills one hole of the applied template, in its hole order. - TLit
- A literal a template writes (strings are written with
TemplateBuilder::str). - Template
Error - Why a template was refused.
- Token
Role - What a token means when it is lowered on its own.
- Type
Name - A type keyword’s meaning.
Constants§
- MAX_
TEMPLATE_ DEPTH - The deepest nesting
Template::parseaccepts: expressions, blocks, patterns, and types inside one another (Mox’s largest template,yield_from, nests 10 deep). Deeper text is refused withSyntaxError::TooDeepinstead of exhausting the stack: at the cap the parser needs under 256 KiB of stack in an unoptimized build and under 64 KiB optimized. - MAX_
TEMPLATE_ SIZE - The most nodes a template’s tree may have once shared sub-trees are
counted at every use; larger templates are refused by
TemplateBuilder::finish. - MAX_
TEMPLATE_ TEXT - The longest template text
Template::parseaccepts, in bytes (1 MiB). Longer texts are refused withSyntaxError::TooLong.
Traits§
- Labeler
- Supplies field labels for the children of a node: the integration point for
trees whose grammar names its fields (LSF2
name:expr).