nsi_parse/lib.rs
1//! A fast reader for [ɴsɪ](https://nsi.readthedocs.io/) scenes.
2//!
3//! `nsi-intermediate` writes ɴsɪ out; this reads it back. Together they
4//! close the loop: a scene can be captured, inspected, replayed and
5//! round-tripped without a renderer.
6//!
7//! # It calls you
8//!
9//! Parsing drives [`nsi_trait::Nsi`] rather than producing a scene type
10//! of its own, so the same parser feeds a live 3Delight context, an
11//! `nsi-intermediate` `Recorder`, or a backend's own implementation. A
12//! reader that insisted on its own representation would make every
13//! consumer translate.
14//!
15//! A sink brings its own *behaviour*, not its own argument type: every
16//! entry point here binds `Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call,
17//! 'static>>`, because the parser has to build the arguments it hands
18//! over and can only build the one shape. Implement [`nsi_trait::Nsi`]
19//! with that associated type and the parser will drive it.
20//!
21//! ```no_run
22//! # use nsi_parse::parse_stream;
23//! # fn main() -> Result<(), Box<dyn std::error::Error>> {
24//! let bytes = std::fs::read("scene.nsi")?;
25//! let recorder = nsi_intermediate::Recorder::new();
26//! parse_stream(&bytes, &recorder)?;
27//! # Ok(())
28//! # }
29//! ```
30//!
31//! # The grammar is observed, not specified
32//!
33//! ɴsɪ publishes no grammar for its stream, only examples. This parser
34//! is written against what 3Delight accepts, and the decisive
35//! observation is that **an entire scene on one line parses**: the
36//! newlines and indents a renderer writes are formatting, not syntax.
37//! So a parameter list runs until the next *bare* token naming a
38//! statement -- parameter names are always quoted, which makes that
39//! unambiguous -- and a line-oriented reader would be wrong on valid
40//! input.
41//!
42//! # Paths are carried verbatim
43//!
44//! A string value may hold a `${VAR}` reference -- ɴsɪ's
45//! `streampathreplacement` writes them so a scene can move between
46//! machines -- and this parser **does not expand them**. Rendered,
47//! that is what 3Delight does too: `renderdl -cat` echoes
48//! `${NSI_PATH_TEST}/out.exr` back unexpanded, while a render whose
49//! `imagefilename` holds it writes to the expanded path. Expansion
50//! happens at *use*, in whatever opens the file.
51//!
52//! Expanding here would bake one machine's paths into a stream whose
53//! purpose is to move between them. The obligation is the consumer's:
54//! open a path without expanding and you open the wrong file, on
55//! exactly the machines where the variable was meant to matter. Note
56//! that **any** variable expands, not only `NSI_PATH_`-prefixed ones;
57//! the prefix governs only which ones 3Delight *writes* as
58//! references.
59//!
60//! # Features
61//!
62//! | Feature | What it adds |
63//! | --- | --- |
64//! | *(none)* | The `.nsi` stream reader. |
65//! | `lua` | Reading a Lua scene, which **runs** the script. Builds Lua 5.4 from vendored C source. |
66//! | `gzip` | Reading a gzip-compressed stream. |
67//! | `zstd` | Reading a zstd-compressed stream. |
68//! | `parallel` | `parse_stream_parallel`: reading and applying a stream on every core. |
69//!
70//! Reading a Lua scene means executing it. ɴsɪ's Lua front end is a
71//! programming language -- a script may compute the scene it describes
72//! -- so an interpreter is the only correct reader, and that is a
73//! different trust decision from parsing a data file.
74
75#![deny(missing_docs)]
76
77mod lex;
78#[cfg(feature = "lua")]
79mod lua;
80#[cfg(feature = "parallel")]
81mod parallel;
82mod parse;
83mod value;
84
85use core::fmt;
86use nsi_trait::Nsi;
87#[cfg(feature = "gzip")]
88use std::io::Read;
89
90/// Why a scene could not be read.
91#[derive(Debug, Clone, PartialEq, Eq)]
92#[non_exhaustive]
93pub enum Error<E> {
94 /// The input is not the grammar.
95 Syntax {
96 /// Byte offset into the input.
97 offset: usize,
98 /// What the parser wanted there.
99 expected: &'static str,
100 },
101 /// A string literal ran to end of input.
102 UnterminatedString {
103 /// Byte offset of the opening quote.
104 offset: usize,
105 },
106 /// A byte sequence that is not UTF-8.
107 NotUtf8 {
108 /// Byte offset.
109 offset: usize,
110 },
111 /// The input is a `binarynsi` stream, which this crate cannot read.
112 ///
113 /// ɴsɪ has three stream formats and this reads one of them. The
114 /// binary encoding is undocumented, and `autonsi` -- 3Delight's
115 /// default for a name not ending `.nsia` -- selects it, so a caller
116 /// can be handed one without having chosen it.
117 ///
118 /// Detected rather than left to fail as "not UTF-8 at byte 0",
119 /// which is true and useless: it sends the reader looking for an
120 /// encoding problem instead of a format one.
121 BinaryStream,
122 /// An escape sequence this format does not define.
123 BadEscape {
124 /// Byte offset of the backslash.
125 offset: usize,
126 },
127 /// A Lua script failed to load or run.
128 #[cfg(feature = "lua")]
129 Lua(String),
130 /// The input announced a compressor and would not decompress.
131 #[cfg(any(feature = "gzip", feature = "zstd"))]
132 Decompress(String),
133 /// The sink refused a statement.
134 ///
135 /// Parsing stops here, and the sink keeps everything applied before
136 /// it. A caller that wants all-or-nothing parses into a `Recorder`
137 /// first and commits afterwards.
138 Sink(E),
139}
140
141impl<E: fmt::Display> fmt::Display for Error<E> {
142 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
143 match self {
144 Self::Syntax { offset, expected } => {
145 write!(f, "at byte {offset}: expected {expected}")
146 }
147 Self::UnterminatedString { offset } => {
148 write!(f, "at byte {offset}: unterminated string")
149 }
150 Self::BinaryStream => write!(
151 f,
152 "this is a binarynsi stream, which this crate does not \
153 read; re-write it as text with `renderdl -cat`"
154 ),
155 Self::NotUtf8 { offset } => {
156 write!(f, "at byte {offset}: not UTF-8")
157 }
158 Self::BadEscape { offset } => {
159 write!(f, "at byte {offset}: unknown escape")
160 }
161 #[cfg(feature = "lua")]
162 Self::Lua(message) => write!(f, "lua: {message}"),
163 #[cfg(any(feature = "gzip", feature = "zstd"))]
164 Self::Decompress(message) => {
165 write!(f, "could not decompress: {message}")
166 }
167 Self::Sink(error) => write!(f, "the sink refused: {error}"),
168 }
169 }
170}
171
172impl<E: fmt::Debug + fmt::Display> core::error::Error for Error<E> {}
173
174impl<E> From<lex::LexError> for Error<E> {
175 fn from(error: lex::LexError) -> Self {
176 match error {
177 lex::LexError::UnterminatedString { offset } => {
178 Self::UnterminatedString { offset }
179 }
180 lex::LexError::NotUtf8 { offset } => Self::NotUtf8 { offset },
181 lex::LexError::BadEscape { offset } => Self::BadEscape { offset },
182 }
183 }
184}
185
186#[cfg(feature = "lua")]
187pub use lua::run_lua;
188
189/// Read an ɴsɪ stream, applying it to `sink`.
190///
191/// # Errors
192///
193/// [`Error::Syntax`] and its neighbours for input that is not the
194/// grammar, and [`Error::Sink`] when the sink refuses a statement.
195pub fn parse_stream<N>(input: &[u8], sink: &N) -> Result<(), Error<N::Error>>
196where
197 N: Nsi,
198 for<'call> N: Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call, 'static>>,
199{
200 // `0xCC` is a UTF-8 continuation byte, so a text stream can never
201 // begin with it. Measured: every `renderdl -cat -binary` output
202 // starts `cc 00`, whatever statement comes first -- the third byte
203 // is a length tag for the keyword that follows.
204 if input.starts_with(&[0xCC, 0x00]) {
205 return Err(Error::BinaryStream);
206 }
207
208 parse::parse(input, sink)
209}
210
211/// Read an ɴsɪ stream on every core, applying it to `sink`.
212///
213/// For a sink that accepts calls from many threads at once -- a
214/// renderer's context. The resulting scene is the one [`parse_stream`]
215/// produces, but the calls arrive in a different order:
216///
217/// 1. every `Create`, concurrently, in stream order per handle;
218/// 2. then every `SetAttribute` and `SetAttributeAtTime`, concurrently,
219/// in stream order per handle, and every `Connect`, concurrently, in
220/// stream order per destination attribute.
221///
222/// `Delete`, `DeleteAttribute`, `Disconnect`, `Evaluate` and
223/// `RenderControl` are **barriers**: everything before one is applied
224/// before it, it is applied alone, and nothing after it is applied
225/// before it. So an interactive stream -- edits, a `RenderControl`,
226/// more edits -- keeps its meaning.
227///
228/// # What it buys
229///
230/// Measured on 20 000 meshes, 5.3 MiB, 16 threads: into a sink that does
231/// nothing, 166 MiB/s becomes about 320. **Into 3Delight 2.9, only
232/// 1.15-1.4x**: its context serialises calls internally -- 20 000
233/// `SetAttribute`s take 11.8 ms from one thread and 21.4 ms from
234/// sixteen -- so what is gained there is parsing overlapped with the
235/// renderer, not calls made side by side. A sink that takes calls
236/// concurrently gains the most.
237///
238/// # Differences from `parse_stream`
239///
240/// - **A reference to a node created later succeeds.** Every `Create`
241/// in a segment runs first, so a `SetAttribute` on a node the stream
242/// creates further down finds it, where the sequential parser fails.
243/// - **On failure, which statements were applied is unspecified.**
244/// Statements that do not depend on the failing one may have been
245/// applied, before or after it in the stream. The error returned is
246/// the earliest failure found, and a stream with a single error
247/// reports the same error as [`parse_stream`].
248///
249/// # Errors
250///
251/// As [`parse_stream`].
252#[cfg(feature = "parallel")]
253pub fn parse_stream_parallel<N>(
254 input: &[u8],
255 sink: &N,
256) -> Result<(), Error<N::Error>>
257where
258 N: Nsi + Sync,
259 for<'call> N: Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call, 'static>>,
260{
261 if input.starts_with(&[0xCC, 0x00]) {
262 return Err(Error::BinaryStream);
263 }
264
265 parallel::parse(input, sink)
266}
267
268/// Read an ɴsɪ stream that may be compressed, applying it to `sink`.
269///
270/// The compressor is detected from the input's leading bytes, so a
271/// caller that took a file from a pipeline does not have to know how it
272/// was written. Uncompressed input is passed straight through.
273///
274/// Only gzip is a format 3Delight itself reads; zstd is supported here
275/// for consumers of this workspace. See `nsi-intermediate`'s
276/// `Compression`.
277///
278/// # Errors
279///
280/// [`Error::Decompress`] when the input announces a compressor and then
281/// fails to decompress, plus everything [`parse_stream`] returns.
282#[cfg(any(feature = "gzip", feature = "zstd"))]
283pub fn parse_compressed<N>(
284 input: &[u8],
285 sink: &N,
286) -> Result<(), Error<N::Error>>
287where
288 N: Nsi,
289 for<'call> N: Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call, 'static>>,
290{
291 #[cfg(feature = "gzip")]
292 if input.starts_with(&[0x1f, 0x8b]) {
293 let mut plain = Vec::new();
294 flate2::read::GzDecoder::new(input)
295 .read_to_end(&mut plain)
296 .map_err(|error| Error::Decompress(error.to_string()))?;
297 return parse_stream(&plain, sink);
298 }
299
300 #[cfg(feature = "zstd")]
301 if input.starts_with(&[0x28, 0xb5, 0x2f, 0xfd]) {
302 let plain = zstd::decode_all(input)
303 .map_err(|error| Error::Decompress(error.to_string()))?;
304 return parse_stream(&plain, sink);
305 }
306
307 parse_stream(input, sink)
308}