Skip to main content

ferrichess_study/raw/
parser.rs

1use shakmaty::{Chess, Move, Position};
2
3use crate::domain::Annotation;
4
5use super::scanner::{match_legal_san, position_ply, read_move_number};
6
7/// A byte span in one source line.
8#[derive(Clone, Copy, Debug, Eq, PartialEq)]
9pub struct SourceSpan {
10    pub start: usize,
11    pub end: usize,
12}
13
14/// One legal move recognized from raw text.
15#[derive(Clone, Debug, Eq, PartialEq)]
16pub struct ParsedMove {
17    pub chess_move: Move,
18    pub annotation: Option<Annotation>,
19    pub span: SourceSpan,
20}
21
22/// Moves parsed from one raw line plus its normalized unparsed tail.
23#[derive(Clone, Debug, Eq, PartialEq)]
24pub struct RawLineParse {
25    pub moves: Vec<ParsedMove>,
26    pub leftover: String,
27}
28
29/// A move found in an explicitly numbered sequence inside prose.
30#[derive(Clone, Debug, Eq, PartialEq)]
31pub struct EmbeddedMove {
32    pub chess_move: Move,
33    pub annotation: Option<Annotation>,
34}
35
36#[derive(Clone, Debug, Default)]
37pub struct RawParser;
38
39impl RawParser {
40    #[must_use]
41    pub const fn new() -> Self {
42        Self
43    }
44
45    #[must_use]
46    pub fn is_move_line(&self, line: &str) -> bool {
47        let trimmed = line.trim_start();
48        let digits = trimmed.bytes().take_while(u8::is_ascii_digit).count();
49        digits > 0 && trimmed[digits..].trim_start().starts_with('.')
50    }
51
52    #[must_use]
53    pub fn starting_ply_for_move_line(&self, line: &str) -> Option<u32> {
54        let offset = line.len() - line.trim_start().len();
55        read_move_number(line, offset).and_then(|number| number.starting_ply)
56    }
57
58    pub(crate) fn has_instructional_null_move(&self, text: &str) -> bool {
59        let mut cursor = 0;
60        while cursor < text.len() {
61            if let Some(number) = read_move_number(text, cursor) {
62                let marker = text[number.end..].trim_start();
63                if marker.starts_with("--") {
64                    return true;
65                }
66                cursor = number.end;
67            } else {
68                cursor += text[cursor..].chars().next().map_or(1, char::len_utf8);
69            }
70        }
71        false
72    }
73
74    /// Returns the ply of the first explicit move number found in text.
75    #[must_use]
76    pub fn first_numbered_ply(&self, text: &str) -> Option<u32> {
77        let text = super::comments::split_glued_move_numbers(text);
78        let mut cursor = 0;
79        while cursor < text.len() {
80            if let Some(number) = read_move_number(&text, cursor)
81                && let Some(ply) = number.starting_ply
82            {
83                return Some(ply);
84            }
85            cursor = next_char_boundary(&text, cursor);
86        }
87        None
88    }
89
90    #[must_use]
91    pub fn parse_move_line(&self, line: &str, position: &Chess) -> RawLineParse {
92        let mut work = position.clone();
93        let mut moves = Vec::new();
94        let mut pos = 0;
95
96        while pos < line.len() {
97            if let Some(number) = read_move_number(line, pos) {
98                pos = number.end;
99                continue;
100            }
101            if line.as_bytes()[pos].is_ascii_whitespace() {
102                pos += 1;
103                continue;
104            }
105            if result_token_at(line, pos) {
106                pos = line.len();
107                break;
108            }
109            let Some(found) = match_legal_san(line, pos, &work) else {
110                break;
111            };
112            let start = pos;
113            pos = found.end;
114            work.play_unchecked(found.chess_move);
115            moves.push(ParsedMove {
116                chess_move: found.chess_move,
117                annotation: found.annotation,
118                span: SourceSpan { start, end: pos },
119            });
120        }
121
122        RawLineParse {
123            moves,
124            leftover: collapse_whitespace(
125                super::comments::split_glued_move_numbers(&line[pos..]).trim(),
126            ),
127        }
128    }
129
130    #[must_use]
131    pub fn parse_embedded_move_sequences(&self, text: &str, position: &Chess) -> Vec<EmbeddedMove> {
132        let text = super::comments::split_glued_move_numbers(text);
133        let mut work = position.clone();
134        let mut moves = Vec::new();
135        let mut cursor = 0;
136        while cursor < text.len() {
137            if read_move_number(&text, cursor).is_none() {
138                cursor = next_char_boundary(&text, cursor);
139                continue;
140            }
141            let (parsed, end) = parse_embedded_sequence(&text, cursor, &work);
142            if parsed.is_empty() {
143                cursor = next_char_boundary(&text, cursor);
144                continue;
145            }
146            for item in parsed {
147                work.play_unchecked(item.chess_move);
148                moves.push(item);
149            }
150            cursor = end;
151        }
152        moves
153    }
154
155    #[must_use]
156    pub fn normalize_comment_text(
157        &self,
158        text: &str,
159        position: Option<&Chess>,
160        positions_by_ply: Option<&[Chess]>,
161    ) -> String {
162        super::comments::normalize(self, text, position, positions_by_ply)
163    }
164
165    pub(crate) fn format_move_sequence(&self, position: &Chess, moves: &[EmbeddedMove]) -> String {
166        use shakmaty::san::SanPlus;
167
168        let mut work = position.clone();
169        let mut parts: Vec<String> = Vec::new();
170        for item in moves {
171            let mut san = SanPlus::from_move(work.clone(), item.chess_move).to_string();
172            if let Some(annotation) = item.annotation {
173                if annotation.evaluation_nag().is_some() {
174                    san.push(' ');
175                }
176                san.push_str(annotation.ascii_suffix());
177            }
178            let fullmove = work.fullmoves().get();
179            if work.turn().is_white() {
180                parts.push(format!("{fullmove}. {san}"));
181            } else if parts
182                .last()
183                .is_some_and(|part| part.starts_with(&format!("{fullmove}. ")))
184            {
185                parts.last_mut().expect("checked above").push(' ');
186                parts.last_mut().expect("checked above").push_str(&san);
187            } else {
188                parts.push(format!("{fullmove}... {san}"));
189            }
190            work.play_unchecked(item.chess_move);
191        }
192        parts.join(" ")
193    }
194}
195
196pub(crate) fn parse_embedded_sequence(
197    text: &str,
198    pos: usize,
199    position: &Chess,
200) -> (Vec<EmbeddedMove>, usize) {
201    let mut work = position.clone();
202    let mut moves = Vec::new();
203    let mut cursor = pos;
204    loop {
205        cursor = skip_whitespace(text, cursor);
206        let token_start = cursor;
207        if let Some(number) = read_move_number(text, cursor) {
208            if number
209                .starting_ply
210                .is_some_and(|ply| ply != position_ply(&work))
211            {
212                return (moves, token_start);
213            }
214            cursor = number.end;
215        }
216        cursor = skip_whitespace(text, cursor);
217        let Some(found) = match_legal_san(text, cursor, &work) else {
218            return (moves, token_start);
219        };
220        cursor = found.end;
221        work.play_unchecked(found.chess_move);
222        moves.push(EmbeddedMove {
223            chess_move: found.chess_move,
224            annotation: found.annotation,
225        });
226        if cursor >= text.len() {
227            return (moves, cursor);
228        }
229        if text.as_bytes()[cursor].is_ascii_alphabetic() {
230            continue;
231        }
232        cursor = skip_whitespace(text, cursor);
233    }
234}
235
236fn result_token_at(text: &str, pos: usize) -> bool {
237    ["1-0", "0-1", "1/2-1/2", "*"]
238        .iter()
239        .any(|result| text[pos..].starts_with(result))
240}
241
242pub(crate) fn skip_whitespace(text: &str, mut pos: usize) -> usize {
243    while text
244        .as_bytes()
245        .get(pos)
246        .is_some_and(u8::is_ascii_whitespace)
247    {
248        pos += 1;
249    }
250    pos
251}
252
253fn next_char_boundary(text: &str, pos: usize) -> usize {
254    pos + text[pos..].chars().next().map_or(1, char::len_utf8)
255}
256
257fn collapse_whitespace(text: &str) -> String {
258    text.split_whitespace().collect::<Vec<_>>().join(" ")
259}
260
261#[cfg(test)]
262mod tests {
263    use shakmaty::{Chess, Position, san::San};
264
265    use crate::domain::Annotation;
266
267    use super::RawParser;
268
269    fn position_after(sans: &[&str]) -> Chess {
270        let mut position = Chess::default();
271        for san in sans {
272            let chess_move = San::from_ascii(san.as_bytes())
273                .unwrap()
274                .to_move(&position)
275                .unwrap();
276            position.play_unchecked(chess_move);
277        }
278        position
279    }
280
281    fn positions_after_each(sans: &[&str]) -> Vec<Chess> {
282        let mut positions = vec![Chess::default()];
283        for san in sans {
284            let mut position = positions.last().unwrap().clone();
285            let chess_move = San::from_ascii(san.as_bytes())
286                .unwrap()
287                .to_move(&position)
288                .unwrap();
289            position.play_unchecked(chess_move);
290            positions.push(position);
291        }
292        positions
293    }
294
295    fn rendered_sans(position: &Chess, parsed: &super::RawLineParse) -> Vec<String> {
296        use shakmaty::san::SanPlus;
297
298        let mut work = position.clone();
299        parsed
300            .moves
301            .iter()
302            .map(|item| {
303                let san = SanPlus::from_move(work.clone(), item.chess_move).to_string();
304                work.play_unchecked(item.chess_move);
305                san
306            })
307            .collect()
308    }
309
310    #[test]
311    fn recognizes_move_lines_and_starting_ply() {
312        let parser = RawParser::new();
313        assert!(parser.is_move_line("  12...Nf6"));
314        assert_eq!(parser.starting_ply_for_move_line("  12...Nf6"), Some(23));
315        assert_eq!(parser.starting_ply_for_move_line("12. Nf3"), Some(22));
316        assert!(!parser.is_move_line("after 12.Nf3"));
317    }
318
319    #[test]
320    fn parses_glued_moves_without_mutating_position() {
321        let parser = RawParser::new();
322        let position = Chess::default();
323        let parsed = parser.parse_move_line("1. e4c62. d4d53. Nc3", &position);
324        assert_eq!(
325            rendered_sans(&position, &parsed),
326            ["e4", "c6", "d4", "d5", "Nc3"]
327        );
328        assert_eq!(parsed.moves[0].span, super::SourceSpan { start: 3, end: 5 });
329        assert_eq!(parsed.moves[1].span, super::SourceSpan { start: 5, end: 7 });
330        assert!(parsed.leftover.is_empty());
331        assert_eq!(position, Chess::default());
332    }
333
334    #[test]
335    fn retains_the_normalized_unparseable_tail() {
336        let parser = RawParser::new();
337        let position = position_after(&["e4", "e5", "Nf3", "Nc6", "d4", "exd4", "Nxd4"]);
338        let parsed = parser.parse_move_line("4...Nf6 foo bar baz5.Nc3Bb46.Nxc6", &position);
339        assert_eq!(rendered_sans(&position, &parsed), ["Nf6"]);
340        assert_eq!(parsed.leftover, "foo bar baz5.Nc3Bb4 6.Nxc6");
341    }
342
343    #[test]
344    fn parses_castling_checks_and_typed_annotations() {
345        let parser = RawParser::new();
346        let castle_position = position_after(&["e4", "e5", "Nf3", "Nc6", "Bc4", "Bc5"]);
347        let parsed = parser.parse_move_line("4. 0-0 Nf6 5. Re1?!", &castle_position);
348        assert_eq!(
349            rendered_sans(&castle_position, &parsed),
350            ["O-O", "Nf6", "Re1"]
351        );
352        assert_eq!(parsed.moves[2].annotation, Some(Annotation::Dubious));
353
354        let mate_position = position_after(&["e4", "e5", "Qh5", "Nc6", "Bc4", "Nf6"]);
355        let parsed = parser.parse_move_line("4. Qxf7#?!", &mate_position);
356        assert_eq!(rendered_sans(&mate_position, &parsed), ["Qxf7#"]);
357        assert_eq!(parsed.moves[0].annotation, Some(Annotation::Dubious));
358    }
359
360    #[test]
361    fn evaluation_suffixes_do_not_desynchronize_the_mainline() {
362        let parser = RawParser::new();
363        let position = Chess::default();
364        let parsed = parser.parse_move_line(
365            "1.e4c52.Nf3g63.c3d54.exd5Qxd55.d4Bg76.Na3cxd47.Bc4Qe4+\
366             8.Be3Nh69.Nb5O-O⇆10.cxd4Nf511.Nc7",
367            &position,
368        );
369
370        assert!(parsed.leftover.is_empty());
371        assert_eq!(parsed.moves.len(), 21);
372        assert_eq!(parsed.moves[17].annotation, Some(Annotation::Counterplay));
373        assert_eq!(
374            rendered_sans(&position, &parsed)[18..],
375            ["cxd4", "Nf5", "Nc7"]
376        );
377    }
378
379    #[test]
380    fn ignores_result_tokens_and_everything_after_them() {
381        let parsed = RawParser::new().parse_move_line("1. e4 e5 1-0 ignored", &Chess::default());
382        assert_eq!(rendered_sans(&Chess::default(), &parsed), ["e4", "e5"]);
383        assert!(parsed.leftover.is_empty());
384    }
385
386    #[test]
387    fn normalizes_comments_without_position_context() {
388        let parser = RawParser::new();
389        let cases = [
390            (
391                "foo bar5.Nf3 baz, when5...Nc66.Nc3a6 quux. lorem ipsum dolor sit amet.",
392                "foo bar 5. Nf3 baz, when 5... Nc6 6. Nc3 a6 quux. lorem ipsum dolor sit amet.",
393            ),
394            ("foo 4. bar baz/018.baz.", "foo 4. bar baz/018.baz."),
395            (
396                "alpha12.Ng5 beta12...Nxc3.",
397                "alpha 12. Ng5 beta 12... Nxc3.",
398            ),
399            ("try6...Ngf67.O-OBg7", "try 6... Ngf6 7. O-O Bg7"),
400            ("after17.Bf4 or17.Bc1", "after 17. Bf4 or 17. Bc1"),
401            (
402                "prioritize playing ...c5 before ...e6.",
403                "prioritize playing ...c5 before ...e6.",
404            ),
405            ("foo ...a6-b5 ... Qc7.", "foo ...a6-b5 ...Qc7."),
406            (
407                "after16.Nxc5?gxh5 and 8.Be2?dxc4",
408                "after 16. Nxc5? gxh5 and 8. Be2? dxc4",
409            ),
410            ("foo bar baz 0.00.", "foo bar baz 0.00."),
411            ("foo bar 1. e4 2.0 baz.", "foo bar 1. e4 2.0 baz."),
412        ];
413        for (raw, expected) in cases {
414            assert_eq!(
415                parser.normalize_comment_text(raw, None, None),
416                expected,
417                "{raw}"
418            );
419        }
420    }
421
422    #[test]
423    fn formats_legal_embedded_sequences_conservatively() {
424        let parser = RawParser::new();
425        let position = position_after(&["e4", "e5", "Nf3", "Nc6", "d4", "exd4", "Nxd4", "Nf6"]);
426        assert_eq!(
427            parser.normalize_comment_text("alpha5.Nc3Bb46.Nxc6 beta", Some(&position), None),
428            "alpha 5. Nc3 Bb4 6. Nxc6 beta"
429        );
430        assert_eq!(
431            parser.normalize_comment_text("alpha beta 4.Nxe4 gamma.", Some(&position), None),
432            "alpha beta 4. Nxe4 gamma."
433        );
434    }
435
436    #[test]
437    fn preserves_annotations_in_embedded_sequences() {
438        let parser = RawParser::new();
439        let position = position_after(&[
440            "c4", "e6", "Nf3", "d5", "g3", "Nf6", "Bg2", "dxc4", "Qa4+", "Bd7", "Qxc4", "c5", "d4",
441            "Nc6",
442        ]);
443        assert_eq!(
444            parser.normalize_comment_text("after8.O-Ocxd4!", Some(&position), None),
445            "after 8. O-O cxd4!"
446        );
447    }
448
449    #[test]
450    fn separates_and_ascii_normalizes_evaluations_in_comment_sequences() {
451        let parser = RawParser::new();
452        assert_eq!(
453            parser.normalize_comment_text("after1.f3e52.g4Qh4# +–", Some(&Chess::default()), None,),
454            "after 1. f3 e5 2. g4 Qh4# +-"
455        );
456    }
457
458    #[test]
459    fn canonicalizes_redundant_check_and_mate_suffixes() {
460        let parser = RawParser::new();
461        assert_eq!(
462            parser.normalize_comment_text("after1.f3e52.g4Qh4+#", Some(&Chess::default()), None),
463            "after 1. f3 e5 2. g4 Qh4#"
464        );
465    }
466
467    #[test]
468    fn preserves_spacing_after_check_sequences() {
469        let parser = RawParser::new();
470        let position = position_after(&[
471            "d4", "d5", "c4", "e6", "Nf3", "Nf6", "g3", "dxc4", "Bg2", "c5", "O-O", "Nc6", "Qa4",
472            "Bd7", "Qxc4", "cxd4", "Nxd4", "Rc8",
473        ]);
474        assert_eq!(
475            parser.normalize_comment_text("foo10.Nxc6Bxc611.Bxc6+Rxc6 bar", Some(&position), None,),
476            "foo 10. Nxc6 Bxc6 11. Bxc6+ Rxc6 bar"
477        );
478    }
479
480    #[test]
481    fn uses_numbered_backtrack_context_for_comment_sequences() {
482        let parser = RawParser::new();
483        let positions = positions_after_each(&["e4", "c6", "Nc3", "d5", "Qf3"]);
484        assert_eq!(
485            parser.normalize_comment_text(
486                "alpha 3.Qe2. beta after3...dxe44.Nxe4Nd7??5.Nd6#.",
487                positions.last(),
488                Some(&positions),
489            ),
490            "alpha 3. Qe2. beta after 3... dxe4 4. Nxe4 Nd7?? 5. Nd6#."
491        );
492    }
493
494    #[test]
495    fn does_not_split_queenside_castling() {
496        let parser = RawParser::new();
497        let position = position_after(&[
498            "e4", "e5", "Nf3", "Nc6", "d4", "exd4", "Nxd4", "Bc5", "Nb3", "Bb6", "Nc3", "Nf6",
499            "Bd3", "O-O",
500        ]);
501        assert_eq!(
502            parser.normalize_comment_text(
503                "foo 7.Qe2 bar with7...O-O8.Be3d59.O-O-Od4.",
504                Some(&position),
505                None,
506            ),
507            "foo 7. Qe2 bar with 7... O-O 8. Be3 d5 9. O-O-O d4."
508        );
509    }
510
511    #[test]
512    fn advances_context_across_prose_and_respects_conflicting_numbers() {
513        let parser = RawParser::new();
514        let position = position_after(&[
515            "f4", "d5", "Nf3", "Nf6", "e3", "c5", "b3", "Nc6", "Bb5", "Bd7", "Bb2", "e6", "O-O",
516            "Bd6",
517        ]);
518        assert_eq!(
519            parser.normalize_comment_text(
520                "foo bar:8.Bxc6Bxc69.Ne5Rc8 baz quux lorem10.d3O-O11.Nd2 ipsum11...Be8!",
521                Some(&position),
522                None,
523            ),
524            "foo bar: 8. Bxc6 Bxc6 9. Ne5 Rc8 baz quux lorem 10. d3 O-O 11. Nd2 ipsum 11... Be8!"
525        );
526
527        let conflict_position = position_after(&[
528            "e4", "e5", "Nf3", "Nc6", "Bc4", "Nf6", "Ng5", "d5", "exd5", "Na5", "Bb5+", "c6",
529            "dxc6", "bxc6", "Ba4", "h6", "Nf3", "e4", "Qe2", "Be6",
530        ]);
531        assert_eq!(
532            parser.normalize_comment_text(
533                "foo after12.Bxc6+Nxc613.Nxc6 and13...Qc5 bar14.Nxe7",
534                Some(&conflict_position),
535                None,
536            ),
537            "foo after 12. Bxc6+ Nxc6 13. Nxc6 and 13... Qc5 bar 14. Nxe7"
538        );
539    }
540
541    #[test]
542    fn preserves_unicode_prose_while_normalizing_moves() {
543        assert_eq!(
544            RawParser::new().normalize_comment_text("idé:1.e4e5 — fortsätt", None, None),
545            "idé: 1. e4 e5 — fortsätt"
546        );
547    }
548}