1 package org.unicode.cldr.api;
2 
3 import static com.google.common.base.Preconditions.checkNotNull;
4 import static com.google.common.base.Preconditions.checkState;
5 import static org.unicode.cldr.api.CldrData.PathOrder.NESTED_GROUPING;
6 
7 import java.util.ArrayDeque;
8 import java.util.Deque;
9 import java.util.function.BiConsumer;
10 import java.util.function.Consumer;
11 
12 import org.unicode.cldr.api.CldrData.PathOrder;
13 import org.unicode.cldr.api.CldrData.PrefixVisitor;
14 import org.unicode.cldr.api.CldrData.PrefixVisitor.Context;
15 import org.unicode.cldr.api.CldrData.ValueVisitor;
16 
17 /**
18  * Utility class for reconstructing nested path visitation from a sequence of path/value pairs. See
19  * {@link PrefixVisitor} for more information.
20  */
21 final class PrefixVisitorHost {
22     /**
23      * Accepts a prefix visitor over a nested sequence of prefix paths derived from the given data
24      * instance. This method synthesizes a sequence of start/end events for all the sub-trees
25      * implied by the sequence of CLDR paths produced by the data supplier.
26      *
27      * <p>For example, given the sequence:
28      *
29      * <pre>{@code
30      * //ldml/foo/bar/first
31      * //ldml/foo/bar/second
32      * //ldml/foo/bar/third
33      * //ldml/foo/baz/first
34      * //ldml/foo/baz/second
35      * //ldml/quux
36      * }</pre>
37      *
38      * the following start, end and value visitation events will be derived:
39      *
40      * <pre>{@code
41      * start: //ldml
42      * start: //ldml/foo
43      * start: //ldml/foo/bar
44      * value: //ldml/foo/bar/first
45      * value: //ldml/foo/bar/second
46      * value: //ldml/foo/bar/third
47      * end:   //ldml/foo/bar
48      * start: //ldml/foo/baz
49      * value: //ldml/foo/baz/first
50      * value: //ldml/foo/baz/second
51      * end:   //ldml/foo/baz
52      * end:   //ldml/foo
53      * value: //ldml/quux
54      * end:   //ldml
55      * }</pre>
56      *
57      * <p>Note that deriving the proper sequence of start/end events can only occur if the data is
58      * provided in at least {@link PathOrder#NESTED_GROUPING NESTED_GROUPING} order. If a lower
59      * path order (e.g. {@link PathOrder#ARBITRARY ARBITRARY}) is given then {@code NESTED_GROUPING}
60      * will be used.
61      */
accept( BiConsumer<PathOrder, ValueVisitor> acceptFn, PathOrder order, PrefixVisitor v)62     static void accept(
63         BiConsumer<PathOrder, ValueVisitor> acceptFn, PathOrder order, PrefixVisitor v) {
64         PrefixVisitorHost host = new PrefixVisitorHost(v);
65         if (order.ordinal() < NESTED_GROUPING.ordinal()) {
66             order = NESTED_GROUPING;
67         }
68         acceptFn.accept(order, host.visitor);
69         host.endVisitation();
70     }
71 
72     /**
73      * Represents the root of a sub hierarchy visitation rooted at some path prefix. VisitorState
74      * instances are kept in a stack; they are added when a new visitor is installed to begin a
75      * sub hierarchy visitation and removed automatically once the visitation is complete.
76      */
77     @SuppressWarnings("unused")  // For unused arguments in no-op default methods.
78     private static abstract class VisitorState implements PrefixVisitor {
79         /** Creates a visitor state from the given visitor for the specified leaf value. */
of( T visitor, Consumer<T> doneHandler, CldrPath prefix)80         static <T extends ValueVisitor> VisitorState of(
81             T visitor, Consumer<T> doneHandler, CldrPath prefix) {
82             return new VisitorState(prefix, () -> doneHandler.accept(visitor)) {
83                 @Override
84                 public void visitValue(CldrValue value) {
85                     visitor.visit(value);
86                 }
87             };
88         }
89 
90         /** Creates a visitor state from the given visitor rooted at the specified path prefix. */
of( T visitor, Consumer<T> doneHandler, CldrPath prefix)91         static <T extends PrefixVisitor> VisitorState of(
92             T visitor, Consumer<T> doneHandler, CldrPath prefix) {
93             return new VisitorState(prefix, () -> doneHandler.accept(visitor)) {
94                 @Override
95                 public void visitPrefixStart(CldrPath prefix, Context ctx) {
96                     visitor.visitPrefixStart(prefix, ctx);
97                 }
98 
99                 @Override
100                 public void visitPrefixEnd(CldrPath prefix) {
101                     visitor.visitPrefixEnd(prefix);
102                 }
103 
104                 @Override
105                 public void visitValue(CldrValue value) {
106                     visitor.visitValue(value);
107                 }
108             };
109         }
110 
111         // The root of the sub hierarchy visitation.
112         /* @Nullable */ private final CldrPath prefix;
113         private final Runnable doneCallback;
114 
115         private VisitorState(CldrPath prefix, Runnable doneCallback) {
116             this.prefix = prefix;
117             this.doneCallback = doneCallback;
118         }
119     }
120 
121     // Stack of currently installed visitor.
122     private final Deque<VisitorState> visitorStack = new ArrayDeque<>();
123     /* @Nullable */ private CldrPath lastValuePath = null;
124 
125     // Visits a single value (with its path) and synthesizes prefix start/end calls according
126     // to the state of the visitor stack.
127     // This is a private field to avoid anyone accidentally calling the visit method directly.
128     private final ValueVisitor visitor = value -> {
129         CldrPath path = value.getPath();
130         int commonLength = 0;
131         if (lastValuePath != null) {
132             commonLength = CldrPath.getCommonPrefixLength(lastValuePath, path);
133             checkState(commonLength <= lastValuePath.getLength(),
134                 "unexpected child path encountered: %s is child of %s", path, lastValuePath);
135             handleLastPath(commonLength);
136         }
137         // ... then down to the new path (which cannot be a parent of the old path either).
138         checkState(commonLength <= path.getLength(),
139             "unexpected parent path encountered: %s is parent of %s", path, lastValuePath);
140         recursiveStartVisit(path.getParent(), commonLength, new PrefixContext());
141         // This is a no-op if the head of the stack is a prefix visitor.
142         visitorStack.peek().visitValue(value);
143         lastValuePath = path;
144     };
145 
146     private PrefixVisitorHost(PrefixVisitor visitor) {
147         this.visitorStack.push(VisitorState.of(visitor, v -> {
148         }, null));
149     }
150 
151     // Called after visitation is complete to close out the last visited value path.
152     private void endVisitation() {
153         if (lastValuePath != null) {
154             handleLastPath(0);
155         }
156     }
157 
158     // Recursively visits new prefix path elements (from top-to-bottom) for a new sub hierarchy.
159     private void recursiveStartVisit(
160         /* @Nullable */ CldrPath prefix, int commonLength, PrefixContext ctx) {
161         if (prefix != null && prefix.getLength() > commonLength) {
162             recursiveStartVisit(prefix.getParent(), commonLength, ctx);
163             // Get the current visitor here (it could have been modified by the call above).
164             // This is a no-op if the head of the stack is a value visitor.
165             visitorStack.peek().visitPrefixStart(prefix, ctx.setPrefix(prefix));
166         }
167     }
168 
169     // Go up from the previous path to the common length (we _have_ already visited the leaf
170     // node of the previous path and we do not allow the new path to be a sub-path) ...
171     private void handleLastPath(int length) {
172         for (CldrPath prefix = lastValuePath.getParent();
173              prefix != null && prefix.getLength() > length;
174              prefix = prefix.getParent()) {
175             // Get the current visitor here (it could have been modified by the last iteration).
176             //
177             // Note: e.prefix can be null for the top-most entry in the stack, but that's fine
178             // since it will never match "prefix" and we never want to remove it anyway.
179             VisitorState e = visitorStack.peek();
180             if (prefix.equals(e.prefix)) {
181                 e.doneCallback.run();
182                 visitorStack.pop();
183                 e = visitorStack.peek();
184             }
185             // This is a no-op if the head of the stack is a value visitor.
186             e.visitPrefixEnd(prefix);
187         }
188     }
189 
190     /**
191      * Implements a reusable context which captures the current prefix being processed. This is
192      * used if a visitor wants to install a sub-visitor at a particular point during visitation.
193      */
194     private final class PrefixContext implements Context {
195         // Only null until first use.
196         private CldrPath prefix = null;
197 
198         // Must be called immediately prior to visiting a prefix visitor.
199         private PrefixContext setPrefix(CldrPath prefix) {
200             this.prefix = checkNotNull(prefix);
201             return this;
202         }
203 
204         @Override
205         public <T extends PrefixVisitor> void install(T visitor, Consumer<T> doneHandler) {
206             visitorStack.push(VisitorState.of(visitor, doneHandler, prefix));
207         }
208 
209         @Override
210         public <T extends ValueVisitor> void install(T visitor, Consumer<T> doneHandler) {
211             visitorStack.push(VisitorState.of(visitor, doneHandler, prefix));
212         }
213     }
214 }
215