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//! # Features
43//!
44//! | Feature | What it adds |
45//! | --- | --- |
46//! | *(none)* | The `.nsi` stream reader. |
47//! | `lua` | Reading a Lua scene, which **runs** the script. Builds Lua 5.4 from vendored C source. |
48//! | `gzip` | Reading a gzip-compressed stream. |
49//! | `zstd` | Reading a zstd-compressed stream. |
50//!
51//! Reading a Lua scene means executing it. ɴsɪ's Lua front end is a
52//! programming language -- a script may compute the scene it describes
53//! -- so an interpreter is the only correct reader, and that is a
54//! different trust decision from parsing a data file.
55
56#![deny(missing_docs)]
57
58mod lex;
59#[cfg(feature = "lua")]
60mod lua;
61mod parse;
62mod value;
63
64use core::fmt;
65use nsi_trait::Nsi;
66#[cfg(feature = "gzip")]
67use std::io::Read;
68
69/// Why a scene could not be read.
70#[derive(Debug, Clone, PartialEq, Eq)]
71#[non_exhaustive]
72pub enum Error<E> {
73    /// The input is not the grammar.
74    Syntax {
75        /// Byte offset into the input.
76        offset: usize,
77        /// What the parser wanted there.
78        expected: &'static str,
79    },
80    /// A string literal ran to end of input.
81    UnterminatedString {
82        /// Byte offset of the opening quote.
83        offset: usize,
84    },
85    /// A byte sequence that is not UTF-8.
86    NotUtf8 {
87        /// Byte offset.
88        offset: usize,
89    },
90    /// The input is a `binarynsi` stream, which this crate cannot read.
91    ///
92    /// ɴsɪ has three stream formats and this reads one of them. The
93    /// binary encoding is undocumented, and `autonsi` -- 3Delight's
94    /// default for a name not ending `.nsia` -- selects it, so a caller
95    /// can be handed one without having chosen it.
96    ///
97    /// Detected rather than left to fail as "not UTF-8 at byte 0",
98    /// which is true and useless: it sends the reader looking for an
99    /// encoding problem instead of a format one.
100    BinaryStream,
101    /// An escape sequence this format does not define.
102    BadEscape {
103        /// Byte offset of the backslash.
104        offset: usize,
105    },
106    /// A Lua script failed to load or run.
107    #[cfg(feature = "lua")]
108    Lua(String),
109    /// The input announced a compressor and would not decompress.
110    #[cfg(any(feature = "gzip", feature = "zstd"))]
111    Decompress(String),
112    /// The sink refused a statement.
113    ///
114    /// Parsing stops here, and the sink keeps everything applied before
115    /// it. A caller that wants all-or-nothing parses into a `Recorder`
116    /// first and commits afterwards.
117    Sink(E),
118}
119
120impl<E: fmt::Display> fmt::Display for Error<E> {
121    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
122        match self {
123            Self::Syntax { offset, expected } => {
124                write!(f, "at byte {offset}: expected {expected}")
125            }
126            Self::UnterminatedString { offset } => {
127                write!(f, "at byte {offset}: unterminated string")
128            }
129            Self::BinaryStream => write!(
130                f,
131                "this is a binarynsi stream, which this crate does not \
132                 read; re-write it as text with `renderdl -cat`"
133            ),
134            Self::NotUtf8 { offset } => {
135                write!(f, "at byte {offset}: not UTF-8")
136            }
137            Self::BadEscape { offset } => {
138                write!(f, "at byte {offset}: unknown escape")
139            }
140            #[cfg(feature = "lua")]
141            Self::Lua(message) => write!(f, "lua: {message}"),
142            #[cfg(any(feature = "gzip", feature = "zstd"))]
143            Self::Decompress(message) => {
144                write!(f, "could not decompress: {message}")
145            }
146            Self::Sink(error) => write!(f, "the sink refused: {error}"),
147        }
148    }
149}
150
151impl<E: fmt::Debug + fmt::Display> core::error::Error for Error<E> {}
152
153impl<E> From<lex::LexError> for Error<E> {
154    fn from(error: lex::LexError) -> Self {
155        match error {
156            lex::LexError::UnterminatedString { offset } => {
157                Self::UnterminatedString { offset }
158            }
159            lex::LexError::NotUtf8 { offset } => Self::NotUtf8 { offset },
160            lex::LexError::BadEscape { offset } => Self::BadEscape { offset },
161        }
162    }
163}
164
165#[cfg(feature = "lua")]
166pub use lua::run_lua;
167
168/// Read an ɴsɪ stream, applying it to `sink`.
169///
170/// # Errors
171///
172/// [`Error::Syntax`] and its neighbours for input that is not the
173/// grammar, and [`Error::Sink`] when the sink refuses a statement.
174pub fn parse_stream<N>(input: &[u8], sink: &N) -> Result<(), Error<N::Error>>
175where
176    N: Nsi,
177    for<'call> N: Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call, 'static>>,
178{
179    // `0xCC` is a UTF-8 continuation byte, so a text stream can never
180    // begin with it. Measured: every `renderdl -cat -binary` output
181    // starts `cc 00`, whatever statement comes first -- the third byte
182    // is a length tag for the keyword that follows.
183    if input.starts_with(&[0xCC, 0x00]) {
184        return Err(Error::BinaryStream);
185    }
186
187    parse::parse(input, sink)
188}
189
190/// Read an ɴsɪ stream that may be compressed, applying it to `sink`.
191///
192/// The compressor is detected from the input's leading bytes, so a
193/// caller that took a file from a pipeline does not have to know how it
194/// was written. Uncompressed input is passed straight through.
195///
196/// Only gzip is a format 3Delight itself reads; zstd is supported here
197/// for consumers of this workspace. See `nsi-intermediate`'s
198/// `Compression`.
199///
200/// # Errors
201///
202/// [`Error::Decompress`] when the input announces a compressor and then
203/// fails to decompress, plus everything [`parse_stream`] returns.
204#[cfg(any(feature = "gzip", feature = "zstd"))]
205pub fn parse_compressed<N>(
206    input: &[u8],
207    sink: &N,
208) -> Result<(), Error<N::Error>>
209where
210    N: Nsi,
211    for<'call> N: Nsi<Arg<'call> = nsi_ffi_wrap::Arg<'call, 'static>>,
212{
213    #[cfg(feature = "gzip")]
214    if input.starts_with(&[0x1f, 0x8b]) {
215        let mut plain = Vec::new();
216        flate2::read::GzDecoder::new(input)
217            .read_to_end(&mut plain)
218            .map_err(|error| Error::Decompress(error.to_string()))?;
219        return parse_stream(&plain, sink);
220    }
221
222    #[cfg(feature = "zstd")]
223    if input.starts_with(&[0x28, 0xb5, 0x2f, 0xfd]) {
224        let plain = zstd::decode_all(input)
225            .map_err(|error| Error::Decompress(error.to_string()))?;
226        return parse_stream(&plain, sink);
227    }
228
229    parse_stream(input, sink)
230}