/*
 * 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;

  /**
   * 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>
   *   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 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.
     */
    Reader openResource(String resourceName) throws IOException;
  }

  /**
   * Parses a VTL template from the given {@code Reader}. The given Reader will be closed on
   * return from this method.
   */
  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 included files for {@code #parse} directives in the
   *     template.
   */
  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);
    return String.valueOf(root.evaluate(evaluationContext));
  }
}

@@ -1506,24 +1506,30 @@
 *%0A   * %3Cpre%3E
+%7B@code
 %0A   *   Reso
@@ -1872,16 +1872,17 @@
 %7D;%0A   * 
+%7D
 %3C/pre%3E%0A 
@@ -1971,22 +1971,30 @@
 turns a 
+%7B@code 
 Reader
+%7D
  that wi
@@ -2141,16 +2141,127 @@
 e null.%0A
+     * @return a %7B@code Reader%7D for the resource.%0A     * @throws IOException if the resource cannot be opened.%0A
      */%0A
@@ -2402,67 +2402,494 @@
 The 
-given Reader will be closed on%0A   * return from this method
+template cannot reference other%0A   * templates (for example with %7B@code #parse%7D). For that, use%0A   * %7B@link #parseFrom(String, ResourceOpener)%7D.%0A   *%0A   * @param reader a Reader that will supply the text of the template. It will be closed on return%0A   *     from this method.%0A   * @return an object representing the parsed template.%0A   * @throws IOException if there is an exception reading from %7B@code reader%7D, or if the template%0A   *     references another template via %7B@code #parse%7D
 .%0A  
@@ -3513,76 +3513,251 @@
 pen 
-included files for %7B@code #parse%7D directives in the%0A   *     templat
+the initial resource and resources referenced by%0A   *     %7B@code #parse%7D directives in the template.%0A   * @return an object representing the parsed template.%0A   * @throws IOException if there is an exception opening or reading from any resourc
 e.%0A 

Fix a javadoc error and some warnings.