antlr4_runtime/atn/
serialized.rs

1use std::borrow::Cow;
2
3use crate::atn::parser_atn::{
4    ParserAtn, ParserAtnBuilder, ParserAtnError, ParserIntervalSetId, ParserTransitionSpec,
5};
6use crate::atn::{
7    AtnStateKind, IntervalSet, LexerAction, LexerAtn, LexerAtnState, LexerTransition,
8};
9use crate::errors::AntlrError;
10use crate::token::TOKEN_EOF;
11
12pub const SERIALIZED_VERSION: i32 = 4;
13
14/// Raw integer form of an ANTLR v4 serialized ATN.
15///
16/// ANTLR targets commonly embed this data as strings or integer arrays. The
17/// Rust generator emits integer arrays from `.interp` files, while
18/// `from_chars` supports targets that encode ATN values in string literals.
19#[derive(Clone, Debug)]
20pub struct SerializedAtn<'a> {
21    values: Cow<'a, [i32]>,
22}
23
24impl<'a> SerializedAtn<'a> {
25    /// Creates serialized ATN data from an already-decoded integer array.
26    pub const fn from_i32(values: &'a [i32]) -> Self {
27        Self {
28            values: Cow::Borrowed(values),
29        }
30    }
31
32    /// Creates serialized ATN data by widening each character to its scalar
33    /// value.
34    ///
35    /// This is useful for ANTLR targets that store serialized ATN data in
36    /// string fragments. Java-style 16-bit word decoding is not applied here;
37    /// callers should pass already-decoded characters for now.
38    pub fn from_chars(chars: impl IntoIterator<Item = char>) -> SerializedAtn<'static> {
39        SerializedAtn {
40            values: Cow::Owned(chars.into_iter().map(|ch| ch as i32).collect()),
41        }
42    }
43
44    pub fn values(&self) -> &[i32] {
45        &self.values
46    }
47}
48
49/// Cursor-based decoder for ANTLR v4 serialized ATN data.
50#[derive(Debug)]
51pub struct AtnDeserializer<'a> {
52    values: &'a [i32],
53    cursor: usize,
54}
55
56impl<'a> AtnDeserializer<'a> {
57    /// Creates a deserializer over immutable serialized ATN storage.
58    pub fn new(serialized: &'a SerializedAtn<'_>) -> Self {
59        Self {
60            values: serialized.values(),
61            cursor: 0,
62        }
63    }
64
65    /// Decodes an ANTLR v4 serialized lexer ATN into the lexer graph.
66    ///
67    /// The layout is order-sensitive: states come first, followed by non-greedy
68    /// and precedence markers, rule tables, mode starts, interval sets, edges,
69    /// decisions, and lexer actions. This method keeps ANTLR's side tables as
70    /// explicit vectors because lexer simulation needs them without depending
71    /// on generated per-rule code. Parser input is rejected; use
72    /// [`Self::deserialize_parser`] for the packed parser representation.
73    pub fn deserialize(mut self) -> Result<LexerAtn, AntlrError> {
74        let version = self.read("version")?;
75        if version != SERIALIZED_VERSION {
76            return Err(AntlrError::Unsupported(format!(
77                "serialized ATN version {version}; expected {SERIALIZED_VERSION}"
78            )));
79        }
80
81        match self.read("grammar type")? {
82            0 => {}
83            1 => {
84                return Err(AntlrError::Unsupported(
85                    "parser ATNs require AtnDeserializer::deserialize_parser()".to_owned(),
86                ));
87            }
88            other => {
89                return Err(AntlrError::Unsupported(format!(
90                    "serialized ATN grammar type {other}"
91                )));
92            }
93        }
94        let max_token_type = self.read("max token type")?;
95        let mut atn = LexerAtn::new(max_token_type);
96
97        self.deserialize_states(&mut atn)?;
98        self.deserialize_non_greedy_states(&mut atn)?;
99        self.deserialize_precedence_states(&mut atn)?;
100        self.deserialize_rules(&mut atn)?;
101        self.deserialize_modes(&mut atn)?;
102        let sets = self.deserialize_sets()?;
103        self.deserialize_edges(&mut atn, &sets)?;
104        self.deserialize_decisions(&mut atn)?;
105        self.deserialize_lexer_actions(&mut atn)?;
106        mark_precedence_decisions(&mut atn);
107
108        Ok(atn)
109    }
110
111    /// Decodes parser metadata directly into the packed parser-only runtime
112    /// representation.
113    ///
114    /// No lexer object graph is constructed. Temporary state and edge records
115    /// live in centralized builder vectors, then become one validated
116    /// index-addressed word stream.
117    pub fn deserialize_parser(mut self) -> Result<ParserAtn, AntlrError> {
118        self.deserialize_parser_header()?;
119        let max_token_type = self.read("max token type")?;
120        let mut builder = ParserAtnBuilder::new(max_token_type);
121        self.deserialize_parser_states(&mut builder)?;
122        self.deserialize_parser_flags(&mut builder)?;
123        self.deserialize_parser_rules(&mut builder)?;
124        self.deserialize_parser_modes(&builder)?;
125        let sets = self.deserialize_parser_sets(&mut builder)?;
126        self.deserialize_parser_edges(&mut builder, &sets)?;
127        self.deserialize_parser_decisions(&mut builder)?;
128        if self.cursor != self.values.len() {
129            return Err(AntlrError::Unsupported(format!(
130                "serialized parser ATN has {} trailing values",
131                self.values.len() - self.cursor
132            )));
133        }
134        builder.finish().map_err(|error| parser_atn_error(&error))
135    }
136
137    fn deserialize_parser_header(&mut self) -> Result<(), AntlrError> {
138        let version = self.read("version")?;
139        if version != SERIALIZED_VERSION {
140            return Err(AntlrError::Unsupported(format!(
141                "serialized ATN version {version}; expected {SERIALIZED_VERSION}"
142            )));
143        }
144        let grammar_type = self.read("grammar type")?;
145        if grammar_type != 1 {
146            return Err(AntlrError::Unsupported(format!(
147                "serialized parser ATN has grammar type {grammar_type}; expected 1"
148            )));
149        }
150        Ok(())
151    }
152
153    fn deserialize_parser_states(
154        &mut self,
155        builder: &mut ParserAtnBuilder,
156    ) -> Result<(), AntlrError> {
157        let state_count = self.read_usize("state count")?;
158        let mut end_states = Vec::new();
159        let mut loop_back_states = Vec::new();
160        for _ in 0..state_count {
161            let kind = decode_state_kind(self.read("state type")?)?;
162            if kind == AtnStateKind::Invalid {
163                builder
164                    .add_state(kind, None)
165                    .map_err(|error| parser_atn_error(&error))?;
166                continue;
167            }
168            let raw_rule_index = self.read("rule index")?;
169            let rule_index = (raw_rule_index >= 0)
170                .then(|| read_index(raw_rule_index, "state rule index"))
171                .transpose()?;
172            let state = builder
173                .add_state(kind, rule_index)
174                .map_err(|error| parser_atn_error(&error))?
175                .index();
176            match kind {
177                AtnStateKind::LoopEnd => {
178                    let target = self.read_usize("loop back state")?;
179                    loop_back_states.push((state, target));
180                }
181                AtnStateKind::BlockStart
182                | AtnStateKind::PlusBlockStart
183                | AtnStateKind::StarBlockStart => {
184                    let target = self.read_usize("block end state")?;
185                    end_states.push((state, target));
186                }
187                _ => {}
188            }
189        }
190        for (state, target) in end_states {
191            builder
192                .set_end_state(state, target)
193                .map_err(|error| parser_atn_error(&error))?;
194        }
195        for (state, target) in loop_back_states {
196            builder
197                .set_loop_back_state(state, target)
198                .map_err(|error| parser_atn_error(&error))?;
199        }
200        Ok(())
201    }
202
203    fn deserialize_parser_flags(
204        &mut self,
205        builder: &mut ParserAtnBuilder,
206    ) -> Result<(), AntlrError> {
207        let non_greedy_count = self.read_usize("non-greedy state count")?;
208        for _ in 0..non_greedy_count {
209            let state = self.read_usize("non-greedy state")?;
210            builder
211                .set_non_greedy(state)
212                .map_err(|error| parser_atn_error(&error))?;
213        }
214        let precedence_count = self.read_usize("precedence state count")?;
215        for _ in 0..precedence_count {
216            let state = self.read_usize("precedence state")?;
217            builder
218                .set_left_recursive_rule(state)
219                .map_err(|error| parser_atn_error(&error))?;
220        }
221        Ok(())
222    }
223
224    fn deserialize_parser_rules(
225        &mut self,
226        builder: &mut ParserAtnBuilder,
227    ) -> Result<(), AntlrError> {
228        let rule_count = self.read_usize("rule count")?;
229        let mut starts = Vec::with_capacity(rule_count);
230        for _ in 0..rule_count {
231            starts.push(self.read_usize("rule start state")?);
232        }
233        let mut stops = vec![None; rule_count];
234        for state in 0..builder.state_count() {
235            let kind = builder
236                .state_kind(state)
237                .expect("state count bounds builder state lookup");
238            if kind != AtnStateKind::RuleStop {
239                continue;
240            }
241            let Some(rule_index) = builder.state_rule_index(state) else {
242                continue;
243            };
244            if let Some(stop) = stops.get_mut(rule_index) {
245                *stop = Some(state);
246            }
247        }
248        let stops = stops
249            .into_iter()
250            .enumerate()
251            .map(|(rule, stop)| {
252                stop.ok_or_else(|| {
253                    AntlrError::Unsupported(format!(
254                        "serialized parser ATN has no stop state for rule {rule}"
255                    ))
256                })
257            })
258            .collect::<Result<Vec<_>, _>>()?;
259        builder
260            .set_rule_to_start_state(starts)
261            .map_err(|error| parser_atn_error(&error))?;
262        builder
263            .set_rule_to_stop_state(stops)
264            .map_err(|error| parser_atn_error(&error))?;
265        Ok(())
266    }
267
268    fn deserialize_parser_modes(&mut self, builder: &ParserAtnBuilder) -> Result<(), AntlrError> {
269        let mode_count = self.read_usize("mode count")?;
270        for _ in 0..mode_count {
271            let state = self.read_usize("mode start state")?;
272            if builder.state_kind(state).is_none() {
273                return Err(AntlrError::Unsupported(format!(
274                    "mode start state {state} outside state list"
275                )));
276            }
277        }
278        Ok(())
279    }
280
281    fn deserialize_parser_sets(
282        &mut self,
283        builder: &mut ParserAtnBuilder,
284    ) -> Result<Vec<ParserIntervalSetId>, AntlrError> {
285        let set_count = self.read_usize("set count")?;
286        let mut sets = Vec::with_capacity(set_count);
287        for _ in 0..set_count {
288            let interval_count = self.read_usize("interval count")?;
289            let contains_eof = self.read("set contains EOF")? != 0;
290            let mut ranges = Vec::with_capacity(interval_count + usize::from(contains_eof));
291            if contains_eof {
292                ranges.push((TOKEN_EOF, TOKEN_EOF));
293            }
294            for _ in 0..interval_count {
295                ranges.push((self.read("interval start")?, self.read("interval stop")?));
296            }
297            sets.push(
298                builder
299                    .add_interval_set(ranges)
300                    .map_err(|error| parser_atn_error(&error))?,
301            );
302        }
303        Ok(sets)
304    }
305
306    fn deserialize_parser_edges(
307        &mut self,
308        builder: &mut ParserAtnBuilder,
309        sets: &[ParserIntervalSetId],
310    ) -> Result<(), AntlrError> {
311        let transition_count = self.read_usize("transition count")?;
312        for _ in 0..transition_count {
313            let source = self.read_usize("transition source")?;
314            let target = self.read_usize("transition target")?;
315            let kind = self.read("transition type")?;
316            let a = self.read("transition arg 1")?;
317            let b = self.read("transition arg 2")?;
318            let c = self.read("transition arg 3")?;
319            let transition = decode_parser_transition(target, kind, a, b, c, sets)?;
320            builder
321                .add_transition(source, transition)
322                .map_err(|error| parser_atn_error(&error))?;
323        }
324        add_parser_rule_return_edges(builder)
325    }
326
327    fn deserialize_parser_decisions(
328        &mut self,
329        builder: &mut ParserAtnBuilder,
330    ) -> Result<(), AntlrError> {
331        let decision_count = self.read_usize("decision count")?;
332        for _ in 0..decision_count {
333            let state = self.read_usize("decision state")?;
334            builder
335                .add_decision_state(state)
336                .map_err(|error| parser_atn_error(&error))?;
337        }
338        Ok(())
339    }
340
341    /// Reads all serialized ATN states and preserves state-specific paired
342    /// links such as block end states and loop-back states.
343    fn deserialize_states(&mut self, atn: &mut LexerAtn) -> Result<(), AntlrError> {
344        let state_count = self.read_usize("state count")?;
345        for state_number in 0..state_count {
346            let kind = decode_state_kind(self.read("state type")?)?;
347            if kind == AtnStateKind::Invalid {
348                atn.add_state(LexerAtnState::new(state_number, kind));
349                continue;
350            }
351
352            let rule_index = self.read("rule index")?;
353            let mut state = LexerAtnState::new(state_number, kind);
354            if rule_index >= 0 {
355                let rule_index = usize::try_from(rule_index).map_err(|_| {
356                    AntlrError::Unsupported(format!("rule index cannot be negative: {rule_index}"))
357                })?;
358                state = state.with_rule_index(rule_index);
359            }
360
361            match kind {
362                AtnStateKind::LoopEnd => {
363                    state.loop_back_state = Some(self.read_usize("loop back state")?);
364                }
365                AtnStateKind::BlockStart
366                | AtnStateKind::PlusBlockStart
367                | AtnStateKind::StarBlockStart => {
368                    state.end_state = Some(self.read_usize("block end state")?);
369                }
370                _ => {}
371            }
372
373            atn.add_state(state);
374        }
375        Ok(())
376    }
377
378    /// Marks lexer and parser decision states that ANTLR encoded as
379    /// non-greedy.
380    fn deserialize_non_greedy_states(&mut self, atn: &mut LexerAtn) -> Result<(), AntlrError> {
381        let count = self.read_usize("non-greedy state count")?;
382        for _ in 0..count {
383            let state_number = self.read_usize("non-greedy state")?;
384            let Some(state) = atn.state_mut(state_number) else {
385                return Err(AntlrError::Unsupported(format!(
386                    "non-greedy state {state_number} outside state list"
387                )));
388            };
389            state.non_greedy = true;
390        }
391        Ok(())
392    }
393
394    /// Marks rule-start states that ANTLR generated for left-recursive
395    /// precedence rules.
396    fn deserialize_precedence_states(&mut self, atn: &mut LexerAtn) -> Result<(), AntlrError> {
397        let count = self.read_usize("precedence state count")?;
398        for _ in 0..count {
399            let state_number = self.read_usize("precedence state")?;
400            let Some(state) = atn.state_mut(state_number) else {
401                return Err(AntlrError::Unsupported(format!(
402                    "precedence state {state_number} outside state list"
403                )));
404            };
405            state.left_recursive_rule = true;
406        }
407        Ok(())
408    }
409
410    /// Decodes rule start states, lexer token types, and derived rule stop
411    /// states.
412    fn deserialize_rules(&mut self, atn: &mut LexerAtn) -> Result<(), AntlrError> {
413        let rule_count = self.read_usize("rule count")?;
414        let mut starts = Vec::with_capacity(rule_count);
415        let mut token_types = Vec::new();
416        for _ in 0..rule_count {
417            starts.push(self.read_usize("rule start state")?);
418            token_types.push(self.read("rule token type")?);
419        }
420
421        let mut stops = vec![usize::MAX; rule_count];
422        for state in atn.states() {
423            if state.kind == AtnStateKind::RuleStop {
424                let Some(rule_index) = state.rule_index else {
425                    continue;
426                };
427                if let Some(stop) = stops.get_mut(rule_index) {
428                    *stop = state.state_number;
429                }
430            }
431        }
432
433        atn.set_rule_to_start_state(starts);
434        atn.set_rule_to_stop_state(stops);
435        atn.set_rule_to_token_type(token_types);
436        Ok(())
437    }
438
439    /// Decodes lexer mode entry states.
440    fn deserialize_modes(&mut self, atn: &mut LexerAtn) -> Result<(), AntlrError> {
441        let mode_count = self.read_usize("mode count")?;
442        for _ in 0..mode_count {
443            atn.add_mode_start_state(self.read_usize("mode start state")?);
444        }
445        Ok(())
446    }
447
448    /// Decodes all interval sets referenced by `SET` and `NOT_SET`
449    /// transitions.
450    fn deserialize_sets(&mut self) -> Result<Vec<IntervalSet>, AntlrError> {
451        let set_count = self.read_usize("set count")?;
452        let mut sets = Vec::with_capacity(set_count);
453        for _ in 0..set_count {
454            let interval_count = self.read_usize("interval count")?;
455            let mut set = IntervalSet::new();
456            let contains_eof = self.read("set contains EOF")? != 0;
457            if contains_eof {
458                set.add(TOKEN_EOF);
459            }
460            for _ in 0..interval_count {
461                let start = self.read("interval start")?;
462                let stop = self.read("interval stop")?;
463                set.add_range(start, stop);
464            }
465            sets.push(set);
466        }
467        Ok(sets)
468    }
469
470    /// Decodes serialized edges and appends derived rule-return epsilon edges.
471    fn deserialize_edges(
472        &mut self,
473        atn: &mut LexerAtn,
474        sets: &[IntervalSet],
475    ) -> Result<(), AntlrError> {
476        let transition_count = self.read_usize("transition count")?;
477        for _ in 0..transition_count {
478            let src = self.read_usize("transition source")?;
479            let target = self.read_usize("transition target")?;
480            let kind = self.read("transition type")?;
481            let a = self.read("transition arg 1")?;
482            let b = self.read("transition arg 2")?;
483            let c = self.read("transition arg 3")?;
484            let transition = decode_transition(target, kind, a, b, c, sets)?;
485            let Some(state) = atn.state_mut(src) else {
486                return Err(AntlrError::Unsupported(format!(
487                    "transition source {src} outside state list"
488                )));
489            };
490            state.add_transition(transition);
491        }
492
493        let mut return_edges = Vec::new();
494        for state in atn.states() {
495            for transition in &state.transitions {
496                let LexerTransition::Rule {
497                    target,
498                    follow_state,
499                    ..
500                } = transition
501                else {
502                    continue;
503                };
504                let Some(rule_index) = atn.state(*target).and_then(|state| state.rule_index) else {
505                    continue;
506                };
507                let Some(stop_state) = atn.rule_to_stop_state().get(rule_index).copied() else {
508                    continue;
509                };
510                if stop_state != usize::MAX {
511                    return_edges.push((stop_state, *follow_state));
512                }
513            }
514        }
515        for (stop_state, follow_state) in return_edges {
516            if let Some(state) = atn.state_mut(stop_state) {
517                state.add_transition(LexerTransition::Epsilon {
518                    target: follow_state,
519                });
520            }
521        }
522
523        Ok(())
524    }
525
526    /// Decodes parser/lexer decision entry states in decision-number order.
527    fn deserialize_decisions(&mut self, atn: &mut LexerAtn) -> Result<(), AntlrError> {
528        let decision_count = self.read_usize("decision count")?;
529        for _ in 0..decision_count {
530            atn.add_decision_state(self.read_usize("decision state")?);
531        }
532        Ok(())
533    }
534
535    /// Decodes grammar-independent lexer actions referenced by action
536    /// transitions.
537    fn deserialize_lexer_actions(&mut self, atn: &mut LexerAtn) -> Result<(), AntlrError> {
538        let action_count = self.read_usize("lexer action count")?;
539        let mut actions = Vec::with_capacity(action_count);
540        for _ in 0..action_count {
541            let action_type = self.read("lexer action type")?;
542            let data1 = self.read("lexer action data 1")?;
543            let data2 = self.read("lexer action data 2")?;
544            actions.push(decode_lexer_action(action_type, data1, data2)?);
545        }
546        atn.set_lexer_actions(actions);
547        Ok(())
548    }
549
550    /// Reads the next integer and reports which logical field was expected if
551    /// the data ends early.
552    fn read(&mut self, label: &str) -> Result<i32, AntlrError> {
553        let value = self.values.get(self.cursor).copied().ok_or_else(|| {
554            AntlrError::Unsupported(format!("serialized ATN ended while reading {label}"))
555        })?;
556        self.cursor += 1;
557        Ok(value)
558    }
559
560    /// Reads the next integer as a non-negative state/table count or index.
561    fn read_usize(&mut self, label: &str) -> Result<usize, AntlrError> {
562        let value = self.read(label)?;
563        usize::try_from(value)
564            .map_err(|_| AntlrError::Unsupported(format!("{label} cannot be negative: {value}")))
565    }
566}
567
568/// Converts ANTLR's serialized state integer into the runtime state enum.
569fn decode_state_kind(value: i32) -> Result<AtnStateKind, AntlrError> {
570    let kind = match value {
571        0 => AtnStateKind::Invalid,
572        1 => AtnStateKind::Basic,
573        2 => AtnStateKind::RuleStart,
574        3 => AtnStateKind::BlockStart,
575        4 => AtnStateKind::PlusBlockStart,
576        5 => AtnStateKind::StarBlockStart,
577        6 => AtnStateKind::TokenStart,
578        7 => AtnStateKind::RuleStop,
579        8 => AtnStateKind::BlockEnd,
580        9 => AtnStateKind::StarLoopBack,
581        10 => AtnStateKind::StarLoopEntry,
582        11 => AtnStateKind::PlusLoopBack,
583        12 => AtnStateKind::LoopEnd,
584        other => return Err(AntlrError::Unsupported(format!("ATN state type {other}"))),
585    };
586    Ok(kind)
587}
588
589/// Converts one serialized edge record into a typed transition.
590fn decode_transition(
591    target: usize,
592    kind: i32,
593    a: i32,
594    b: i32,
595    c: i32,
596    sets: &[IntervalSet],
597) -> Result<LexerTransition, AntlrError> {
598    let transition = match kind {
599        1 => LexerTransition::Epsilon { target },
600        2 => LexerTransition::Range {
601            target,
602            start: if c != 0 { TOKEN_EOF } else { a },
603            stop: b,
604        },
605        3 => LexerTransition::Rule {
606            target: read_index(a, "rule transition target")?,
607            rule_index: read_index(b, "rule transition rule index")?,
608            follow_state: target,
609            precedence: c,
610        },
611        4 => LexerTransition::Predicate {
612            target,
613            rule_index: read_index(a, "predicate rule index")?,
614            pred_index: read_index(b, "predicate index")?,
615            context_dependent: c != 0,
616        },
617        5 => LexerTransition::Atom {
618            target,
619            label: if c != 0 { TOKEN_EOF } else { a },
620        },
621        6 => LexerTransition::Action {
622            target,
623            rule_index: read_index(a, "action rule index")?,
624            action_index: usize::try_from(b).ok(),
625            context_dependent: c != 0,
626        },
627        7 => LexerTransition::Set {
628            target,
629            set: sets
630                .get(read_index(a, "set transition set index")?)
631                .cloned()
632                .ok_or_else(|| {
633                    AntlrError::Unsupported(format!("set index {a} outside set list"))
634                })?,
635        },
636        8 => LexerTransition::NotSet {
637            target,
638            set: sets
639                .get(read_index(a, "not-set transition set index")?)
640                .cloned()
641                .ok_or_else(|| {
642                    AntlrError::Unsupported(format!("set index {a} outside set list"))
643                })?,
644        },
645        9 => LexerTransition::Wildcard { target },
646        10 => LexerTransition::Precedence {
647            target,
648            precedence: a,
649        },
650        other => {
651            return Err(AntlrError::Unsupported(format!(
652                "ATN transition type {other}"
653            )));
654        }
655    };
656    Ok(transition)
657}
658
659/// Converts one serialized parser edge directly into a packed-builder record.
660fn decode_parser_transition(
661    target: usize,
662    kind: i32,
663    a: i32,
664    b: i32,
665    c: i32,
666    sets: &[ParserIntervalSetId],
667) -> Result<ParserTransitionSpec, AntlrError> {
668    let transition = match kind {
669        1 => ParserTransitionSpec::Epsilon { target },
670        2 => ParserTransitionSpec::Range {
671            target,
672            start: if c != 0 { TOKEN_EOF } else { a },
673            stop: b,
674        },
675        3 => ParserTransitionSpec::Rule {
676            target: read_index(a, "rule transition target")?,
677            rule_index: read_index(b, "rule transition rule index")?,
678            follow_state: target,
679            precedence: c,
680        },
681        4 => ParserTransitionSpec::Predicate {
682            target,
683            rule_index: read_index(a, "predicate rule index")?,
684            pred_index: read_index(b, "predicate index")?,
685            context_dependent: c != 0,
686        },
687        5 => ParserTransitionSpec::Atom {
688            target,
689            label: if c != 0 { TOKEN_EOF } else { a },
690        },
691        6 => ParserTransitionSpec::Action {
692            target,
693            rule_index: read_index(a, "action rule index")?,
694            action_index: usize::try_from(b).ok(),
695            context_dependent: c != 0,
696        },
697        7 => ParserTransitionSpec::Set {
698            target,
699            set: parser_set_id(sets, a, "set transition")?,
700        },
701        8 => ParserTransitionSpec::NotSet {
702            target,
703            set: parser_set_id(sets, a, "not-set transition")?,
704        },
705        9 => ParserTransitionSpec::Wildcard { target },
706        10 => ParserTransitionSpec::Precedence {
707            target,
708            precedence: a,
709        },
710        other => {
711            return Err(AntlrError::Unsupported(format!(
712                "ATN transition type {other}"
713            )));
714        }
715    };
716    Ok(transition)
717}
718
719fn parser_set_id(
720    sets: &[ParserIntervalSetId],
721    value: i32,
722    label: &str,
723) -> Result<ParserIntervalSetId, AntlrError> {
724    let index = read_index(value, label)?;
725    sets.get(index).copied().ok_or_else(|| {
726        AntlrError::Unsupported(format!("{label} set index {value} outside set list"))
727    })
728}
729
730/// Adds ANTLR's derived epsilon returns without constructing per-state edge
731/// vectors. The builder keeps the original edge order for each stop state and
732/// appends these derived returns after serialized edges.
733fn add_parser_rule_return_edges(builder: &mut ParserAtnBuilder) -> Result<(), AntlrError> {
734    let mut return_edges = Vec::new();
735    for source in 0..builder.state_count() {
736        for transition in builder.transitions_from(source) {
737            let ParserTransitionSpec::Rule {
738                target,
739                follow_state,
740                ..
741            } = transition
742            else {
743                continue;
744            };
745            let Some(rule_index) = builder.state_rule_index(target) else {
746                continue;
747            };
748            let Some(stop_state) = builder.rule_stop_state(rule_index) else {
749                continue;
750            };
751            return_edges.push((stop_state, follow_state));
752        }
753    }
754    for (stop_state, follow_state) in return_edges {
755        builder
756            .add_transition(
757                stop_state,
758                ParserTransitionSpec::Epsilon {
759                    target: follow_state,
760                },
761            )
762            .map_err(|error| parser_atn_error(&error))?;
763    }
764    Ok(())
765}
766
767fn parser_atn_error(error: &ParserAtnError) -> AntlrError {
768    AntlrError::Unsupported(error.to_string())
769}
770
771/// Converts ANTLR's serialized lexer action ordinal and data operands into a
772/// runtime action.
773fn decode_lexer_action(
774    action_type: i32,
775    data1: i32,
776    data2: i32,
777) -> Result<LexerAction, AntlrError> {
778    let action = match action_type {
779        0 => LexerAction::Channel(data1),
780        1 => LexerAction::Custom {
781            rule_index: data1,
782            action_index: data2,
783        },
784        2 => LexerAction::Mode(data1),
785        3 => LexerAction::More,
786        4 => LexerAction::PopMode,
787        5 => LexerAction::PushMode(data1),
788        6 => LexerAction::Skip,
789        7 => LexerAction::Type(data1),
790        other => {
791            return Err(AntlrError::Unsupported(format!(
792                "lexer action type {other}"
793            )));
794        }
795    };
796    Ok(action)
797}
798
799/// Marks star-loop entry states that are parser precedence decisions.
800fn mark_precedence_decisions(atn: &mut LexerAtn) {
801    let mut decisions = Vec::new();
802    for state in atn.states() {
803        if state.kind != AtnStateKind::StarLoopEntry {
804            continue;
805        }
806        let Some(rule_index) = state.rule_index else {
807            continue;
808        };
809        let Some(rule_start) = atn
810            .rule_to_start_state()
811            .get(rule_index)
812            .and_then(|state_number| atn.state(*state_number))
813        else {
814            continue;
815        };
816        if !rule_start.left_recursive_rule {
817            continue;
818        }
819        let Some(loop_end_state) = state
820            .transitions
821            .last()
822            .and_then(|transition| atn.state(transition.target()))
823        else {
824            continue;
825        };
826        if loop_end_state.kind != AtnStateKind::LoopEnd {
827            continue;
828        }
829        let Some(target) = loop_end_state
830            .transitions
831            .first()
832            .and_then(|transition| atn.state(transition.target()))
833        else {
834            continue;
835        };
836        if target.kind == AtnStateKind::RuleStop {
837            decisions.push(state.state_number);
838        }
839    }
840
841    for state_number in decisions {
842        if let Some(state) = atn.state_mut(state_number) {
843            state.precedence_rule_decision = true;
844        }
845    }
846}
847
848/// Converts a serialized integer operand to an index with a field-specific
849/// error.
850fn read_index(value: i32, label: &str) -> Result<usize, AntlrError> {
851    usize::try_from(value)
852        .map_err(|_| AntlrError::Unsupported(format!("{label} cannot be negative: {value}")))
853}
854
855#[cfg(test)]
856mod tests {
857    use super::*;
858
859    #[test]
860    fn reads_small_parser_atn() {
861        let serialized = SerializedAtn::from_i32(&[
862            4, 1, 9, // header: version, parser, max token type
863            2, // states
864            2, 0, // rule start
865            7, 0, // rule stop
866            0, // non-greedy states
867            0, // precedence states
868            1, // rules
869            0, // rule 0 start
870            0, // modes
871            0, // sets
872            1, // transitions
873            0, 1, 5, 42, 0, 0, // atom to state 1 with label 42
874            1, // decisions
875            0,
876        ]);
877        let atn = AtnDeserializer::new(&serialized)
878            .deserialize_parser()
879            .expect("artificial parser ATN should deserialize");
880        assert_eq!(atn.max_token_type(), 9);
881        assert_eq!(atn.states().len(), 2);
882        assert_eq!(atn.rule_to_start_state().iter().collect::<Vec<_>>(), [0]);
883        assert_eq!(atn.rule_to_stop_state().iter().collect::<Vec<_>>(), [1]);
884        assert_eq!(atn.decision_to_state().iter().collect::<Vec<_>>(), [0]);
885        assert_eq!(atn.stats().transitions, 1);
886    }
887
888    #[test]
889    fn graph_deserializer_rejects_parser_input() {
890        let serialized = SerializedAtn::from_i32(&[4, 1, 0]);
891        let error = AtnDeserializer::new(&serialized)
892            .deserialize()
893            .expect_err("parser input must not create a lexer graph");
894        assert!(
895            error
896                .to_string()
897                .contains("AtnDeserializer::deserialize_parser()")
898        );
899    }
900}
antlr4_runtime/atn/serialized.rs

antlr4_runtime/atn/
serialized.rs
