Skip to main content

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//! See the [embedding guide](https://nybl-lang.com/docs/embedding/) for the
52//! complete host-function table and custom-host examples.
53
54mod args;
55mod env;
56mod error;
57mod fs;
58mod host;
59mod stdio;
60mod time;
61
62pub use host::{StandardHost, StdHost, resolve_module_from_root};