Add graphs describing ATNState relations

runtime/Java/pom.xml

@@ -24,6 +24,32 @@
         </dependency>
     </dependencies>
 
+    <profiles>
+        <profile>
+            <id>sonatype-oss-release</id>
+            <build>
+                <plugins>
+                    <plugin>
+                        <groupId>us.bryon</groupId>
+                        <artifactId>graphviz-maven-plugin</artifactId>
+                        <version>1.0</version>
+                        <executions>
+                            <execution>
+                                <goals>
+                                    <goal>dot</goal>
+                                </goals>
+                                <configuration>
+                                    <destdir>${project.build.directory}/apidocs</destdir>
+                                    <output>svg</output>
+                                </configuration>
+                            </execution>
+                        </executions>
+                    </plugin>
+                </plugins>
+            </build>
+        </profile>
+    </profiles>
+
     <build>
 
         <sourceDirectory>src</sourceDirectory>

runtime/Java/src/main/dot/org/antlr/v4/runtime/atn/images/Block.dot

@@ -0,0 +1,35 @@
+digraph "" {
+    graph[fontname="Consolas,Courier";rankdir="LR";pad="0.25"];
+    node[fontname="Consolas,Courier";target="_parent"];
+    edge[fontname="Consolas,Courier"];
+    subgraph cluster0 {
+        subgraph[color="white"];
+        {   node[shape="record"];
+            BasicBlockStartState[URL="../BasicBlockStartState.html";label="{BasicBlockStartState | {<alt1> alt 1 |<alt2> alt 2 | &#0183;\n&#0183;\n&#0183; |<altn> alt n}}"];
+            BlockEndState[URL="../BlockEndState.html"];
+        }
+
+        {   node[style="dashed"];
+            content1[label="alt 1"];
+            content2[label="alt 2"];
+            more[label="alt n"];
+        }
+    }
+
+    {   node[style="dashed"];
+        begin;
+        end;
+    }
+
+    begin -> BasicBlockStartState[style="dashed"];
+    BlockEndState -> end[label="&#0949;"];
+
+    BasicBlockStartState:alt1 -> content1[label="&#0949;"];
+    content1 -> BlockEndState[style="dashed"];
+
+    BasicBlockStartState:alt2 -> content2[label="&#0949;"];
+    content2 -> BlockEndState[style="dashed"];
+
+    BasicBlockStartState:altn -> more[label="&#0949;"];
+    more -> BlockEndState[style="dashed"];
+}

runtime/Java/src/main/dot/org/antlr/v4/runtime/atn/images/ClosureGreedy.dot

@@ -0,0 +1,46 @@
+digraph "" {
+    graph[fontname="Consolas,Courier";rankdir="LR";pad="0.25"];
+    node[fontname="Consolas,Courier";target="_parent"];
+    edge[fontname="Consolas,Courier"];
+    subgraph cluster0 {
+        subgraph[color="white"];
+        {   node[shape="record"];
+            StarLoopEntryState[URL="../StarLoopEntryState.html";label="{StarLoopEntryState | {<alt1> alt 1 |<alt2> alt 2}}"];
+            StarLoopbackState[URL="../StarLoopbackState.html"];
+            StarBlockStartState[URL="../StarBlockStartState.html";label="{StarBlockStartState | {<alt1> alt 1 |<alt2> alt 2 | &#0183;\n&#0183;\n&#0183; |<altn> alt n}}"];
+            BlockEndState[URL="../BlockEndState.html"];
+
+            {   rank="sink";
+                LoopEndState[URL="../LoopEndState.html";rank="max"];
+            }
+        }
+
+        {   node[style="dashed"];
+            content1[label="alt 1"];
+            content2[label="alt 2"];
+            more[label="alt n"];
+        }
+    }
+
+    {   node[style="dashed"];
+        begin;
+        end;
+    }
+
+    begin -> StarLoopEntryState[style="dashed"];
+    LoopEndState -> end[label="&#0949;"];
+
+    StarBlockStartState:alt1 -> content1[label="&#0949;"];
+    content1 -> BlockEndState[style="dashed"];
+
+    StarBlockStartState:alt2 -> content2[label="&#0949;"];
+    content2 -> BlockEndState[style="dashed"];
+
+    StarBlockStartState:altn -> more[label="&#0949;"];
+    more -> BlockEndState[style="dashed"];
+
+    BlockEndState:e -> StarLoopbackState:w[label="&#0949;"];
+    StarLoopEntryState:alt1 -> StarBlockStartState[label="&#0949;"];
+    StarLoopEntryState:alt2 -> LoopEndState[label="&#0949;"];
+    StarLoopbackState:n -> StarLoopEntryState:n[label="&#0949;"];
+}

