nybl_sys/lib.rs
1//! OS-backed host integration for the Nybl programming language.
2//!
3//! [`StandardHost`] implements [`nybl::NyblHost`] for command-line, desktop,
4//! and server applications that intentionally want ordinary process
5//! capabilities. It:
6//!
7//! - writes Nybl's `print(...)` output to stdout;
8//! - exposes `readline`, UTF-8 file reads and writes, environment lookup, and
9//! Unix time as host functions;
10//! - resolves dot-separated module names beneath a guarded filesystem root;
11//! - resolves Nybl's bundled `std.*` modules first when the default `nybl-std`
12//! feature is enabled.
13//!
14//! # Running a program
15//!
16//! ```
17//! use nybl::NyblLimits;
18//! use nybl_sys::StandardHost;
19//!
20//! let mut host = StandardHost::new();
21//! nybl::run(
22//! r#"use std.math.{PI}
23//! print("pi = {PI}")"#,
24//! &mut host,
25//! &NyblLimits::standard(),
26//! ).unwrap();
27//! ```
28//!
29//! The same host works with `nybl_vm::run` and with Rust generated by
30//! `nybl-compile`.
31//!
32//! Host functions always receive value arguments. Nybl's explicit `ref`
33//! arguments apply only to user-defined language functions, so a script that
34//! needs transactional caller mutation should put it behind a Nybl wrapper.
35//!
36//! # Filesystem modules
37//!
38//! [`StandardHost::with_module_root`] maps `use app.config` to
39//! `<root>/app/config.nybl`. Module names are validated before joining, so
40//! separators, empty segments, and traversal components cannot escape the
41//! configured root. [`resolve_module_from_root`] exposes that filesystem-only
42//! behavior for build tools and AOT module resolvers.
43//!
44//! # Trust boundary
45//!
46//! This crate is deliberately not a sandbox: scripts can call the enabled
47//! filesystem, environment, stdin, and clock functions. Applications running
48//! untrusted code should implement a narrow [`nybl::NyblHost`] instead and only
49//! expose approved capabilities.
50//!
51//! # WebAssembly clocks
52//!
53//! `StandardHost` remains an OS-oriented host. On WASI, its clock functions use
54//! the platform clock normally. On `wasm32-unknown-unknown`, where Rust's
55//! [`std::time::SystemTime`] has no clock implementation, `unix_time()` and
56//! `unix_time_ms()` return an actionable Nybl runtime error instead of
57//! panicking. Browser and other freestanding wasm embeddings should expose a
58//! clock through a custom [`nybl::NyblHost`] backed by their JavaScript host or
59//! a caller-supplied deterministic tick.
60//!
61//! See the [embedding guide](https://nybl-lang.com/docs/embedding/) for the
62//! complete host-function table and custom-host examples.
63
64mod args;
65mod env;
66mod error;
67mod fs;
68mod host;
69mod stdio;
70mod time;
71
72pub use host::{StandardHost, StdHost, resolve_module_from_root};