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}