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. |
| 16 | macro_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 | |
| 37 | pub mod args; |
| 38 | pub mod content; |
| 39 | #[allow(clippy::module_inception)] |
| 40 | pub mod eval; |
| 41 | pub mod fixpoint; |
| 42 | pub mod fp; |
| 43 | pub mod func; |
| 44 | pub mod import; |
| 45 | pub mod intro; |
| 46 | pub mod lib; |
| 47 | pub mod locate; |
| 48 | pub mod methods; |
| 49 | pub mod ops; |
| 50 | pub mod package; |
| 51 | #[cfg(feature = "plugin")] |
| 52 | pub mod plugin; |
| 53 | pub mod realise; |
| 54 | pub mod scope; |
| 55 | pub mod select; |
| 56 | pub mod styles; |
| 57 | pub mod value; |
| 58 | |
| 59 | use crate::caches::Caches; |
| 60 | use crate::diag::{ |
| 61 | Diagnostic, |
| 62 | DiagnosticKind, |
| 63 | }; |
| 64 | use crate::eval::intro::{ |
| 65 | Introspector, |
| 66 | ReadLog, |
| 67 | }; |
| 68 | use crate::eval::locate::{ |
| 69 | Location, |
| 70 | Locator, |
| 71 | Place, |
| 72 | }; |
| 73 | use crate::eval::scope::Scope; |
| 74 | use crate::eval::styles::StyleChain; |
| 75 | use crate::eval::value::Module; |
| 76 | use crate::flow::text::FontStore; |
| 77 | use crate::syntax::{ |
| 78 | FileId, |
| 79 | Source, |
| 80 | Span, |
| 81 | }; |
| 82 | use crate::timings::{ |
| 83 | Counter, |
| 84 | Phase, |
| 85 | Timings, |
| 86 | }; |
| 87 | use crate::vfs; |
| 88 | |
| 89 | use oxedyne_fe2o3_core::prelude::*; |
| 90 | |
| 91 | use std::collections::HashMap; |
| 92 | use std::collections::BTreeSet; |
| 93 | use std::path::{ |
| 94 | Path, |
| 95 | PathBuf, |
| 96 | }; |
| 97 | use std::sync::Arc; |
| 98 | |
| 99 | pub const MAX_CALL_DEPTH: usize = 80; // Typst's own limit |
| 100 | pub 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)] |
| 105 | pub 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 | |
| 114 | impl 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 | |
| 127 | impl 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)] |
| 180 | pub 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)] |
| 188 | pub 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. |
| 208 | pub(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 | |
| 215 | impl 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. |
| 376 | pub 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 | } |