Skip to main content

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}