Struct Compiler

pub struct Compiler(/* private fields */);

The compiler.

This is the main entry point and driver for the compiler.

It must be entered to perform most operations, as it makes use of thread-local storage, which is only available inside of a closure. enter_mut is only necessary when parsing sources and lowering the ASTs. All accesses after can make use of gcx, passed by immutable reference.

Once a stage-advancing operation is performed, such as parse, lower, etc., the compiler may not perform the same or a previous operation again, with the exception of parse.

Examples

use solar::{
    interface::{Session, diagnostics::EmittedDiagnostics},
    sema::Compiler,
};
use std::{ops::ControlFlow, path::Path};

#[test]
fn main() -> Result<(), EmittedDiagnostics> {
    let paths = [Path::new("src/AnotherCounter.sol")];

    // Create a new session with a buffer emitter.
    // This is required to capture the emitted diagnostics and to return them at the end.
    let sess = Session::builder().with_buffer_emitter(solar::interface::ColorChoice::Auto).build();

    // Create a new compiler.
    let mut compiler = Compiler::new(sess);

    // Enter the context and parse the file.
    // Counter will be parsed, even if not explicitly provided, since it is a dependency.
    let _ = compiler.enter_mut(|compiler| -> solar::interface::Result<_> {
        // Parse the files.
        let mut parsing_context = compiler.parse();
        parsing_context.load_files(paths)?;
        parsing_context.parse();
        Ok(())
    });

    // Do some other stuff, store the compiler in a struct...

    // Enter the context again and lower the ASTs to inspect the HIR.
    let contracts = compiler.enter_mut(|compiler| -> solar::interface::Result<_> {
        // Perform AST lowering to populate the HIR.
        let ControlFlow::Continue(()) = compiler.lower_asts()? else {
            // Can't continue because HIR was not populated,
            // possibly because it was requested in `Session` with `stop_after`.
            return Ok(vec![]);
        };

        // Inspect the HIR.
        let gcx = compiler.gcx();
        let contracts = gcx.hir.contracts().map(|c| c.name.to_string()).collect::<Vec<_>>();
        Ok(contracts)
    });
    if let Ok(mut contracts) = contracts {
        // No order is guaranteed.
        contracts.sort();
        assert_eq!(contracts, ["AnotherCounter".to_string(), "Counter".to_string()]);
    }

    // `compiler` can be entered again to perform analysis, type checking, etc, without needing
    // mutable access, since `gcx` is the main context that is passed by immutable reference.

    // Return the emitted diagnostics as a `Result<(), _>`.
    // If any errors were emitted, this returns `Err(_)`, otherwise `Ok(())`.
    // Note that this discards warnings and other non-error diagnostics.
    compiler.sess().emitted_errors().unwrap()
}

Implementations

impl Compiler

pub fn new(sess: Session) -> Self

Creates a new compiler.

pub fn sess(&self) -> &Session

Returns a reference to the compiler session.

pub fn sess_mut(&mut self) -> &mut Session

Returns a mutable reference to the compiler session.

pub fn dcx(&self) -> &DiagCtxt

Returns a reference to the diagnostics context.

pub fn dcx_mut(&mut self) -> &mut DiagCtxt

Returns a mutable reference to the diagnostics context.

pub fn enter<T: Send>(&self, f: impl FnOnce(&CompilerRef<'_>) -> T + Send) -> T

Enters the compiler context.

See Session::enter for more details.

pub fn enter_mut<T: Send>( &mut self, f: impl FnOnce(&mut CompilerRef<'_>) -> T + Send, ) -> T

Enters the compiler context with mutable access.

This is currently only necessary when parsing sources and lowering the ASTs. All accesses after can make use of gcx, passed by immutable reference.

See Session::enter for more details.

pub fn enter_sequential<T>(&self, f: impl FnOnce(&CompilerRef<'_>) -> T) -> T

Enters the compiler context.

Note that this does not set up the rayon thread pool. This is only useful when parsing sequentially, like manually using Parser. Otherwise, it might cause panics later on if a thread pool is expected to be set up correctly.

See enter for more details.

pub fn enter_sequential_mut<T>( &mut self, f: impl FnOnce(&mut CompilerRef<'_>) -> T, ) -> T

Enters the compiler context with mutable access.

Note that this does not set up the rayon thread pool. This is only useful when parsing sequentially, like manually using Parser. Otherwise, it might cause panics later on if a thread pool is expected to be set up correctly.

See enter_mut for more details.

Trait Implementations

impl Debug for Compiler

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Compiler

fn drop(&mut self)

Executes the destructor for this type.