mirror of
https://github.com/storytold/craft-libs.git
synced 2026-11-16 23:42:27 +00:00
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:
1 parent
58964adec1
commit
9a6d894200
7 files changed
+192
No files matched your search
Generated
+9
@@ -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"
|
||||
|
||||
@@ -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" }
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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 }
|
||||
@@ -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`.
|
||||
@@ -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;
|
||||
@@ -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(_))));
|
||||
}
|
||||
Reference in new issue
Block a user