user/src/com/google/gwt/safehtml/rebind/HtmlTemplateParser.java

/*
 * Copyright 2009 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.gwt.safehtml.rebind;

import com.google.gwt.core.ext.TreeLogger;
import com.google.gwt.core.ext.UnableToCompleteException;
import com.google.gwt.dev.util.Preconditions;
import com.google.gwt.safehtml.rebind.ParsedHtmlTemplate.HtmlContext;
import com.google.gwt.safehtml.rebind.ParsedHtmlTemplate.ParameterChunk;
import com.google.gwt.thirdparty.streamhtmlparser.HtmlParser;
import com.google.gwt.thirdparty.streamhtmlparser.HtmlParserFactory;
import com.google.gwt.thirdparty.streamhtmlparser.ParseException;

import java.util.regex.Matcher;
import java.util.regex.Pattern;

/**
 * A HTML context-aware parser for a simple HTML template language.
 *
 * <p>
 * This parser parses templates consisting of HTML markup, with template
 * variables of the form {@code {n}}. For example, a template might look like,
 *
 * <pre>  {@code
 *   <span style="{0}"><a href="{1}/{2}">{3}</a></span>
 * }</pre>
 *
 * <p>
 * The parser is lenient, and will accept HTML that is not well-formed; the
 * accepted set of HTML is similar to what is typically accepted by browsers.
 * However, the following constraints on the HTML template are enforced:
 *
 * <ol>
 * <li>Template variables may not appear in a JavaScript context (inside a
 * {@code <script>} tag, or in an {@code onClick} etc handler).</li>
 * <li>Template variables may not appear inside HTML comments.</li>
 * <li>If a template variable appears inside the value of an attribute, the
 * value must be enclosed in quotes.</li>
 * <li>Template variables may not appear in the context of an attribute name,
 * nor elsewhere inside a tag except within a quoted attribute value.
 * </li>
 * <li>The template must end in "inner HTML" context, and not inside a tag or
 * attribute.</li>
 * </ol>
 *
 * <p>
 * The parser produces a parsed form of the template (returned as a
 * {@link ParsedHtmlTemplate}) consisting of a sequence of chunks corresponding
 * to the literal strings and parameters of the template. The parser is HTML
 * context aware and tags each parameter with its parameter index as well as a
 * {@link HtmlContext} that corresponds to the HTML context in which the
 * parameter occurs in the template.
 *
 * <p>
 * The following contexts are recognized and instantiated:
 * <dl>
 * <dt>{@link HtmlContext.Type#TEXT}
 * <dd>This context corresponds to basic inner text. In the above example,
 * parameter #3 would be tagged with this context.
 * <dt>{@link HtmlContext.Type#URL_ATTRIBUTE_START}
 * <dd>This context corresponds to a parameter that appears at the very start of
 * a URL-valued HTML attribute's value; in the above example this applies to
 * parameter #1.
 * <dt>{@link HtmlContext.Type#URL_ATTRIBUTE_ENTIRE}
 * <dd>This context corresponds to a parameter that comprises an entire
 * URL-valued attribute, for example in {@code <img src='{0}'/>}.
 * <dt>{@link HtmlContext.Type#CSS_ATTRIBUTE_START}
 * <dd>This context corresponds to a parameter that appears at the very
 * beginning of a {@code style} attribute's value; in the above example this
 * applies to parameter #0.
 * <dt>{@link HtmlContext.Type#CSS_ATTRIBUTE}
 * <dd>This context corresponds to a parameter that appears in the context of a
 * {@code style} attribute, except at the very beginning of the attribute's
 * value.
 * <dt>{@link HtmlContext.Type#ATTRIBUTE_VALUE}
 * <dd>This context corresponds to a parameter that appears within an attribute
 * and is not in one of the more specific in-attribute contexts above. In
 * the example, this applies to parameter #2.
 * <dt>{@link HtmlContext.Type#CSS}
 * <dd>This context corresponds to a parameter that appears within a
 * {@code <style>} tag.
 * </dl>
 *
 * <p>
 * For attribute contexts, the {@code tag} and {@code attribute} properties
 * of the context are set to the name of the enclosing tag and attribute,
 * respectively.
 *
 * <p>
 * The implementation is subject to the following limitation:
 *
 * <p>
 * There is no escaping mechanism for the parameter syntax, i.e. it is
 * impossible to write a template that results in a literal output chunk
 * containing a substring of the form "{@code {0}}".
 *
 * <p>
 * This class is not thread safe.
 */
