01: package org.kohsuke.rngom.ast.builder;
02:
03: import org.kohsuke.rngom.ast.om.Location;
04: import org.kohsuke.rngom.ast.om.ParsedElementAnnotation;
05: import org.kohsuke.rngom.ast.om.ParsedPattern;
06:
07: /**
08: * The container that can have <define> elements.
09: * <p>
10: * {@link Div}, {@link Grammar}, {@link Include}, or {@link IncludedGrammar}.
11: */
12: public interface GrammarSection<P extends ParsedPattern, E extends ParsedElementAnnotation, L extends Location, A extends Annotations<E, L, CL>, CL extends CommentList<L>> {
13:
14: static final class Combine {
15: private final String name;
16:
17: private Combine(String name) {
18: this .name = name;
19: }
20:
21: final public String toString() {
22: return name;
23: }
24: }
25:
26: static final Combine COMBINE_CHOICE = new Combine("choice");
27: static final Combine COMBINE_INTERLEAVE = new Combine("interleave");
28:
29: // using \u0000 guarantees that the name will be never used as
30: // a user-defined pattern name.
31: static final String START = "\u0000#start\u0000";
32:
33: /**
34: * Called when a pattern is defined.
35: *
36: * @param name
37: * Name of the pattern. For the definition by a <start/> element,
38: * this parameter is the same as {@link #START}.
39: * to test if it's a named pattern definition or the start pattern definition.
40: * @param combine
41: * null or {@link #COMBINE_CHOICE} or {@link #COMBINE_INTERLEAVE} depending
42: * on the value of the combine attribute.
43: * @param pattern
44: * The pattern to be defined.
45: */
46: void define(String name, Combine combine, P pattern, L loc, A anno)
47: throws BuildException;
48:
49: /**
50: * Called when an annotation is found.
51: */
52: void topLevelAnnotation(E ea) throws BuildException;
53:
54: /**
55: * Called when a comment is found.
56: */
57: void topLevelComment(CL comments) throws BuildException;
58:
59: /**
60: * Called when <div> is found.
61: *
62: * @return
63: * the returned {@link Div} object will receive callbacks for structures
64: * inside the <div> element.
65: */
66: Div<P, E, L, A, CL> makeDiv();
67:
68: /**
69: * Returns null if already in an include.
70: */
71: Include<P, E, L, A, CL> makeInclude();
72: }
|