Add craft-gridcraft-format: GridCraft's native JSON workbook (#1749)

GridCraft's native workbook format, moved from storytold/gridcraft at
1d0b311b: the `.json`/`.scjson` extensions (crates/engine/src/io.rs), the
reader and its error text (io.rs), and the pretty writer with newer macros kept
unread and appended to `macros` as the file held them
(crates/engine/src/macros/mod.rs json_bytes).

The Workbook model, the index rebuilds after a read, and macro reading stay in
GridCraft. The consumer's golden test shows saved bytes are unchanged.

Part of #778.
This commit is contained in:
FredApps authored and GitHub committed 2026-11-16 02:03:41 +01:00
1 parent 58964adec1
commit 9a6d894200
7 files changed
+192

No files matched your search

Generated
+9
View File
@@ -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"
+1
View File
@@ -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" }
+3
View File
@@ -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.
+16
View File
@@ -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 }
+17
View File
@@ -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`.
+59
View File
@@ -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<T: DeserializeOwned>(bytes: &[u8]) -> Result<T, Error> {
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<T: Serialize>(workbook: &T) -> Result<Vec<u8>, 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<T: Serialize>(workbook: &T, field: &str, kept: &[Value]) -> Result<Vec<u8>, 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;
+87
View File
@@ -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<String>,
active: u32,
#[serde(default)]
macros: Vec<Value>,
}
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::<Book>(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<String>,
}
let bytes = write_with_kept(&Bare { sheets: vec![] }, "macros", &[json!(1)]).unwrap();
assert_eq!(serde_json::from_slice::<Value>(&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::<Value>(&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::<Book>(bad).unwrap_err();
assert!(matches!(err, Error::Read(_)));
assert!(err.to_string().starts_with("not a GridCraft JSON workbook: "), "{err}");
}
assert_eq!(
read::<Book>(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<Vec<u8>, u8> = [(vec![1], 1)].into();
assert!(matches!(write(&bad), Err(Error::Write(_))));
assert!(matches!(write_with_kept(&bad, "macros", &[json!(1)]), Err(Error::Write(_))));
}