runtime/Java/src/main/dot/org/antlr/v4/runtime/atn/images/ClosureNonGreedy.dot

@@ -0,0 +1,46 @@
+digraph "" {
+    graph[fontname="Consolas,Courier";rankdir="LR";pad="0.25"];
+    node[fontname="Consolas,Courier";target="_parent"];
+    edge[fontname="Consolas,Courier"];
+    subgraph cluster0 {
+        subgraph[color="white"];
+        {   node[shape="record"];
+            StarLoopEntryState[URL="../StarLoopEntryState.html";label="{StarLoopEntryState | {<alt1> alt 1 |<alt2> alt 2}}"];
+            StarLoopbackState[URL="../StarLoopbackState.html"];
+            StarBlockStartState[URL="../StarBlockStartState.html";label="{StarBlockStartState | {<alt1> alt 1 |<alt2> alt 2 | &#0183;\n&#0183;\n&#0183; |<altn> alt n}}"];
+            BlockEndState[URL="../BlockEndState.html"];
+
+            {   rank="sink";
+                LoopEndState[URL="../LoopEndState.html";rank="max"];
+            }
+        }
+
+        {   node[style="dashed"];
+            content1[label="alt 1"];
+            content2[label="alt 2"];
+            more[label="alt n"];
+        }
+    }
+
+    {   node[style="dashed"];
+        begin;
+        end;
+    }
+
+    begin -> StarLoopEntryState[style="dashed"];
+    LoopEndState -> end[label="&#0949;"];
+
+    StarBlockStartState:alt1 -> content1[label="&#0949;"];
+    content1 -> BlockEndState[style="dashed"];
+
+    StarBlockStartState:alt2 -> content2[label="&#0949;"];
+    content2 -> BlockEndState[style="dashed"];
+
+    StarBlockStartState:altn -> more[label="&#0949;"];
+    more -> BlockEndState[style="dashed"];
+
+    BlockEndState:e -> StarLoopbackState:w[label="&#0949;"];
+    StarLoopEntryState:alt2 -> StarBlockStartState[label="&#0949;"];
+    StarLoopEntryState:alt1 -> LoopEndState[label="&#0949;"];
+    StarLoopbackState:s -> StarLoopEntryState:s[label="&#0949;"];
+}

runtime/Java/src/main/dot/org/antlr/v4/runtime/atn/images/OptionalGreedy.dot

@@ -0,0 +1,29 @@
+digraph "" {
+    graph[fontname="Consolas,Courier";rankdir="LR";pad="0.25"];
+    node[fontname="Consolas,Courier";target="_parent"];
+    edge[fontname="Consolas,Courier"];
+    subgraph cluster0 {
+        subgraph[color="white"];
+        {   node[shape="record"];
+            BasicBlockStartState[URL="../BasicBlockStartState.html";label="{BasicBlockStartState | {<alt1> alt 1 |<alt2> alt 2}}"];
+            BlockEndState[URL="../BlockEndState.html"];
+        }
+
+        {   node[style="dashed"];
+            content[label="alt"];
+        }
+    }
+
+    {   node[style="dashed"];
+        begin;
+        end;
+    }
+
+    begin -> BasicBlockStartState[style="dashed"];
+    BlockEndState -> end[label="&#0949;"];
+
+    BasicBlockStartState:alt1 -> content[label="&#0949;"];
+    content -> BlockEndState[style="dashed"];
+
+    BasicBlockStartState:alt2 -> BlockEndState[label="&#0949;"];
+}

runtime/Java/src/main/dot/org/antlr/v4/runtime/atn/images/OptionalNonGreedy.dot

