brink_compiler/
lib.rs

1//! Compiler for inkle's ink narrative scripting language.
2//!
3//! Orchestrates the full compilation pipeline: file discovery, parsing
4//! (`brink-syntax`), HIR lowering (`brink-ir`), semantic analysis
5//! (`brink-analyzer`), and codegen into the `brink-format` binary
6//! representation consumed by `brink-runtime`.
7
8mod driver;
9
10pub use brink_ir::FileId;
11
12use brink_format::StoryData;
13use brink_ir::Diagnostic;
14use std::io;
15use std::path::Path;
16
17/// Successful compilation output, including any non-fatal warnings.
18#[derive(Debug)]
19pub struct CompileOutput {
20    pub data: StoryData,
21    pub warnings: Vec<Diagnostic>,
22}
23
24/// Successful LIR compilation output, including any non-fatal warnings.
25pub struct LirOutput {
26    pub program: brink_ir::lir::Program,
27    pub warnings: Vec<Diagnostic>,
28}
29
30/// Compile an ink story from an entry-point file path.
31///
32/// Reads files from disk, follows INCLUDEs, and runs the full compilation
33/// pipeline. Returns the compiled story data or a list of diagnostics.
34pub fn compile_path(path: &Path) -> Result<CompileOutput, CompileError> {
35    compile(path.to_string_lossy().as_ref(), |p| {
36        std::fs::read_to_string(p).map_err(|e| io::Error::new(e.kind(), format!("{p}: {e}")))
37    })
38}
39
40/// Compile an ink story with caller-provided file reading.
41///
42/// The `read_file` callback is called for the entry point and each
43/// `INCLUDE`d file discovered during parsing. This enables compilation in
44/// WASM, tests, and editor contexts where files are not on disk.
45pub fn compile<F>(entry: &str, read_file: F) -> Result<CompileOutput, CompileError>
46where
47    F: FnMut(&str) -> Result<String, io::Error>,
48{
49    driver::compile(entry, read_file)
50}
51
52/// Compile an ink story to the ink.json format (same as inklecate output).
53///
54/// Useful for diffing brink's output against the reference compiler.
55pub fn compile_to_json<F>(entry: &str, read_file: F) -> Result<brink_json::InkJson, CompileError>
56where
57    F: FnMut(&str) -> Result<String, io::Error>,
58{
59    let lir_output = driver::compile_to_lir(entry, read_file)?;
60    Ok(brink_codegen_json::emit(&lir_output.program))
61}
62
63/// Compile ink source from a string to the ink.json format.
64pub fn compile_string_to_json(source: &str) -> Result<brink_json::InkJson, CompileError> {
65    compile_to_json("<string>", |_| Ok(source.to_string()))
66}
67
68/// Errors that can occur during compilation.
69#[derive(Debug, thiserror::Error)]
70pub enum CompileError {
71    /// File I/O error (missing file, permission denied, etc.).
72    #[error("I/O error: {0}")]
73    Io(#[from] io::Error),
74    /// One or more diagnostics prevented compilation.
75    #[error("{} diagnostic(s) prevented compilation", .0.len())]
76    Diagnostics(Vec<Diagnostic>),
77    /// Circular INCLUDE dependency detected.
78    #[error("circular INCLUDE dependency: {0}")]
79    CircularInclude(String),
80}
81
82impl From<brink_driver::DiscoverError> for CompileError {
83    fn from(err: brink_driver::DiscoverError) -> Self {
84        match err {
85            brink_driver::DiscoverError::Io(e) => Self::Io(e),
86            brink_driver::DiscoverError::CircularInclude(msg) => Self::CircularInclude(msg),
87        }
88    }
89}
brink_compiler/lib.rs

brink_compiler/
lib.rs
