Skip to main content

Crate nybl_compile

Crate nybl_compile 

Source
Expand description

Ahead-of-time Nybl-to-Rust transpiler.

transpile parses a Nybl program and emits readable Rust source that links against nybl-lang for runtime values, operators, built-ins, host calls, and diagnostics. The generated source can be compiled as a native binary or included as a module in a larger Rust application.

The AOT engine implements the same language semantics as the tree-walker and bytecode VM, including methods, closures, string interpolation, indexed and field mutation, transactional ref parameters, structs and enums, pattern matching, Result, lazy iteration, and all forms of use. A three-engine differential suite exercises their observable behavior together.

§Basic transpilation

use nybl_compile::{Options, transpile};

let rust_source = transpile(
    r#"let answer = 6 * 7
print("answer = {answer}")"#,
    &Options::default(),
).unwrap();
assert!(rust_source.contains("fn main()"));

use statements need a compile-time ModuleResolver. For bundled stdlib modules, callers normally delegate that resolver to nybl::stdlib::resolve; for in-memory programs, modules_from_map is convenient:

use nybl_compile::{Options, modules_from_map, transpile};

let rust_source = transpile(
    "use config.{answer}\nprint(answer)",
    &Options {
        module_resolver: Some(modules_from_map([
            ("config", "let answer = 42"),
        ])),
        ..Options::default()
    },
).unwrap();
assert!(rust_source.contains("42"));

With the default options, the output contains fn main() and constructs nybl_sys::StandardHost. Set Options::emit_main and Options::use_nybl_sys to false for a library surface driven by a custom nybl::NyblHost.

§Sandboxed output

Options::sandbox adds nybl::NyblLimits accounting and host tick callbacks to generated code. With sandbox: true and emit_main: false, direct root-level pub fn declarations also generate a persistent NyblInstance API with load, entry_points, call, and call_value. Globals, modules, functions, callbacks, types, methods, and random-number state remain live between calls.

Rust calls into the generated NyblInstance remain value-only and reject ref-bearing entries or callbacks before execution. A value-only public entry can use reference parameters internally. Generated ref calls preserve the language’s target validation, copy-in/copy-out staging, atomic commit, error rollback, forwarding, and mutating receiver behavior. See the reference-parameters guide. Generated user methods also preserve ref self receiver write-back and rollback; ordinary self receivers are read-only.

Unsandboxed library output exposes the one-shot run API and deliberately omits accounting overhead. Do not run untrusted programs through that mode.

§Output shaping

Options::module_name wraps the generated items in a public Rust module, which lets one crate include several transpiled programs without name collisions. transpile_ast accepts an already parsed Nybl AST for build tools that perform their own parse and diagnostic pass.

See the embedding guide and stateful instance guide for generated signatures, dependency setup, limits, and lifecycle rules.

Structs§

Options
Options that control the shape of the emitted Rust.

Functions§

modules_from_map
Build a ModuleResolver from an in-memory name→source map. Convenience for tests and simple embedders.
transpile
Parse Nybl source and emit the equivalent Rust source.
transpile_ast
Lower-level entry point: emit Rust from an already-parsed AST.

Type Aliases§

ModuleResolver
A compile-time module resolver. The AOT runs this eagerly for every use it encounters, threading the entire module graph into the generated Rust. Same contract as nybl::NyblHost::resolve_module: None = not handled, Some(Ok(source)) = module source text, Some(Err(_)) = resolver failure.