lehit 0.2.0

Embeddable Lehit language frontend and Cranelift JIT runtime
Documentation
//! Experimental Lehit language frontend and embeddable Cranelift JIT runtime.
//!
//! # Quick start
//!
//! Checked execution is the recommended host-facing mode because instrumented
//! runtime failures are returned as structured errors instead of backend traps.
//!
//! ```
//! use lehit::runtime::{ExecutionMode, RuntimeBuilder};
//!
//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
//! let mut runtime = RuntimeBuilder::new()
//!     .with_execution_mode(ExecutionMode::Checked)
//!     .build()?;
//!
//! runtime.load_script(
//!     "app://entry.lt",
//!     "as fn(argument: usize) -> i32
//!      let values: [i32; 2] = [11, 22] return values[argument]",
//! )?;
//! let function = runtime.function("app://entry.lt", "")?.abi_function()?;
//! let mut call = function.abi_call_builder();
//! call.push_rust_value_argument(1usize)?;
//! assert_eq!(call.call()?.into_rust_value::<i32>()?, 22);
//!
//! let mut call = function.abi_call_builder();
//! call.push_rust_value_argument(3usize)?;
//! assert!(matches!(
//!     call.call(),
//!     Err(lehit::runtime::AbiCallError::Execution(status))
//!         if status == lehit::runtime::AbiCallStatus::BOUNDS_VIOLATION
//! ));
//! # Ok(())
//! # }
//! ```
//!
//! # Choosing an API
//!
//! - [`runtime`] is the supported embedding and execution facade.
//! - [`rust_lib`] and [`LehitRegistration`] register trusted native Rust code.
//! - [`parsing::parse_file`] is the source-level frontend entry point.
//! - [`semantic`] exposes the experimental compiler passes and typed IR.
//! - [`core_lib`] exposes the embedded `core://` source modules.
//! - [`guides`] contains the long-form documentation rendered on docs.rs.
//!
//! # Status and trust model
//!
//! The project is pre-release and is not a sandbox. Checked execution only
//! covers failures explicitly instrumented by codegen; native pointers, custom
//! layouts, allocator callbacks, and aggregate byte validity remain trusted-host
//! responsibilities. Read [`guides::safety`] before using native integration.

#![deny(rustdoc::broken_intra_doc_links)]
#![deny(missing_docs)]

extern crate self as lehit;

pub use lehit_macros::LehitRegistration;

// These pre-release compiler/runtime surfaces still contain low-level data
// models. Their curated entry points are documented while item-by-item coverage
// is completed alongside the planned API narrowing.
#[allow(missing_docs)]
pub mod core_lib;
/// Long-form guides rendered directly in docs.rs navigation.
pub mod guides;
#[allow(missing_docs)]
pub mod parsing;
#[allow(missing_docs)]
pub mod runtime;
#[allow(missing_docs)]
pub mod rust_lib;
#[allow(missing_docs)]
pub mod semantic;

/// Common imports for host applications using the high-level runtime API.
pub mod prelude {
    pub use crate::{
        LehitRegistration,
        runtime::{
            AbiCallError, AbiCallStatus, ExecutionError, ExecutionMode, Function, LehitRuntime,
            ModuleSourceProvider, Runtime, RuntimeBuilder, RuntimeFunction,
        },
    };
}