# `nsi-parse`
[](https://github.com/virtualritz/nsi/actions)
[](https://docs.rs/nsi-parse)
[](https://crates.io/crates/nsi-parse)
A fast reader for [ɴsɪ](https://nsi.readthedocs.io/) 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.
```rust
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
| *(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
```bash
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/`](https://github.com/virtualritz/nsi/tree/master/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.