scratch_test_model/
lib.rs

1#![doc = include_str!("../../../README.md")]
2//! ## scratch-test-model
3//!
4//! Model to parse the [`*.sb3` file format](https://en.scratch-wiki.info/wiki/Scratch_File_Format)
5//! of the [Scratch](https://scratch.mit.edu/) block-oriented programming language
6//!
7//! (I want to note that I was unable to find the above link to the format specification
8//! when I was developing this so I reverse-engineered the format from example files.
9//! Luckily, it looks like I correctly understood the meaning of the components.
10//! This is the second version of the parser that supports all standard blocks
11//! and some extensions even blocks that aren't supported by the interpreter.)
12//!
13//!
14//! The program components extracted from a `*.sb3` file are represented by the
15//! [`ProjectDoc`] type which offers different methods for parsing a file or
16//! a sequence of bytes representing the file's content.
17//! The simplest is to first parse the document as json as this value
18//! will be borrowed internally.
19//!
20//! ```no_run
21//! # use scratch_test_model::{ProjectDoc, json_from_sb3_file};
22//! let json = json_from_sb3_file("/path/to/file.sb3").unwrap();
23//! let doc = ProjectDoc::from_json(&json);
24//! println!("{doc:#?}");
25//! ```
26//!
27//! # Steps
28//!
29//! ## JSON extraction
30//!
31//! A [Scratch file](https://en.scratch-wiki.info/wiki/Scratch_File_Format#Project_Files)
32//! is a ZIP file with images, sounds, ... and a `project.json`
33//! that contains all information about the program structure.
34//!
35//! If the used decompression algorithm is unable to read the file
36//! or if you want to provide the `project.json` file directly
37//! you can use [`ProjectDoc::from_json`] which can be called with
38//! an already parsed JSON document.
39//!
40//! (See [`ProjectDoc`] for details.)
41//!
42//! (The next sections will explain how all program blocks are
43//! extracted from an entered JSON document
44//! – regardless how it was obtained in this section.)
45//!
46//! ## Targets
47//!
48//! Each document contains some meta information and – most
49//! importantly – a `targets` field containing a list of "targets".
50//! A [target](https://en.scratch-wiki.info/wiki/Scratch_File_Format#Targets)
51//! is a sprite or the background and contains different data.
52//! (The sprites have _local_ variables and the background's
53//! variables and lists are seen as _global_.)
54//!
55//! The relevant information stored in the modeled target:
56//! - [`TargetVariables`]: all variables of the target (local for sprites and global for the stage)
57//! - [`TargetLists`]: all lists of the target (local for sprites and global for the stage)
58//! - [`TargetBlocks`]: collection of all statement, expression, comparison, event, ... blocks of the program
59//! - [`TargetProcedures`]: generated from the blocks.
60//!   (The information about a procedure is split
61//!   across multiple blocks in a weird format.
62//!   This combines this data per procedure)
63//!
64//! (See [`Target`] for details.)
65
66#[allow(unused)]
67use scopes::{Target, TargetBlocks, TargetLists, TargetProcedures, TargetVariables};
68
69pub mod attrs;
70mod aux;
71pub mod blocks;
72pub mod error;
73mod reader;
74pub mod scopes;
75
76#[cfg(feature = "sb3")]
77pub use reader::json_from_sb3_file;
78#[cfg(feature = "sb3")]
79pub use reader::json_from_sb3_stream;
80pub use scopes::ProjectDoc;
81pub type Id = svalue::ARc<str>;
82
83/// everything that the proc-macro needs to reference is here
84#[allow(unused)]
85mod _exports {
86    pub use crate::aux::AttrLocation;
87    pub(crate) use crate::aux::do_for_attrs::{DoForAttrs, DoForAttrsStrategy};
88    pub(crate) use crate::aux::errors::BlockKindError;
89    pub use crate::aux::opcode_trait::{AsOpcodeName, AsOpcodeUnit};
90    pub(crate) use crate::aux::parse_attr::helper_attr_access;
91    pub(crate) use crate::aux::parse_block::{BlockProperties, JsonBlocks, ParseJsonBlock};
92}
scratch_test_model/lib.rs

scratch_test_model/
lib.rs
