sheetkit_xml/
relationships.rs

1//! Relationships XML schema structures.
2//!
3//! Used in `_rels/.rels`, `xl/_rels/workbook.xml.rels`, and other relationship files.
4
5use serde::{Deserialize, Serialize};
6
7use crate::namespaces;
8
9/// Relationships root element.
10#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
11#[serde(rename = "Relationships")]
12pub struct Relationships {
13    #[serde(rename = "@xmlns")]
14    pub xmlns: String,
15
16    #[serde(rename = "Relationship", default)]
17    pub relationships: Vec<Relationship>,
18}
19
20/// Individual relationship entry.
21#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
22pub struct Relationship {
23    #[serde(rename = "@Id")]
24    pub id: String,
25
26    #[serde(rename = "@Type")]
27    pub rel_type: String,
28
29    #[serde(rename = "@Target")]
30    pub target: String,
31
32    #[serde(rename = "@TargetMode", skip_serializing_if = "Option::is_none")]
33    pub target_mode: Option<String>,
34}
35
36/// Creates the package-level relationships (`_rels/.rels`).
37///
38/// Contains relationships from the package root to the workbook, core
39/// properties, and extended properties parts.
40pub fn package_rels() -> Relationships {
41    Relationships {
42        xmlns: namespaces::PACKAGE_RELATIONSHIPS.to_string(),
43        relationships: vec![
44            Relationship {
45                id: "rId1".to_string(),
46                rel_type: rel_types::OFFICE_DOCUMENT.to_string(),
47                target: "xl/workbook.xml".to_string(),
48                target_mode: None,
49            },
50            Relationship {
51                id: "rId2".to_string(),
52                rel_type: rel_types::CORE_PROPERTIES.to_string(),
53                target: "docProps/core.xml".to_string(),
54                target_mode: None,
55            },
56            Relationship {
57                id: "rId3".to_string(),
58                rel_type: rel_types::EXTENDED_PROPERTIES.to_string(),
59                target: "docProps/app.xml".to_string(),
60                target_mode: None,
61            },
62        ],
63    }
64}
65
66/// Creates the workbook-level relationships (`xl/_rels/workbook.xml.rels`).
67///
68/// Contains relationships to worksheets, styles, and shared strings.
69pub fn workbook_rels() -> Relationships {
70    Relationships {
71        xmlns: namespaces::PACKAGE_RELATIONSHIPS.to_string(),
72        relationships: vec![
73            Relationship {
74                id: "rId1".to_string(),
75                rel_type: rel_types::WORKSHEET.to_string(),
76                target: "worksheets/sheet1.xml".to_string(),
77                target_mode: None,
78            },
79            Relationship {
80                id: "rId2".to_string(),
81                rel_type: rel_types::STYLES.to_string(),
82                target: "styles.xml".to_string(),
83                target_mode: None,
84            },
85            Relationship {
86                id: "rId3".to_string(),
87                rel_type: rel_types::SHARED_STRINGS.to_string(),
88                target: "sharedStrings.xml".to_string(),
89                target_mode: None,
90            },
91        ],
92    }
93}
94
95/// Relationship type URI constants.
96pub mod rel_types {
97    // Package level
98    pub const OFFICE_DOCUMENT: &str =
99        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument";
100    pub const CORE_PROPERTIES: &str =
101        "http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties";
102    pub const EXTENDED_PROPERTIES: &str =
103        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties";
104
105    // Workbook level
106    pub const WORKSHEET: &str =
107        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet";
108    pub const SHARED_STRINGS: &str =
109        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings";
110    pub const STYLES: &str =
111        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles";
112    pub const THEME: &str =
113        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/theme";
114    pub const CHARTSHEET: &str =
115        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chartsheet";
116    pub const CALC_CHAIN: &str =
117        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/calcChain";
118    pub const EXTERNAL_LINK: &str =
119        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/externalLink";
120    pub const PIVOT_CACHE_DEF: &str =
121        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheDefinition";
122    pub const PIVOT_TABLE: &str =
123        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotTable";
124    pub const PIVOT_CACHE_RECORDS: &str =
125        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/pivotCacheRecords";
126
127    // Worksheet level
128    pub const COMMENTS: &str =
129        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/comments";
130    pub const DRAWING: &str =
131        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/drawing";
132    pub const TABLE: &str =
133        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/table";
134    pub const HYPERLINK: &str =
135        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
136    pub const PRINTER_SETTINGS: &str =
137        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/printerSettings";
138
139    pub const VML_DRAWING: &str =
140        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/vmlDrawing";
141
142    // Drawing level
143    pub const CHART: &str =
144        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/chart";
145    pub const IMAGE: &str =
146        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image";
147
148    // Custom properties
149    pub const CUSTOM_PROPERTIES: &str =
150        "http://schemas.openxmlformats.org/officeDocument/2006/relationships/custom-properties";
151}
152
153#[cfg(test)]
154mod tests {
155    use super::*;
156
157    #[test]
158    fn test_package_rels_factory() {
159        let rels = package_rels();
160        assert_eq!(rels.xmlns, namespaces::PACKAGE_RELATIONSHIPS);
161        assert_eq!(rels.relationships.len(), 3);
162
163        // Office document relationship
164        assert_eq!(rels.relationships[0].id, "rId1");
165        assert_eq!(rels.relationships[0].rel_type, rel_types::OFFICE_DOCUMENT);
166        assert_eq!(rels.relationships[0].target, "xl/workbook.xml");
167        assert!(rels.relationships[0].target_mode.is_none());
168
169        // Core properties relationship
170        assert_eq!(rels.relationships[1].id, "rId2");
171        assert_eq!(rels.relationships[1].rel_type, rel_types::CORE_PROPERTIES);
172        assert_eq!(rels.relationships[1].target, "docProps/core.xml");
173
174        // Extended properties relationship
175        assert_eq!(rels.relationships[2].id, "rId3");
176        assert_eq!(
177            rels.relationships[2].rel_type,
178            rel_types::EXTENDED_PROPERTIES
179        );
180        assert_eq!(rels.relationships[2].target, "docProps/app.xml");
181    }
182
183    #[test]
184    fn test_workbook_rels_factory() {
185        let rels = workbook_rels();
186        assert_eq!(rels.xmlns, namespaces::PACKAGE_RELATIONSHIPS);
187        assert_eq!(rels.relationships.len(), 3);
188
189        // Verify worksheet relationship
190        assert_eq!(rels.relationships[0].id, "rId1");
191        assert_eq!(rels.relationships[0].rel_type, rel_types::WORKSHEET);
192        assert_eq!(rels.relationships[0].target, "worksheets/sheet1.xml");
193
194        // Verify styles relationship
195        assert_eq!(rels.relationships[1].id, "rId2");
196        assert_eq!(rels.relationships[1].rel_type, rel_types::STYLES);
197        assert_eq!(rels.relationships[1].target, "styles.xml");
198
199        // Verify shared strings relationship
200        assert_eq!(rels.relationships[2].id, "rId3");
201        assert_eq!(rels.relationships[2].rel_type, rel_types::SHARED_STRINGS);
202        assert_eq!(rels.relationships[2].target, "sharedStrings.xml");
203    }
204
205    #[test]
206    fn test_relationships_roundtrip() {
207        let rels = package_rels();
208        let xml = quick_xml::se::to_string(&rels).unwrap();
209        let parsed: Relationships = quick_xml::de::from_str(&xml).unwrap();
210        assert_eq!(rels.xmlns, parsed.xmlns);
211        assert_eq!(rels.relationships.len(), parsed.relationships.len());
212        assert_eq!(rels.relationships[0].id, parsed.relationships[0].id);
213        assert_eq!(
214            rels.relationships[0].rel_type,
215            parsed.relationships[0].rel_type
216        );
217        assert_eq!(rels.relationships[0].target, parsed.relationships[0].target);
218    }
219
220    #[test]
221    fn test_workbook_rels_roundtrip() {
222        let rels = workbook_rels();
223        let xml = quick_xml::se::to_string(&rels).unwrap();
224        let parsed: Relationships = quick_xml::de::from_str(&xml).unwrap();
225        assert_eq!(rels.relationships.len(), parsed.relationships.len());
226        for (orig, parsed) in rels.relationships.iter().zip(parsed.relationships.iter()) {
227            assert_eq!(orig.id, parsed.id);
228            assert_eq!(orig.rel_type, parsed.rel_type);
229            assert_eq!(orig.target, parsed.target);
230        }
231    }
232
233    #[test]
234    fn test_relationship_with_target_mode() {
235        let rel = Relationship {
236            id: "rId1".to_string(),
237            rel_type: rel_types::HYPERLINK.to_string(),
238            target: "https://example.com".to_string(),
239            target_mode: Some("External".to_string()),
240        };
241        let xml = quick_xml::se::to_string(&rel).unwrap();
242        assert!(xml.contains("TargetMode=\"External\""));
243
244        let parsed: Relationship = quick_xml::de::from_str(&xml).unwrap();
245        assert_eq!(parsed.target_mode, Some("External".to_string()));
246    }
247
248    #[test]
249    fn test_relationship_without_target_mode_omits_attr() {
250        let rel = Relationship {
251            id: "rId1".to_string(),
252            rel_type: rel_types::WORKSHEET.to_string(),
253            target: "worksheets/sheet1.xml".to_string(),
254            target_mode: None,
255        };
256        let xml = quick_xml::se::to_string(&rel).unwrap();
257        assert!(!xml.contains("TargetMode"));
258    }
259
260    #[test]
261    fn test_parse_real_excel_rels() {
262        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
263<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
264  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="xl/workbook.xml"/>
265</Relationships>"#;
266
267        let parsed: Relationships = quick_xml::de::from_str(xml).unwrap();
268        assert_eq!(parsed.xmlns, namespaces::PACKAGE_RELATIONSHIPS);
269        assert_eq!(parsed.relationships.len(), 1);
270        assert_eq!(parsed.relationships[0].id, "rId1");
271        assert_eq!(parsed.relationships[0].target, "xl/workbook.xml");
272    }
273
274    #[test]
275    fn test_parse_real_excel_workbook_rels() {
276        let xml = r#"<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
277<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
278  <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" Target="worksheets/sheet1.xml"/>
279  <Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/styles" Target="styles.xml"/>
280  <Relationship Id="rId3" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/sharedStrings" Target="sharedStrings.xml"/>
281</Relationships>"#;
282
283        let parsed: Relationships = quick_xml::de::from_str(xml).unwrap();
284        assert_eq!(parsed.relationships.len(), 3);
285        assert_eq!(parsed.relationships[0].rel_type, rel_types::WORKSHEET);
286        assert_eq!(parsed.relationships[1].rel_type, rel_types::STYLES);
287        assert_eq!(parsed.relationships[2].rel_type, rel_types::SHARED_STRINGS);
288    }
289
290    #[test]
291    fn test_serialize_structure() {
292        let rels = package_rels();
293        let xml = quick_xml::se::to_string(&rels).unwrap();
294        assert!(xml.contains("<Relationships"));
295        assert!(xml.contains("<Relationship"));
296        assert!(xml.contains("Id="));
297        assert!(xml.contains("Type="));
298        assert!(xml.contains("Target="));
299    }
300
301    #[test]
302    fn test_empty_relationships() {
303        let rels = Relationships {
304            xmlns: namespaces::PACKAGE_RELATIONSHIPS.to_string(),
305            relationships: vec![],
306        };
307        let xml = quick_xml::se::to_string(&rels).unwrap();
308        let parsed: Relationships = quick_xml::de::from_str(&xml).unwrap();
309        assert!(parsed.relationships.is_empty());
310    }
311}
sheetkit_xml/relationships.rs

sheetkit_xml/
relationships.rs
