diff --git a/Cargo.lock b/Cargo.lock index eddc22221..d606ce018 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1868,6 +1868,15 @@ dependencies = [ "image", ] +[[package]] +name = "craft-gridcraft-format" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-gzip" version = "0.1.0" diff --git a/Cargo.toml b/Cargo.toml index e58ac33cf..64099b941 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -41,6 +41,7 @@ bytemuck = "1" kurbo = "0.13" thiserror = "2" craft-gzip = { path = "crates/gzip" } +craft-gridcraft-format = { path = "crates/gridcraft-format" } craft-aaf = { path = "crates/aaf" } craft-atomic = { path = "crates/atomic" } craft-captions = { path = "crates/captions" } diff --git a/README.md b/README.md index 0b4b9a415..8150dfea9 100644 --- a/README.md +++ b/README.md @@ -176,6 +176,9 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit every frame's position, delay, disposal and transparent colour, the loop count and the first frame's colour table, without decompressing pixels. Tells an animation from a still and whether a file can hold the picture it declares before a decoder runs. +- [`craft-gridcraft-format`](crates/gridcraft-format/README.md): GridCraft's native JSON workbook + (`.json`, `.scjson`): the extensions, the reader, the pretty writer, and newer entries kept + unread and written back into a list. The workbook model and what follows a read stay in GridCraft. - [`craft-hdr`](crates/hdr/src/lib.rs): Radiance HDR (RGBE) picture reader, from FilmCraft: flat, old and new run-length scan lines and all eight axis orders, to linear float RGB. Scan lines are validated before the picture is allocated. diff --git a/crates/gridcraft-format/Cargo.toml b/crates/gridcraft-format/Cargo.toml new file mode 100644 index 000000000..c965189c2 --- /dev/null +++ b/crates/gridcraft-format/Cargo.toml @@ -0,0 +1,16 @@ +[package] +name = "craft-gridcraft-format" +description = "GridCraft's native JSON workbook file: its extensions, reader and pretty writer" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true + +[lints] +workspace = true + +[dependencies] +serde = { workspace = true } +serde_json = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/gridcraft-format/README.md b/crates/gridcraft-format/README.md new file mode 100644 index 000000000..0f77538f5 --- /dev/null +++ b/crates/gridcraft-format/README.md @@ -0,0 +1,17 @@ +# craft-gridcraft-format + +GridCraft's native workbook file is one pretty-printed UTF-8 JSON object, with a two-space indent +and no newline at the end. It is saved as `.json`, or as `.scjson` by older builds. + +The workbook is a type parameter. GridCraft owns the model, and after a read it rebuilds the +model's indexes, drops cells outside the grid and reads the macros. This crate owns the bytes: + +- `EXTENSIONS` and `is_extension` name the format. +- `read(bytes)` reads a workbook. A failure reads as "not a GridCraft JSON workbook: …". +- `write(workbook)` writes one with `serde_json`'s pretty printer. +- `write_with_kept(workbook, field, kept)` appends entries that a newer version wrote, and this + build kept without reading, to the top-level list `field`, as the file held them. With nothing + kept, the output is exactly `write`'s. Otherwise the workbook goes through a `serde_json::Value` + first, so its object keys come out in map order, as GridCraft has always written them. + +There is no `unsafe` and no panics, and it builds for `wasm32-unknown-unknown`. diff --git a/crates/gridcraft-format/src/lib.rs b/crates/gridcraft-format/src/lib.rs new file mode 100644 index 000000000..0a60ace3a --- /dev/null +++ b/crates/gridcraft-format/src/lib.rs @@ -0,0 +1,59 @@ +//! GridCraft's native workbook file: the workbook as one pretty-printed UTF-8 JSON object, +//! saved as `.json` (or `.scjson`, its older name). +//! +//! GridCraft owns the workbook model and what happens after a read: rebuilding its indexes, +//! dropping cells outside the grid, and reading its macros. This crate owns the bytes: which +//! extensions name the format, how the JSON is read and written, and how entries kept from a +//! newer version are written back into a list as the file held them. +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + +use serde::Serialize; +use serde::de::DeserializeOwned; +use serde_json::Value; + +/// The extensions of the format, lower case. `scjson` is the name older builds saved. +pub const EXTENSIONS: [&str; 2] = ["json", "scjson"]; + +/// Whether `extension` (without the dot, any case) names the format. +pub fn is_extension(extension: &str) -> bool { + EXTENSIONS.iter().any(|e| e.eq_ignore_ascii_case(extension)) +} + +#[derive(Debug, thiserror::Error)] +pub enum Error { + /// The bytes are not a workbook: not JSON, or JSON of another shape. + #[error("not a GridCraft JSON workbook: {0}")] + Read(serde_json::Error), + /// The workbook could not be written as JSON. + #[error("{0}")] + Write(serde_json::Error), +} + +/// Read a workbook. Unknown fields are left to the model's own serde rules. +pub fn read(bytes: &[u8]) -> Result { + serde_json::from_slice(bytes).map_err(Error::Read) +} + +/// Write a workbook as pretty-printed JSON (two-space indent, no newline at the end). +pub fn write(workbook: &T) -> Result, Error> { + serde_json::to_vec_pretty(workbook).map_err(Error::Write) +} + +/// [`write`], with `kept` appended to the top-level list `field` (made if absent): entries a +/// newer version wrote that this build kept without reading. With nothing kept this is exactly +/// [`write`]. Otherwise the workbook goes through a [`Value`] first, so its object keys are +/// written in `serde_json`'s map order. +pub fn write_with_kept(workbook: &T, field: &str, kept: &[Value]) -> Result, Error> { + if kept.is_empty() { + return write(workbook); + } + let mut v = serde_json::to_value(workbook).map_err(Error::Write)?; + if let Some(list) = v.as_object_mut().map(|o| o.entry(field).or_insert_with(|| Value::Array(vec![]))).and_then(Value::as_array_mut) { + list.extend(kept.iter().cloned()); + } + serde_json::to_vec_pretty(&v).map_err(Error::Write) +} + +#[cfg(test)] +mod tests; diff --git a/crates/gridcraft-format/src/tests.rs b/crates/gridcraft-format/src/tests.rs new file mode 100644 index 000000000..6adc5254d --- /dev/null +++ b/crates/gridcraft-format/src/tests.rs @@ -0,0 +1,87 @@ +#![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)] + +use serde::Deserialize; +use serde_json::json; + +use super::*; + +/// A stand-in for an app's workbook: fields in declaration order, one of them a list. +#[derive(Debug, PartialEq, Serialize, Deserialize)] +struct Book { + sheets: Vec, + active: u32, + #[serde(default)] + macros: Vec, +} + +fn book() -> Book { + Book { sheets: vec!["Sheet1".into(), "Été ✓".into()], active: 1, macros: vec![json!({"v": 1, "name": "Fill"})] } +} + +#[test] +fn extensions_are_json_and_scjson_in_any_case() { + for yes in ["json", "scjson", "JSON", "ScJson"] { + assert!(is_extension(yes), "{yes}"); + } + for no in ["", "xlsx", "jsonl", ".json", "scjs"] { + assert!(!is_extension(no), "{no}"); + } +} + +#[test] +fn a_workbook_is_written_pretty_in_field_order() { + let bytes = write(&book()).unwrap(); + let text = String::from_utf8(bytes).unwrap(); + assert_eq!( + text, + "{\n \"sheets\": [\n \"Sheet1\",\n \"Été ✓\"\n ],\n \"active\": 1,\n \"macros\": [\n {\n \"name\": \"Fill\",\n \"v\": 1\n }\n ]\n}" + ); + assert_eq!(read::(text.as_bytes()).unwrap(), book()); +} + +#[test] +fn kept_entries_are_appended_as_the_file_held_them() { + let kept = [json!({"v": 9, "name": "Future", "extra": [1, 2]})]; + let bytes = write_with_kept(&book(), "macros", &kept).unwrap(); + let back: Book = read(&bytes).unwrap(); + assert_eq!(back.macros, [json!({"v": 1, "name": "Fill"}), kept[0].clone()]); + // Through a JSON value, keys are in map order: `active` before `macros` before `sheets`. + let text = String::from_utf8(bytes).unwrap(); + assert!(text.find("\"active\"") < text.find("\"macros\"") && text.find("\"macros\"") < text.find("\"sheets\""), "{text}"); + // With nothing kept, the plain writer's bytes. + assert_eq!(write_with_kept(&book(), "macros", &[]).unwrap(), write(&book()).unwrap()); +} + +#[test] +fn kept_entries_make_the_list_when_it_is_absent() { + #[derive(Serialize)] + struct Bare { + sheets: Vec, + } + let bytes = write_with_kept(&Bare { sheets: vec![] }, "macros", &[json!(1)]).unwrap(); + assert_eq!(serde_json::from_slice::(&bytes).unwrap(), json!({"sheets": [], "macros": [1]})); + // A field that is not a list is left as it is. + let bytes = write_with_kept(&json!({"macros": "text"}), "macros", &[json!(1)]).unwrap(); + assert_eq!(serde_json::from_slice::(&bytes).unwrap(), json!({"macros": "text"})); +} + +#[test] +fn what_is_not_a_workbook_says_so() { + for bad in [&b""[..], b"{", b"[]", b"{\"sheets\": 7, \"active\": 0}", b"\xff\xfe"] { + let err = read::(bad).unwrap_err(); + assert!(matches!(err, Error::Read(_))); + assert!(err.to_string().starts_with("not a GridCraft JSON workbook: "), "{err}"); + } + assert_eq!( + read::(b"{\"sheets\": 7}").unwrap_err().to_string(), + "not a GridCraft JSON workbook: invalid type: integer `7`, expected a sequence at line 1 column 12" + ); +} + +#[test] +fn a_value_json_cannot_hold_is_a_write_error() { + use std::collections::BTreeMap; + let bad: BTreeMap, u8> = [(vec![1], 1)].into(); + assert!(matches!(write(&bad), Err(Error::Write(_)))); + assert!(matches!(write_with_kept(&bad, "macros", &[json!(1)]), Err(Error::Write(_)))); +}