sb3-decoder 0.1.0

A Rust library for decoding Scratch 3.0 project files (.sb3)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116

//! A builder for creating a Decoder from either a file or in-memory bytes.
//!
//! # Example
//! ```no_run
//! # use sb3_decoder::prelude::*;
//! let builder = DecoderBuilder::new()
//!     .use_file("path/to/project.sb3");
//!
//! let decoder = match builder.build() {
//!     Ok(decoder) => decoder,
//!     Err(e) => panic!("Failed to build decoder: {}", e),
//! };
//! ```

use std::path::PathBuf;

use crate::{decoder::Decoder, error::BuilderError};

/// Represents the source of the .sb3 data.
enum Source {
    /// No source specified.
    None,

    /// Source from a file path.
    File(PathBuf),

    /// Source from in-memory bytes.
    Memory(Vec<u8>),
}

/// A builder for creating a [`Decoder`] from either a file or in-memory bytes.
///
/// # Example
/// ```no_run
/// # use sb3_decoder::prelude::*;
/// let builder = DecoderBuilder::new()
///     .use_file("path/to/project.sb3");
///
/// let decoder = match builder.build() {
///     Ok(decoder) => decoder,
///     Err(e) => panic!("Failed to build decoder: {}", e),
/// };
/// ```
pub struct DecoderBuilder {
    source: Source,
}

impl Default for DecoderBuilder {
    fn default() -> Self {
        Self::new()
    }
}

impl DecoderBuilder {
    /// Creates a new [`DecoderBuilder`] instance with no source specified.
    pub fn new() -> Self {
        Self {
            source: Source::None,
        }
    }

    /// Specifies the source as a file path.
    ///
    /// # Example
    /// ```no_run
    /// # use sb3_decoder::prelude::*;
    /// let builder = DecoderBuilder::new()
    ///     .use_file("path/to/project.sb3");
    /// ```
    pub fn use_file(mut self, path: impl Into<PathBuf>) -> Self {
        self.source = Source::File(path.into());
        self
    }

    /// Specifies the source as in-memory bytes.
    ///
    /// # Example
    /// ```no_run
    /// # use sb3_decoder::prelude::*;
    /// let builder = DecoderBuilder::new()
    /// #   .use_bytes(&[]); /*
    ///     .use_bytes(include_bytes!("path/to/project.sb3"));
    /// # */
    /// ```
    pub fn use_bytes(mut self, bytes: &[u8]) -> Self {
        self.source = Source::Memory(bytes.to_vec());
        self
    }

    /// Builds the [`Decoder`] from the specified source.
    ///
    /// # Example
    /// ```no_run
    /// # use sb3_decoder::prelude::*;
    /// # let builder = DecoderBuilder::new()
    /// #     .use_file("path/to/project.sb3");
    /// let decoder = match builder.build() {
    ///   Ok(decoder) => decoder,
    ///   Err(e) => panic!("Failed to build decoder: {}", e),
    /// };
    /// ```
    ///
    /// # Errors
    /// Returns [`BuilderError::FileRead`] if there is an error reading the file.  
    /// Returns [`BuilderError::NoSource`] if no source was specified.  
    /// Returns [`BuilderError::Decode`] if there is an error creating the decoder.
    pub fn build(self) -> Result<Decoder, BuilderError> {
        let bytes = match self.source {
            Source::File(path) => std::fs::read(path)?,
            Source::Memory(data) => data,
            Source::None => return Err(BuilderError::NoSource),
        };

        Ok(Decoder::new(bytes)?)
    }
}