From f9f48838553a36409ff04ef3b81e768754d9b599 Mon Sep 17 00:00:00 2001 From: Sam Harwell Date: Tue, 14 May 2013 16:26:45 -0500 Subject: [PATCH] Updated documentation in LL1Analyzer --- .../org/antlr/v4/runtime/atn/LL1Analyzer.java | 68 ++++++++++++++----- 1 file changed, 51 insertions(+), 17 deletions(-) diff --git a/runtime/Java/src/org/antlr/v4/runtime/atn/LL1Analyzer.java b/runtime/Java/src/org/antlr/v4/runtime/atn/LL1Analyzer.java index e4fa0ebb8..e175a7618 100644 --- a/runtime/Java/src/org/antlr/v4/runtime/atn/LL1Analyzer.java +++ b/runtime/Java/src/org/antlr/v4/runtime/atn/LL1Analyzer.java @@ -30,7 +30,6 @@ package org.antlr.v4.runtime.atn; -import org.antlr.v4.runtime.IntStream; import org.antlr.v4.runtime.RuleContext; import org.antlr.v4.runtime.Token; import org.antlr.v4.runtime.misc.IntervalSet; @@ -43,7 +42,7 @@ import java.util.Set; public class LL1Analyzer { /** Special value added to the lookahead sets to indicate that we hit - * a predicate during analysis if seeThruPreds==false. + * a predicate during analysis if {@code seeThruPreds==false}. */ public static final int HIT_PRED = Token.INVALID_TYPE; @@ -53,8 +52,14 @@ public class LL1Analyzer { public LL1Analyzer(@NotNull ATN atn) { this.atn = atn; } /** - * From an ATN state, {@code s}, find the set of all labels reachable from - * {@code s} at depth k. Only for DecisionStates. + * Calculates the SLL(1) expected lookahead set for each outgoing transition + * of an {@link ATNState}. The returned array has one element for each + * outgoing transition in {@code s}. If the closure from transition + * i leads to a semantic predicate before matching a symbol, the + * element at index i of the result will be {@code null}. + * + * @param s the ATN state + * @return the expected symbols for each outgoing transition of {@code s}. */ @Nullable public IntervalSet[] getDecisionLookahead(@Nullable ATNState s) { @@ -81,12 +86,20 @@ public class LL1Analyzer { } /** - * Get lookahead, using {@code ctx} if we reach end of rule. If {@code ctx} - * is {@code null} or {@link RuleContext#EMPTY EMPTY}, don't chase FOLLOW. - * If {@code ctx} is {@code null}, {@link Token#EPSILON EPSILON} is in set - * if we can reach end of rule. If {@code ctx} is - * {@link RuleContext#EMPTY EMPTY}, {@link IntStream#EOF EOF} is in set if - * we can reach end of rule. + * Compute set of tokens that can follow {@code s} in the ATN in the + * specified {@code ctx}. + *

+ * If {@code ctx} is {@code null} and the end of the rule containing + * {@code s} is reached, {@link Token#EPSILON} is added to the result set. + * If {@code ctx} is not {@code null} and the end of the outermost rule is + * reached, {@link Token#EOF} is added to the result set. + * + * @param s the ATN state + * @param ctx the complete parser context, or {@code null} if the context + * should be ignored + * + * @return The set of tokens that can follow {@code s} in the ATN in the + * specified {@code ctx}. */ @NotNull public IntervalSet LOOK(@NotNull ATNState s, @Nullable RuleContext ctx) { @@ -98,13 +111,34 @@ public class LL1Analyzer { return r; } - /** Compute set of tokens that can come next. If the {@code ctx} is {@link PredictionContext#EMPTY}, - * then we don't go anywhere when we hit the end of the rule. We have - * the correct set. If {@code ctx} is null, that means that we did not want - * any tokens following this rule--just the tokens that could be found within this - * rule. Add {@link Token#EPSILON} to the set indicating we reached the end of the ruled out having - * to match a token. - */ + /** + * Compute set of tokens that can follow {@code s} in the ATN in the + * specified {@code ctx}. + *

+ * If {@code ctx} is {@code null} and the end of the rule containing + * {@code s} is reached, {@link Token#EPSILON} is added to the result set. + * If {@code ctx} is not {@code null} and {@code addEOF} is {@code true} and + * the end of the outermost rule is reached, {@link Token#EOF} is added to + * the result set. + * + * @param s the ATN state. + * @param ctx The outer context, or {@code null} if the outer context should + * not be used. + * @param look The result lookahead set. + * @param lookBusy A set used for preventing epsilon closures in the ATN + * from causing a stack overflow. Outside code should pass + * {@code new HashSet} for this argument. + * @param calledRuleStack A set used for preventing left recursion in the + * ATN from causing a stack overflow. Outside code should pass + * {@code new BitSet()} for this argument. + * @param seeThruPreds {@code true} to true semantic predicates as + * implicitly {@code true} and "see through them", otherwise {@code false} + * to treat semantic predicates as opaque and add {@link #HIT_PRED} to the + * result if one is encountered. + * @param addEOF Add {@link Token#EOF} to the result if the end of the + * outermost context is reached. This parameter has no effect if {@code ctx} + * is {@code null}. + */ protected void _LOOK(@NotNull ATNState s, @Nullable PredictionContext ctx, @NotNull IntervalSet look, @NotNull Set lookBusy,