/*
 * Copyright (C) 2010 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.clearsilver.jsilver.template;

import com.google.clearsilver.jsilver.autoescape.AutoEscapeOptions;
import com.google.clearsilver.jsilver.autoescape.EscapeMode;
import com.google.clearsilver.jsilver.data.DataContext;
import com.google.clearsilver.jsilver.exceptions.JSilverInterpreterException;
import com.google.clearsilver.jsilver.resourceloader.ResourceLoader;
import com.google.clearsilver.jsilver.values.Value;

/**
 * State that is shared across a template rendering.
 */
public interface RenderingContext {

  /**
   * Execute a named function. Will throw an exception if the function is not found, or the function
   * does not return a value.
   */
  Value executeFunction(String name, Value... args) throws JSilverInterpreterException;

  /**
   * Look up a function by name, and report whether it is an escaping function. Usually, the output
   * of escaping functions will be written using writeUnescaped() instead of writeEscaped().
   * 
   * @see com.google.clearsilver.jsilver.compiler.EscapingEvaluator
   */
  public boolean isEscapingFunction(String name);

  /**
   * Write some text out, using the current escaping function.
   * 
   * @see #pushEscapingFunction(String)
   * @see #popEscapingFunction()
   */
  void writeEscaped(String text);

  /**
   * Write some text out, without doing any escaping. Use this only for trusted content.
   */
  void writeUnescaped(CharSequence text);

  /**
   * Push a new escaping function onto the context. All calls to writeEscape() will use this new
   * function. When done with this function, call popEscapingFunction() to return to the previous
   * escaping function.
   * 
   * If the escaping function is not found, an exception will be thrown. To use no escaping function
   * pass null as the escaperName.
   * 
   * @see #popEscapingFunction()
   */
  void pushEscapingFunction(String escaperName);

  /**
   * @see #pushEscapingFunction(String)
   */
  void popEscapingFunction();

  /**
   * Push a new template onto the current execution context. This is to generate stack traces when
   * things go wrong deep in templates, to allow users to figure out how they got there.
   * 
   * @see #popExecutionContext()
   */
  void pushExecutionContext(Template template);

  /**
   * @see #pushExecutionContext(Template)
   */
  void popExecutionContext();

  /**
   * Sets the current position in the template. Used to help generate error messages.
   */
  void setCurrentPosition(int line, int column);

  /**
   * Register a macro in the current rendering context. This macro will be available to all other
   * templates, regardless of implementation.
   */
  void registerMacro(String name, Macro macro);

  /**
   * Lookup a macro that's already been registered. Throws JSilverInterpreterException if macro not
   * found.
   */
  Macro findMacro(String name) throws JSilverInterpreterException;

  /**
   * Return the DataContext object associated with this RenderingContext.
   */
  DataContext getDataContext();

  /**
   * Returns the ResourceLoader object to use to fetch files needed to render the current template.
   */
  ResourceLoader getResourceLoader();

  /**
   * Returns the configured AutoEscapeOptions to be used while rendering the current template.
   */
  AutoEscapeOptions getAutoEscapeOptions();

  /**
   * Push a new auto escaping mode onto the context. Any template loads via include() or
   * evaluateVariable() will use this auto escaping mode when loading the template.
   * 
   * @see #popAutoEscapeMode
   * 
   */
  void pushAutoEscapeMode(EscapeMode mode);

  /**
   * @see #pushAutoEscapeMode
   */
  void popAutoEscapeMode();

  /**
   * Read the currently set auto escape mode.
   * 
   * @return EscapeMode
   */
  EscapeMode getAutoEscapeMode();

  /**
   * Indicates whether runtime auto escaping is in progress.
   * 
   * @return true if runtime auto escaping is enabled.
   * 
   * @see #isRuntimeAutoEscaping
   */
  boolean isRuntimeAutoEscaping();

  /**
   * Start an auto escaping context to parse and auto escape template contents as they are being
   * rendered.
   * 
   * @see #stopRuntimeAutoEscaping
   */
  void startRuntimeAutoEscaping();

  /**
   * Stop runtime auto escaping.
   * 
   * @see #startRuntimeAutoEscaping
   */
  void stopRuntimeAutoEscaping();

  /**
   * Adds an entry with a name of the template to the stack keeping all names of already included
   * templates. The name is added only if it is not already on the stack.
   * 
   * @param templateName name of the template to be added to the stack. If {@code null} a {@code
   *        NullPointerException} will be thrown.
   * @return true if the {@code templateName} was added.
   */
  boolean pushIncludeStackEntry(String templateName);

  /**
   * Removes an entry with a name of the template from the stack.
   * 
   * @param templateName
   * @return true if the {@code templateName} was on the stack.
   */
  boolean popIncludeStackEntry(String templateName);

  /**
   * Returns the ordered, mutable stack of names of included templates.
   */
  Iterable<String> getIncludedTemplateNames();
}