rgbds_obj/
fstack.rs

1use crate::util::{opt_u32, read_str, read_u32le, read_u8};
2use std::convert::TryInto;
3use std::fmt::{self, Display, Formatter};
4use std::io::{self, Read};
5
6/// A file stack node.
7///
8/// Historically, RGBDS stored locations as simple strings, which were extended to contain the
9/// the full "file stack" (included files, macro calls, etc.); however, object files grew very
10/// large, as the strings contained a lot of repetition.
11///
12/// To solve the bloat problem, file stack nodes were introduced in [format v9 r5]; they store each
13/// scope in a unique way, building a tree.
14/// However, scopes don't store line numbers, since several definitions may occur per scope, but
15/// instead store the line number at which their parent scope was exited.
16///
17/// [format v9 r5]: https://rgbds.gbdev.io/docs/v0.4.2/rgbds.5
18#[derive(Debug)]
19pub struct Node {
20    parent_id: Option<u32>,
21    parent_line_no: u32,
22    node_type: NodeType,
23    quiet: bool,
24}
25impl Node {
26    pub(crate) fn read_from(mut input: impl Read) -> Result<Self, io::Error> {
27        let parent_id = opt_u32(read_u32le(&mut input)?);
28        let parent_line_no = read_u32le(&mut input)?;
29        let (node_type, quiet) = NodeType::read_from(input)?;
30
31        Ok(Node {
32            parent_id,
33            parent_line_no,
34            node_type,
35            quiet,
36        })
37    }
38
39    /// Returns the ID of the parent node, and the line number at which it was exited.
40    /// If the node is a root node, `None` is returned instead.
41    pub fn parent(&self) -> Option<(u32, u32)> {
42        self.parent_id.map(|id| (id, self.parent_line_no))
43    }
44
45    /// The node's type and associated data.
46    pub fn type_data(&self) -> &NodeType {
47        &self.node_type
48    }
49
50    /// Whether the node is "quiet" (excluded from error and warning backtraces).
51    pub fn is_quiet(&self) -> &bool {
52        &self.quiet
53    }
54
55    /// Whether the node is a `REPT`.
56    pub fn is_rept(&self) -> bool {
57        matches!(self.type_data(), NodeType::Rept(..))
58    }
59}
60
61/// A file stack node's type, and associated type-dependent data.
62#[derive(Debug)]
63pub enum NodeType {
64    /// The node represents one or more `REPT` blocks, and contains the iteration count for each of
65    /// them.
66    Rept(Vec<u32>),
67    /// The node represents a top-level or `INCLUDE`d file, and contains the file's path (which may
68    /// not be valid UTF-8).
69    File(Vec<u8>),
70    /// The node represents a macro invocation, and contains the macro's name (which may not be
71    /// valid UTF-8).
72    Macro(Vec<u8>),
73}
74impl NodeType {
75    fn read_from(mut input: impl Read) -> Result<(Self, bool), io::Error> {
76        let node_type = read_u8(&mut input)?;
77        let quiet = (node_type & 0x80) != 0;
78        match node_type & 0x7F {
79            0 => {
80                let depth = read_u32le(&mut input)?.try_into().unwrap();
81                let mut iters = Vec::with_capacity(depth);
82                for _ in 0..depth {
83                    iters.push(read_u32le(&mut input)?);
84                }
85                Ok((NodeType::Rept(iters), quiet))
86            }
87            1 => Ok((NodeType::File(read_str(input)?), quiet)),
88            2 => Ok((NodeType::Macro(read_str(input)?), quiet)),
89            _ => Err(io::Error::new(
90                io::ErrorKind::InvalidData,
91                "Invalid fstack node type",
92            )),
93        }
94    }
95}
96impl Display for NodeType {
97    fn fmt(&self, fmt: &mut Formatter) -> Result<(), fmt::Error> {
98        use NodeType::*;
99
100        match self {
101            Rept(iters) => {
102                for iter in iters {
103                    write!(fmt, "::REPT~{iter}")?;
104                }
105            }
106            File(name) | Macro(name) => write!(fmt, "{}", String::from_utf8_lossy(name))?,
107        };
108        Ok(())
109    }
110}
rgbds_obj/fstack.rs

rgbds_obj/
fstack.rs
