Skip to main content

lower_lang/
lib.rs

1//! # lower_lang
2//!
3//! Lowers a lossless syntax tree into HIR. A language describes what its
4//! constructs *mean* as data — a [`Mapping`] from node kinds to semantic
5//! [archetypes](Arch) (binders, scopes, declarations, control, expressions,
6//! patterns, types), operator tables with their policies, and hygienic
7//! [templates](Template) for sugar — and lower-lang builds the HIR, records
8//! where every node came from, and validates the result.
9//!
10//! ## The lazy path
11//!
12//! Build a mapping once, then [`lower`] any tree of that language:
13//!
14//! ```
15//! use hir_lang::OpKind;
16//! use intern_lang::Interner;
17//! use lower_lang::{lower, Arch, MappingBuilder, OpSpec, Pick, TokenRole};
18//! use syntax_lang::{Element, Node, Span, Token, TokenKind};
19//!
20//! #[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord)]
21//! enum K { File, Add, Num, Plus, Space }
22//! impl TokenKind for K {
23//!     fn is_trivia(&self) -> bool { matches!(self, K::Space) }
24//! }
25//!
26//! let mut b = MappingBuilder::new();
27//! b.node(K::File, Arch::Module { name: Pick::Absent, items: Pick::Nodes });
28//! b.node(K::Add, Arch::binary());
29//! b.token(K::Num, TokenRole::Int);
30//! b.binary_op(K::Plus, OpSpec::Op(OpKind::Add));
31//! let mapping = b.build()?;
32//!
33//! // `1 + 2`
34//! let tok = |k, s, e| Element::Token(Token::new(k, Span::new(s, e)));
35//! let add = Node::new(K::Add, vec![
36//!     tok(K::Num, 0, 1), tok(K::Space, 1, 2), tok(K::Plus, 2, 3),
37//!     tok(K::Space, 3, 4), tok(K::Num, 4, 5),
38//! ]);
39//! let file = Node::new(K::File, vec![Element::Node(add)]);
40//!
41//! let mut names = Interner::new();
42//! let out = lower(&file, "1 + 2", &mapping, &mut names).expect("within budget");
43//! assert!(out.problems.is_empty());
44//! assert!(hir_lang::print(&out.hir, &names).contains("(op add overflow=error"));
45//! # Ok::<(), lower_lang::MappingError>(())
46//! ```
47//!
48//! ## Templates as text
49//!
50//! Sugar is lowered through hygienic [templates](Template), written in HIR's
51//! template syntax and parsed once (never substituted):
52//!
53//! ```
54//! use lower_lang::{MappingBuilder, OpSpec};
55//!
56//! let mut b = MappingBuilder::<u8>::new();
57//! // PHP's `&&` (a bool), and `++$x` with the place evaluated once.
58//! let and = b.parse_template("bool_and", "if ${lhs} { not(not(${rhs})) } else { false }")?;
59//! let inc = b.parse_template("pre_increment", "let_place p = ${place} in p = add(p, 1)")?;
60//! b.binary_op(1, OpSpec::Template(and));
61//! b.prefix_op(2, OpSpec::Template(inc));
62//! assert!(b.build().is_ok());
63//! # Ok::<(), Box<dyn std::error::Error>>(())
64//! ```
65//!
66//! ## What lowering guarantees
67//!
68//! - **It never panics and always returns valid HIR** for any tree, including
69//!   trees full of syntax errors, unmapped kinds, missing parts, and spans
70//!   outside the source: each broken construct becomes an HIR error form and a
71//!   [`Problem`] with its source span, and hir-lang's lenient validation
72//!   repairs and reports everything else. Only an exhausted [`Budget`] (or
73//!   exhausted interner or arena space) stops it.
74//! - **Every HIR node has an origin inside the source**: its own syntax span,
75//!   or, for template output, the span of the node that invoked the template,
76//!   with the template's expansion recorded.
77//! - **Templates are hygienic**: names a template introduces carry its
78//!   expansion's mark and are resolved by construction, so they never capture
79//!   or shadow user names.
80//! - **It is deterministic and iterative**: the same input lowers to the same
81//!   HIR, at any tree depth.
82//!
83//! ## `no_std`
84//!
85//! The crate needs only `alloc`. The default `std` feature is additive.
86
87#![cfg_attr(not(feature = "std"), no_std)]
88#![cfg_attr(docsrs, feature(doc_cfg))]
89#![forbid(unsafe_code)]
90#![deny(missing_docs)]
91#![deny(unused_must_use)]
92#![deny(unused_results)]
93#![deny(clippy::unwrap_used)]
94#![deny(clippy::expect_used)]
95#![deny(clippy::todo)]
96#![deny(clippy::unimplemented)]
97#![deny(clippy::print_stdout)]
98#![deny(clippy::print_stderr)]
99#![deny(clippy::dbg_macro)]
100#![deny(clippy::unreachable)]
101
102extern crate alloc;
103
104mod arch;
105mod lower;
106mod mapping;
107mod pick;
108mod problem;
109mod template;
110pub mod templates;
111mod text;
112
113pub use arch::{Arch, RecordShape, TemplateUse};
114pub use hir_lang::Span;
115pub use lower::{Budget, Lowered, Lowerer};
116pub use mapping::{
117    BreakLevels, EffectMode, Escapes, Fixity, IdentPatterns, Join, LangPolicy, LegacyOctal,
118    Literals, Mapping, MappingBuilder, MappingError, Modifier, NameRef, OpSpec, PlaceArgs,
119    Separators, TokenRole, TypeName,
120};
121pub use pick::{Labeler, Pick};
122pub use problem::{Context, HoistBlocker, LowerError, Problem, ProblemKind};
123pub use template::{
124    ArgsHole, ExprHole, HoleKind, LabelHole, LabelRef, MAX_TEMPLATE_SIZE, PatHole, StmtsHole, TArg,
125    TBinder, TExpr, TLabel, TLit, TPat, TStmt, TTy, Template, TemplateBuilder, TemplateError,
126    TemplateId, TyHole,
127};
128pub use text::{MAX_TEMPLATE_DEPTH, MAX_TEMPLATE_TEXT, SyntaxError};
129
130use intern_lang::Interner;
131use syntax_lang::{Node, TokenKind};
132
133/// Lowers `tree`, parsed from `source`, into a validated HIR unit with the
134/// default [`Budget`], names interned in `names`.
135///
136/// The Tier-1 entry point; use [`Lowerer`] for a budget, a unit id, or field
137/// labels.
138///
139/// # Errors
140///
141/// Only for exhausted resources: [`LowerError::NodeBudget`],
142/// [`LowerError::SymbolSpaceExhausted`], or [`LowerError::Hir`] when hir-lang's
143/// arenas overflow. Problems in the code are never errors; they are in
144/// [`Lowered::problems`], and the HIR is still valid.
145///
146/// # Examples
147///
148/// See the [crate documentation](crate).
149pub fn lower<K>(
150    tree: &Node<K>,
151    source: &str,
152    mapping: &Mapping<K>,
153    names: &mut Interner,
154) -> Result<Lowered, LowerError>
155where
156    K: Copy + Ord + TokenKind,
157{
158    Lowerer::new(mapping).lower(tree, source, names)
159}
160
161/// Compiles and runs the `rust` code blocks in `README.md` and `docs/API.md` as
162/// part of `cargo test`, so the published examples cannot drift from the API.
163#[cfg(doctest)]
164#[doc = include_str!("../README.md")]
165#[doc = include_str!("../docs/API.md")]
166pub struct MarkdownDocTests;