@@ -0,0 +1,29 @@
+digraph "" {
+    graph[fontname="Consolas,Courier";rankdir="LR";pad="0.25"];
+    node[fontname="Consolas,Courier";target="_parent"];
+    edge[fontname="Consolas,Courier"];
+    subgraph cluster0 {
+        subgraph[color="white"];
+        {   node[shape="record"];
+            BasicBlockStartState[URL="../BasicBlockStartState.html";label="{BasicBlockStartState | {<alt1> alt 1 |<alt2> alt 2}}"];
+            BlockEndState[URL="../BlockEndState.html"];
+        }
+
+        {   node[style="dashed"];
+            content[label="alt"];
+        }
+    }
+
+    {   node[style="dashed"];
+        begin;
+        end;
+    }
+
+    begin -> BasicBlockStartState[style="dashed"];
+    BlockEndState -> end[label="&#0949;"];
+
+    BasicBlockStartState:alt2 -> content[label="&#0949;"];
+    content -> BlockEndState[style="dashed"];
+
+    BasicBlockStartState:alt1 -> BlockEndState[label="&#0949;"];
+}

runtime/Java/src/main/dot/org/antlr/v4/runtime/atn/images/PositiveClosureGreedy.dot

@@ -0,0 +1,47 @@
+digraph "" {
+    graph[fontname="Consolas,Courier";rankdir="LR";pad="0.25"];
+    node[fontname="Consolas,Courier";target="_parent"];
+    edge[fontname="Consolas,Courier"];
+    subgraph cluster0 {
+        subgraph[color="white"];
+        {   node[shape="record"];
+            {   rank="source";
+                PlusBlockStartState[URL="../PlusBlockStartState.html";label="{PlusBlockStartState | {<alt1> alt 1 |<alt2> alt 2 | &#0183;\n&#0183;\n&#0183; |<altn> alt n}}"];
+            }
+
+            PlusLoopbackState[URL="../PlusLoopbackState.html";label="{PlusLoopbackState | {<alt1> alt 1 |<alt2> alt 2}}"];
+            BlockEndState[URL="../BlockEndState.html"];
+
+            {   rank="sink";
+                LoopEndState[URL="../LoopEndState.html"];
+            }
+        }
+
+        {   node[style="dashed"];
+            content1[label="alt 1"];
+            content2[label="alt 2"];
+            more[label="alt n"];
+        }
+    }
+
+    {   node[style="dashed"];
+        begin;
+        end;
+    }
+
+    begin -> PlusBlockStartState[style="dashed"];
+    LoopEndState -> end[label="&#0949;"];
+
+    PlusBlockStartState:alt1 -> content1[label="&#0949;"];
+    content1 -> BlockEndState[style="dashed"];
+
+    PlusBlockStartState:alt2 -> content2[label="&#0949;"];
+    content2 -> BlockEndState[style="dashed"];
+
+    PlusBlockStartState:altn -> more[label="&#0949;"];
+    more -> BlockEndState[style="dashed"];
+
+    BlockEndState -> PlusLoopbackState[label="&#0949;"];
+    PlusLoopbackState:alt1:n -> PlusBlockStartState:n[label="&#0949;"];
+    PlusLoopbackState:alt2 -> LoopEndState[label="&#0949;"];
+}

runtime/Java/src/main/dot/org/antlr/v4/runtime/atn/images/PositiveClosureNonGreedy.dot

@@ -0,0 +1,47 @@
+digraph "" {
+    graph[fontname="Consolas,Courier";rankdir="LR";pad="0.25"];
+    node[fontname="Consolas,Courier";target="_parent"];
+    edge[fontname="Consolas,Courier"];
+    subgraph cluster0 {
+        subgraph[color="white"];
+        {   node[shape="record"];
+            {   rank="source";
+                PlusBlockStartState[URL="../PlusBlockStartState.html";label="{PlusBlockStartState | {<alt1> alt 1 |<alt2> alt 2 | &#0183;\n&#0183;\n&#0183; |<altn> alt n}}"];
+            }
+
+            PlusLoopbackState[URL="../PlusLoopbackState.html";label="{PlusLoopbackState | {<alt1> alt 1 |<alt2> alt 2}}"];
+            BlockEndState[URL="../BlockEndState.html"];
+
+            {   rank="sink";
+                LoopEndState[URL="../LoopEndState.html"];
+            }
+        }
+
+        {   node[style="dashed"];
+            content1[label="alt 1"];
+            content2[label="alt 2"];
+            more[label="alt n"];
+        }
+    }
+
+    {   node[style="dashed"];
+        begin;
+        end;
+    }
+
+    begin -> PlusBlockStartState[style="dashed"];
+    LoopEndState -> end[label="&#0949;"];
+
+    PlusBlockStartState:alt1 -> content1[label="&#0949;"];
+    content1 -> BlockEndState[style="dashed"];
+
+    PlusBlockStartState:alt2 -> content2[label="&#0949;"];
+    content2 -> BlockEndState[style="dashed"];
+
+    PlusBlockStartState:altn -> more[label="&#0949;"];
+    more -> BlockEndState[style="dashed"];
+
+    BlockEndState -> PlusLoopbackState[label="&#0949;"];
+    PlusLoopbackState:alt2:s -> PlusBlockStartState:s[label="&#0949;"];
+    PlusLoopbackState:alt1 -> LoopEndState[label="&#0949;"];
+}

