Oregami
Repositories/oxedyne/fe2o3

oxedyne/fe2o3/fe2o3_austenite/src/eval/mod.rs

13.4 KiB, 62 runs

created by r1870400018:63502, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1//! Contract (U0, 2026-09-23). Every evaluator type other units name is declared by U0 and keeps its
2//! name and public shape; the unit that owns a file may add fields, variants and methods but not rename
3//! or remove. Three facts a reader cannot derive from the types:
4//!
5//! * Native functions are a two-level enum, not trait objects: [`func::NativeFunc`] has one variant per
6//! library area, and each area's inner enum and `call` live in that area's own file, so adding a
7//! library function never touches a shared file.
8//! * An element's fields are a schema (`&'static [FieldSpec]`) owned by the unit that lays the element
9//! out; `content.rs` dispatches `ElemKind` to that unit's `fields`, `construct` and `show` by
10//! [`content::Family`].
11//! * An evaluation error is reported with [`Engine::error`], which records a spanned
12//! [`Diagnostic`](crate::diag::Diagnostic) and returns the `Error` to propagate with `res!`.
13
14// Declares an area's inner native-function enum with each variant's Typst-facing name. Defined before the
15// module list so every submodule sees it.
16macro_rules! native_fns {
17 ($(#[$m:meta])* pub enum $name:ident { $($v:ident => $s:literal,)* }) => {
18 $(#[$m])*
19 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
20 pub enum $name {
21 $($v,)*
22 }
23
24 impl $name {
25 pub const ALL: &'static [$name] = &[$($name::$v,)*];
26
27 /// The name Typst code calls it by, within its area (`pow` for `calc.pow`).
28 pub fn name(&self) -> &'static str {
29 match *self {
30 $($name::$v => $s,)*
31 }
32 }
33 }
34 };
35}
36
37pub mod args;
38pub mod content;
39#[allow(clippy::module_inception)]
40pub mod eval;
41pub mod fixpoint;
42pub mod fp;
43pub mod func;
44pub mod import;
45pub mod intro;
46pub mod lib;
47pub mod locate;
48pub mod methods;
49pub mod ops;
50pub mod package;
51#[cfg(feature = "plugin")]
52pub mod plugin;
53pub mod realise;
54pub mod scope;
55pub mod select;
56pub mod styles;
57pub mod value;
58
59use crate::caches::Caches;
60use crate::diag::{
61 Diagnostic,
62 DiagnosticKind,
63};
64use crate::eval::intro::{
65 Introspector,
66 ReadLog,
67};
68use crate::eval::locate::{
69 Location,
70 Locator,
71 Place,
72};
73use crate::eval::scope::Scope;
74use crate::eval::styles::StyleChain;
75use crate::eval::value::Module;
76use crate::flow::text::FontStore;
77use crate::syntax::{
78 FileId,
79 Source,
80 Span,
81};
82use crate::timings::{
83 Counter,
84 Phase,
85 Timings,
86};
87use crate::vfs;
88
89use oxedyne_fe2o3_core::prelude::*;
90
91use std::collections::HashMap;
92use std::collections::BTreeSet;
93use std::path::{
94 Path,
95 PathBuf,
96};
97use std::sync::Arc;
98
99pub const MAX_CALL_DEPTH: usize = 80; // Typst's own limit
100pub const MAX_LAYOUT_DEPTH: usize = 72; // ditto, for nested layout
101
102/// The sources of one compilation and the modules evaluated from them. Loading a path is here;
103/// resolving an import spec to a path, caching and cycle detection are `import.rs` (U10).
104#[derive(Clone, Debug)]
105pub struct World {
106 pub root: PathBuf, // the project root a leading `/` resolves against
107 pub sources: Vec<Source>, // indexed by `FileId.0`
108 pub modules: HashMap<PathBuf, Arc<Module>>, // evaluated once, by canonical path
109 pub route: Vec<PathBuf>, // modules being evaluated, outermost first, for cycles
110 pub files: BTreeSet<PathBuf>, // every vfs path the compile asked for, found or not
111 pub library: Arc<Scope>, // the standard library, `sys.inputs` included
112}
113
114impl Default for World {
115 fn default() -> Self {
116 Self {
117 root: PathBuf::new(),
118 sources: Vec::new(),
119 modules: HashMap::new(),
120 route: Vec::new(),
121 files: BTreeSet::new(),
122 library: eval::library(),
123 }
124 }
125}
126
127impl World {
128 pub fn new(root: PathBuf) -> Self {
129 Self { root, ..Self::default() }
130 }
131
132 /// A world whose documents read `inputs` as `sys.inputs`, as `typst compile --input` gives them.
133 pub fn with_inputs(root: PathBuf, inputs: &[(String, String)]) -> Self {
134 Self { root, library: eval::library_with_inputs(inputs), ..Self::default() }
135 }
136
137 /// Parses `text` as a new source and returns its id; a path already loaded returns its existing id.
138 pub fn add_source(&mut self, path: PathBuf, text: String) -> Outcome<FileId> {
139 if let Some(s) = self.sources.iter().find(|s| s.path == path) {
140 return Ok(s.id);
141 }
142 if self.sources.len() >= FileId::DETACHED.0 as usize {
143 return Err(err!("Too many source files: {} is the limit.", FileId::DETACHED.0; Excessive));
144 }
145 let id = FileId(self.sources.len() as u16);
146 self.sources.push(Source::new(id, path, text));
147 Ok(id)
148 }
149
150 /// Records that the compile asked the vfs for `path`. A path that is not there is recorded too: the
151 /// file whose appearance would change the result is as much a dependency as one that was read.
152 pub fn note(&mut self, path: &Path) {
153 if !self.files.contains(path) {
154 self.files.insert(path.to_path_buf());
155 }
156 }
157
158 /// Reads a path through the vfs (native disc or the wasm source map) and parses it.
159 pub fn load(&mut self, path: &Path) -> Outcome<FileId> {
160 self.note(path);
161 if let Some(s) = self.sources.iter().find(|s| s.path == path) {
162 return Ok(s.id);
163 }
164 let text = match vfs::read_to_string(path) {
165 Ok(t) => t,
166 // A file that is there but is not text is told from one that cannot be read, since the remedy differs.
167 Err(e) if vfs::is_not_utf8(&e) => return Err(err!(
168 "The source {} is not valid UTF-8 text.", path.display(); IO, File, Decode, UTF8)),
169 Err(e) => return Err(err!("Could not read source {}: {}", path.display(), e; IO, File, Read)),
170 };
171 self.add_source(path.to_path_buf(), text)
172 }
173
174 pub fn source(&self, id: FileId) -> Option<&Source> { self.sources.get(id.0 as usize) }
175}
176
177/// What `here()` and a contextual `text.size` read: set while a `context` body or a show-rule closure
178/// runs, empty elsewhere (reading it then is Typst's "can only be used when context is known").
179#[derive(Clone, Debug, Default)]
180pub struct Context {
181 pub location: Option<Location>,
182 pub styles: Option<StyleChain>,
183}
184
185/// Everything evaluation, realisation and flow share for one compilation. Passed as `&mut Engine`;
186/// the introspector is replaced between fixpoint passes, everything else persists.
187#[derive(Debug)]
188pub struct Engine {
189 pub world: World,
190 pub intro: Arc<Introspector>, // the previous pass's layout facts (empty on pass one)
191 pub locator: Locator, // hands out stable element locations during realisation
192 pub diags: Vec<Diagnostic>,
193 pub depth: usize, // current closure call depth
194 pub route: usize, // layout layers and show rules entered, Typst's route; the document is the first
195 pub fuel: Option<u64>, // loop iterations remaining; none is unbounded, as Typst is
196 #[cfg(feature = "plugin")]
197 pub plugin_fuel: u64, // wasmi fuel for each plugin load and call, `plugin::FUEL` unless the host sets it
198 pub context: Context,
199 pub reads: ReadLog, // introspection reads recorded for the fixpoint (U8)
200 pub fonts: FontStore, // faces for shaping and `measure` (U6a)
201 pub body: Option<bool>, // whether the pass's realised body set content; none until it is realised
202 pub timings: Option<Timings>, // the per-phase clock of `--timings`; none costs a test of the option
203 pub caches: Caches, // the session's, lent for the compile and taken back after it
204}
205
206/// The kind of an error a native function raised with `err!` and no diagnostic of its own: the kind its
207/// tags give, with an input fault, a bad argument or value, read as a type error.
208pub(crate) fn native_kind(e: &Error<ErrTag>) -> DiagnosticKind {
209 match DiagnosticKind::from_error_tags(e) {
210 DiagnosticKind::Internal if e.tags().contains(&ErrTag::Input) => DiagnosticKind::Type,
211 kind => kind,
212 }
213}
214
215impl Engine {
216 pub fn new(world: World) -> Self {
217 Self {
218 world,
219 intro: Arc::new(Introspector::default()),
220 locator: Locator::default(),
221 diags: Vec::new(),
222 depth: 0,
223 route: 1,
224 fuel: None,
225 #[cfg(feature = "plugin")]
226 plugin_fuel: crate::eval::plugin::FUEL,
227 context: Context::default(),
228 reads: ReadLog::default(),
229 fonts: FontStore::default(),
230 body: None,
231 timings: None,
232 caches: Caches::default(),
233 }
234 }
235
236 /// Runs `f` as phase `p` of the timing record. With no recorder it is a call of `f`.
237 pub fn timed<R, F: FnOnce(&mut Engine) -> R>(&mut self, p: Phase, f: F) -> R {
238 if let Some(t) = self.timings.as_mut() {
239 t.enter(p);
240 }
241 let out = f(self);
242 if let Some(t) = self.timings.as_mut() {
243 t.leave();
244 }
245 out
246 }
247
248 /// Adds `by` to a counter of the timing record's current pass. With no recorder it is a test of the option.
249 pub fn bump(&mut self, c: Counter, by: u64) {
250 if let Some(t) = self.timings.as_mut() {
251 t.bump(c, by);
252 }
253 }
254
255 /// Records an error diagnostic at `span` and returns the error to propagate.
256 pub fn error<S: Into<String>>(&mut self, kind: DiagnosticKind, span: Span, message: S) -> Error<ErrTag> {
257 let message = message.into();
258 let e = err!("{}", message; Input, Invalid);
259 self.diags.push(Diagnostic::error(kind, span, message));
260 e
261 }
262
263 /// As [`error`](Self::error), with a hint line.
264 pub fn error_hint<S: Into<String>, H: Into<String>>(
265 &mut self,
266 kind: DiagnosticKind,
267 span: Span,
268 message: S,
269 hint: H,
270 )
271 -> Error<ErrTag>
272 {
273 let message = message.into();
274 let e = err!("{}", message; Input, Invalid);
275 self.diags.push(Diagnostic::error(kind, span, message).with_hint(hint));
276 e
277 }
278
279 /// Records a warning of `kind`. A warning of a kind that [`refuses_strict`](DiagnosticKind::refuses_strict)
280 /// fails a strict compile, so one for a construct passed over or set otherwise than Typst sets it is
281 /// `Unsupported`.
282 ///
283 /// A warning identical to one already recorded is dropped, as Typst's sink drops it, so a set rule met
284 /// again, or a paragraph laid out in every pass, warns once.
285 pub fn warn<S: Into<String>>(&mut self, kind: DiagnosticKind, span: Span, message: S) {
286 let d = Diagnostic::warning(kind, span, message);
287 if !self.diags.contains(&d) {
288 self.diags.push(d);
289 }
290 }
291
292 /// Typst's `Engine::delay`: the failure of a show rule is recorded and the element it was showing shows as
293 /// nothing, so the compile goes on. The error stays among the diagnostics, and fails the compile only if it is
294 /// still there after the final pass: an earlier pass may fail for want of a label or a counter that a later
295 /// one has, and the fixpoint drops each pass's diagnostics before the next. `mark` is the length of
296 /// `diags` before the show ran, so an error raised without a diagnostic of its own is given one at `span`.
297 pub fn delay<T: Default>(&mut self, mark: usize, span: Span, result: Outcome<T>) -> T {
298 match result {
299 Ok(v) => v,
300 Err(e) => {
301 self.adopt(mark, span, e);
302 T::default()
303 },
304 }
305 }
306
307 /// Enters a closure call; past [`MAX_CALL_DEPTH`] it is an error, not a stack overflow.
308 pub fn enter_call(&mut self, span: Span) -> Outcome<()> {
309 if self.depth >= MAX_CALL_DEPTH {
310 return Err(self.error(DiagnosticKind::Limit, span, "maximum function call depth exceeded"));
311 }
312 self.depth += 1;
313 Ok(())
314 }
315
316 pub fn exit_call(&mut self) { self.depth = self.depth.saturating_sub(1); }
317
318 /// Runs `f` one layer deeper in the nesting Typst's route counts: a layout call Typst memoises (a
319 /// paragraph, a block, a fragment) or a show rule's output being visited. The layer is left however `f`
320 /// ends.
321 pub fn descend<R, F: FnOnce(&mut Engine) -> R>(&mut self, f: F) -> R {
322 self.route += 1;
323 let out = f(self);
324 self.route -= 1;
325 out
326 }
327
328 /// As [`descend`](Self::descend), for the layer that lays a fragment out. Past [`MAX_LAYOUT_DEPTH`] it is an
329 /// error at `span`, not a stack overflow: the recursion of nested containers ends here, as Typst's does.
330 pub fn descend_fragment<R, F: FnOnce(&mut Engine) -> Outcome<R>>(&mut self, span: Span, f: F) -> Outcome<R> {
331 if self.route >= MAX_LAYOUT_DEPTH {
332 return Err(self.error_hint(
333 DiagnosticKind::Limit,
334 span,
335 "maximum layout depth exceeded",
336 "try to reduce the amount of nesting in your layout",
337 ));
338 }
339 self.descend(f)
340 }
341
342 /// Runs `f` with realisations counted afresh at `place`, Typst's `Locator::relayout`: content laid out
343 /// again at the place it was laid out at is realised to the same locations, whatever was realised in
344 /// between. `None` leaves the realisation where it stands. The locator in force comes back when `f` ends,
345 /// by whichever route.
346 pub fn within<R, F: FnOnce(&mut Engine) -> R>(&mut self, place: Option<Place>, f: F) -> R {
347 match place {
348 None => f(self),
349 Some(p) => {
350 let outer = std::mem::replace(&mut self.locator, Locator::new(p));
351 let out = f(self);
352 self.locator = outer;
353 out
354 },
355 }
356 }
357
358 /// Spends one loop iteration when the host set a budget, and ends the compile with a diagnostic when it
359 /// is spent, so a runaway loop terminates. Without a budget a loop runs as long as it runs.
360 pub fn burn(&mut self, span: Span) -> Outcome<()> {
361 match self.fuel {
362 Some(0) => Err(self.error(DiagnosticKind::Limit, span, "loop seems to be infinite")),
363 Some(n) => {
364 self.fuel = Some(n - 1);
365 Ok(())
366 },
367 None => Ok(()),
368 }
369 }
370
371 pub fn has_errors(&self) -> bool { self.diags.iter().any(|d| d.is_error()) }
372}
373
374/// Evaluates a loaded source into a module. The body is U2's [`eval::eval_module`]. The source goes on
375/// the import route while it runs, so a file it imports that imports it back is a cycle, as in Typst.
376pub fn eval_source(engine: &mut Engine, id: FileId) -> Outcome<Module> {
377 let path = match engine.world.source(id) {
378 Some(s) => s.path.clone(),
379 None => return Err(err!("No source with id {} is loaded.", id.0; Missing, Input)),
380 };
381 engine.world.route.push(path);
382 let out = eval::eval_module(engine, id);
383 engine.world.route.pop();
384 out
385}