nsi-parse 0.2.0

Fast parser for Nodal Scene Interface – ɴsɪ – streams and Lua scenes.
Documentation

nsi-parse

Build Documentation Crate

A fast reader for ɴsɪ scenes.

nsi-intermediate writes ɴsɪ out; this reads it back. Together they close the loop: a scene can be captured, inspected, replayed and round-tripped without a renderer.

It calls you

Parsing drives nsi_trait::Nsi rather than producing a scene type of its own, so the same parser feeds a live 3Delight context, an nsi-intermediate Recorder, or a backend's own implementation. A reader that insisted on its own representation would make every consumer translate.

A sink brings its own behaviour, not its own argument type: every entry point here binds Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call, 'static>>, because the parser has to build the arguments it hands over and can only build the one shape. Implement nsi_trait::Nsi with that associated type and the parser will drive it.

let bytes = std::fs::read("scene.nsi")?;
let recorder = nsi_intermediate::Recorder::new();
parse_stream(&bytes, &recorder)?;

The grammar is observed, not specified

ɴsɪ publishes no grammar for its stream, only examples. This parser is written against what 3Delight accepts, and the decisive observation is that an entire scene on one line parses: the newlines and indents a renderer writes are formatting, not syntax. So a parameter list runs until the next bare token naming a statement -- parameter names are always quoted, which makes that unambiguous -- and a line-oriented reader would be wrong on valid input.

Paths are carried verbatim

A string value may hold a ${VAR} reference -- ɴsɪ's streampathreplacement writes them so a scene can move between machines -- and this parser does not expand them. Rendered, that is what 3Delight does too: renderdl -cat echoes ${NSI_PATH_TEST}/out.exr back unexpanded, while a render whose imagefilename holds it writes to the expanded path. Expansion happens at use, in whatever opens the file.

Expanding here would bake one machine's paths into a stream whose purpose is to move between them. The obligation is the consumer's: open a path without expanding and you open the wrong file, on exactly the machines where the variable was meant to matter. Note that any variable expands, not only NSI_PATH_-prefixed ones; the prefix governs only which ones 3Delight writes as references.

Features

Feature What it adds
(none) The .nsi stream reader.
lua Reading a Lua scene, which runs the script. Builds Lua 5.4 from vendored C source.
gzip Reading a gzip-compressed stream.
zstd Reading a zstd-compressed stream.
parallel parse_stream_parallel: reading and applying a stream on every core.

Reading a Lua scene means executing it. ɴsɪ's Lua front end is a programming language -- a script may compute the scene it describes -- so an interpreter is the only correct reader, and that is a different trust decision from parsing a data file.

Testing

cargo test -p nsi-parse --features lua,gzip,zstd

One gate needs 3Delight: tests/renderdl.rs builds a scene through a real apistream context and parses what the renderer wrote, with grouped attributes, wrapped continuation lines and the renderer's own float spellings. A round-trip against this workspace's own writer proves much less, because that writer emits one attribute per statement and never wraps.

Specification

Behaviour is specified in specs/004-nsi-parse/, with a contract matrix per surface. The stream grammar there is recorded as observed, not quoted: ɴsɪ publishes no grammar for its stream, so every rule names the probe that established it.

License

MIT OR Apache-2.0 OR Zlib, at your option.