Skip to main content

Crate lower_lang

Crate lower_lang 

Source
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 Problem with its source span, and hir-lang’s lenient validation repairs and reports everything else. Only an exhausted Budget (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§

ArgsHole
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.
ExprHole
An expression hole.
LabelHole
A label hole.
LangPolicy
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.
MappingBuilder
Builds a Mapping. Every method records; build checks 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..end into a single source.
StmtsHole
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.
TemplateBuilder
Builds a Template bottom-up, like hir-lang’s Builder builds HIR.
TemplateId
A template registered in a mapping, from MappingBuilder::template.
TemplateUse
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.
BreakLevels
What the label of a break or continue is (LangPolicy::break_levels; LSF2 break_levels).
Context
The context a construct was lowered in, for problem messages.
EffectMode
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.
HoistBlocker
Why a binding could not be hoisted to its function.
HoleKind
What a hole is filled with, and where it may be used.
IdentPatterns
How a bare identifier in a match arm pattern is lowered.
Join
How the pieces of an interpolated string become one string.
LabelRef
The label of a loop or block a template creates, or a jump’s target.
LegacyOctal
What a leading 0 followed by more digits means (0777).
LowerError
Why lowering stopped without a result. Problems in the code never stop it; only exhausted resources do.
MappingError
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.
PlaceArgs
Which call arguments are passed as places, so a by-reference parameter can alias them.
ProblemKind
What is wrong with one construct.
RecordShape
How a record or variant’s field layout is decided.
Separators
Where _ may separate the digits of a number.
SyntaxError
What is wrong with a template text. Carried by TemplateError::Syntax together 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).
TemplateError
Why a template was refused.
TokenRole
What a token means when it is lowered on its own.
TypeName
A type keyword’s meaning.

Constants§

MAX_TEMPLATE_DEPTH
The deepest nesting Template::parse accepts: expressions, blocks, patterns, and types inside one another (Mox’s largest template, yield_from, nests 10 deep). Deeper text is refused with SyntaxError::TooDeep instead 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::parse accepts, in bytes (1 MiB). Longer texts are refused with SyntaxError::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).

Functions§

lower
Lowers tree, parsed from source, into a validated HIR unit with the default Budget, names interned in names.