nybl-sys 0.5.0

Standard host integration for the Nybl programming language
Documentation
# nybl-sys

The standard host for the [Nybl](https://github.com/stevepryde/nybl-lang) programming language — a `NyblHost` implementation that wires Nybl up to the normal OS-backed conveniences (filesystem, stdio, environment, time) plus the bundled Nybl stdlib.

If you're writing a command-line tool or a desktop / server app that runs Nybl scripts, `StdHost` is the default you want. Custom embeddings (sandboxed, wasm, no_std) should write their own `NyblHost` impl.

## What `StdHost` provides

### Import resolution

- `use std.math` / `std.json` / `std.collections` / … → resolved via `nybl-lang`'s bundled stdlib (the `nybl-std` feature, forwarded by default)
- `use my_module` / `my.nested.module` → resolved from the filesystem beneath
  the host's module root (the current working directory by default; the CLI
  sets it to the script's parent)

### Host functions (available to Nybl code as `fn_name(...)`)

- `readline()` — read a line from stdin
- `read_file(path)` / `write_file(path, contents)` / `append_file(path, contents)` / `file_exists(path)` — filesystem basics
- `env(var_name)` — read an environment variable
- `unix_time()` / `unix_time_ms()` — current time, seconds / milliseconds since epoch
- `print` is provided by `nybl-lang` itself; `StdHost` routes output to stdout

Host functions always receive value arguments. Explicit `ref` arguments are
supported only by user-defined Nybl functions; write a Nybl wrapper when a
script needs to update one of its own variables transactionally.

## Quick start

```toml
[dependencies]
nybl-lang = "0.5"
nybl-sys  = "0.5"
```

```rust
use nybl::{run, NyblLimits};
use nybl_sys::StdHost;

fn main() {
    let mut host = StdHost::new();
    run(r#"
        use std.math
        print("π ≈ {PI}")
        let now = unix_time()
        print("running at {now}")
    "#, &mut host, &NyblLimits::standard()).unwrap();
}
```

Prefer the faster bytecode runtime? Drop in [`nybl-vm`](https://crates.io/crates/nybl-vm) — `StdHost` works unchanged:

```rust
nybl_vm::run(source, &mut host, &NyblLimits::standard())?;
```

## When *not* to use `nybl-sys`

- **Sandboxed embeddings** that need to block filesystem / env access — write a bare `NyblHost` impl and skip this crate entirely.
- **WASM / no_std builds** — `nybl-sys` depends on `std` and is an OS-oriented
  host. On WASI its clock functions use the platform clock. On
  `wasm32-unknown-unknown`, `unix_time()` and `unix_time_ms()` return a Nybl
  runtime error instead of panicking because that target has no system clock.
  Browser and other freestanding wasm embeddings should use `nybl-lang`
  (optionally with `nybl-vm`) directly and provide time through a custom
  `NyblHost`.
- **Anywhere you want a tighter custom host surface** — `NyblHost::call` is the only thing you need to implement; your host can expose exactly the functions your app wants Nybl to reach.

## Related crates

- [`nybl-lang`]https://crates.io/crates/nybl-lang — the language core + `NyblHost` trait
- The Nybl stdlib this crate routes `use std.*` to lives inside `nybl-lang` behind the `nybl-std` feature (forwarded by default from `nybl-sys`).
- [`nybl-vm`]https://crates.io/crates/nybl-vm — faster bytecode runtime, drop-in with the same `StdHost`
- [`nybl-cli`]https://crates.io/crates/nybl-cli — the `nybl` binary built on top of `nybl-sys`

## License

Dual-licensed under [MIT](https://github.com/stevepryde/nybl-lang/blob/main/LICENSE-MIT) or [Apache 2.0](https://github.com/stevepryde/nybl-lang/blob/main/LICENSE-APACHE), at your option.