Crate formalang 

FormaLang

An embeddable compiler frontend for FormaLang, a statically typed, declarative language. The library parses the source, checks it, and gives a fully resolved IrModule. The application that embeds it supplies the backend: an interpreter, a JIT compiler, a query engine or a code generator, through the plugin system.

Entry points

• compile_to_ir: compile source to a resolved IrModule.
• compile_to_ir_with_path: the same, with the source path in the file table of the module.
• compile_to_ir_with_resolver: compile a program of several modules through a semantic::module_resolver::ModuleResolver, then run ir::MonomorphisePass.
• compile_to_ir_with_path_and_resolver: the same as compile_to_ir_with_resolver, with the source path. It also runs ir::MonomorphisePass.
• compile_with_analyzer and compile_with_analyzer_and_resolver: the AST and the SemanticAnalyzer, for LSP-style use.
• parse_only: lex and parse, with no semantic analysis.
• compile_and_report: compile_to_ir, with the errors as a report that a person can read.

Plugin system

Embedders compose IrPass transforms and a Backend via Pipeline. The built-in passes are in ir: ir::MonomorphisePass, ir::ResolveReferencesPass, ir::ClosureConversionPass, ir::DefunctionalisePass, ir::DeadCodeEliminationPass and ir::ConstantFoldingPass.

Threads and the stack

Each entry point that compiles runs its work on a thread of its own, with a stack sized from the nesting of the program, and waits for it. So the stack of the caller does not matter: a caller on a small thread can compile the deepest program that the parser accepts. For this reason a semantic::module_resolver::ModuleResolver is Send + Sync, and an IrPass is Send. A Backend runs on the thread of the caller.

Cargo features

• serde (off by default): derive serde::Serialize and serde::Deserialize on IrModule and on every type in it. The JSON form of the IR is not a stable format. The AST has no serialized form.

Re-exports

pub use ast::Definition;

pub use ast::Expr;

pub use ast::File;

pub use ast::Ident;

pub use ast::Statement;

pub use ast::Type;

pub use error::CompilerError;

pub use error::ImplError;

pub use ir::simple_type_name;

pub use ir::EnumId;

pub use ir::FunctionId;

pub use ir::GenericBase;

pub use ir::ImportedKind;

pub use ir::IrFunction;

pub use ir::IrFunctionParam;

pub use ir::IrFunctionSig;

pub use ir::IrImport;

pub use ir::IrImportItem;

pub use ir::IrModule;

pub use ir::ResolvedType;

pub use ir::StructId;

pub use ir::TraitId;

pub use lexer::Lexer;

pub use lexer::Token;

pub use location::Location;

pub use location::Span;

pub use parser::parse_file;

pub use parser::parse_file_with_source;

pub use pipeline::Backend;

pub use pipeline::IrPass;

pub use pipeline::Pipeline;

pub use pipeline::PipelineError;

pub use reporting::report_error;

pub use reporting::report_errors;

pub use semantic::module_resolver::FileSystemResolver;

pub use semantic::module_resolver::MemoryResolver;

pub use semantic::SemanticAnalyzer;

Modules

ast

Abstract Syntax Tree (AST) for FormaLang

error

The errors the compiler reports, and where each one points.

ir

Intermediate Representation (IR) for FormaLang

lexer

location

parser

pipeline

Backend pipeline for IR transformation and code generation.

reporting

semantic

Semantic analysis (validation only — no evaluation or expansion).

Functions

compile_and_report

Compile to IR, formatting errors as a human-readable report on failure.

compile_to_ir

Compile FormaLang source code into an IR module.

compile_to_ir_with_path

Compile FormaLang source to IR with a known source-file path.

compile_to_ir_with_path_and_resolver

Compile FormaLang source to IR with both a custom resolver and a known source-file path.

compile_to_ir_with_resolver

Compile FormaLang source code to IR with a custom module resolver.

compile_with_analyzer

Compile and return both the AST and the semantic analyzer.

compile_with_analyzer_and_resolver

Compile with a custom resolver, returning both AST and analyzer.

parse_only

Parse FormaLang source without semantic analysis.