Skip to main content

louis/
parser.rs

1//! A parser for [liblouis](https://liblouis.io) braille tables
2
3use std::{
4    collections::{HashMap, HashSet},
5    ffi::OsStr,
6    fs::read_to_string,
7    io,
8    iter::Peekable,
9    num::ParseIntError,
10    path::{Path, PathBuf},
11    str::{Chars, SplitAsciiWhitespace},
12};
13
14use enumset::enum_set;
15use enumset::{EnumSet, EnumSetType};
16
17use search_path::SearchPath;
18
19use crate::hyphenation::{self, HyphenationTable};
20
21pub use attribute::Attribute;
22pub use braille::{BrailleChar, BrailleChars};
23pub use character_class::{CharacterClass, CharacterClasses};
24pub use match_rule::{Pattern, Patterns, Side};
25pub use multipass::action::ActionInstruction;
26pub use multipass::test::{Quantifier, TestInstruction};
27pub use multipass::{Action, Test};
28
29mod attribute;
30mod braille;
31mod character_class;
32// pub(crate) so that the match pattern tests can build patterns with its `PatternParser`
33pub(crate) mod match_rule;
34pub mod multipass;
35
36/// A restriction that applies to a [`Rule`].
37///
38/// Rules can have optional restrictions, for example they could only
39/// apply in forward translation.
40#[derive(EnumSetType, Debug)]
41pub enum Constraint {
42    /// Not applied when translating text to braille
43    Nofor,
44    /// Not applied when translating braille to text
45    Noback,
46    /// Not applied when the translation crosses a sylable boundary
47    Nocross,
48}
49
50impl std::fmt::Display for Constraint {
51    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
52        match self {
53            Constraint::Nofor => write!(f, "nofor"),
54            Constraint::Noback => write!(f, "noback"),
55            Constraint::Nocross => write!(f, "nocross"),
56        }
57    }
58}
59
60/// A set of [`Constraint`]s.
61///
62/// A tiny facade around an [`EnumSet`] of [`Constraint`].
63#[derive(Debug, PartialEq, Clone, Copy)]
64pub struct Constraints(EnumSet<Constraint>);
65
66impl Constraints {
67    fn contains(&self, value: Constraint) -> bool {
68        self.0.contains(value)
69    }
70
71    fn is_subset(&self, other: Self) -> bool {
72        self.0.is_subset(other.0)
73    }
74
75    fn difference(&self, other: Self) -> Self {
76        Constraints(self.0.difference(other.0))
77    }
78
79    fn empty() -> Self {
80        Constraints(EnumSet::empty())
81    }
82
83    fn insert(&mut self, value: Constraint) -> bool {
84        self.0.insert(value)
85    }
86}
87
88/// Creates a [`Constraints`] facade wrapper around an [`EnumSet`].
89///
90/// This is a convenience macro that wraps the [`enum_set!`] macro
91/// to create constraint sets more concisely.
92macro_rules! constraint_set {
93    ($($args:tt)*) => {
94        Constraints(enum_set!($($args)*))
95    };
96}
97
98impl std::fmt::Display for Constraints {
99    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
100        if self.0.is_empty() {
101            write!(f, "")
102        } else {
103            let constraints: Vec<String> = self.0.iter().map(|c| c.to_string()).collect();
104            write!(f, "{}", constraints.join(" "))
105        }
106    }
107}
108
109/// A set of [`Constraints`](Constraint) that contains both directions
110const ANY_DIRECTION: Constraints = constraint_set!(Constraint::Nofor | Constraint::Noback);
111
112/// Which way a translation goes: from text to braille, or from braille back to text.
113///
114/// A [`Translator`](crate::Translator) translates in one direction. A table's rules apply in
115/// both unless they are restricted with `nofor` or `noback`.
116// no_ops: no `|` that would return an `EnumSet` and put enumset in the API
117#[derive(EnumSetType, Debug, Default, Hash)]
118#[enumset(no_ops)]
119pub enum Direction {
120    /// From text to braille
121    #[default]
122    Forward,
123    /// From braille to text
124    Backward,
125}
126
127#[derive(PartialEq, Debug, Clone)]
128pub enum WithClass {
129    Before { class: String },
130    After { class: String },
131}
132
133type WithClasses = Vec<WithClass>;
134
135#[derive(Debug, Hash, PartialEq, Eq, Clone)]
136pub enum WithMatch {
137    Before,
138    After,
139}
140
141type WithMatches = HashSet<WithMatch>;
142
143/// An error that occurred during parsing of a [liblouis](https://liblouis.io) braille table
144#[derive(thiserror::Error, Debug, PartialEq)]
145pub enum ParseError {
146    #[error("expected {expected:?}, got {found:?}")]
147    TokenExpected {
148        expected: String,
149        found: Option<String>,
150    },
151    #[error("invalid braille")]
152    InvalidBraille(#[from] braille::ParseError),
153    #[error("braille expected")]
154    DotsExpected,
155    #[error("comma separated tuple of Braille expected")]
156    DotsTupleExpected,
157    #[error("same number of replacements in swap opcode expected ({0} vs {1})")]
158    SameNumberOfSwapReplacementsExpected(usize, usize),
159    #[error("{found:?} is a multi-cell dot pattern, but only single cells are allowed here")]
160    SingleCellDotsExpected { found: String },
161    #[error("invalid unicode literal {found:?}")]
162    InvalidUnicodeLiteral { found: Option<String> },
163    #[error("invalid number")]
164    InvalidNumber(#[from] ParseIntError),
165    #[error("invalid escape sequence {0:?}")]
166    InvalidEscape(Option<char>),
167    #[error("names can only contain a-z and A-Z, got {name:?}")]
168    InvalidName { name: String },
169    #[error("constraints '{constraints:?}' not allowed for opcode {opcode:?}")]
170    InvalidConstraints {
171        constraints: Constraints,
172        opcode: Opcode,
173    },
174    #[error("expected classname, got {found:?}")]
175    ClassNameExpected { found: Option<String> },
176    #[error("opcode expected, got {found:?}")]
177    OpcodeExpected { found: Option<String> },
178    #[error("name expected")]
179    NameExpected,
180    #[error("characters expected")]
181    CharsExpected,
182    #[error("filename expected")]
183    FilenameExpected,
184    #[error("number expected, got {found:?}")]
185    NumberExpected { found: Option<String> },
186    #[error("multipass test expected")]
187    MultipassTestExpected,
188    #[error("multipass action expected")]
189    MultipassActionExpected,
190    #[error("invalid multipass operand: {0}")]
191    InvalidMultipassOperand(#[from] multipass::ParseError),
192    #[error("invalid match pattern: {0}")]
193    InvalidMatchPattern(#[from] match_rule::ParseError),
194    #[error("match pre-pattern expected")]
195    MatchPreExpected,
196    #[error("match post-pattern expected")]
197    MatchPostExpected,
198    #[error("expected a single char, got {found:?}")]
199    SingleCharExpected { found: Option<String> },
200}
201
202/// A translation command
203#[derive(PartialEq, Debug)]
204pub enum Opcode {
205    Include,
206    Undefined,
207    Display,
208    Multind,
209
210    // Character-Definition Opcodes
211    Space,
212    Punctuation,
213    Digit,
214    Grouping,
215    Letter,
216    Base,
217    Lowercase,
218    Uppercase,
219    Litdigit,
220    Sign,
221    Math,
222
223    // Braille Indicator Opcodes
224    Modeletter,
225    Capsletter,
226    Begmodeword,
227    Endmodeword,
228    Begcapsword,
229    Endcapsword,
230    Capsmodechars,
231    Begmode,
232    Endmode,
233    Begcaps,
234    Endcaps,
235    Begcapsphrase,
236    Endcapsphrase,
237    Lencapsphrase,
238    Letsign,
239    Noletsign,
240    Noletsignbefore,
241    Noletsignafter,
242    Nocontractsign,
243    Numsign,
244    Nonumsign,
245    Numericnocontchars,
246    Numericmodechars,
247    Midendnumericmodechars,
248
249    Begmodephrase,
250    Endmodephrase,
251    Lenmodephrase,
252
253    // Opcodes for Standing Alone Sequences
254    Seqdelimiter,
255    Seqbeforechars,
256    Seqafterchars,
257    Seqafterpattern,
258    Seqafterexpression,
259
260    // Emphasis Opcodes
261    Class,
262    Emphclass,
263    Begemph,
264    Endemph,
265    Noemphchars,
266    Emphletter,
267    Begemphword,
268    Endemphword,
269    Emphmodechars,
270    Begemphphrase,
271    Endemphphrase,
272    Lenemphphrase,
273
274    // Special Symbol Opcodes
275    Decpoint,
276    Hyphen,
277
278    // Special Processing Opcodes
279    Capsnocont,
280
281    // Translation Opcodes
282    Compbrl,
283    Comp6,
284    Nocont,
285    Replace,
286    Always,
287    Repeated,
288    Repword,
289    Rependword,
290    Largesign,
291    Word,
292    Syllable,
293    Joinword,
294    Lowword,
295    Contraction,
296    Sufword,
297    Prfword,
298    Begword,
299    Begmidword,
300    Midword,
301    Midendword,
302    Endword,
303    Partword,
304    Exactdots,
305    Prepunc,
306    Postpunc,
307    Begnum,
308    Midnum,
309    Endnum,
310    Joinnum,
311
312    // Computer braille
313    Begcomp,
314    Endcomp,
315
316    // Character-Class Opcodes
317    Attribute,
318
319    // Swap Opcodes
320    Swapcd,
321    Swapdd,
322    Swapcc,
323
324    // Context and Multipass Opcodes
325    Context,
326    Pass2,
327    Pass3,
328    Pass4,
329
330    // The correct Opcode
331    Correct,
332
333    // The match Opcode
334    Match,
335    Literal,
336}
337
338/// A translation rule
339///
340/// A translation rule is often composed of three parts: the translation command ([`Opcode`]), the
341/// character(s) and the corresponding braille dots ([`BrailleChars`]).
342#[derive(PartialEq, Debug, Clone)]
343pub enum Rule {
344    Include {
345        file: String,
346    },
347    /// A rule carrying an included hyphenation table.
348    ///
349    /// There is no specific opcode for this but we make this an extra rule to separate the
350    /// inclusion of braille tables vs hyphenation pattern. Like every other `include`, the
351    /// included content is embedded here during expansion rather than left as a path to be
352    /// read later, so an expanded rule list does not depend on the filesystem it was parsed
353    /// on.
354    // FIXME: The `.dic` is parsed here, during expansion, rather than each pattern line
355    // becoming a rule of its own for the compiler to assemble. That split would be the tidier
356    // one, but for some tables this would blow up the rule count enormously. The pipeline
357    // clones and re-filters the whole rule list per direction. If we ever get table bundling
358    // (#10) this might have to be reconsidered, as this couples the bundle format to
359    // `HyphenationTable`'s field layout.
360    IncludeHyphenation {
361        table: HyphenationTable,
362    },
363    Undefined {
364        dots: BrailleChars,
365    },
366    Display {
367        character: char,
368        dots: BrailleChar,
369        constraints: Constraints,
370    },
371    Multind {
372        dots: BrailleChars,
373        names: Vec<String>,
374        constraints: Constraints,
375    },
376
377    Space {
378        character: char,
379        dots: BrailleChars,
380        constraints: Constraints,
381    },
382    Punctuation {
383        character: char,
384        dots: BrailleChars,
385        constraints: Constraints,
386    },
387    Digit {
388        character: char,
389        dots: BrailleChars,
390        constraints: Constraints,
391    },
392    Grouping {
393        name: String,
394        chars: String,
395        left: BrailleChar,
396        right: BrailleChar,
397    },
398    Letter {
399        character: char,
400        dots: BrailleChars,
401        constraints: Constraints,
402    },
403    Base {
404        name: String,
405        derived: char,
406        base: char,
407    },
408    Lowercase {
409        character: char,
410        dots: BrailleChars,
411        constraints: Constraints,
412    },
413    Uppercase {
414        character: char,
415        dots: BrailleChars,
416        constraints: Constraints,
417    },
418    Litdigit {
419        character: char,
420        dots: BrailleChars,
421        constraints: Constraints,
422    },
423    Sign {
424        character: char,
425        dots: BrailleChars,
426        constraints: Constraints,
427    },
428    Math {
429        character: char,
430        dots: BrailleChars,
431        constraints: Constraints,
432    },
433
434    Modeletter {
435        name: String,
436        dots: BrailleChars,
437        constraints: Constraints,
438    },
439    Capsletter {
440        dots: BrailleChars,
441        constraints: Constraints,
442    },
443    Begmodeword {
444        name: String,
445        dots: BrailleChars,
446        constraints: Constraints,
447    },
448    Endmodeword {
449        name: String,
450        dots: BrailleChars,
451        constraints: Constraints,
452    },
453    Begcapsword {
454        dots: BrailleChars,
455        constraints: Constraints,
456    },
457    Endcapsword {
458        dots: BrailleChars,
459        constraints: Constraints,
460    },
461    Capsmodechars {
462        chars: String,
463    },
464    Begmode {
465        name: String,
466        dots: BrailleChars,
467    },
468    Endmode {
469        name: String,
470        dots: BrailleChars,
471    },
472    Begcaps {
473        dots: BrailleChars,
474    },
475    Endcaps {
476        dots: BrailleChars,
477    },
478    Begcapsphrase {
479        dots: BrailleChars,
480    },
481    Endcapsphrase {
482        dots: BrailleChars,
483        position: Position,
484    },
485    Lencapsphrase {
486        number: i32,
487    },
488    Letsign {
489        dots: BrailleChars,
490    },
491    Noletsign {
492        chars: String,
493    },
494    Noletsignbefore {
495        chars: String,
496    },
497    Noletsignafter {
498        chars: String,
499    },
500    Nocontractsign {
501        dots: BrailleChars,
502        constraints: Constraints,
503    },
504    Numsign {
505        dots: BrailleChars,
506    },
507    Nonumsign {
508        dots: BrailleChars,
509        constraints: Constraints,
510    },
511    Numericnocontchars {
512        chars: String,
513    },
514    Numericmodechars {
515        chars: String,
516    },
517    Midendnumericmodechars {
518        chars: String,
519    },
520
521    Begmodephrase {
522        name: String,
523        dots: BrailleChars,
524    },
525    Endmodephrase {
526        name: String,
527        dots: BrailleChars,
528        position: Position,
529    },
530    Lenmodephrase {
531        name: String,
532        number: i32,
533    },
534
535    Seqdelimiter {
536        chars: String,
537    },
538    Seqbeforechars {
539        chars: String,
540    },
541    Seqafterchars {
542        chars: String,
543    },
544    Seqafterpattern {
545        chars: String,
546    },
547    Seqafterexpression {
548        chars: String,
549    },
550
551    Class {
552        name: String,
553        chars: String,
554    },
555    Emphclass {
556        name: String,
557    },
558    Begemph {
559        name: String,
560        dots: BrailleChars,
561        constraints: Constraints,
562    },
563    Endemph {
564        name: String,
565        dots: BrailleChars,
566        constraints: Constraints,
567    },
568    Noemphchars {
569        name: String,
570        chars: String,
571    },
572    Emphletter {
573        name: String,
574        dots: BrailleChars,
575    },
576    Begemphword {
577        name: String,
578        dots: BrailleChars,
579    },
580    Endemphword {
581        name: String,
582        dots: BrailleChars,
583    },
584    Emphmodechars {
585        name: String,
586        chars: String,
587    },
588    Begemphphrase {
589        name: String,
590        dots: BrailleChars,
591    },
592    Endemphphrase {
593        name: String,
594        dots: BrailleChars,
595        position: Position,
596    },
597    Lenemphphrase {
598        name: String,
599        number: i32,
600    },
601
602    Begcomp {
603        dots: BrailleChars,
604        constraints: Constraints,
605    },
606    Endcomp {
607        dots: BrailleChars,
608        constraints: Constraints,
609    },
610
611    Decpoint {
612        character: char,
613        dots: BrailleChars,
614    },
615    Hyphen {
616        character: char,
617        dots: BrailleChars,
618        constraints: Constraints,
619    },
620
621    Capsnocont {},
622
623    Compbrl {
624        chars: String,
625        constraints: Constraints,
626    },
627    Comp6 {
628        character: char,
629        dots: Braille,
630    },
631    Nocont {
632        chars: String,
633    },
634    Replace {
635        chars: String,
636        replacement: Option<String>,
637    },
638    Always {
639        chars: String,
640        dots: Braille,
641        constraints: Constraints,
642        with_classes: Vec<WithClass>,
643    },
644    Repeated {
645        chars: String,
646        dots: BrailleChars,
647        constraints: Constraints,
648    },
649    // liblouis also allows a separator of several characters, but no table uses one
650    Repword {
651        separator: char,
652        dots: BrailleChars,
653    },
654    Rependword {
655        separator: char,
656        dots: BrailleChars,
657        other: BrailleChars,
658    },
659    Largesign {
660        chars: String,
661        dots: BrailleChars,
662    },
663    Word {
664        chars: String,
665        dots: Braille,
666        constraints: Constraints,
667        with_classes: Vec<WithClass>,
668    },
669    Syllable {
670        chars: String,
671        dots: Braille,
672    },
673    Joinword {
674        chars: String,
675        dots: BrailleChars,
676    },
677    Lowword {
678        chars: String,
679        dots: BrailleChars,
680        constraints: Constraints,
681    },
682    Contraction {
683        chars: String,
684    },
685    Sufword {
686        chars: String,
687        dots: Braille,
688        constraints: Constraints,
689        with_classes: Vec<WithClass>,
690    },
691    Prfword {
692        chars: String,
693        dots: Braille,
694        constraints: Constraints,
695        with_classes: Vec<WithClass>,
696    },
697    Begword {
698        chars: String,
699        dots: Braille,
700        constraints: Constraints,
701        with_classes: Vec<WithClass>,
702    },
703    Begmidword {
704        chars: String,
705        dots: Braille,
706        constraints: Constraints,
707        with_classes: Vec<WithClass>,
708    },
709    Midword {
710        chars: String,
711        dots: Braille,
712        constraints: Constraints,
713        with_classes: Vec<WithClass>,
714    },
715    Midendword {
716        chars: String,
717        dots: Braille,
718        constraints: Constraints,
719        with_classes: Vec<WithClass>,
720    },
721    Endword {
722        chars: String,
723        dots: Braille,
724        constraints: Constraints,
725        with_classes: Vec<WithClass>,
726    },
727    Partword {
728        chars: String,
729        dots: Braille,
730        constraints: Constraints,
731        with_classes: Vec<WithClass>,
732    },
733    Exactdots {
734        chars: String,
735    },
736    Prepunc {
737        chars: String,
738        dots: BrailleChars,
739        constraints: Constraints,
740    },
741    Postpunc {
742        chars: String,
743        dots: BrailleChars,
744        constraints: Constraints,
745    },
746    Begnum {
747        chars: String,
748        dots: BrailleChars,
749        constraints: Constraints,
750    },
751    Midnum {
752        chars: String,
753        dots: BrailleChars,
754        constraints: Constraints,
755    },
756    Endnum {
757        chars: String,
758        dots: Braille,
759        constraints: Constraints,
760    },
761    Joinnum {
762        chars: String,
763        dots: BrailleChars,
764        constraints: Constraints,
765    },
766
767    Swapcd {
768        name: String,
769        chars: String,
770        dots: Vec<BrailleChars>,
771    },
772    Swapdd {
773        name: String,
774        dots: BrailleChars,
775        replacement: Vec<BrailleChars>,
776    },
777    Swapcc {
778        name: String,
779        chars: String,
780        replacement: String,
781    },
782
783    Attribute {
784        name: String,
785        chars: String,
786    },
787    Context {
788        test: multipass::Test,
789        action: Action,
790        constraints: Constraints,
791    },
792    Pass2 {
793        test: multipass::Test,
794        action: Action,
795        constraints: Constraints,
796    },
797    Pass3 {
798        test: multipass::Test,
799        action: Action,
800        constraints: Constraints,
801    },
802    Pass4 {
803        test: multipass::Test,
804        action: Action,
805        constraints: Constraints,
806    },
807    Correct {
808        test: multipass::Test,
809        action: Action,
810        constraints: Constraints,
811    },
812
813    Match {
814        pre: Patterns,
815        chars: String,
816        post: Patterns,
817        dots: Braille,
818        constraints: Constraints,
819        matches: Option<WithMatches>,
820    },
821    Literal {
822        chars: String,
823    },
824}
825
826/// Display a list of braille cell sequences the way a table writes it, separated by
827/// commas
828fn display_braille_chars_list(dots: &[BrailleChars]) -> String {
829    dots.iter()
830        .map(BrailleChars::to_string)
831        .collect::<Vec<_>>()
832        .join(",")
833}
834
835impl std::fmt::Display for Rule {
836    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
837        match self {
838            Rule::Undefined { dots } => write!(f, "undefined {}", dots),
839            Rule::Space {
840                character, dots, ..
841            } => {
842                write!(f, "space {} {}", character, dots)
843            }
844            Rule::Punctuation {
845                character, dots, ..
846            } => {
847                write!(f, "punctuation {} {}", character, dots)
848            }
849            Rule::Digit {
850                character, dots, ..
851            } => {
852                write!(f, "digit {} {}", character, dots)
853            }
854            Rule::Letter {
855                character, dots, ..
856            } => {
857                write!(f, "letter {} {}", character, dots)
858            }
859            Rule::Base {
860                name,
861                derived,
862                base,
863            } => {
864                write!(f, "base {} {} {}", name, derived, base)
865            }
866            Rule::Lowercase {
867                character, dots, ..
868            } => {
869                write!(f, "lowercase {} {}", character, dots)
870            }
871            Rule::Uppercase {
872                character, dots, ..
873            } => {
874                write!(f, "uppercase {} {}", character, dots)
875            }
876            Rule::Litdigit {
877                character, dots, ..
878            } => {
879                write!(f, "litdigit {} {}", character, dots)
880            }
881            Rule::Sign {
882                character, dots, ..
883            } => {
884                write!(f, "sign {} {}", character, dots)
885            }
886            Rule::Math {
887                character, dots, ..
888            } => {
889                write!(f, "math {} {}", character, dots)
890            }
891            Rule::Letsign { dots } => write!(f, "letsign {}", dots),
892            Rule::Noletsign { chars } => write!(f, "noletsign {}", chars),
893            Rule::Nocontractsign { dots, .. } => write!(f, "nocontractsign {}", dots),
894            Rule::Numsign { dots } => write!(f, "numsign {}", dots),
895            Rule::Nonumsign { dots, .. } => write!(f, "nonumsign {}", dots),
896            Rule::Compbrl { chars, .. } => write!(f, "compbrl {}", chars),
897            Rule::Comp6 { character, dots } => write!(f, "comp6 {} {}", character, dots),
898            Rule::Always { chars, dots, .. } => write!(f, "always {} {}", chars, dots),
899            Rule::Largesign { chars, dots } => {
900                write!(f, "largesign {} {}", chars, dots)
901            }
902            Rule::Word { chars, dots, .. } => write!(f, "word {} {}", chars, dots),
903            Rule::Contraction { chars } => write!(f, "contraction {}", chars),
904            Rule::Begword { chars, dots, .. } => write!(f, "begword {} {}", chars, dots),
905            Rule::Begmidword { chars, dots, .. } => write!(f, "begmidword {} {}", chars, dots),
906            Rule::Midword { chars, dots, .. } => write!(f, "midword {} {}", chars, dots),
907            Rule::Midendword { chars, dots, .. } => write!(f, "midendword {} {}", chars, dots),
908            Rule::Endword { chars, dots, .. } => write!(f, "endword {} {}", chars, dots),
909            Rule::Partword { chars, dots, .. } => write!(f, "partword {} {}", chars, dots),
910            Rule::Begnum { chars, dots, .. } => {
911                write!(f, "begnum {} {}", chars, dots)
912            }
913            Rule::Midnum { chars, dots, .. } => {
914                write!(f, "midnum {} {}", chars, dots)
915            }
916            Rule::Endnum { chars, dots, .. } => write!(f, "endnum {} {}", chars, dots),
917            Rule::Modeletter { name, dots, .. } => write!(f, "modeletter {} {}", name, dots),
918            Rule::Capsletter { dots, .. } => write!(f, "capsletter {}", dots),
919            Rule::Begmodeword { name, dots, .. } => write!(f, "begmodeword {} {}", name, dots),
920            Rule::Endmodeword { name, dots, .. } => write!(f, "endmodeword {} {}", name, dots),
921            Rule::Begcapsword { dots, .. } => write!(f, "begcapsword {}", dots),
922            Rule::Endcapsword { dots, .. } => write!(f, "endcapsword {}", dots),
923            Rule::Begmode { name, dots } => write!(f, "begmode {} {}", name, dots),
924            Rule::Endmode { name, dots } => write!(f, "endmode {} {}", name, dots),
925            Rule::Begcaps { dots } => write!(f, "begcaps {}", dots),
926            Rule::Endcaps { dots } => write!(f, "endcaps {}", dots),
927            Rule::Begmodephrase { name, dots } => write!(f, "begmodephrase {} {}", name, dots),
928            Rule::Endmodephrase { name, dots, .. } => {
929                write!(f, "endmodephrase {} {}", name, dots)
930            }
931            Rule::Lenmodephrase { name, number } => {
932                write!(f, "lenmodephrase {} {}", name, number)
933            }
934            Rule::Correct { test, action, .. } => write!(f, "correct {} {}", test, action),
935            Rule::Sufword { chars, dots, .. } => write!(f, "sufword {} {}", chars, dots),
936            Rule::Prfword { chars, dots, .. } => write!(f, "prfword {} {}", chars, dots),
937            Rule::Context { test, action, .. } => write!(f, "context {} {}", test, action),
938            Rule::Pass2 { test, action, .. } => write!(f, "pass2 {} {}", test, action),
939            Rule::Pass3 { test, action, .. } => write!(f, "pass3 {} {}", test, action),
940            Rule::Pass4 { test, action, .. } => write!(f, "pass4 {} {}", test, action),
941            Rule::Attribute { name, chars } => write!(f, "attribute {} {}", name, chars),
942            Rule::Literal { chars } => write!(f, "literal {}", chars),
943            Rule::Prepunc { chars, dots, .. } => write!(f, "prepunc {} {}", chars, dots),
944            Rule::Postpunc { chars, dots, .. } => write!(f, "postpunc {} {}", chars, dots),
945            Rule::Decpoint {
946                character, dots, ..
947            } => write!(f, "decpoint {} {}", character, dots),
948            Rule::Hyphen {
949                character, dots, ..
950            } => write!(f, "hyphen {} {}", character, dots),
951            Rule::Match {
952                pre,
953                chars,
954                post,
955                dots,
956                ..
957            } => write!(f, "match {} {} {} {}", pre, chars, post, dots),
958            Rule::Display {
959                character, dots, ..
960            } => write!(f, "display {} {}", character, dots),
961            Rule::Include { file } => write!(f, "include {}", file),
962            Rule::IncludeHyphenation { .. } => write!(f, "include <hyphenation table>"),
963            Rule::Multind { dots, names, .. } => {
964                write!(f, "multind {} {}", dots, names.join(" "))
965            }
966            Rule::Grouping {
967                name,
968                chars,
969                left,
970                right,
971            } => write!(f, "grouping {} {} {},{}", name, chars, left, right),
972            Rule::Capsmodechars { chars } => write!(f, "capsmodechars {}", chars),
973            Rule::Begcapsphrase { dots } => write!(f, "begcapsphrase {}", dots),
974            Rule::Endcapsphrase { dots, position } => {
975                write!(f, "endcapsphrase {} {}", position, dots)
976            }
977            Rule::Lencapsphrase { number } => write!(f, "lencapsphrase {}", number),
978            Rule::Noletsignbefore { chars } => write!(f, "noletsignbefore {}", chars),
979            Rule::Noletsignafter { chars } => write!(f, "noletsignafter {}", chars),
980            Rule::Numericnocontchars { chars } => write!(f, "numericnocontchars {}", chars),
981            Rule::Numericmodechars { chars } => write!(f, "numericmodechars {}", chars),
982            Rule::Midendnumericmodechars { chars } => {
983                write!(f, "midendnumericmodechars {}", chars)
984            }
985            Rule::Seqdelimiter { chars } => write!(f, "seqdelimiter {}", chars),
986            Rule::Seqbeforechars { chars } => write!(f, "seqbeforechars {}", chars),
987            Rule::Seqafterchars { chars } => write!(f, "seqafterchars {}", chars),
988            Rule::Seqafterpattern { chars } => write!(f, "seqafterpattern {}", chars),
989            Rule::Seqafterexpression { chars } => write!(f, "seqafterexpression {}", chars),
990            Rule::Class { name, chars } => write!(f, "class {} {}", name, chars),
991            Rule::Emphclass { name } => write!(f, "emphclass {}", name),
992            Rule::Begemph { name, dots, .. } => write!(f, "begemph {} {}", name, dots),
993            Rule::Endemph { name, dots, .. } => write!(f, "endemph {} {}", name, dots),
994            Rule::Noemphchars { name, chars } => write!(f, "noemphchars {} {}", name, chars),
995            Rule::Emphletter { name, dots } => write!(f, "emphletter {} {}", name, dots),
996            Rule::Begemphword { name, dots } => write!(f, "begemphword {} {}", name, dots),
997            Rule::Endemphword { name, dots } => write!(f, "endemphword {} {}", name, dots),
998            Rule::Emphmodechars { name, chars } => {
999                write!(f, "emphmodechars {} {}", name, chars)
1000            }
1001            Rule::Begemphphrase { name, dots } => write!(f, "begemphphrase {} {}", name, dots),
1002            Rule::Endemphphrase {
1003                name,
1004                dots,
1005                position,
1006            } => write!(f, "endemphphrase {} {} {}", name, position, dots),
1007            Rule::Lenemphphrase { name, number } => {
1008                write!(f, "lenemphphrase {} {}", name, number)
1009            }
1010            Rule::Begcomp { dots, .. } => write!(f, "begcomp {}", dots),
1011            Rule::Endcomp { dots, .. } => write!(f, "endcomp {}", dots),
1012            Rule::Capsnocont {} => write!(f, "capsnocont"),
1013            Rule::Nocont { chars } => write!(f, "nocont {}", chars),
1014            Rule::Replace { chars, replacement } => match replacement {
1015                Some(r) => write!(f, "replace {} {}", chars, r),
1016                None => write!(f, "replace {}", chars),
1017            },
1018            Rule::Repeated { chars, dots, .. } => write!(f, "repeated {} {}", chars, dots),
1019            Rule::Repword { separator, dots } => write!(f, "repword {} {}", separator, dots),
1020            Rule::Rependword {
1021                separator,
1022                dots,
1023                other,
1024            } => {
1025                write!(f, "rependword {} {},{}", separator, dots, other)
1026            }
1027            Rule::Syllable { chars, dots } => write!(f, "syllable {} {}", chars, dots),
1028            Rule::Joinword { chars, dots } => write!(f, "joinword {} {}", chars, dots),
1029            Rule::Lowword { chars, dots, .. } => write!(f, "lowword {} {}", chars, dots),
1030            Rule::Exactdots { chars } => write!(f, "exactdots {}", chars),
1031            Rule::Joinnum { chars, dots, .. } => write!(f, "joinnum {} {}", chars, dots),
1032            Rule::Swapcd { name, chars, dots } => {
1033                write!(
1034                    f,
1035                    "swapcd {} {} {}",
1036                    name,
1037                    chars,
1038                    display_braille_chars_list(dots)
1039                )
1040            }
1041            Rule::Swapdd {
1042                name,
1043                dots,
1044                replacement,
1045            } => write!(
1046                f,
1047                "swapdd {} {} {}",
1048                name,
1049                dots,
1050                display_braille_chars_list(replacement)
1051            ),
1052            Rule::Swapcc {
1053                name,
1054                chars,
1055                replacement,
1056            } => write!(f, "swapcc {} {} {}", name, chars, replacement),
1057        }
1058    }
1059}
1060
1061/// A trait to query the direction of a [`Rule`].
1062pub trait HasDirection {
1063    /// Returns the set of directions associated with this Rule.
1064    fn directions(&self) -> EnumSet<Direction>;
1065
1066    /// Checks if this Rule has the specified direction.
1067    fn is_direction(&self, direction: Direction) -> bool {
1068        self.directions().contains(direction)
1069    }
1070}
1071
1072impl HasDirection for Rule {
1073    fn directions(&self) -> EnumSet<Direction> {
1074        match self {
1075            Rule::Display { constraints, .. }
1076            | Rule::Multind { constraints, .. }
1077            | Rule::Space { constraints, .. }
1078            | Rule::Punctuation { constraints, .. }
1079            | Rule::Digit { constraints, .. }
1080            | Rule::Letter { constraints, .. }
1081            | Rule::Lowercase { constraints, .. }
1082            | Rule::Uppercase { constraints, .. }
1083            | Rule::Litdigit { constraints, .. }
1084            | Rule::Sign { constraints, .. }
1085            | Rule::Math { constraints, .. }
1086            | Rule::Modeletter { constraints, .. }
1087            | Rule::Capsletter { constraints, .. }
1088            | Rule::Begmodeword { constraints, .. }
1089            | Rule::Endmodeword { constraints, .. }
1090            | Rule::Begcapsword { constraints, .. }
1091            | Rule::Endcapsword { constraints, .. }
1092            | Rule::Begemph { constraints, .. }
1093            | Rule::Endemph { constraints, .. }
1094            | Rule::Begcomp { constraints, .. }
1095            | Rule::Endcomp { constraints, .. }
1096            | Rule::Hyphen { constraints, .. }
1097            | Rule::Compbrl { constraints, .. }
1098            | Rule::Always { constraints, .. }
1099            | Rule::Repeated { constraints, .. }
1100            | Rule::Word { constraints, .. }
1101            | Rule::Lowword { constraints, .. }
1102            | Rule::Sufword { constraints, .. }
1103            | Rule::Prfword { constraints, .. }
1104            | Rule::Begword { constraints, .. }
1105            | Rule::Begmidword { constraints, .. }
1106            | Rule::Midword { constraints, .. }
1107            | Rule::Midendword { constraints, .. }
1108            | Rule::Endword { constraints, .. }
1109            | Rule::Partword { constraints, .. }
1110            | Rule::Prepunc { constraints, .. }
1111            | Rule::Postpunc { constraints, .. }
1112            | Rule::Begnum { constraints, .. }
1113            | Rule::Midnum { constraints, .. }
1114            | Rule::Endnum { constraints, .. }
1115            | Rule::Joinnum { constraints, .. }
1116            | Rule::Context { constraints, .. }
1117            | Rule::Pass2 { constraints, .. }
1118            | Rule::Pass3 { constraints, .. }
1119            | Rule::Pass4 { constraints, .. }
1120            | Rule::Correct { constraints, .. }
1121            | Rule::Match { constraints, .. }
1122            | Rule::Nocontractsign { constraints, .. }
1123            | Rule::Nonumsign { constraints, .. } => {
1124                if constraints.contains(Constraint::Nofor) {
1125                    enum_set!(Direction::Backward)
1126                } else if constraints.contains(Constraint::Noback) {
1127                    enum_set!(Direction::Forward)
1128                } else {
1129                    enum_set!(Direction::Forward | Direction::Backward)
1130                }
1131            }
1132            _ => enum_set!(Direction::Forward | Direction::Backward),
1133        }
1134    }
1135}
1136
1137/// A trait to query whether a [`Rule`] has a nocross contraint.
1138pub trait HasNocross {
1139    /// Returns the set of contraints associated with this Rule.
1140    fn constraints(&self) -> Constraints;
1141
1142    /// Checks if this Rule has the nocross contraint.
1143    fn is_nocross(&self) -> bool {
1144        self.constraints().contains(Constraint::Nocross)
1145    }
1146}
1147
1148impl HasNocross for Rule {
1149    fn constraints(&self) -> Constraints {
1150        match self {
1151            Rule::Always { constraints, .. }
1152            | Rule::Word { constraints, .. }
1153            | Rule::Lowword { constraints, .. }
1154            | Rule::Sufword { constraints, .. }
1155            | Rule::Prfword { constraints, .. }
1156            | Rule::Begword { constraints, .. }
1157            | Rule::Begmidword { constraints, .. }
1158            | Rule::Midword { constraints, .. }
1159            | Rule::Midendword { constraints, .. }
1160            | Rule::Endword { constraints, .. }
1161            | Rule::Partword { constraints, .. }
1162            | Rule::Prepunc { constraints, .. }
1163            | Rule::Postpunc { constraints, .. }
1164            | Rule::Begnum { constraints, .. }
1165            | Rule::Midnum { constraints, .. }
1166            | Rule::Endnum { constraints, .. }
1167            | Rule::Joinnum { constraints, .. } => *constraints,
1168            _ => constraint_set!(),
1169        }
1170    }
1171}
1172
1173/// Precedence levels for [`Rules`](Rule): when two rules match the same input and nothing
1174/// else separates them, the higher one wins, see [`Rank`](crate::translator::translation::Rank).
1175#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
1176pub enum Precedence {
1177    /// `letter`, `punctuation`, `digit`, ..., plus `litdigit`, `base` and `hyphen`: only
1178    /// the fallback when no other rule matches, which liblouis expresses by putting them
1179    /// at the end of its rule chains.
1180    CharacterDefinition,
1181    /// Backward-only emphasis indicators (`begemphword`, `endemphphrase`, ...). Any other
1182    /// rule with the same dots wins over them, as `endcapsword 6-3` does over
1183    /// `endemphword italic 6-3` in `fr-bfu-comp6.utb`.
1184    Emphasis,
1185    /// Backward-only indicator opcodes (`capsletter`, `numsign`, ...). Above the
1186    /// character definitions, whose dots they can coincide with in some tables, but below
1187    /// `always`: a same-dots `always` rule is a more specific language rule that must
1188    /// still win.
1189    Indicator,
1190    /// `always`: liblouis puts it after the other translation rules of the same length, but
1191    /// only in its multi-character chains, so [`Rank`](crate::translator::translation::Rank) treats a
1192    /// one-character `always` match as [`Precedence::Translation`].
1193    Always,
1194    /// Every other rule: the word family, `match`, `context`, the passes, ...
1195    Translation,
1196}
1197
1198/// A trait to query the precedence of a [`Rule`].
1199pub trait HasPrecedence {
1200    /// Returns the precedence level of this Rule.
1201    fn precedence(&self) -> Precedence;
1202}
1203
1204impl HasPrecedence for Rule {
1205    fn precedence(&self) -> Precedence {
1206        match self {
1207            Rule::Space { .. }
1208            | Rule::Digit { .. }
1209            | Rule::Punctuation { .. }
1210            | Rule::Math { .. }
1211            | Rule::Sign { .. }
1212            | Rule::Letter { .. }
1213            | Rule::Uppercase { .. }
1214            | Rule::Lowercase { .. }
1215            | Rule::Grouping { .. }
1216            // outside liblouis' character definition opcodes, but they define a character too:
1217            // `base` a derived one, `hyphen` one that can break a word. `litdigit` must also
1218            // not beat a `lowercase` with the same dots backward, it only applies in a number
1219            | Rule::Litdigit { .. }
1220            | Rule::Base { .. }
1221            | Rule::Hyphen { .. } => Precedence::CharacterDefinition,
1222            Rule::Capsletter { .. }
1223            | Rule::Begcapsword { .. }
1224            | Rule::Endcapsword { .. }
1225            | Rule::Numsign { .. }
1226            | Rule::Nonumsign { .. } => Precedence::Indicator,
1227            Rule::Begemph { .. }
1228            | Rule::Endemph { .. }
1229            | Rule::Emphletter { .. }
1230            | Rule::Begemphword { .. }
1231            | Rule::Endemphword { .. }
1232            | Rule::Begemphphrase { .. }
1233            | Rule::Endemphphrase { .. } => Precedence::Emphasis,
1234            Rule::Always { .. } => Precedence::Always,
1235            _ => Precedence::Translation,
1236        }
1237    }
1238}
1239
1240impl Rule {
1241    /// How many characters of a pass or `correct` test are spelled out literally rather than
1242    /// given by a class, see [`Test::literal_count`](multipass::Test::literal_count); 0 for
1243    /// every other rule.
1244    pub fn literal_count(&self) -> usize {
1245        match self {
1246            Rule::Correct { test, .. }
1247            | Rule::Pass2 { test, .. }
1248            | Rule::Pass3 { test, .. }
1249            | Rule::Pass4 { test, .. } => test.literal_count(),
1250            _ => 0,
1251        }
1252    }
1253}
1254
1255#[derive(PartialEq, Debug, Clone)]
1256pub enum Braille {
1257    Implicit,
1258    Explicit(BrailleChars),
1259}
1260
1261impl std::fmt::Display for Braille {
1262    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1263        match self {
1264            Braille::Implicit => write!(f, "="),
1265            Braille::Explicit(dots) => write!(f, "{}", dots),
1266        }
1267    }
1268}
1269
1270#[derive(PartialEq, Debug, Clone)]
1271pub enum Position {
1272    Before,
1273    After,
1274}
1275
1276impl std::fmt::Display for Position {
1277    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
1278        match self {
1279            Position::Before => write!(f, "before"),
1280            Position::After => write!(f, "after"),
1281        }
1282    }
1283}
1284
1285#[derive(PartialEq, Debug)]
1286pub enum EscapingContext {
1287    Default,
1288    MatchPattern,
1289}
1290
1291fn unescape_unicode(chars: &mut Chars, len: u8) -> Result<char, ParseError> {
1292    let mut s = String::new();
1293
1294    for _ in 0..len {
1295        match chars.next() {
1296            Some(c) => s.push(c),
1297            _ => return Err(ParseError::InvalidUnicodeLiteral { found: None }),
1298        }
1299    }
1300
1301    let Ok(value) = u32::from_str_radix(&s, 16) else {
1302        return Err(ParseError::InvalidUnicodeLiteral { found: Some(s) });
1303    };
1304
1305    if let Some(c) = char::from_u32(value) {
1306        return Ok(c);
1307    }
1308
1309    // A hex literal that fits a UTF-16 code unit (`\x`, always 4 digits) can
1310    // only fail to be a scalar value by being a surrogate half -- that's the
1311    // one gap in `char::from_u32`'s range for u16-sized input. Anything wider
1312    // (only reachable via `\y`/`\z`) is a genuine out-of-range literal.
1313    let Ok(unit) = u16::try_from(value) else {
1314        return Err(ParseError::InvalidUnicodeLiteral { found: Some(s) });
1315    };
1316
1317    // liblouis tables written for 16-bit widechar builds spell a character
1318    // above U+FFFF as a `\x`-escaped high/low surrogate pair. Look ahead for
1319    // a second `\x` escape and hand both units to `char::decode_utf16`, which
1320    // already knows the surrogate-pairing rules -- it accepts a valid pair
1321    // and rejects everything else (a lone half, two highs, a high with a
1322    // non-surrogate after it, ...).
1323    let mut lookahead = chars.clone();
1324    if len == 4 && lookahead.next() == Some('\\') && lookahead.next() == Some('x') {
1325        let low: String = (0..4).map_while(|_| lookahead.next()).collect();
1326        if let Ok(low) = u16::from_str_radix(&low, 16)
1327            && let Some(Ok(c)) = char::decode_utf16([unit, low]).next()
1328        {
1329            *chars = lookahead;
1330            return Ok(c);
1331        }
1332    }
1333
1334    // An unpaired surrogate half isn't a real character. A couple of tables
1335    // use one as a sentinel to strip stray remnants of bad UTF-16 splitting --
1336    // input a Rust `char` can never actually hold, by construction. Map it to
1337    // the standard "invalid code unit" placeholder instead of failing the
1338    // whole table over a rule that can never match anything.
1339    Ok('\u{FFFD}')
1340}
1341
1342fn simple_escape(c: char) -> Option<char> {
1343    Some(match c {
1344        'e' => '\u{001B}',
1345        'f' => '\u{000C}',
1346        'n' => '\n',
1347        'r' => '\r',
1348        's' => ' ',
1349        't' => '\t',
1350        'v' => '\u{000B}',
1351        '\\' => '\\',
1352        _ => return None,
1353    })
1354}
1355
1356pub fn unescape(s: &str, context: EscapingContext) -> Result<String, ParseError> {
1357    let mut iter = s.chars();
1358    let mut new = String::new();
1359
1360    while let Some(c) = iter.next() {
1361        if c != '\\' {
1362            new.push(c);
1363            continue;
1364        }
1365
1366        match iter.next() {
1367            // when unescaping a match pattern leave \(, \) and \] alone as they are needed later
1368            Some(c @ ('(' | ')' | ']')) if context == EscapingContext::MatchPattern => {
1369                new.push('\\');
1370                new.push(c);
1371            }
1372            Some('x') => new.push(unescape_unicode(&mut iter, 4)?),
1373            Some('y') => new.push(unescape_unicode(&mut iter, 5)?),
1374            Some(c) => new.push(simple_escape(c).ok_or(ParseError::InvalidEscape(Some(c)))?),
1375            _ => return Err(ParseError::InvalidEscape(None)),
1376        };
1377    }
1378    Ok(new)
1379}
1380
1381/// Return an error if `actual` contains more constraints than `expected`
1382fn fail_if_invalid_constraints(
1383    expected: Constraints,
1384    actual: Constraints,
1385    opcode: Opcode,
1386) -> Result<(), ParseError> {
1387    if !actual.is_subset(expected) {
1388        Err(ParseError::InvalidConstraints {
1389            constraints: actual.difference(expected),
1390            opcode,
1391        })
1392    } else {
1393        Ok(())
1394    }
1395}
1396
1397/// Return an error if `actual` contains more constraints than `expected`
1398fn fail_if_differing_number_of_replacements(
1399    length1: usize,
1400    length2: usize,
1401) -> Result<(), ParseError> {
1402    if length1 != length2 {
1403        Err(ParseError::SameNumberOfSwapReplacementsExpected(
1404            length1, length2,
1405        ))
1406    } else {
1407        Ok(())
1408    }
1409}
1410
1411pub struct RuleParser<'a> {
1412    tokens: Peekable<SplitAsciiWhitespace<'a>>,
1413}
1414
1415impl<'a> RuleParser<'a> {
1416    pub fn new(source: &'a str) -> Self {
1417        Self {
1418            tokens: source.split_ascii_whitespace().peekable(),
1419        }
1420    }
1421
1422    fn nofor(&mut self) -> bool {
1423        self.tokens.next_if_eq(&"nofor").is_some()
1424    }
1425
1426    fn noback(&mut self) -> bool {
1427        self.tokens.next_if_eq(&"noback").is_some()
1428    }
1429
1430    fn nocross(&mut self) -> bool {
1431        self.tokens.next_if_eq(&"nocross").is_some()
1432    }
1433
1434    fn constraints(&mut self) -> Constraints {
1435        let mut constraints = Constraints::empty();
1436        if self.nofor() {
1437            constraints.insert(Constraint::Nofor);
1438        } else if self.noback() {
1439            constraints.insert(Constraint::Noback);
1440        }
1441        if self.nocross() {
1442            constraints.insert(Constraint::Nocross);
1443        }
1444        constraints
1445    }
1446
1447    fn with_class(&mut self) -> Result<Option<WithClass>, ParseError> {
1448        if self.tokens.next_if_eq(&"before").is_some() {
1449            match self.tokens.next() {
1450                Some(class) => {
1451                    return Ok(Some(WithClass::Before {
1452                        class: class.into(),
1453                    }));
1454                }
1455                None => return Err(ParseError::ClassNameExpected { found: None }),
1456            }
1457        }
1458        if self.tokens.next_if_eq(&"after").is_some() {
1459            match self.tokens.next() {
1460                Some(class) => {
1461                    return Ok(Some(WithClass::After {
1462                        class: class.into(),
1463                    }));
1464                }
1465                None => return Err(ParseError::ClassNameExpected { found: None }),
1466            }
1467        }
1468        Ok(None)
1469    }
1470
1471    fn with_classes(&mut self) -> Result<Option<WithClasses>, ParseError> {
1472        let mut classes = WithClasses::new();
1473        while self.tokens.peek() == Some(&"before") || self.tokens.peek() == Some(&"after") {
1474            if let Some(class) = self.with_class()? {
1475                classes.push(class);
1476            }
1477        }
1478        Ok(Some(classes))
1479    }
1480
1481    fn with_matches(&mut self) -> Option<WithMatches> {
1482        let mut matches = WithMatches::new();
1483        // TODO: make sure "empmatchbefore empmatchbefore" is not allowed
1484        while self.tokens.peek() == Some(&"empmatchbefore")
1485            || self.tokens.peek() == Some(&"empmatchafter")
1486        {
1487            if self.tokens.next_if_eq(&"empmatchbefore").is_some() {
1488                matches.insert(WithMatch::Before);
1489            }
1490            if self.tokens.next_if_eq(&"empmatchafter").is_some() {
1491                matches.insert(WithMatch::After);
1492            }
1493        }
1494        if !matches.is_empty() {
1495            Some(matches)
1496        } else {
1497            None
1498        }
1499    }
1500
1501    fn opcode(&mut self) -> Result<Opcode, ParseError> {
1502        if let Some(token) = self.tokens.next() {
1503            match token {
1504                "include" => Ok(Opcode::Include),
1505                "undefined" => Ok(Opcode::Undefined),
1506                "display" => Ok(Opcode::Display),
1507                "multind" => Ok(Opcode::Multind),
1508                "space" => Ok(Opcode::Space),
1509                "punctuation" => Ok(Opcode::Punctuation),
1510                "digit" => Ok(Opcode::Digit),
1511                "grouping" => Ok(Opcode::Grouping),
1512                "letter" => Ok(Opcode::Letter),
1513                "base" => Ok(Opcode::Base),
1514                "lowercase" => Ok(Opcode::Lowercase),
1515                "uppercase" => Ok(Opcode::Uppercase),
1516                "litdigit" => Ok(Opcode::Litdigit),
1517                "sign" => Ok(Opcode::Sign),
1518                "math" => Ok(Opcode::Math),
1519
1520                // Braille Indicator Opcodes
1521                "modeletter" => Ok(Opcode::Modeletter),
1522                "capsletter" => Ok(Opcode::Capsletter),
1523                "begmodeword" => Ok(Opcode::Begmodeword),
1524                "endmodeword" => Ok(Opcode::Endmodeword),
1525                "begcapsword" => Ok(Opcode::Begcapsword),
1526                "endcapsword" => Ok(Opcode::Endcapsword),
1527                "capsmodechars" => Ok(Opcode::Capsmodechars),
1528                "begmode" => Ok(Opcode::Begmode),
1529                "endmode" => Ok(Opcode::Endmode),
1530                "begcaps" => Ok(Opcode::Begcaps),
1531                "endcaps" => Ok(Opcode::Endcaps),
1532                "begcapsphrase" => Ok(Opcode::Begcapsphrase),
1533                "endcapsphrase" => Ok(Opcode::Endcapsphrase),
1534                "lencapsphrase" => Ok(Opcode::Lencapsphrase),
1535                "letsign" => Ok(Opcode::Letsign),
1536                "noletsign" => Ok(Opcode::Noletsign),
1537                "noletsignbefore" => Ok(Opcode::Noletsignbefore),
1538                "noletsignafter" => Ok(Opcode::Noletsignafter),
1539                "nocontractsign" => Ok(Opcode::Nocontractsign),
1540                "numsign" => Ok(Opcode::Numsign),
1541                "nonumsign" => Ok(Opcode::Nonumsign),
1542                "numericnocontchars" => Ok(Opcode::Numericnocontchars),
1543                "numericmodechars" => Ok(Opcode::Numericmodechars),
1544                "midendnumericmodechars" => Ok(Opcode::Midendnumericmodechars),
1545
1546                "begmodephrase" => Ok(Opcode::Begmodephrase),
1547                "endmodephrase" => Ok(Opcode::Endmodephrase),
1548                "lenmodephrase" => Ok(Opcode::Lenmodephrase),
1549
1550                // Opcodes for Standing Alone Sequences
1551                "seqdelimiter" => Ok(Opcode::Seqdelimiter),
1552                "seqbeforechars" => Ok(Opcode::Seqbeforechars),
1553                "seqafterchars" => Ok(Opcode::Seqafterchars),
1554                "seqafterpattern" => Ok(Opcode::Seqafterpattern),
1555                "seqafterexpression" => Ok(Opcode::Seqafterexpression),
1556
1557                // Emphasis Opcodes
1558                "class" => Ok(Opcode::Class),
1559                "emphclass" => Ok(Opcode::Emphclass),
1560                "begemph" => Ok(Opcode::Begemph),
1561                "endemph" => Ok(Opcode::Endemph),
1562                "noemphchars" => Ok(Opcode::Noemphchars),
1563                "emphletter" => Ok(Opcode::Emphletter),
1564                "begemphword" => Ok(Opcode::Begemphword),
1565                "endemphword" => Ok(Opcode::Endemphword),
1566                "emphmodechars" => Ok(Opcode::Emphmodechars),
1567                "begemphphrase" => Ok(Opcode::Begemphphrase),
1568                "endemphphrase" => Ok(Opcode::Endemphphrase),
1569                "lenemphphrase" => Ok(Opcode::Lenemphphrase),
1570
1571                // Special Symbol Opcodes
1572                "decpoint" => Ok(Opcode::Decpoint),
1573                "hyphen" => Ok(Opcode::Hyphen),
1574
1575                // Special Processing Opcodes
1576                "capsnocont" => Ok(Opcode::Capsnocont),
1577
1578                // Translation Opcodes
1579                "compbrl" => Ok(Opcode::Compbrl),
1580                "comp6" => Ok(Opcode::Comp6),
1581                "nocont" => Ok(Opcode::Nocont),
1582                "replace" => Ok(Opcode::Replace),
1583                "always" => Ok(Opcode::Always),
1584                "repeated" => Ok(Opcode::Repeated),
1585                "repword" => Ok(Opcode::Repword),
1586                "rependword" => Ok(Opcode::Rependword),
1587                "largesign" => Ok(Opcode::Largesign),
1588                "word" => Ok(Opcode::Word),
1589                "syllable" => Ok(Opcode::Syllable),
1590                "joinword" => Ok(Opcode::Joinword),
1591                "lowword" => Ok(Opcode::Lowword),
1592                "contraction" => Ok(Opcode::Contraction),
1593                "sufword" => Ok(Opcode::Sufword),
1594                "prfword" => Ok(Opcode::Prfword),
1595                "begword" => Ok(Opcode::Begword),
1596                "begmidword" => Ok(Opcode::Begmidword),
1597                "midword" => Ok(Opcode::Midword),
1598                "midendword" => Ok(Opcode::Midendword),
1599                "endword" => Ok(Opcode::Endword),
1600                "partword" => Ok(Opcode::Partword),
1601                "exactdots" => Ok(Opcode::Exactdots),
1602                "prepunc" => Ok(Opcode::Prepunc),
1603                "postpunc" => Ok(Opcode::Postpunc),
1604                "begnum" => Ok(Opcode::Begnum),
1605                "midnum" => Ok(Opcode::Midnum),
1606                "endnum" => Ok(Opcode::Endnum),
1607                "joinnum" => Ok(Opcode::Joinnum),
1608
1609                // Computer braille
1610                "begcomp" => Ok(Opcode::Begcomp),
1611                "endcomp" => Ok(Opcode::Endcomp),
1612
1613                // Character-Class Opcodes
1614                "attribute" => Ok(Opcode::Attribute),
1615
1616                // Swap Opcodes
1617                "swapcd" => Ok(Opcode::Swapcd),
1618                "swapdd" => Ok(Opcode::Swapdd),
1619                "swapcc" => Ok(Opcode::Swapcc),
1620
1621                // Context and Multipass Opcodes
1622                "context" => Ok(Opcode::Context),
1623                "pass2" => Ok(Opcode::Pass2),
1624                "pass3" => Ok(Opcode::Pass3),
1625                "pass4" => Ok(Opcode::Pass4),
1626
1627                // The correct Opcode
1628                "correct" => Ok(Opcode::Correct),
1629
1630                // The match Opcode
1631                "match" => Ok(Opcode::Match),
1632                "literal" => Ok(Opcode::Literal),
1633                unknown => Err(ParseError::OpcodeExpected {
1634                    found: Some(unknown.into()),
1635                }),
1636            }
1637        } else {
1638            Err(ParseError::OpcodeExpected { found: None })
1639        }
1640    }
1641
1642    fn name(&mut self) -> Result<String, ParseError> {
1643        let name = self
1644            .tokens
1645            .next()
1646            .ok_or(ParseError::NameExpected)
1647            .map(|s| s.to_string())?;
1648        if name.chars().all(|c| c.is_ascii_alphanumeric()) {
1649            Ok(name)
1650        } else {
1651            Err(ParseError::InvalidName { name })
1652        }
1653    }
1654
1655    fn many_names(&mut self) -> Result<Vec<String>, ParseError> {
1656        let mut names: Vec<String> = Vec::new();
1657        for name in self.tokens.by_ref() {
1658            names.push(name.into());
1659        }
1660        if names.len() > 1 {
1661            Ok(names)
1662        } else {
1663            Err(ParseError::TokenExpected {
1664                expected: "At least one name expected".into(),
1665                found: None,
1666            })
1667        }
1668    }
1669
1670    fn one_char(&mut self) -> Result<char, ParseError> {
1671        let s = self
1672            .tokens
1673            .next()
1674            .ok_or(ParseError::SingleCharExpected { found: None })?;
1675        let s = unescape(s, EscapingContext::Default)?;
1676        if s.chars().count() == 1 {
1677            Ok(s.chars().next().unwrap())
1678        } else {
1679            Err(ParseError::SingleCharExpected { found: Some(s) })
1680        }
1681    }
1682
1683    fn number(&mut self) -> Result<i32, ParseError> {
1684        let s = self
1685            .tokens
1686            .next()
1687            .ok_or(ParseError::NumberExpected { found: None })?;
1688        let number = s.parse::<i32>()?;
1689        Ok(number)
1690    }
1691
1692    fn chars(&mut self) -> Result<String, ParseError> {
1693        let s = self.tokens.next().ok_or(ParseError::CharsExpected)?;
1694        unescape(s, EscapingContext::Default)
1695    }
1696
1697    /// The optional replacement of a `replace` rule. One starting with `#` is a comment, so
1698    /// there is none; `\#` starts it with a literal `#`.
1699    fn replacement(&mut self) -> Result<Option<String>, ParseError> {
1700        match self.tokens.next() {
1701            None => Ok(None),
1702            Some(s) if s.starts_with('#') => Ok(None),
1703            Some(s) => match s.strip_prefix("\\#") {
1704                Some(rest) => Ok(Some(format!(
1705                    "#{}",
1706                    unescape(rest, EscapingContext::Default)?
1707                ))),
1708                None => unescape(s, EscapingContext::Default).map(Some),
1709            },
1710        }
1711    }
1712
1713    fn filename(&mut self) -> Result<String, ParseError> {
1714        self.tokens
1715            .next()
1716            .ok_or(ParseError::FilenameExpected)
1717            .map(|s| s.to_string())
1718    }
1719
1720    fn position(&mut self) -> Result<Position, ParseError> {
1721        if self.tokens.next_if_eq(&"before").is_some() {
1722            return Ok(Position::Before);
1723        }
1724        if self.tokens.next_if_eq(&"after").is_some() {
1725            return Ok(Position::After);
1726        }
1727        Err(ParseError::TokenExpected {
1728            expected: "Before/After".into(),
1729            found: self.tokens.peek().map(|&s| s.into()),
1730        })
1731    }
1732
1733    fn dots(&mut self) -> Result<Braille, ParseError> {
1734        let token = self.tokens.next().ok_or(ParseError::DotsExpected)?;
1735        if token == "=" {
1736            Ok(Braille::Implicit)
1737        } else {
1738            Ok(Braille::Explicit(BrailleChars::try_from(token)?))
1739        }
1740    }
1741
1742    fn explicit_dots(&mut self) -> Result<BrailleChars, ParseError> {
1743        self.tokens
1744            .next()
1745            .ok_or(ParseError::DotsExpected)?
1746            .split('-')
1747            .map(BrailleChar::try_from)
1748            // FIXME: it feels really weird that we manually have to
1749            // map braille::ParseError to ParseError. I thought the
1750            // thisError crate implements the from trait between the
1751            // two?
1752            .map(|r| r.map_err(ParseError::InvalidBraille))
1753            .collect()
1754    }
1755
1756    fn many_braillechars(&mut self) -> Result<Vec<BrailleChars>, ParseError> {
1757        self.tokens
1758            .next()
1759            .ok_or(ParseError::DotsExpected)?
1760            .split(',')
1761            .map(|chars| {
1762                chars
1763                    .split('-')
1764                    .map(BrailleChar::try_from)
1765                    // FIXME: it feels really weird that we manually have to
1766                    // map braille::ParseError to ParseError.
1767                    .map(|r| r.map_err(ParseError::InvalidBraille))
1768                    .collect()
1769            })
1770            .collect()
1771    }
1772
1773    /// Parse a single cell braille dot pattern.
1774    fn single_braillechar(&mut self) -> Result<BrailleChar, ParseError> {
1775        self.tokens
1776            .next()
1777            .ok_or(ParseError::DotsExpected)?
1778            .try_into()
1779            .map_err(ParseError::InvalidBraille)
1780    }
1781
1782    /// Parse many single cell braille chars separated by ','
1783    fn many_braillechar(&mut self) -> Result<BrailleChars, ParseError> {
1784        self.tokens
1785            .next()
1786            .ok_or(ParseError::DotsExpected)?
1787            .split(',')
1788            .map(|chars| {
1789                if chars.contains('-') {
1790                    return Err(ParseError::SingleCellDotsExpected {
1791                        found: chars.to_string(),
1792                    });
1793                }
1794                BrailleChar::try_from(chars).map_err(ParseError::InvalidBraille)
1795            })
1796            .collect()
1797    }
1798
1799    fn multipass_test(&mut self) -> Result<Test, ParseError> {
1800        self.tokens
1801            .next()
1802            .ok_or(ParseError::MultipassTestExpected)
1803            .map(|s| {
1804                multipass::test::Parser::new(s)
1805                    .tests()
1806                    .map_err(ParseError::InvalidMultipassOperand)
1807            })?
1808    }
1809
1810    fn multipass_action(&mut self) -> Result<Action, ParseError> {
1811        self.tokens
1812            .next()
1813            .ok_or(ParseError::MultipassActionExpected)
1814            .map(|s| {
1815                multipass::action::Parser::new(s)
1816                    .actions()
1817                    .map_err(ParseError::InvalidMultipassOperand)
1818            })?
1819    }
1820
1821    fn match_pre(&mut self) -> Result<Patterns, ParseError> {
1822        self.tokens
1823            .next()
1824            .ok_or(ParseError::MatchPreExpected)
1825            .map(|s| {
1826                match_rule::PatternParser::new(
1827                    &unescape(s, EscapingContext::MatchPattern)?,
1828                    Side::Pre,
1829                )
1830                .pattern()
1831                .map_err(ParseError::InvalidMatchPattern)
1832            })?
1833    }
1834
1835    fn match_post(&mut self) -> Result<Patterns, ParseError> {
1836        self.tokens
1837            .next()
1838            .ok_or(ParseError::MatchPostExpected)
1839            .map(|s| {
1840                match_rule::PatternParser::new(
1841                    &unescape(s, EscapingContext::MatchPattern)?,
1842                    Side::Post,
1843                )
1844                .pattern()
1845                .map_err(ParseError::InvalidMatchPattern)
1846            })?
1847    }
1848
1849    pub fn rule(&mut self) -> Result<Rule, ParseError> {
1850        let constraints = self.constraints();
1851        let classes = self.with_classes().unwrap_or_default().unwrap_or_default();
1852        let matches = self.with_matches();
1853        let opcode = self.opcode()?;
1854        let rule = match opcode {
1855            Opcode::Include => {
1856                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
1857                Rule::Include {
1858                    file: self.filename()?,
1859                }
1860            }
1861            Opcode::Undefined => {
1862                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
1863                Rule::Undefined {
1864                    dots: self.explicit_dots()?,
1865                }
1866            }
1867            Opcode::Display => {
1868                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1869                Rule::Display {
1870                    character: self.one_char()?,
1871                    dots: self.single_braillechar()?,
1872                    constraints,
1873                }
1874            }
1875            Opcode::Multind => {
1876                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1877                Rule::Multind {
1878                    dots: self.explicit_dots()?,
1879                    names: self.many_names()?,
1880                    constraints,
1881                }
1882            }
1883            Opcode::Space => {
1884                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1885                Rule::Space {
1886                    character: self.one_char()?,
1887                    dots: self.explicit_dots()?,
1888                    constraints,
1889                }
1890            }
1891            Opcode::Punctuation => {
1892                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1893                Rule::Punctuation {
1894                    character: self.one_char()?,
1895                    dots: self.explicit_dots()?,
1896                    constraints,
1897                }
1898            }
1899            Opcode::Digit => {
1900                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1901                Rule::Digit {
1902                    character: self.one_char()?,
1903                    dots: self.explicit_dots()?,
1904                    constraints,
1905                }
1906            }
1907            Opcode::Grouping => {
1908                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1909                let name = self.name()?;
1910                let chars = self.chars()?;
1911                let dots = self.many_braillechar()?;
1912                if dots.len() != 2 {
1913                    return Err(ParseError::DotsTupleExpected);
1914                }
1915                let left = dots.iter().next().unwrap().clone();
1916                let right = dots.iter().last().unwrap().clone();
1917                Rule::Grouping {
1918                    name,
1919                    chars,
1920                    left,
1921                    right,
1922                }
1923            }
1924            Opcode::Letter => {
1925                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1926                Rule::Letter {
1927                    character: self.one_char()?,
1928                    dots: self.explicit_dots()?,
1929                    constraints,
1930                }
1931            }
1932            Opcode::Base => {
1933                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
1934                Rule::Base {
1935                    name: self.name()?,
1936                    derived: self.one_char()?,
1937                    base: self.one_char()?,
1938                }
1939            }
1940            Opcode::Lowercase => {
1941                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1942                Rule::Lowercase {
1943                    character: self.one_char()?,
1944                    dots: self.explicit_dots()?,
1945                    constraints,
1946                }
1947            }
1948            Opcode::Uppercase => {
1949                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1950                Rule::Uppercase {
1951                    character: self.one_char()?,
1952                    dots: self.explicit_dots()?,
1953                    constraints,
1954                }
1955            }
1956            Opcode::Litdigit => {
1957                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1958                Rule::Litdigit {
1959                    character: self.one_char()?,
1960                    dots: self.explicit_dots()?,
1961                    constraints,
1962                }
1963            }
1964            Opcode::Sign => {
1965                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1966                Rule::Sign {
1967                    character: self.one_char()?,
1968                    dots: self.explicit_dots()?,
1969                    constraints,
1970                }
1971            }
1972            Opcode::Math => {
1973                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1974                Rule::Math {
1975                    character: self.one_char()?,
1976                    dots: self.explicit_dots()?,
1977                    constraints,
1978                }
1979            }
1980
1981            Opcode::Modeletter => {
1982                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1983                Rule::Modeletter {
1984                    name: self.name()?,
1985                    dots: self.explicit_dots()?,
1986                    constraints,
1987                }
1988            }
1989            Opcode::Capsletter => {
1990                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1991                Rule::Capsletter {
1992                    dots: self.explicit_dots()?,
1993                    constraints,
1994                }
1995            }
1996            Opcode::Begmodeword => {
1997                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
1998                Rule::Begmodeword {
1999                    name: self.name()?,
2000                    dots: self.explicit_dots()?,
2001                    constraints,
2002                }
2003            }
2004            Opcode::Endmodeword => {
2005                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2006                Rule::Endmodeword {
2007                    name: self.name()?,
2008                    dots: self.explicit_dots()?,
2009                    constraints,
2010                }
2011            }
2012            Opcode::Begcapsword => {
2013                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2014                Rule::Begcapsword {
2015                    dots: self.explicit_dots()?,
2016                    constraints,
2017                }
2018            }
2019            Opcode::Endcapsword => {
2020                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2021                Rule::Endcapsword {
2022                    dots: self.explicit_dots()?,
2023                    constraints,
2024                }
2025            }
2026            Opcode::Capsmodechars => {
2027                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2028                Rule::Capsmodechars {
2029                    chars: self.chars()?,
2030                }
2031            }
2032            Opcode::Begmode => {
2033                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2034                Rule::Begmode {
2035                    name: self.name()?,
2036                    dots: self.explicit_dots()?,
2037                }
2038            }
2039            Opcode::Endmode => {
2040                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2041                Rule::Endmode {
2042                    name: self.name()?,
2043                    dots: self.explicit_dots()?,
2044                }
2045            }
2046            Opcode::Begcaps => {
2047                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2048                Rule::Begcaps {
2049                    dots: self.explicit_dots()?,
2050                }
2051            }
2052            Opcode::Endcaps => {
2053                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2054                Rule::Endcaps {
2055                    dots: self.explicit_dots()?,
2056                }
2057            }
2058            Opcode::Begcapsphrase => {
2059                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2060                Rule::Begcapsphrase {
2061                    dots: self.explicit_dots()?,
2062                }
2063            }
2064            Opcode::Endcapsphrase => {
2065                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2066                Rule::Endcapsphrase {
2067                    position: self.position()?,
2068                    dots: self.explicit_dots()?,
2069                }
2070            }
2071            Opcode::Lencapsphrase => {
2072                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2073                Rule::Lencapsphrase {
2074                    number: self.number()?,
2075                }
2076            }
2077            Opcode::Letsign => {
2078                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2079                Rule::Letsign {
2080                    dots: self.explicit_dots()?,
2081                }
2082            }
2083            Opcode::Noletsign => {
2084                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2085                Rule::Noletsign {
2086                    chars: self.chars()?,
2087                }
2088            }
2089            Opcode::Noletsignbefore => {
2090                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2091                Rule::Noletsignbefore {
2092                    chars: self.chars()?,
2093                }
2094            }
2095            Opcode::Noletsignafter => {
2096                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2097                Rule::Noletsignafter {
2098                    chars: self.chars()?,
2099                }
2100            }
2101            Opcode::Nocontractsign => {
2102                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2103                Rule::Nocontractsign {
2104                    dots: self.explicit_dots()?,
2105                    constraints,
2106                }
2107            }
2108            Opcode::Numsign => {
2109                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2110                Rule::Numsign {
2111                    dots: self.explicit_dots()?,
2112                }
2113            }
2114            Opcode::Nonumsign => {
2115                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2116                Rule::Nonumsign {
2117                    dots: self.explicit_dots()?,
2118                    constraints,
2119                }
2120            }
2121            Opcode::Numericnocontchars => {
2122                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2123                Rule::Numericnocontchars {
2124                    chars: self.chars()?,
2125                }
2126            }
2127            Opcode::Numericmodechars => {
2128                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2129                Rule::Numericmodechars {
2130                    chars: self.chars()?,
2131                }
2132            }
2133            Opcode::Midendnumericmodechars => {
2134                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2135                Rule::Midendnumericmodechars {
2136                    chars: self.chars()?,
2137                }
2138            }
2139
2140            Opcode::Begmodephrase => {
2141                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2142                Rule::Begmodephrase {
2143                    name: self.name()?,
2144                    dots: self.explicit_dots()?,
2145                }
2146            }
2147            Opcode::Endmodephrase => {
2148                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2149                Rule::Endmodephrase {
2150                    name: self.name()?,
2151                    position: self.position()?,
2152                    dots: self.explicit_dots()?,
2153                }
2154            }
2155            Opcode::Lenmodephrase => {
2156                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2157                Rule::Lenmodephrase {
2158                    name: self.name()?,
2159                    number: self.number()?,
2160                }
2161            }
2162
2163            Opcode::Seqdelimiter => {
2164                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2165                Rule::Seqdelimiter {
2166                    chars: self.chars()?,
2167                }
2168            }
2169            Opcode::Seqbeforechars => {
2170                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2171                Rule::Seqbeforechars {
2172                    chars: self.chars()?,
2173                }
2174            }
2175            Opcode::Seqafterchars => {
2176                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2177                Rule::Seqafterchars {
2178                    chars: self.chars()?,
2179                }
2180            }
2181            Opcode::Seqafterpattern => {
2182                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2183                Rule::Seqafterpattern {
2184                    chars: self.chars()?,
2185                }
2186            }
2187            Opcode::Seqafterexpression => {
2188                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2189                Rule::Seqafterexpression {
2190                    chars: self.chars()?,
2191                }
2192            }
2193
2194            Opcode::Class => {
2195                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2196                Rule::Class {
2197                    name: self.name()?,
2198                    chars: self.chars()?,
2199                }
2200            }
2201            Opcode::Emphclass => {
2202                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2203                Rule::Emphclass { name: self.name()? }
2204            }
2205            Opcode::Begemph => {
2206                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2207                Rule::Begemph {
2208                    name: self.name()?,
2209                    dots: self.explicit_dots()?,
2210                    constraints,
2211                }
2212            }
2213            Opcode::Endemph => {
2214                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2215                Rule::Endemph {
2216                    name: self.name()?,
2217                    dots: self.explicit_dots()?,
2218                    constraints,
2219                }
2220            }
2221            Opcode::Noemphchars => {
2222                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2223                Rule::Noemphchars {
2224                    name: self.name()?,
2225                    chars: self.chars()?,
2226                }
2227            }
2228            Opcode::Emphletter => {
2229                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2230                Rule::Emphletter {
2231                    name: self.name()?,
2232                    dots: self.explicit_dots()?,
2233                }
2234            }
2235            Opcode::Begemphword => {
2236                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2237                Rule::Begemphword {
2238                    name: self.name()?,
2239                    dots: self.explicit_dots()?,
2240                }
2241            }
2242            Opcode::Endemphword => {
2243                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2244                Rule::Endemphword {
2245                    name: self.name()?,
2246                    dots: self.explicit_dots()?,
2247                }
2248            }
2249            Opcode::Emphmodechars => {
2250                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2251                Rule::Emphmodechars {
2252                    name: self.name()?,
2253                    chars: self.chars()?,
2254                }
2255            }
2256            Opcode::Begemphphrase => {
2257                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2258                Rule::Begemphphrase {
2259                    name: self.name()?,
2260                    dots: self.explicit_dots()?,
2261                }
2262            }
2263            Opcode::Endemphphrase => {
2264                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2265                Rule::Endemphphrase {
2266                    name: self.name()?,
2267                    position: self.position()?,
2268                    dots: self.explicit_dots()?,
2269                }
2270            }
2271            Opcode::Lenemphphrase => {
2272                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2273                Rule::Lenemphphrase {
2274                    name: self.name()?,
2275                    number: self.number()?,
2276                }
2277            }
2278
2279            Opcode::Begcomp => {
2280                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2281                Rule::Begcomp {
2282                    dots: self.explicit_dots()?,
2283                    constraints,
2284                }
2285            }
2286            Opcode::Endcomp => {
2287                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2288                Rule::Endcomp {
2289                    dots: self.explicit_dots()?,
2290                    constraints,
2291                }
2292            }
2293
2294            Opcode::Decpoint => {
2295                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2296                Rule::Decpoint {
2297                    character: self.one_char()?,
2298
2299                    dots: self.explicit_dots()?,
2300                }
2301            }
2302            Opcode::Hyphen => {
2303                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2304                Rule::Hyphen {
2305                    character: self.one_char()?,
2306                    dots: self.explicit_dots()?,
2307                    constraints,
2308                }
2309            }
2310
2311            Opcode::Capsnocont => {
2312                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2313                Rule::Capsnocont {}
2314            }
2315
2316            Opcode::Compbrl => {
2317                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2318                Rule::Compbrl {
2319                    chars: self.chars()?,
2320                    constraints,
2321                }
2322            }
2323            Opcode::Comp6 => {
2324                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2325                Rule::Comp6 {
2326                    character: self.one_char()?,
2327                    dots: self.dots()?,
2328                }
2329            }
2330            Opcode::Nocont => {
2331                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2332                Rule::Nocont {
2333                    chars: self.chars()?,
2334                }
2335            }
2336            Opcode::Replace => {
2337                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2338                Rule::Replace {
2339                    chars: self.chars()?,
2340                    replacement: self.replacement()?,
2341                }
2342            }
2343            Opcode::Always => Rule::Always {
2344                chars: self.chars()?,
2345                dots: self.dots()?,
2346                constraints,
2347                with_classes: classes,
2348            },
2349            Opcode::Repeated => {
2350                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2351                Rule::Repeated {
2352                    chars: self.chars()?,
2353                    dots: self.explicit_dots()?,
2354                    constraints,
2355                }
2356            }
2357            Opcode::Repword => {
2358                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2359                Rule::Repword {
2360                    separator: self.one_char()?,
2361                    dots: self.explicit_dots()?,
2362                }
2363            }
2364            Opcode::Rependword => {
2365                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2366                let separator = self.one_char()?;
2367                let many_dots = self.many_braillechars()?;
2368                if many_dots.len() != 2 {
2369                    return Err(ParseError::DotsTupleExpected);
2370                }
2371                let mut iterator = many_dots.into_iter();
2372                let dots = iterator.next().unwrap();
2373                let other = iterator.next().unwrap();
2374                Rule::Rependword {
2375                    separator,
2376                    dots,
2377                    other,
2378                }
2379            }
2380            Opcode::Largesign => {
2381                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2382                Rule::Largesign {
2383                    chars: self.chars()?,
2384                    dots: self.explicit_dots()?,
2385                }
2386            }
2387            Opcode::Word => {
2388                // FIXME: in theory nocross would be allowed for this opcode, so no need to check
2389                // for invalid contraints
2390                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2391                Rule::Word {
2392                    chars: self.chars()?,
2393                    dots: self.dots()?,
2394                    constraints,
2395                    with_classes: classes,
2396                }
2397            }
2398            Opcode::Syllable => {
2399                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2400                Rule::Syllable {
2401                    chars: self.chars()?,
2402                    dots: self.dots()?,
2403                }
2404            }
2405            Opcode::Joinword => {
2406                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2407                Rule::Joinword {
2408                    chars: self.chars()?,
2409                    dots: self.explicit_dots()?,
2410                }
2411            }
2412            Opcode::Lowword => {
2413                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2414                Rule::Lowword {
2415                    chars: self.chars()?,
2416                    dots: self.explicit_dots()?,
2417                    constraints,
2418                }
2419            }
2420            Opcode::Contraction => {
2421                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2422                Rule::Contraction {
2423                    chars: self.chars()?,
2424                }
2425            }
2426            Opcode::Sufword => Rule::Sufword {
2427                chars: self.chars()?,
2428                dots: self.dots()?,
2429                constraints,
2430                with_classes: classes,
2431            },
2432            Opcode::Prfword => Rule::Prfword {
2433                chars: self.chars()?,
2434                dots: self.dots()?,
2435                constraints,
2436                with_classes: classes,
2437            },
2438            Opcode::Begword => Rule::Begword {
2439                chars: self.chars()?,
2440                dots: self.dots()?,
2441                constraints,
2442                with_classes: classes,
2443            },
2444            Opcode::Begmidword => Rule::Begmidword {
2445                chars: self.chars()?,
2446                dots: self.dots()?,
2447                constraints,
2448                with_classes: classes,
2449            },
2450            Opcode::Midword => Rule::Midword {
2451                chars: self.chars()?,
2452                dots: self.dots()?,
2453                constraints,
2454                with_classes: classes,
2455            },
2456            Opcode::Midendword => Rule::Midendword {
2457                chars: self.chars()?,
2458                dots: self.dots()?,
2459                constraints,
2460                with_classes: classes,
2461            },
2462            Opcode::Endword => Rule::Endword {
2463                chars: self.chars()?,
2464                dots: self.dots()?,
2465                constraints,
2466                with_classes: classes,
2467            },
2468            Opcode::Partword => Rule::Partword {
2469                chars: self.chars()?,
2470                dots: self.dots()?,
2471                constraints,
2472                with_classes: classes,
2473            },
2474            Opcode::Exactdots => {
2475                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2476                Rule::Exactdots {
2477                    chars: self.chars()?,
2478                }
2479            }
2480            Opcode::Prepunc => Rule::Prepunc {
2481                chars: self.chars()?,
2482                dots: self.explicit_dots()?,
2483                constraints,
2484            },
2485            Opcode::Postpunc => Rule::Postpunc {
2486                chars: self.chars()?,
2487                dots: self.explicit_dots()?,
2488                constraints,
2489            },
2490            Opcode::Begnum => Rule::Begnum {
2491                chars: self.chars()?,
2492                dots: self.explicit_dots()?,
2493                constraints,
2494            },
2495            Opcode::Midnum => Rule::Midnum {
2496                chars: self.chars()?,
2497                dots: self.explicit_dots()?,
2498                constraints,
2499            },
2500            Opcode::Endnum => Rule::Endnum {
2501                chars: self.chars()?,
2502                dots: self.dots()?,
2503                constraints,
2504            },
2505            Opcode::Joinnum => Rule::Joinnum {
2506                chars: self.chars()?,
2507                dots: self.explicit_dots()?,
2508                constraints,
2509            },
2510
2511            Opcode::Attribute => {
2512                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2513                Rule::Attribute {
2514                    name: self.name()?,
2515                    chars: self.chars()?,
2516                }
2517            }
2518
2519            Opcode::Swapcd => {
2520                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2521                let name = self.name()?;
2522                let chars = self.chars()?;
2523                let dots = self.many_braillechars()?;
2524                fail_if_differing_number_of_replacements(chars.chars().count(), dots.len())?;
2525                Rule::Swapcd { name, chars, dots }
2526            }
2527            Opcode::Swapdd => {
2528                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2529                let name = self.name()?;
2530                let dots = self.many_braillechar()?;
2531                let replacement = self.many_braillechars()?;
2532                fail_if_differing_number_of_replacements(dots.len(), replacement.len())?;
2533                Rule::Swapdd {
2534                    name,
2535                    dots,
2536                    replacement,
2537                }
2538            }
2539            Opcode::Swapcc => {
2540                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2541                let name = self.name()?;
2542                let chars = self.chars()?;
2543                let replacement = self.chars()?;
2544                fail_if_differing_number_of_replacements(
2545                    chars.chars().count(),
2546                    replacement.chars().count(),
2547                )?;
2548                Rule::Swapcc {
2549                    name,
2550                    chars,
2551                    replacement,
2552                }
2553            }
2554
2555            Opcode::Context => {
2556                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2557                Rule::Context {
2558                    test: self.multipass_test()?,
2559                    action: self.multipass_action()?,
2560                    constraints,
2561                }
2562            }
2563            Opcode::Pass2 => {
2564                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2565                Rule::Pass2 {
2566                    test: self.multipass_test()?,
2567                    action: self.multipass_action()?,
2568                    constraints,
2569                }
2570            }
2571            Opcode::Pass3 => {
2572                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2573                Rule::Pass3 {
2574                    test: self.multipass_test()?,
2575                    action: self.multipass_action()?,
2576                    constraints,
2577                }
2578            }
2579            Opcode::Pass4 => {
2580                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2581                Rule::Pass4 {
2582                    test: self.multipass_test()?,
2583                    action: self.multipass_action()?,
2584                    constraints,
2585                }
2586            }
2587            Opcode::Correct => {
2588                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2589                Rule::Correct {
2590                    test: self.multipass_test()?,
2591                    action: self.multipass_action()?,
2592                    constraints,
2593                }
2594            }
2595
2596            Opcode::Match => {
2597                fail_if_invalid_constraints(ANY_DIRECTION, constraints, opcode)?;
2598                Rule::Match {
2599                    pre: self.match_pre()?,
2600                    chars: self.chars()?,
2601                    post: self.match_post()?,
2602                    dots: self.dots()?,
2603                    matches,
2604                    constraints,
2605                }
2606            }
2607            Opcode::Literal => {
2608                fail_if_invalid_constraints(Constraints::empty(), constraints, opcode)?;
2609                Rule::Literal {
2610                    chars: self.chars()?,
2611                }
2612            }
2613        };
2614        Ok(rule)
2615    }
2616}
2617
2618/// What is wrong with a line of a table, or with a hyphenation table. Its message says
2619/// what; the details are not public API, as they follow the parser's internals.
2620#[derive(thiserror::Error, Debug)]
2621#[error(transparent)]
2622pub struct SyntaxError(SyntaxErrorKind);
2623
2624#[derive(thiserror::Error, Debug)]
2625enum SyntaxErrorKind {
2626    #[error(transparent)]
2627    Rule(ParseError),
2628    #[error(transparent)]
2629    Hyphenation(hyphenation::ParseError),
2630}
2631
2632/// The start of a syntax error's message: the table and a colon, or `line ` for table
2633/// source given in memory
2634fn location(path: &Option<PathBuf>) -> String {
2635    match path {
2636        Some(path) => format!("{}:", path.display()),
2637        None => "line ".to_string(),
2638    }
2639}
2640
2641/// An error that occurred during reading of a [liblouis](https://liblouis.io) braille table
2642#[derive(thiserror::Error, Debug)]
2643#[non_exhaustive]
2644pub enum TableError {
2645    /// A line of a table could not be parsed
2646    #[error("{}{line}: {error}", location(.path))]
2647    Syntax {
2648        /// The table, or `None` for table source given in memory
2649        path: Option<PathBuf>,
2650        /// The line number, counting from 1
2651        line: usize,
2652        /// What is wrong with the line
2653        error: SyntaxError,
2654    },
2655    /// Table source given in memory has an `include`, which needs the filesystem
2656    #[error("include directives are not supported when parsing table source in memory")]
2657    IncludesNotSupportedInMemory,
2658    /// A table was found but could not be read
2659    #[error("cannot read table {path}: {error}")]
2660    NotReadable {
2661        /// The table
2662        path: PathBuf,
2663        /// Why it could not be read
2664        error: io::Error,
2665    },
2666    /// A table is not on the search path
2667    #[error("cannot find table {0}")]
2668    NotFound(PathBuf),
2669    /// A hyphenation table is not on the search path
2670    #[error("hyphenation table {0} not found")]
2671    HyphenationNotFound(PathBuf),
2672    /// A hyphenation table was found but could not be read
2673    #[error("cannot read hyphenation table {path}: {error}")]
2674    HyphenationNotReadable {
2675        /// The hyphenation table
2676        path: PathBuf,
2677        /// Why it could not be read
2678        error: io::Error,
2679    },
2680    /// A hyphenation table could not be parsed
2681    #[error("cannot parse hyphenation table {path}: {error}")]
2682    HyphenationSyntax {
2683        /// The hyphenation table
2684        path: PathBuf,
2685        /// What is wrong with it
2686        error: SyntaxError,
2687    },
2688    /// Tables include each other in a cycle, listed in the order of inclusion
2689    #[error("circular table inclusion detected: {0:?}")]
2690    CircularInclude(Vec<PathBuf>),
2691    /// A chain of includes is deeper than the given maximum
2692    #[error("table inclusion chain exceeds the maximum depth of {0}")]
2693    IncludeTooDeep(usize),
2694    /// The `endmodephrase` of the named emphasis class is defined both before and after
2695    #[error("endmodephrase {0:?} may only be defined as before or after, not both")]
2696    ConflictingEndmodephrasePosition(String),
2697    /// `endcapsphrase` is defined both before and after
2698    #[error("endcapsphrase may only be defined as before or after, not both")]
2699    ConflictingEndcapsphrasePosition,
2700}
2701
2702/// Maximum length of an `include` chain, guarding against stack overflow from a very deep
2703/// (but acyclic) chain of includes -- cyclic ones are caught earlier, by [`TableError::CircularInclude`].
2704const MAX_INCLUDE_DEPTH: usize = 64;
2705
2706/// A `Rule` combined with information about which table file it originated from.
2707#[derive(PartialEq, Debug, Clone)]
2708pub struct AnchoredRule {
2709    pub rule: Rule,
2710    path: Option<PathBuf>,
2711    line: usize,
2712    /// Position in the rule list a table was compiled from, i.e. definition order across
2713    /// `include`s and table lists. Only the last resort for picking between candidates, see
2714    /// [`Rank`](crate::translator::translation::Rank).
2715    definition_order: usize,
2716}
2717
2718impl std::fmt::Display for AnchoredRule {
2719    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
2720        if let Some(path) = &self.path {
2721            write!(f, "{:?}:{} ", path.as_os_str(), self.line)?;
2722        }
2723        write!(f, "{}", self.rule)
2724    }
2725}
2726
2727impl AnchoredRule {
2728    pub fn new(rule: Rule, path: Option<PathBuf>, line: usize) -> Self {
2729        Self {
2730            rule,
2731            path,
2732            line,
2733            definition_order: 0,
2734        }
2735    }
2736
2737    pub fn definition_order(&self) -> usize {
2738        self.definition_order
2739    }
2740
2741    /// The table the rule comes from, or `None` for table source given in memory
2742    pub fn path(&self) -> Option<&Path> {
2743        self.path.as_deref()
2744    }
2745
2746    /// The line the rule is on, counting from 1
2747    pub fn line(&self) -> usize {
2748        self.line
2749    }
2750}
2751
2752impl HasDirection for AnchoredRule {
2753    fn directions(&self) -> EnumSet<Direction> {
2754        self.rule.directions()
2755    }
2756}
2757
2758impl HasPrecedence for AnchoredRule {
2759    fn precedence(&self) -> Precedence {
2760        self.rule.precedence()
2761    }
2762}
2763
2764impl HasNocross for AnchoredRule {
2765    fn constraints(&self) -> Constraints {
2766        self.rule.constraints()
2767    }
2768}
2769
2770impl From<Rule> for AnchoredRule {
2771    fn from(rule: Rule) -> Self {
2772        Self {
2773            rule,
2774            path: None,
2775            line: 0,
2776            definition_order: 0,
2777        }
2778    }
2779}
2780
2781/// `rules` stamped with their position in it, which is their definition order: the last
2782/// resort for picking between candidates, see [`Rank`](crate::translator::translation::Rank).
2783pub fn in_definition_order(rules: &[AnchoredRule]) -> Vec<AnchoredRule> {
2784    rules
2785        .iter()
2786        .enumerate()
2787        .map(|(definition_order, r)| AnchoredRule {
2788            definition_order,
2789            ..r.clone()
2790        })
2791        .collect()
2792}
2793
2794pub fn table(table: &str, path: Option<PathBuf>) -> Result<Vec<AnchoredRule>, Vec<TableError>> {
2795    let (rules, errors): (Vec<_>, Vec<_>) = table
2796        .lines()
2797        .enumerate()
2798        // drop comments and empty lines
2799        .filter(|(_, line)| !line.trim().starts_with('#') && !line.trim().is_empty())
2800        .map(|(line_no, line)| {
2801            // parse the line
2802            RuleParser::new(line)
2803                .rule()
2804                .map(|rule| AnchoredRule::new(rule, path.clone(), line_no + 1))
2805                .map_err(|e| TableError::Syntax {
2806                    path: path.clone(),
2807                    line: line_no + 1,
2808                    error: SyntaxError(SyntaxErrorKind::Rule(e)),
2809                })
2810        })
2811        .partition(Result::is_ok);
2812    let rules: Vec<_> = rules.into_iter().map(Result::unwrap).collect();
2813    let errors: Vec<_> = errors.into_iter().map(Result::unwrap_err).collect();
2814    if errors.is_empty() {
2815        Ok(rules)
2816    } else {
2817        Err(errors)
2818    }
2819}
2820
2821pub fn table_file(path: &Path) -> Result<Vec<AnchoredRule>, Vec<TableError>> {
2822    let text = read_to_string(path).map_err(|error| {
2823        vec![TableError::NotReadable {
2824            path: path.into(),
2825            error,
2826        }]
2827    })?;
2828    table(&text, Some(path.into()))
2829}
2830
2831/// Expands `file` and every table it includes, looking names up in `search_path`. Where that
2832/// search path comes from is the caller's business: the parser neither reads the environment nor
2833/// adds directories of its own.
2834pub fn table_expanded_in(
2835    file: &Path,
2836    search_path: &SearchPath,
2837) -> Result<Vec<AnchoredRule>, Vec<TableError>> {
2838    table_expanded_with(file, search_path, &[])
2839}
2840
2841/// `chain` holds the canonicalized path of every table currently being expanded, from the root
2842/// down to (but not including) `file` -- i.e. the ancestor chain, not a global "already seen"
2843/// set. This lets the same table be legitimately included multiple times from different
2844/// branches (a diamond dependency, common for shared base tables) while still catching a table
2845/// that includes itself, directly or transitively: each recursive call extends its own copy of
2846/// the chain, so a sibling include never sees paths pushed by another branch's descendants.
2847fn table_expanded_with(
2848    file: &Path,
2849    search_path: &SearchPath,
2850    chain: &[PathBuf],
2851) -> Result<Vec<AnchoredRule>, Vec<TableError>> {
2852    match search_path.find_file(file) {
2853        Some(path) => {
2854            let canonical = path.canonicalize().map_err(|error| {
2855                vec![TableError::NotReadable {
2856                    path: path.clone(),
2857                    error,
2858                }]
2859            })?;
2860            if chain.len() >= MAX_INCLUDE_DEPTH {
2861                return Err(vec![TableError::IncludeTooDeep(MAX_INCLUDE_DEPTH)]);
2862            }
2863            if chain.contains(&canonical) {
2864                let mut cycle = chain.to_vec();
2865                cycle.push(canonical);
2866                return Err(vec![TableError::CircularInclude(cycle)]);
2867            }
2868            let mut chain = chain.to_vec();
2869            chain.push(canonical);
2870            table_file(path.as_path()).and_then(|rules| expand_includes(rules, search_path, &chain))
2871        }
2872        None => Err(vec![TableError::NotFound(file.into())]),
2873    }
2874}
2875
2876fn expand_include(
2877    rule: AnchoredRule,
2878    search_path: &SearchPath,
2879    chain: &[PathBuf],
2880) -> Result<Vec<AnchoredRule>, Vec<TableError>> {
2881    match rule.rule {
2882        Rule::Include { ref file } => {
2883            let path = Path::new(file);
2884            if path.extension().and_then(OsStr::to_str) == Some("dic") {
2885                // Hyphenation dictionaries are liblouis's own pattern-dictionary
2886                // format (see the `hyphenation` module), not a translation table --
2887                // parse them with their own parser and embed the result.
2888                let resolved = search_path
2889                    .find_file(path)
2890                    .ok_or(vec![TableError::HyphenationNotFound(path.into())])?;
2891                let source = read_to_string(&resolved).map_err(|error| {
2892                    vec![TableError::HyphenationNotReadable {
2893                        path: resolved.clone(),
2894                        error,
2895                    }]
2896                })?;
2897                let table = HyphenationTable::parse(&source).map_err(|error| {
2898                    vec![TableError::HyphenationSyntax {
2899                        path: resolved,
2900                        error: SyntaxError(SyntaxErrorKind::Hyphenation(error)),
2901                    }]
2902                })?;
2903                return Ok(vec![AnchoredRule::new(
2904                    Rule::IncludeHyphenation { table },
2905                    rule.path,
2906                    rule.line,
2907                )]);
2908            }
2909            table_expanded_with(path, search_path, chain)
2910        }
2911        _ => Ok(vec![rule]),
2912    }
2913}
2914
2915/// Some rules contradict with each other. Check that not both are defined within the same
2916/// table.
2917fn check_conflicting_rules(rules: &[AnchoredRule]) -> Result<(), Vec<TableError>> {
2918    let mut endmodephrase: HashMap<&str, &Position> = HashMap::new();
2919    let mut endcapsphrase: Option<&Position> = None;
2920
2921    for rule in rules {
2922        match &rule.rule {
2923            // make sure all endmodephrase for the same class define the same position
2924            Rule::Endmodephrase { name, position, .. } => {
2925                let seen = endmodephrase.entry(name).or_insert(position);
2926                if *seen != position {
2927                    return Err(vec![TableError::ConflictingEndmodephrasePosition(
2928                        name.clone(),
2929                    )]);
2930                }
2931            }
2932            // make sure all endcapsphrase define the same position
2933            Rule::Endcapsphrase { position, .. } => {
2934                let seen = endcapsphrase.get_or_insert(position);
2935                if *seen != position {
2936                    return Err(vec![TableError::ConflictingEndcapsphrasePosition]);
2937                }
2938            }
2939            _ => {}
2940        }
2941    }
2942
2943    Ok(())
2944}
2945
2946/// See `table_expanded_with` for what `chain` tracks. Callers expanding a rule set that isn't
2947/// itself nested inside another include expansion (e.g. an inline/in-memory table) should pass
2948/// `&[]`.
2949pub fn expand_includes(
2950    rules: Vec<AnchoredRule>,
2951    search_path: &SearchPath,
2952    chain: &[PathBuf],
2953) -> Result<Vec<AnchoredRule>, Vec<TableError>> {
2954    let (rules, errors): (Vec<_>, Vec<_>) = rules
2955        .into_iter()
2956        .map(|r| expand_include(r, search_path, chain))
2957        .partition(Result::is_ok);
2958    let rules: Vec<_> = rules.into_iter().flat_map(Result::unwrap).collect();
2959    let errors: Vec<_> = errors.into_iter().flat_map(Result::unwrap_err).collect();
2960    if errors.is_empty() {
2961        check_conflicting_rules(&rules)?;
2962        Ok(rules)
2963    } else {
2964        Err(errors)
2965    }
2966}
2967
2968#[cfg(test)]
2969mod tests {
2970    use crate::parser::braille::{BrailleChar, BrailleDot};
2971
2972    use super::*;
2973    use enumset::enum_set;
2974
2975    #[test]
2976    fn nocross() {
2977        assert!(RuleParser::new("nocross").nocross());
2978        assert!(RuleParser::new("nocross nofor").nocross());
2979        assert!(!RuleParser::new("nofor nocross").nocross());
2980        assert!(!RuleParser::new("nofor").nocross());
2981    }
2982
2983    #[test]
2984    fn repword_separator_is_one_character() {
2985        assert!(RuleParser::new("repword - 123456").rule().is_ok());
2986        assert_eq!(
2987            RuleParser::new("rependword -- 25,123456").rule(),
2988            Err(ParseError::SingleCharExpected {
2989                found: Some("--".to_string())
2990            })
2991        );
2992    }
2993
2994    #[test]
2995    fn nofor() {
2996        assert!(RuleParser::new(" nofor ").nofor());
2997        assert!(RuleParser::new("nofor nocross").nofor());
2998        assert!(!RuleParser::new("nocross nofor").nofor());
2999        assert!(!RuleParser::new("").nofor());
3000    }
3001
3002    #[test]
3003    fn unicode_surrogate_pairs() {
3004        // A plain BMP escape is unaffected.
3005        assert_eq!(
3006            Ok('A'.to_string()),
3007            unescape("\\x0041", EscapingContext::Default)
3008        );
3009        // A high/low surrogate pair combines into the astral character it encodes.
3010        assert_eq!(
3011            Ok("🌑".to_string()),
3012            unescape("\\xD83C\\xDF11", EscapingContext::Default)
3013        );
3014        // An unpaired surrogate half can't be a real character; some tables use one
3015        // to strip stray remnants of bad UTF-16 splitting, so it maps to the
3016        // standard placeholder rather than failing the whole table.
3017        assert_eq!(
3018            Ok('\u{FFFD}'.to_string()),
3019            unescape("\\xD83D", EscapingContext::Default)
3020        );
3021    }
3022
3023    #[test]
3024    fn nocontractsign_and_nonumsign_honor_direction() {
3025        assert_eq!(
3026            enum_set!(Direction::Forward),
3027            RuleParser::new("noback nonumsign 156")
3028                .rule()
3029                .unwrap()
3030                .directions()
3031        );
3032        assert_eq!(
3033            enum_set!(Direction::Backward),
3034            RuleParser::new("nofor nocontractsign 56")
3035                .rule()
3036                .unwrap()
3037                .directions()
3038        );
3039        assert_eq!(
3040            enum_set!(Direction::Forward | Direction::Backward),
3041            RuleParser::new("nonumsign 156")
3042                .rule()
3043                .unwrap()
3044                .directions()
3045        );
3046    }
3047
3048    #[test]
3049    fn constraints() {
3050        assert_eq!(
3051            constraint_set!(Constraint::Nofor),
3052            RuleParser::new(" nofor ").constraints()
3053        );
3054        assert_eq!(
3055            constraint_set!(Constraint::Nofor | Constraint::Nocross),
3056            RuleParser::new("nofor nocross").constraints()
3057        );
3058    }
3059
3060    #[test]
3061    fn test_fail_if_invalid_constraints() {
3062        assert_eq!(
3063            Ok(()),
3064            fail_if_invalid_constraints(Constraints::empty(), Constraints::empty(), Opcode::Space)
3065        );
3066        assert_eq!(
3067            Err(ParseError::InvalidConstraints {
3068                constraints: constraint_set!(Constraint::Nofor),
3069                opcode: Opcode::Space
3070            }),
3071            fail_if_invalid_constraints(
3072                Constraints::empty(),
3073                constraint_set!(Constraint::Nofor),
3074                Opcode::Space
3075            )
3076        );
3077        assert_eq!(
3078            Err(ParseError::InvalidConstraints {
3079                constraints: constraint_set!(Constraint::Nofor | Constraint::Nocross),
3080                opcode: Opcode::Space
3081            }),
3082            fail_if_invalid_constraints(
3083                Constraints::empty(),
3084                constraint_set!(Constraint::Nofor | Constraint::Nocross),
3085                Opcode::Space
3086            )
3087        );
3088        assert_eq!(
3089            Err(ParseError::InvalidConstraints {
3090                constraints: constraint_set!(Constraint::Nocross),
3091                opcode: Opcode::Space
3092            }),
3093            fail_if_invalid_constraints(
3094                constraint_set!(Constraint::Nofor | Constraint::Noback),
3095                constraint_set!(Constraint::Nofor | Constraint::Nocross),
3096                Opcode::Space
3097            )
3098        );
3099    }
3100
3101    #[test]
3102    fn withclass() {
3103        assert_eq!(
3104            Ok(Some(WithClass::Before {
3105                class: "foo".into()
3106            })),
3107            RuleParser::new("before foo ").with_class()
3108        );
3109        assert_eq!(
3110            Ok(Some(WithClass::After {
3111                class: "foo".into()
3112            })),
3113            RuleParser::new(" after foo ").with_class()
3114        );
3115        assert_eq!(
3116            Err(ParseError::ClassNameExpected { found: None }),
3117            RuleParser::new(" after ").with_class()
3118        );
3119    }
3120
3121    #[test]
3122    fn withclasses() {
3123        assert_eq!(
3124            Ok(Some(vec![
3125                WithClass::Before {
3126                    class: "foo".into()
3127                },
3128                WithClass::After {
3129                    class: "bar".into()
3130                },
3131            ])),
3132            RuleParser::new("before foo after bar").with_classes()
3133        );
3134
3135        assert_eq!(
3136            Err(ParseError::ClassNameExpected { found: None }),
3137            RuleParser::new("before foo after").with_classes()
3138        );
3139    }
3140
3141    #[test]
3142    fn opcode() {
3143        assert_eq!(Ok(Opcode::Include), RuleParser::new("include").opcode());
3144        assert_eq!(
3145            Ok(Opcode::Always),
3146            RuleParser::new("always foo after").opcode()
3147        );
3148
3149        assert_eq!(
3150            Err(ParseError::OpcodeExpected {
3151                found: Some("h".into())
3152            }),
3153            RuleParser::new("h").opcode()
3154        );
3155        assert_eq!(
3156            Err(ParseError::OpcodeExpected {
3157                found: Some("hello".into())
3158            }),
3159            RuleParser::new("hello world").opcode()
3160        );
3161    }
3162
3163    #[test]
3164    fn with_matches() {
3165        assert_eq!(
3166            Some(HashSet::from([WithMatch::After])),
3167            RuleParser::new("empmatchafter match").with_matches()
3168        );
3169        assert_eq!(
3170            Some(HashSet::from([WithMatch::Before])),
3171            RuleParser::new("empmatchbefore match").with_matches()
3172        );
3173        assert_eq!(None, RuleParser::new("match").with_matches());
3174        assert_eq!(
3175            Some(HashSet::from([WithMatch::After, WithMatch::Before])),
3176            RuleParser::new("empmatchbefore empmatchafter match").with_matches()
3177        );
3178    }
3179
3180    #[test]
3181    fn rule() {
3182        assert_eq!(
3183            Ok(Rule::Include {
3184                file: "foo.ctb".into()
3185            }),
3186            RuleParser::new("include foo.ctb").rule()
3187        );
3188        assert_eq!(
3189            Err(ParseError::FilenameExpected),
3190            RuleParser::new("include").rule()
3191        );
3192        assert_eq!(
3193            Err(ParseError::OpcodeExpected {
3194                found: Some("Include".into())
3195            }),
3196            RuleParser::new("Include foo.ctb").rule()
3197        );
3198    }
3199
3200    #[test]
3201    fn display() {
3202        use self::braille::BrailleDot;
3203        assert_eq!(
3204            Ok(Rule::Display {
3205                character: 'a',
3206                dots: BrailleChar::from(enum_set!(BrailleDot::Dot1)),
3207                constraints: Constraints::empty()
3208            }),
3209            RuleParser::new("display a 1").rule()
3210        );
3211    }
3212
3213    #[test]
3214    fn correct() {
3215        assert_eq!(
3216            Ok(Rule::Correct {
3217                test: Test::new(vec![TestInstruction::String { s: "a".into() }]),
3218                action: Action::new(vec![ActionInstruction::String { s: "b".into() }]),
3219                constraints: constraint_set!(Constraint::Noback)
3220            }),
3221            RuleParser::new("noback correct \"a\" \"b\"").rule()
3222        );
3223    }
3224
3225    #[test]
3226    fn swapdd() {
3227        assert_eq!(
3228            Ok(Rule::Swapdd { name: "cancelcontraction".to_string(), dots: BrailleChars::from(vec![
3229		BrailleChar::from(enum_set!(BrailleDot::Dot2|BrailleDot::DotA)),
3230		BrailleChar::from(enum_set!(BrailleDot::Dot2|BrailleDot::Dot3|BrailleDot::DotA)),
3231		BrailleChar::from(enum_set!(BrailleDot::Dot2|BrailleDot::Dot5|BrailleDot::DotA)),
3232		BrailleChar::from(enum_set!(BrailleDot::Dot2|BrailleDot::Dot5|BrailleDot::Dot6|BrailleDot::DotA)),
3233		BrailleChar::from(enum_set!(BrailleDot::Dot2|BrailleDot::Dot6|BrailleDot::DotA)),
3234		BrailleChar::from(enum_set!(BrailleDot::Dot3|BrailleDot::Dot5|BrailleDot::DotA)),
3235		BrailleChar::from(enum_set!(BrailleDot::Dot2|BrailleDot::Dot3|BrailleDot::Dot6|BrailleDot::DotA)),
3236	    ]), replacement: vec![
3237		BrailleChars::from(vec![
3238		    BrailleChar::from(enum_set!(BrailleDot::Dot1)),
3239		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot2))]),
3240		BrailleChars::from(vec![
3241		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot2)),
3242		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot2|BrailleDot::Dot3|BrailleDot::Dot5))]),
3243		BrailleChars::from(vec![
3244		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot4)),
3245		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot2|BrailleDot::Dot3|BrailleDot::Dot5))]),
3246		BrailleChars::from(vec![
3247		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot4|BrailleDot::Dot5)),
3248		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot2|BrailleDot::Dot3|BrailleDot::Dot5))]),
3249		BrailleChars::from(vec![
3250		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot5)),
3251		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot3|BrailleDot::Dot4|BrailleDot::Dot5))]),
3252		BrailleChars::from(vec![
3253		    BrailleChar::from(enum_set!(BrailleDot::Dot2|BrailleDot::Dot4)),
3254		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot3|BrailleDot::Dot4|BrailleDot::Dot5))]),
3255		BrailleChars::from(vec![
3256		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot5)),
3257		    BrailleChar::from(enum_set!(BrailleDot::Dot1|BrailleDot::Dot2|BrailleDot::Dot3|BrailleDot::Dot5))]),
3258	    ]}),
3259            RuleParser::new("swapdd cancelcontraction 2a,23a,25a,256a,26a,35a,236a 1-12,12-1235,14-1235,145-1235,15-1345,24-1345,15-1235").rule()
3260        );
3261    }
3262
3263    #[test]
3264    fn swapdd_rejects_multi_cell_in_search_operand() {
3265        // Per the manual (doc/liblouis.texi): the search operand of `swapdd` must be
3266        // single cells; multi-cell patterns there would be ambiguous. Only the
3267        // replacement operand may use them.
3268        assert_eq!(
3269            Err(ParseError::SingleCellDotsExpected {
3270                found: "156-2".to_string()
3271            }),
3272            RuleParser::new("swapdd Aheadbrl 156,156-2,24,124 156,156-2,24,124").rule()
3273        );
3274    }
3275
3276    #[test]
3277    fn grouping() {
3278        assert_eq!(
3279            Ok(Rule::Grouping {
3280                name: "brackets".to_string(),
3281                chars: "()".to_string(),
3282                left: BrailleChar::from(enum_set!(
3283                    BrailleDot::Dot1 | BrailleDot::Dot2 | BrailleDot::Dot3
3284                )),
3285                right: BrailleChar::from(enum_set!(
3286                    BrailleDot::Dot1 | BrailleDot::Dot4 | BrailleDot::Dot5
3287                ))
3288            }),
3289            RuleParser::new("grouping brackets () 123,145").rule()
3290        );
3291        assert_eq!(
3292            Err(ParseError::DotsTupleExpected),
3293            RuleParser::new("grouping brackets () 123").rule()
3294        );
3295    }
3296
3297    /// Sets up a scratch directory (removing any leftovers from a previous run) for a
3298    /// table-inclusion test and returns a [`SearchPath`] rooted at it -- built directly from the
3299    /// directory rather than via [`SearchPath::new_or`], so tests don't need to touch the
3300    /// process-wide `LOUIS_TABLE_PATH` env var (which would race with other tests).
3301    fn include_test_dir(name: &str) -> (PathBuf, SearchPath) {
3302        let dir = std::env::temp_dir().join(format!("louis-rs-include-test-{name}"));
3303        let _ = std::fs::remove_dir_all(&dir);
3304        std::fs::create_dir_all(&dir).unwrap();
3305        let search_path = SearchPath::from(dir.clone());
3306        (dir, search_path)
3307    }
3308
3309    #[test]
3310    fn table_expanded_rejects_self_include() {
3311        let (dir, search_path) = include_test_dir("self");
3312        std::fs::write(dir.join("a.utb"), "include a.utb\n").unwrap();
3313        let result = table_expanded_with(Path::new("a.utb"), &search_path, &[]);
3314        assert!(matches!(
3315            result,
3316            Err(errors) if matches!(errors.as_slice(), [TableError::CircularInclude(_)])
3317        ));
3318    }
3319
3320    #[test]
3321    fn table_expanded_rejects_indirect_cycle() {
3322        let (dir, search_path) = include_test_dir("indirect-cycle");
3323        std::fs::write(dir.join("a.utb"), "include b.utb\n").unwrap();
3324        std::fs::write(dir.join("b.utb"), "include a.utb\n").unwrap();
3325        let result = table_expanded_with(Path::new("a.utb"), &search_path, &[]);
3326        assert!(matches!(
3327            result,
3328            Err(errors) if matches!(errors.as_slice(), [TableError::CircularInclude(_)])
3329        ));
3330    }
3331
3332    #[test]
3333    fn table_expanded_rejects_deep_include_chain() {
3334        let (dir, search_path) = include_test_dir("deep-chain");
3335        std::fs::write(dir.join("chain0.utb"), "space \\s 0\n").unwrap();
3336        for i in 1..=MAX_INCLUDE_DEPTH {
3337            std::fs::write(
3338                dir.join(format!("chain{i}.utb")),
3339                format!("include chain{}.utb\n", i - 1),
3340            )
3341            .unwrap();
3342        }
3343        let result = table_expanded_with(
3344            Path::new(&format!("chain{MAX_INCLUDE_DEPTH}.utb")),
3345            &search_path,
3346            &[],
3347        );
3348        assert!(matches!(
3349            result,
3350            Err(errors) if matches!(errors.as_slice(), [TableError::IncludeTooDeep(_)])
3351        ));
3352    }
3353
3354    #[test]
3355    fn table_expanded_allows_diamond_include() {
3356        // The same table included from two different branches (a shared base table, common in
3357        // liblouis) is not a cycle and must succeed.
3358        let (dir, search_path) = include_test_dir("diamond");
3359        std::fs::write(dir.join("base.utb"), "space \\s 0\n").unwrap();
3360        std::fs::write(dir.join("left.utb"), "include base.utb\n").unwrap();
3361        std::fs::write(dir.join("right.utb"), "include base.utb\n").unwrap();
3362        std::fs::write(dir.join("top.utb"), "include left.utb\ninclude right.utb\n").unwrap();
3363        let result = table_expanded_with(Path::new("top.utb"), &search_path, &[]);
3364        assert!(result.is_ok());
3365    }
3366
3367    #[test]
3368    fn table_expanded_rejects_endmodephrase_conflicting_across_includes() {
3369        // Neither included table conflicts with itself; the conflict only exists once both
3370        // are merged into one table, which is exactly the case a per-direction compile-time
3371        // check would miss if this table were never compiled backward.
3372        let (dir, search_path) = include_test_dir("endmodephrase-conflict");
3373        std::fs::write(dir.join("before.utb"), "endmodephrase foo before 2\n").unwrap();
3374        std::fs::write(dir.join("after.utb"), "endmodephrase foo after 2\n").unwrap();
3375        std::fs::write(
3376            dir.join("top.utb"),
3377            "include before.utb\ninclude after.utb\n",
3378        )
3379        .unwrap();
3380        let result = table_expanded_with(Path::new("top.utb"), &search_path, &[]);
3381        assert!(matches!(
3382            result,
3383            Err(errors) if matches!(
3384                errors.as_slice(),
3385                [TableError::ConflictingEndmodephrasePosition(name)] if name == "foo"
3386            )
3387        ));
3388    }
3389
3390    #[test]
3391    fn table_expanded_allows_endmodephrase_repeated_same_position() {
3392        let (dir, search_path) = include_test_dir("endmodephrase-repeat");
3393        std::fs::write(dir.join("a.utb"), "endmodephrase foo before 2\n").unwrap();
3394        std::fs::write(dir.join("b.utb"), "endmodephrase foo before 2\n").unwrap();
3395        std::fs::write(dir.join("top.utb"), "include a.utb\ninclude b.utb\n").unwrap();
3396        let result = table_expanded_with(Path::new("top.utb"), &search_path, &[]);
3397        assert!(result.is_ok());
3398    }
3399
3400    #[test]
3401    fn table_expanded_rejects_endcapsphrase_conflicting_across_includes() {
3402        let (dir, search_path) = include_test_dir("endcapsphrase-conflict");
3403        std::fs::write(dir.join("before.utb"), "endcapsphrase before 2\n").unwrap();
3404        std::fs::write(dir.join("after.utb"), "endcapsphrase after 2\n").unwrap();
3405        std::fs::write(
3406            dir.join("top.utb"),
3407            "include before.utb\ninclude after.utb\n",
3408        )
3409        .unwrap();
3410        let result = table_expanded_with(Path::new("top.utb"), &search_path, &[]);
3411        assert!(matches!(
3412            result,
3413            Err(errors) if matches!(errors.as_slice(), [TableError::ConflictingEndcapsphrasePosition])
3414        ));
3415    }
3416}