Skip to main content

ferrichess_study/pgn/
mod.rs

1//! PGN document construction and deterministic rendering.
2
3mod writer;
4
5use std::{error::Error, fmt};
6
7use crate::{
8    domain::{RepertoireRole, RepertoireSide},
9    tree::{MergeError, MoveTree, RawTreeBuilder, TreeError},
10};
11
12pub use writer::PgnWriter;
13
14/// A PGN header, retained in insertion order by [`Headers`].
15#[derive(Clone, Debug, Eq, PartialEq)]
16pub struct Header {
17    pub name: String,
18    pub value: String,
19}
20
21/// Ordered PGN headers.
22#[derive(Clone, Debug, Default, Eq, PartialEq)]
23pub struct Headers(Vec<Header>);
24
25impl Headers {
26    #[must_use]
27    pub const fn new() -> Self {
28        Self(Vec::new())
29    }
30
31    pub fn insert(&mut self, name: impl Into<String>, value: impl Into<String>) {
32        let name = name.into();
33        let value = value.into();
34        if let Some(header) = self.0.iter_mut().find(|header| header.name == name) {
35            header.value = value;
36        } else {
37            self.0.push(Header { name, value });
38        }
39    }
40
41    #[must_use]
42    pub fn get(&self, name: &str) -> Option<&str> {
43        self.0
44            .iter()
45            .find(|header| header.name == name)
46            .map(|header| header.value.as_str())
47    }
48
49    pub fn iter(&self) -> impl ExactSizeIterator<Item = &Header> {
50        self.0.iter()
51    }
52
53    #[must_use]
54    pub const fn len(&self) -> usize {
55        self.0.len()
56    }
57
58    #[must_use]
59    pub const fn is_empty(&self) -> bool {
60        self.0.is_empty()
61    }
62}
63
64impl IntoIterator for Headers {
65    type Item = Header;
66    type IntoIter = std::vec::IntoIter<Header>;
67
68    fn into_iter(self) -> Self::IntoIter {
69        self.0.into_iter()
70    }
71}
72
73/// Metadata needed to turn one raw repertoire into a standalone PGN document.
74#[derive(Clone, Debug, Eq, PartialEq)]
75pub struct SingleRawMetadata {
76    pub course_title: String,
77    pub event: String,
78    pub chapter_slug: String,
79    pub index: String,
80    pub repertoire_side: RepertoireSide,
81    pub repertoire_role: RepertoireRole,
82}
83
84/// A PGN boundary representation backed by an owned move tree.
85#[derive(Clone, Debug, Eq, PartialEq)]
86pub struct PgnDocument {
87    headers: Headers,
88    tree: MoveTree,
89    result: String,
90}
91
92impl PgnDocument {
93    pub(crate) fn new(headers: Headers, tree: MoveTree, result: impl Into<String>) -> Self {
94        Self {
95            headers,
96            tree,
97            result: result.into(),
98        }
99    }
100
101    #[must_use]
102    pub const fn headers(&self) -> &Headers {
103        &self.headers
104    }
105
106    #[must_use]
107    pub const fn tree(&self) -> &MoveTree {
108        &self.tree
109    }
110
111    #[must_use]
112    pub fn result(&self) -> &str {
113        &self.result
114    }
115}
116
117/// Converts one raw text value without reading or writing the filesystem.
118pub fn convert_single_raw(
119    text: &str,
120    metadata: &SingleRawMetadata,
121) -> Result<PgnDocument, PgnError> {
122    let built = RawTreeBuilder::new(metadata.repertoire_side).build(text)?;
123    let mut headers = Headers::new();
124    headers.insert("Event", &metadata.event);
125    headers.insert("Site", "?");
126    headers.insert("Date", "????.??.??");
127    headers.insert("Round", &metadata.index);
128    headers.insert("White", &metadata.index);
129    headers.insert("Black", &metadata.course_title);
130    headers.insert("Result", "*");
131    headers.insert("Chapter", title_from_slug(&metadata.chapter_slug));
132    headers.insert(
133        "Orientation",
134        match metadata.repertoire_side {
135            RepertoireSide::White => "White",
136            RepertoireSide::Black => "Black",
137        },
138    );
139    headers.insert(
140        "RepertoireSide",
141        match metadata.repertoire_side {
142            RepertoireSide::White => "White",
143            RepertoireSide::Black => "Black",
144        },
145    );
146    headers.insert(
147        "RepertoireRole",
148        match metadata.repertoire_role {
149            RepertoireRole::Main => "Main",
150            RepertoireRole::Variant => "Variant",
151        },
152    );
153
154    Ok(PgnDocument {
155        headers,
156        tree: built.tree,
157        result: "*".to_owned(),
158    })
159}
160
161fn title_from_slug(slug: &str) -> String {
162    slug.replace('_', "-")
163        .split('-')
164        .filter(|part| !part.is_empty())
165        .map(|part| {
166            let lowercase = part.to_lowercase();
167            let mut characters = lowercase.chars();
168            characters.next().map_or_else(String::new, |first| {
169                first.to_uppercase().chain(characters).collect()
170            })
171        })
172        .collect::<Vec<_>>()
173        .join(" ")
174}
175
176#[derive(Clone, Debug, Eq, PartialEq)]
177pub enum PgnError {
178    Tree(TreeError),
179    Merge(MergeError),
180}
181
182impl fmt::Display for PgnError {
183    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
184        match self {
185            Self::Tree(error) => error.fmt(formatter),
186            Self::Merge(error) => error.fmt(formatter),
187        }
188    }
189}
190
191impl Error for PgnError {
192    fn source(&self) -> Option<&(dyn Error + 'static)> {
193        match self {
194            Self::Tree(error) => Some(error),
195            Self::Merge(error) => Some(error),
196        }
197    }
198}
199
200impl From<TreeError> for PgnError {
201    fn from(error: TreeError) -> Self {
202        Self::Tree(error)
203    }
204}
205
206impl From<MergeError> for PgnError {
207    fn from(error: MergeError) -> Self {
208        Self::Merge(error)
209    }
210}
211
212#[cfg(test)]
213mod tests {
214    use crate::domain::{RepertoireRole, RepertoireSide};
215
216    use super::{Headers, SingleRawMetadata, title_from_slug};
217
218    #[test]
219    fn headers_keep_insertion_order_when_updated() {
220        let mut headers = Headers::new();
221        headers.insert("Event", "First");
222        headers.insert("Site", "Local");
223        headers.insert("Event", "Updated");
224
225        let headers: Vec<_> = headers
226            .iter()
227            .map(|header| (header.name.as_str(), header.value.as_str()))
228            .collect();
229        assert_eq!(headers, [("Event", "Updated"), ("Site", "Local")]);
230    }
231
232    #[test]
233    fn slug_titles_match_the_python_boundary_behavior() {
234        assert_eq!(title_from_slug("white-queen_pawn"), "White Queen Pawn");
235        assert_eq!(title_from_slug("alpha--beta"), "Alpha Beta");
236        assert_eq!(title_from_slug("WHITE-oPEN"), "White Open");
237    }
238
239    #[test]
240    fn metadata_is_owned_for_filesystem_independent_conversion() {
241        let metadata = SingleRawMetadata {
242            course_title: "Course".to_owned(),
243            event: "Chapter".to_owned(),
244            chapter_slug: "white-open".to_owned(),
245            index: "001".to_owned(),
246            repertoire_side: RepertoireSide::White,
247            repertoire_role: RepertoireRole::Main,
248        };
249        assert_eq!(metadata.index, "001");
250    }
251}