diff options
author | Colin Cross <ccross@android.com> | 2020-06-19 06:42:10 +0000 |
---|---|---|
committer | Automerger Merge Worker <android-build-automerger-merge-worker@system.gserviceaccount.com> | 2020-06-19 06:42:10 +0000 |
commit | baaddbfbc5c804da71c6f41f8ab92bba7f340327 (patch) | |
tree | 2f8cc743bd7babbb6fa85cd2b98e4e5e46c847f8 /src/main/java/com/google/escapevelocity/Template.java | |
parent | 4e70048b1a58f2f479f6d9179eecb395edb95522 (diff) | |
parent | 6ddc2e77d3a9e66174e0344e8f17338a511d4f03 (diff) | |
download | escapevelocity-baaddbfbc5c804da71c6f41f8ab92bba7f340327.tar.gz |
Merge tag 'escapevelocity-0.9.1' into master am: 43799cbf40 am: 6b276f51ce am: f29fb6ed5e am: cc05f1b8c0 am: 6ddc2e77d3
Original change: https://android-review.googlesource.com/c/platform/external/escapevelocity/+/1343296
Change-Id: I98942f8946a7975cef65e6df530e22321112bb8f
Diffstat (limited to 'src/main/java/com/google/escapevelocity/Template.java')
-rw-r--r-- | src/main/java/com/google/escapevelocity/Template.java | 133 |
1 files changed, 133 insertions, 0 deletions
diff --git a/src/main/java/com/google/escapevelocity/Template.java b/src/main/java/com/google/escapevelocity/Template.java new file mode 100644 index 0000000..6bc75c2 --- /dev/null +++ b/src/main/java/com/google/escapevelocity/Template.java @@ -0,0 +1,133 @@ +/* + * Copyright (C) 2018 Google, Inc. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package com.google.escapevelocity; + +import com.google.escapevelocity.EvaluationContext.PlainEvaluationContext; +import java.io.IOException; +import java.io.Reader; +import java.util.Map; + +/** + * A template expressed in EscapeVelocity, a subset of the Velocity Template Language (VTL) from + * Apache. The intent of this implementation is that if a template is accepted and successfully + * produces output, that output will be identical to what Velocity would have produced for the same + * template and input variables. + * + * @author emcmanus@google.com (Éamonn McManus) + */ +// TODO(emcmanus): spell out exactly what Velocity features are unsupported. +public class Template { + private final Node root; + + /** + * Caches {@link Method} objects for public methods accessed through references. The first time + * we evaluate {@code $var.property} or {@code $var.method(...)} for a {@code $var} of a given + * class and for a given property or method signature, we'll store the resultant {@link Method} + * object. Every subsequent time we'll reuse that {@link Method}. The method lookup is quite slow + * so caching is useful. The main downside is that we may potentially hold on to {@link Method} + * objects that will never be used with this {@link Template} again. But in practice templates + * tend to be used repeatedly with the same classes. + */ + private final MethodFinder methodFinder = new MethodFinder(); + + /** + * Used to resolve references to resources in the template, through {@code #parse} directives. + * + * <p>Here is an example that opens nested templates as resources relative to the calling class: + * + * <pre>{@code + * ResourceOpener resourceOpener = resourceName -> { + * InputStream inputStream = getClass().getResource(resourceName); + * if (inputStream == null) { + * throw new IOException("Unknown resource: " + resourceName); + * } + * return new BufferedReader(InputStreamReader(inputStream, StandardCharsets.UTF_8)); + * }; + * }</pre> + */ + @FunctionalInterface + public interface ResourceOpener { + + /** + * Returns a {@code Reader} that will be used to read the given resource, then closed. + * + * @param resourceName the name of the resource to be read. This will never be null. + * @return a {@code Reader} for the resource. + * @throws IOException if the resource cannot be opened. + */ + Reader openResource(String resourceName) throws IOException; + } + + /** + * Parses a VTL template from the given {@code Reader}. The template cannot reference other + * templates (for example with {@code #parse}). For that, use + * {@link #parseFrom(String, ResourceOpener)}. + * + * @param reader a Reader that will supply the text of the template. It will be closed on return + * from this method. + * @return an object representing the parsed template. + * @throws IOException if there is an exception reading from {@code reader}, or if the template + * references another template via {@code #parse}. + */ + public static Template parseFrom(Reader reader) throws IOException { + ResourceOpener resourceOpener = resourceName -> { + if (resourceName == null) { + return reader; + } else { + throw new IOException("No ResourceOpener has been configured to read " + resourceName); + } + }; + try { + return parseFrom((String) null, resourceOpener); + } finally { + reader.close(); + } + } + + /** + * Parse a VTL template of the given name using the given {@code ResourceOpener}. + * + * @param resourceName name of the resource. May be null. + * @param resourceOpener used to open the initial resource and resources referenced by + * {@code #parse} directives in the template. + * @return an object representing the parsed template. + * @throws IOException if there is an exception opening or reading from any resource. + */ + public static Template parseFrom( + String resourceName, ResourceOpener resourceOpener) throws IOException { + try (Reader reader = resourceOpener.openResource(resourceName)) { + return new Parser(reader, resourceName, resourceOpener).parse(); + } + } + + Template(Node root) { + this.root = root; + } + + /** + * Evaluate the given template with the given initial set of variables. + * + * @param vars a map where the keys are variable names and the values are the corresponding + * variable values. For example, if {@code "x"} maps to 23, then {@code $x} in the template + * will expand to 23. + * + * @return the string result of evaluating the template. + */ + public String evaluate(Map<String, ?> vars) { + EvaluationContext evaluationContext = new PlainEvaluationContext(vars, methodFinder); + return String.valueOf(root.evaluate(evaluationContext)); + } +} |