nybl-sys 0.5.0

Standard host integration for the Nybl programming language
Documentation
//! OS-backed host integration for the Nybl programming language.
//!
//! [`StandardHost`] implements [`nybl::NyblHost`] for command-line, desktop,
//! and server applications that intentionally want ordinary process
//! capabilities. It:
//!
//! - writes Nybl's `print(...)` output to stdout;
//! - exposes `readline`, UTF-8 file reads and writes, environment lookup, and
//!   Unix time as host functions;
//! - resolves dot-separated module names beneath a guarded filesystem root;
//! - resolves Nybl's bundled `std.*` modules first when the default `nybl-std`
//!   feature is enabled.
//!
//! # Running a program
//!
//! ```
//! use nybl::NyblLimits;
//! use nybl_sys::StandardHost;
//!
//! let mut host = StandardHost::new();
//! nybl::run(
//!     r#"use std.math.{PI}
//! print("pi = {PI}")"#,
//!     &mut host,
//!     &NyblLimits::standard(),
//! ).unwrap();
//! ```
//!
//! The same host works with `nybl_vm::run` and with Rust generated by
//! `nybl-compile`.
//!
//! Host functions always receive value arguments. Nybl's explicit `ref`
//! arguments apply only to user-defined language functions, so a script that
//! needs transactional caller mutation should put it behind a Nybl wrapper.
//!
//! # Filesystem modules
//!
//! [`StandardHost::with_module_root`] maps `use app.config` to
//! `<root>/app/config.nybl`. Module names are validated before joining, so
//! separators, empty segments, and traversal components cannot escape the
//! configured root. [`resolve_module_from_root`] exposes that filesystem-only
//! behavior for build tools and AOT module resolvers.
//!
//! # Trust boundary
//!
//! This crate is deliberately not a sandbox: scripts can call the enabled
//! filesystem, environment, stdin, and clock functions. Applications running
//! untrusted code should implement a narrow [`nybl::NyblHost`] instead and only
//! expose approved capabilities.
//!
//! # WebAssembly clocks
//!
//! `StandardHost` remains an OS-oriented host. On WASI, its clock functions use
//! the platform clock normally. On `wasm32-unknown-unknown`, where Rust's
//! [`std::time::SystemTime`] has no clock implementation, `unix_time()` and
//! `unix_time_ms()` return an actionable Nybl runtime error instead of
//! panicking. Browser and other freestanding wasm embeddings should expose a
//! clock through a custom [`nybl::NyblHost`] backed by their JavaScript host or
//! a caller-supplied deterministic tick.
//!
//! See the [embedding guide](https://nybl-lang.com/docs/embedding/) for the
//! complete host-function table and custom-host examples.

mod args;
mod env;
mod error;
mod fs;
mod host;
mod stdio;
mod time;

pub use host::{StandardHost, StdHost, resolve_module_from_root};