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