/*
    * Licensed to the Apache Software Foundation (ASF) under one or more
    * contributor license agreements.  See the NOTICE file distributed with
    * this work for additional information regarding copyright ownership.
    * The ASF licenses this file to You 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 org.apache.commons.jexl3;
  
  import java.io.Reader;
  import java.io.StringReader;
  import java.io.Writer;
  import java.util.List;
  import java.util.Map;
  import java.util.Set;
  
  /**
   * A simple "JeXL Template" engine.
   *
   * <p>At the base is an evaluator similar to the Unified EL evaluator used in JSP/JSF based on JEXL.
   * At the top is a template engine inspired by Velocity that uses JEXL (instead of OGNL/VTL) as the scripting
   * language.</p>
   *
   * <p>The evaluator is intended to be used in configuration modules, XML based frameworks or JSP taglibs
   * and facilitate the implementation of expression evaluation.</p>
   *
   * <p>The template engine is intended to output any form of text; html, XML, CSV...</p>
   *
   * @since 3.0
   */
  public abstract class JxltEngine {
  
      /** Default constructor */
      public JxltEngine() {} // Keep Javadoc happy
  
      /**
       * The sole type of (runtime) exception the JxltEngine can throw.
       */
      public static class Exception extends JexlException {
  
          /** Serial version UID. */
          private static final long serialVersionUID = 201112030113L;
  
          /**
           * Creates an Exception.
           *
           * @param info the contextual information
           * @param msg the exception message
           * @param cause the exception cause
           */
          public Exception(final JexlInfo info, final String msg, final Throwable cause) {
              super(info, msg, cause);
          }
      }
  
      /**
       * A unified expression that can mix immediate, deferred and nested sub-expressions as well as string constants;
       * <ul>
       *   <li>The "immediate" syntax is of the form <code>"...${jexl-expr}..."</code></li>
       *   <li>The "deferred" syntax is of the form <code>"...#{jexl-expr}..."</code></li>
       *   <li>The "nested" syntax is of the form <code>"...#{...${jexl-expr0}...}..."</code></li>
       *   <li>The "composite" syntax is of the form <code>"...${jexl-expr0}... #{jexl-expr1}..."</code></li>
       * </ul>
       *
       * <p>Deferred and immediate expression carry different intentions:</p>
       *
       * <ul>
       *   <li>An immediate expression indicate that evaluation is intended to be performed close to
       *       the definition/parsing point.</li>
       *   <li>A deferred expression indicate that evaluation is intended to occur at a later stage.</li>
       * </ul>
       *
       * <p>For instance: <code>"Hello ${name}, now is #{time}"</code> is a composite "deferred" expression since one
       * of its subexpressions is deferred. Furthermore, this (composite) expression intent is
       * to perform two evaluations; one close to its definition and another one in a later
       * phase.</p>
       *
       * <p>The API reflects this feature in 2 methods, prepare and evaluate. The prepare method
       * will evaluate the immediate subexpression and return an expression that contains only
       * the deferred subexpressions (and constants), a prepared expression. Such a prepared expression
       * is suitable for a later phase evaluation that may occur with a different JexlContext.
       * Note that it is valid to call evaluate without prepare in which case the same JexlContext
       * is used for the 2 evaluation phases.</p>
       *
       * <p>In the most common use-case where deferred expressions are to be kept around as properties of objects,
       * one should createExpression and prepare an expression before storing it and evaluate it each time
       * the property storing it is accessed.</p>
       *
       * <p>Note that nested expression use the JEXL syntax as in:</p>
      *
      * <blockquote><code>"#{${bar}+'.charAt(2)'}"</code></blockquote>
      *
      * <p>The most common mistake leading to an invalid expression being the following:</p>
      *
      * <blockquote><code>"#{${bar}charAt(2)}"</code></blockquote>
      *
      * <p>Also note that methods that createExpression evaluate expressions may throw <em>unchecked</em> exceptions;
      * The {@link JxltEngine.Exception} are thrown when the engine instance is in "non-silent" mode
      * but since these are RuntimeException, user-code <em>should</em> catch them where appropriate.</p>
      *
      * @since 2.0
      */
     public interface Expression {
 
         /**
          * Generates this expression's string representation.
          *
          * @return the string representation
          */
         String asString();
 
         /**
          * Adds this expression's string representation to a StringBuilder.
          *
          * @param strb the builder to fill
          * @return the builder argument
          */
         StringBuilder asString(StringBuilder strb);
 
         /**
          * Evaluates this expression.
          *
          * <p>If the underlying JEXL engine is silent, errors will be logged through its logger as warning.</p>
          *
          * @param context the variable context
          * @return the result of this expression evaluation or null if an error occurs and the {@link JexlEngine} is
          * running in silent mode
          * @throws Exception if an error occurs and the {@link JexlEngine}
          * is not silent
          */
         Object evaluate(JexlContext context);
 
         /**
          * Retrieves this expression's source expression.
          * <p>
          * If this expression was prepared, this allows to retrieve the
          * original expression that lead to it.</p>
          * <p>Other expressions return themselves.</p>
          *
          * @return the source expression
          */
         Expression getSource();
 
         /**
          * Gets the list of variables accessed by this expression.
          * <p>This method will visit all nodes of the sub-expressions and extract all variables whether they
          * are written in 'dot' or 'bracketed' notation. (a.b is equivalent to a['b']).</p>
          *
          * @return the set of variables, each as a list of strings (ant-ish variables use more than 1 string)
          * or the empty set if no variables are used
          */
         Set<List<String>> getVariables();
 
         /**
          * Checks whether this expression is deferred.
          *
          * @return true if deferred, false otherwise
          */
         boolean isDeferred();
 
         /**
          * Checks whether this expression is immediate.
          *
          * @return true if immediate, false otherwise
          */
         boolean isImmediate();
 
         /**
          * Evaluates the immediate sub-expressions.
          *
          * <p>When the expression is dependant upon immediate and deferred sub-expressions,
          * evaluates the immediate sub-expressions with the context passed as parameter
          * and returns this expression deferred form.</p>
          *
          * <p>In effect, this binds the result of the immediate sub-expressions evaluation in the
          * context, allowing to differ evaluation of the remaining (deferred) expression within another context.
          * This only has an effect to nested and composite expressions that contain differed and
          * immediate sub-expressions.</p>
          *
          * <p>If the underlying JEXL engine is silent, errors will be logged through its logger as warning.* </p>
          *
          * @param context the context to use for immediate expression evaluations
          * @return an {@link Expression} or null if an error occurs and the {@link JexlEngine} is running
          * in silent mode
          * @throws Exception if an error occurs and the {@link JexlEngine} is not in silent mode
          */
         Expression prepare(JexlContext context);
 
         /**
          * Formats this expression, adding its source string representation in
          * comments if available: 'expression /*= source *\/'' .
          *
          * @return the formatted expression string
          */
         @Override
         String toString();
     }
 
     /**
      * A template is a JEXL script that evaluates by writing its content through a Writer.
      * <p>
      * The source text is parsed considering each line beginning with '$$' (as default pattern) as JEXL script code
      * and all others as Unified JEXL expressions; those expressions will be invoked from the script during
      * evaluation and their output gathered through a writer.
      * It is thus possible to use looping or conditional construct "around" expressions generating output.
      * </p>
      * For instance:
      * <blockquote><pre>{@code
      * $$ for (var x : [1, 3, 5, 42, 169]) {
      * $$   if (x == 42) {
      * Life, the universe, and everything
      * $$   } else if (x > 42) {
      * The value $(x} is over forty-two
      * $$   } else {
      * The value ${x} is under forty-two
      * $$   }
      * $$ }
      * }</pre></blockquote>
      *
      * <p>Will evaluate as:</p>
      *
      * <blockquote><pre>
      * The value 1 is under forty-two
      * The value 3 is under forty-two
      * The value 5 is under forty-two
      * Life, the universe, and everything
      * The value 169 is over forty-two
      * </pre></blockquote>
      *
      * <p>During evaluation, the template context exposes its writer as '$jexl' which is safe to use in this case.
      * This allows writing directly through the writer without adding new-lines as in:</p>
      *
      * <blockquote><pre>
      * $$ for(var cell : cells) { $jexl.print(cell); $jexl.print(';') }
      * </pre></blockquote>
      *
      * <p>A template is expanded as one JEXL script and a list of template expressions; each template expression is
      * being replaced in the script by a call to jexl:print(expr) (the expr is in fact the expr number in the template).
      * This integration uses a specialized JexlContext (TemplateContext) that serves as a namespace (for jexl:)
      * and stores the template expression array and the writer (java.io.Writer) that the 'jexl:print(...)'
      * delegates the output generation to.</p>
      *
      * @since 3.0
      */
     public interface Template {
 
         /**
          * Recreate the template source from its inner components.
          *
          * @return the template source rewritten
          */
         String asString();
 
         /**
          * Evaluates this template.
          *
          * @param context the context to use during evaluation
          * @param writer the writer to use for output
          */
         void evaluate(JexlContext context, Writer writer);
 
         /**
          * Evaluates this template.
          *
          * @param context the context to use during evaluation
          * @param writer the writer to use for output
          * @param args the arguments
          */
         void evaluate(JexlContext context, Writer writer, Object... args);
 
         /**
          * Gets the list of parameters expected by this template.
          *
          * @return the parameter names array
          */
         String[] getParameters();
 
         /**
          * Gets this script pragmas.
          *
          * @return the (non null, may be empty) pragmas map
          * @since 3.1
          */
         Map<String, Object> getPragmas();
 
         /**
          * Gets the list of variables accessed by this template.
          * <p>This method will visit all nodes of the sub-expressions and extract all variables whether they
          * are written in 'dot' or 'bracketed' notation. (a.b is equivalent to a['b']).</p>
          *
          * @return the set of variables, each as a list of strings (ant-ish variables use more than 1 string)
          * or the empty set if no variables are used
          */
         Set<List<String>> getVariables();
 
         /**
          * Prepares this template by expanding any contained deferred TemplateExpression.
          *
          * @param context the context to prepare against
          * @return the prepared version of the template
          */
         Template prepare(JexlContext context);
     }
 
     /**
      * Clears the cache.
      */
     public abstract void clearCache();
 
     /**
      * Creates a {@link Expression} from an expression string.
      * Uses and fills up the expression cache if any.
      *
      * <p>If the underlying JEXL engine is silent, errors will be logged through its logger as warnings.</p>
      *
      * @param info the {@link JexlInfo} source information
      * @param expression the {@link Template} string expression
      * @return the {@link Expression}, null if silent and an error occurred
      * @throws Exception if an error occurs and the {@link JexlEngine} is not silent
      */
     public abstract Expression createExpression(JexlInfo info, String expression);
 
     /**
      * Creates a {@link Expression} from an expression string.
      * Uses and fills up the expression cache if any.
      *
      * <p>If the underlying JEXL engine is silent, errors will be logged through its logger as warnings.</p>
      *
      * @param expression the {@link Template} string expression
      * @return the {@link Expression}, null if silent and an error occurred
      * @throws Exception if an error occurs and the {@link JexlEngine} is not silent
      */
     public Expression createExpression(final String expression) {
         return createExpression(null, expression);
     }
 
     /**
      * Creates a new template.
      *
      * @param info the source info
      * @param source the source
      * @return the template
      */
     public Template createTemplate(final JexlInfo info, final String source) {
         return createTemplate(info, "$$", new StringReader(source), (String[]) null);
     }
 
     /**
      * Creates a new template.
      *
      * @param info the jexl info (file, line, column)
      * @param prefix the directive prefix
      * @param source the source
      * @param parms the parameter names
      * @return the template
      */
     public abstract Template createTemplate(JexlInfo info, String prefix, Reader source, String... parms);
 
     /**
      * Creates a new template.
      *
      * @param info the source info
      * @param parms the parameter names
      * @param source the source
      * @return the template
      */
     public Template createTemplate(final JexlInfo info, final String source, final String... parms) {
         return createTemplate(info, "$$", new StringReader(source), parms);
     }
 
     /**
      * Creates a new template.
      *
      * @param source the source
      * @return the template
      */
     public Template createTemplate(final String source) {
         return createTemplate(null, source);
     }
 
     /**
      * Creates a new template.
      *
      * @param prefix the directive prefix
      * @param source the source
      * @param parms the parameter names
      * @return the template
      */
     public Template createTemplate(final String prefix, final Reader source, final String... parms) {
         return createTemplate(null, prefix, source, parms);
     }
 
     /**
      * Creates a new template.
      *
      * @param source the source
      * @param parms the parameter names
      * @return the template
      */
     public Template createTemplate(final String source, final String... parms) {
         return createTemplate(null, source, parms);
     }
 
     /**
      * Gets the {@link JexlEngine} underlying this template engine.
      *
      * @return the JexlEngine
      */
     public abstract JexlEngine getEngine();
 }