final class HtmlTemplateParser {

  /**
   * Pattern to find template parameters references.
   */
  private static final Pattern TEMPLATE_PARAM_PATTERN =
      Pattern.compile("\\{(\\d+)\\}");

  private final TreeLogger logger;

  private final ParsedHtmlTemplate parsedTemplate;

  private final HtmlParser streamHtmlParser;

  /**
   * The template string being parsed.
   */
  private String template;

  /**
   * The index in the template up to which the template has been parsed.
   *
   * <p>
   * Used for error reporting.
   */
  private int parsePosition;

  /**
   * The character preceding a template parameter, at the time a template
   * parameter is being parsed.
   */
  private char lookBehind;

  /**
   * The character succeeding a template parameter, at the time a template
   * parameter is being parsed.
   */
  private char lookAhead;

  /**
   * Creates a {@link HtmlTemplateParser}.
   *
   * @param logger the {@link TreeLogger} to log to
   */
  public HtmlTemplateParser(TreeLogger logger) {
    this.logger = logger;
    this.parsedTemplate = new ParsedHtmlTemplate();
    this.streamHtmlParser = HtmlParserFactory.createParser();
  }

  /**
   * Returns the parsed representation of the template.
   */
  public ParsedHtmlTemplate getParsedTemplate() {
    return parsedTemplate;
  }

  /**
   * Parses a {@link String} that may contain template parameters of the form
   * {@code {n}} into corresponding literal and parameter
   * {@link ParsedHtmlTemplate.TemplateChunk}s.
   *
   * @param template the template {@link String} to parse
   * @throws UnableToCompleteException if an unrecoverable parse error occurs
   */
  // @VisibleForTesting
  void parseTemplate(String template) throws UnableToCompleteException {
    this.template = template;
    parsePosition = 0;
    lookBehind = 0;
    lookAhead = 0;
    Matcher match = TEMPLATE_PARAM_PATTERN.matcher(template);

    int endOfPreviousMatch = 0;
    while (match.find()) {
      if (match.start() > endOfPreviousMatch) {
        // There is a non-empty string between the previous match and this
        // match; add this as a literal chunk to the parsed representation.
        parseAndAppendTemplateSegment(
            template.substring(endOfPreviousMatch, match.start()));
        parsePosition = match.start();
        lookBehind = template.charAt(parsePosition - 1);
      }

      int paramIndex = Integer.parseInt(match.group(1));
      parsePosition = match.end();
      if (parsePosition < template.length()) {
        lookAhead = template.charAt(parsePosition);
      } else {
        lookAhead = 0;
      }
      parsedTemplate.addParameter(
          new ParameterChunk(getHtmlContextFromParseState(), paramIndex));

      endOfPreviousMatch = match.end();
    }

    // Add a literal chunk for the substring after the last match, if any.
    if (endOfPreviousMatch < template.length()) {
      parseAndAppendTemplateSegment(template.substring(endOfPreviousMatch));
    }

    if (!streamHtmlParser.getState().equals(HtmlParser.STATE_TEXT)) {
      logger.log(TreeLogger.ERROR,
          "Template does not end in inner-HTML context: " + template);
      throw new UnableToCompleteException();
    }
  }