runtime/Java/src/main/dot/org/antlr/v4/runtime/atn/images/Rule.dot

@@ -0,0 +1,15 @@
+digraph "" {
+    graph[fontname="Consolas,Courier";rankdir="LR";pad="0.25"];
+    node[fontname="Consolas,Courier";target="_parent"];
+    edge[fontname="Consolas,Courier"];
+    {   node[shape="box"];
+        RuleStartState[URL="../RuleStartState.html"];
+        RuleStopState[URL="../RuleStopState.html"];
+    }
+    {   node[style="dashed"];
+        content;
+    }
+
+    RuleStartState -> content[label="ε"];
+    content -> RuleStopState[style="dashed"];
+}

runtime/Java/src/org/antlr/v4/runtime/atn/ATNState.java

@@ -35,10 +35,60 @@ import org.antlr.v4.runtime.misc.IntervalSet;
 import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.Collections;
-import java.util.HashMap;
 import java.util.List;
-import java.util.Map;
 
+/**
+ * The following images show the relation of states and
+ * {@link ATNState#transitions} for various grammar constructs.
+ *
+ * <ul>
+ * <li>Solid edges marked with an &#0949; indicate a required
+ * {@link EpsilonTransition}.</li>
+ * <li>Dashed edges indicate locations where any transition derived from
+ * {@link Transition} might appear.</li>
+ * <li>Dashed nodes are place holders for either a sequence of linked
+ * {@link BasicState} states or the inclusion of a block representing a nested
+ * construct in one of the forms below.</li>
+ * </ul>
+ *
+ * <h2>Basic Blocks</h2>
+ *
+ * <h3>Rule</h3>
+ *
+ * <embed src="images/Rule.svg" type="image/svg+xml"/>
+ *
+ * <h3>Block of 1 or more alternatives</h3>
+ *
+ * <embed src="images/Block.svg" type="image/svg+xml"/>
+ *
+ * <h2>Greedy Loops</h2>
+ *
+ * <h3>Greedy Closure: {@code (...)*}</h3>
+ *
+ * <embed src="images/ClosureGreedy.svg" type="image/svg+xml"/>
+ *
+ * <h3>Greedy Positive Closure: {@code (...)+}</h3>
+ *
+ * <embed src="images/PositiveClosureGreedy.svg" type="image/svg+xml"/>
+ *
+ * <h3>Greedy Optional: {@code (...)?}</h3>
+ *
+ * <embed src="images/OptionalGreedy.svg" type="image/svg+xml"/>
+ *
+ * <h2>Non-Greedy Loops</h2>
+ *
+ * <h3>Non-Greedy Closure: {@code (...)*?}</h3>
+ *
+ * <embed src="images/ClosureNonGreedy.svg" type="image/svg+xml"/>
+ *
+ * <h3>Non-Greedy Positive Closure: {@code (...)+?}</h3>
+ *
+ * <embed src="images/PositiveClosureNonGreedy.svg" type="image/svg+xml"/>
+ *
+ * <h3>Non-Greedy Optional: {@code (...)??}</h3>
+ *
+ * <embed src="images/OptionalNonGreedy.svg" type="image/svg+xml"/>
+ */
 public abstract class ATNState {
 	public static final int INITIAL_NUM_TRANSITIONS = 4;