  /**
   * Determines the {@link HtmlContext} in the parser's current state.
   *
   * <p>
   * This method translates from the stream HTML parser's internal state
   * representation to our HTML context representation, and is intended to be
   * invoked at the point where a template variable is encountered.
   *
   * <p>
   * This method checks for certain illegal/unsupported template constructs,
   * such as template variables that occur in an un-quoted attribute (see this
   * class' class documentation for details).
   *
   * @throws UnableToCompleteException if an illegal/unuspported template
   *           construct is encountered
   */
  private HtmlContext getHtmlContextFromParseState()
      throws UnableToCompleteException {
    // TODO(xtof): Consider refactoring such that state related to the position
    // of the template variable in an attribute is exposed separately (as
    // HtmlContext#isAttributeStart(), etc). In doing so, consider trade off
    // between combinatorial explosion of possible states vs. complexity of
    // client code.
    if (streamHtmlParser.getState().equals(HtmlParser.STATE_ERROR)) {
      logger.log(TreeLogger.ERROR,
          "Parsing template resulted in parse error: "
              + getTemplateParsedSoFar());
      throw new UnableToCompleteException();
    }

    if (streamHtmlParser.inJavascript()) {
      logger.log(TreeLogger.ERROR,
          "Template variables in javascript context are not supported: "
              + getTemplateParsedSoFar());
      throw new UnableToCompleteException();
    }
    if (streamHtmlParser.getState().equals(HtmlParser.STATE_COMMENT)) {
      logger.log(TreeLogger.ERROR,
          "Template variables inside HTML comments are not supported: "
              + getTemplateParsedSoFar());
      throw new UnableToCompleteException();
    } else if (streamHtmlParser.getState().equals(HtmlParser.STATE_TEXT)
        && !streamHtmlParser.inCss()) {
      return new HtmlContext(HtmlContext.Type.TEXT);
    } else if (streamHtmlParser.getState().equals(HtmlParser.STATE_VALUE)) {
      final String tag = streamHtmlParser.getTag();
      final String attribute = streamHtmlParser.getAttribute();
      Preconditions.checkState(!tag.equals(""),
          "streamHtmlParser.getTag() should not be empty  while in "
              + "attribute value context; at %s", getTemplateParsedSoFar());
      Preconditions.checkState(!attribute.equals(""),
          "streamHtmlParser.getAttribute() should not be empty while in "
              + "attribute value context; at %s", getTemplateParsedSoFar());
      if (!streamHtmlParser.isAttributeQuoted()) {
        logger.log(TreeLogger.ERROR,
            "Template variable in unquoted attribute value: "
                + getTemplateParsedSoFar());
        throw new UnableToCompleteException();
      }
      if ("meta".equals(tag) && "content".equals(attribute)) {
        logger.log(TreeLogger.ERROR,
            "Template variables in content attribute of meta tag are not supported: "
                + getTemplateParsedSoFar());
        throw new UnableToCompleteException();
      }
      if (streamHtmlParser.isUrlStart()) {
        // Note that we have established above that the attribute is quoted.
        // Furthermore, we have ruled out template variables in the content
        // attribute of a meta tag, which is the only case where isUrlStart()
        // is true and the URL does not appear at the very beginning of the
        // attribute.
        Preconditions.checkState(lookBehind == '"' || lookBehind == '\'',
            "At the start of a quoted attribute, lookBehind should be a quote character; at %s",
            getTemplateParsedSoFar());
        // If the the character immediately succeeding the template parameter is
        // a quote that matches the one that started the attribute, we know
        // that the parameter comprises the entire attribute.
        if (lookAhead == lookBehind) {
          return new HtmlContext(HtmlContext.Type.URL_ATTRIBUTE_ENTIRE, tag, attribute);
        } else {
          return new HtmlContext(HtmlContext.Type.URL_ATTRIBUTE_START, tag, attribute);
        }
      } else if (streamHtmlParser.inCss()) {
        if (streamHtmlParser.getValueIndex() == 0) {
          return new HtmlContext(HtmlContext.Type.CSS_ATTRIBUTE_START, tag, attribute);
        } else {
          return new HtmlContext(HtmlContext.Type.CSS_ATTRIBUTE, tag, attribute);
        }
      } else {
        return new HtmlContext(
            HtmlContext.Type.ATTRIBUTE_VALUE, tag, attribute);
      }
    } else if (streamHtmlParser.inCss()) {
      return new HtmlContext(HtmlContext.Type.CSS);
    } else if (streamHtmlParser.getState().equals(HtmlParser.STATE_TAG)
        || streamHtmlParser.inAttribute()) {
      logger.log(TreeLogger.ERROR,
          "Template variables in tags or in attribute names are not supported: "
              + getTemplateParsedSoFar());
      throw new UnableToCompleteException();
    }

    logger.log(TreeLogger.ERROR,
        "unhandeled/illegal parse state" + streamHtmlParser.getState());
    throw new UnableToCompleteException();
  }

  /**
   * Returns the prefix of the template string that has been parsed so far.
   */
  private String getTemplateParsedSoFar() {
    return template.substring(0, parsePosition);
  }

  /**
   * Feeds a literal string to the stream parser and appends it to the parsed
   * template representation.
   *
   * @param segment the template segment to parse and append to the parsed
   *          template representation
   * @throws UnableToCompleteException if an unrecoverable parse error occurs
   */
  private void parseAndAppendTemplateSegment(String segment)
      throws UnableToCompleteException {
    try {
      streamHtmlParser.parse(segment);
    } catch (ParseException cause) {
      logger.log(TreeLogger.ERROR,
          "Parse exception when parsing segment '" + segment + "' of template '"
              + template + "'", cause);
      throw new UnableToCompleteException();
    }
    parsedTemplate.addLiteral(segment);
  }
}