src/com/google/clearsilver/jsilver/syntax/StructuralWhitespaceStripper.java

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

import com.google.clearsilver.jsilver.syntax.analysis.DepthFirstAdapter;
import com.google.clearsilver.jsilver.syntax.node.AAltCommand;
import com.google.clearsilver.jsilver.syntax.node.ACallCommand;
import com.google.clearsilver.jsilver.syntax.node.ADataCommand;
import com.google.clearsilver.jsilver.syntax.node.ADefCommand;
import com.google.clearsilver.jsilver.syntax.node.AEachCommand;
import com.google.clearsilver.jsilver.syntax.node.AEscapeCommand;
import com.google.clearsilver.jsilver.syntax.node.AEvarCommand;
import com.google.clearsilver.jsilver.syntax.node.AIfCommand;
import com.google.clearsilver.jsilver.syntax.node.ALoopCommand;
import com.google.clearsilver.jsilver.syntax.node.ALoopIncCommand;
import com.google.clearsilver.jsilver.syntax.node.ALoopToCommand;
import com.google.clearsilver.jsilver.syntax.node.ALvarCommand;
import com.google.clearsilver.jsilver.syntax.node.ANameCommand;
import com.google.clearsilver.jsilver.syntax.node.ANoopCommand;
import com.google.clearsilver.jsilver.syntax.node.ASetCommand;
import com.google.clearsilver.jsilver.syntax.node.AUvarCommand;
import com.google.clearsilver.jsilver.syntax.node.AVarCommand;
import com.google.clearsilver.jsilver.syntax.node.AWithCommand;
import com.google.clearsilver.jsilver.syntax.node.Start;
import com.google.clearsilver.jsilver.syntax.node.TData;

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

/**
 * Detects sequences of commands corresponding to a line in the template containing only structural
 * commands, comments or whitespace and rewrites the syntax tree to effectively remove any data
 * (text) associated with that line (including the trailing whitespace).
 * <p>
 * A structural command is any command that never emits any output. These come in three types:
 * <ul>
 * <li>Commands that can contain other commands (eg, "alt", "each", "escape", "if", "loop", "with",
 * etc...).
 * <li>Commands that operate on the template itself (eg, "include", "autoescape", etc...).
 * <li>Comments.
 * </ul>
 * <p>
 * This makes it much easier to write human readable templates in cases where the output format is
 * whitespace sensitive.
 * <p>
 * Thus the input:
 * 
 * <pre>
 * {@literal
 * ----------------
 * Value is:
 * <?cs if:x>0 ?>
 *   positive
 * <?cs elif:x<0 ?>
 *   negative
 * <?cs else ?>
 *   zero
 * <?cs /if ?>.
 * ----------------
 * }
 * </pre>
 * is equivalent to:
 * 
 * <pre>
 * {@literal
 * ----------------
 * Value is:
 * <?cs if:x>0 ?>  positive
 * <?cs elif:x<0 ?>  negative
 * <?cs else ?>  zero
 * <?cs /if ?>.
 * ----------------
 * }
 * </pre>
 * but is much easier to read.
 * <p>
 * Where data commands become empty they are replaced with Noop commands, which effectively removes
 * them from the tree. These can be removed (if needed) by a later optimization step but shouldn't
 * cause any issues.
 */
public class StructuralWhitespaceStripper extends DepthFirstAdapter {
  /**
   * A regex snippet to match sequences of inline whitespace. The easiest way to define this is as
   * "not (non-space or newline)".
   */
  private static final String IWS = "[^\\S\\n]*";

  /** Pattern to match strings that consist only of inline whitespace. */
  private static final Pattern INLINE_WHITESPACE = Pattern.compile(IWS);

  /**
   * Pattern to match strings that start with arbitrary (inline) whitespace, followed by a newline.
   */
  private static final Pattern STARTS_WITH_NEWLINE = Pattern.compile("^" + IWS + "\\n");

  /**
   * Pattern to match strings that end with a newline, followed by trailing (inline) whitespace.
   */
  private static final Pattern ENDS_WITH_NEWLINE = Pattern.compile("\\n" + IWS + "$");

  /**
   * Pattern to capture the content of a string after a leading newline. Only ever used on input
   * that previously matched STARTS_WITH_NEWLINE.
   */
  private static final Pattern LEADING_WHITESPACE_AND_NEWLINE =
      Pattern.compile("^" + IWS + "\\n(.*)$", Pattern.DOTALL);

  /**
   * Pattern to capture the content of a string before a trailing newline. Note that this may have
   * to match text that has already had the final newline removed so we must greedily match the
   * whitespace rather than the content.
   */
  private static final Pattern TRAILING_WHITESPACE =
      Pattern.compile("^(.*?)" + IWS + "$", Pattern.DOTALL);

  /**
   * Flag to tell us if we are in whitespace chomping mode. By default we start in this mode because
   * the content of the first line in a template is not preceded by a newline (but should behave as
   * if it was). Once this flag has been set to false, it remains unset until a new line is
   * encountered.
   * <p>
   * Note that we only actually remove whitespace when we find the terminating condition rather than
   * when as visit the nodes (ie, this mode can be aborted and any visited whitespace will be left
   * untouched).
   */
  private boolean maybeChompWhitespace = true;

  /**
   * Flag to tell us if the line we are processing has an inline command in it.
   * <p>
   * An inline command is a complex command (eg. 'if', 'loop') where both the start and end of the
   * command exists on the same line. Non-complex commands (eg. 'var', 'name') cannot be considered
   * inline.
   * <p>
   * This flag is set when we process the start of a complex command and unset when we finish
   * processing a line. Thus if the flag is still true when we encounter the end of a complex
   * command, it tells us that (at least one) complex command was entirely contained within the
   * current line and that we should stop chomping whitespace for the current line.
   * <p>
   * This means we can detect input such as:
   * 
   * <pre>
   * {@literal <?cs if:x?>   <?cs /if?>}
   * </pre>
   * for which the trailing newline and surrounding whitespace should not be removed, as opposed to:
   * 
   * <pre>
   * {@literal <?cs if:x?>
   *    something
   *  <?cs /if?>
   * }
   * </pre>
   * where the trailing newlines for both the opening and closing of the 'if' command should be
   * removed.
   */
  private boolean currentLineContainsInlineComplexCommand = false;

  /**
   * First data command we saw when we started 'chomping' whitespace (note that this can be null if
   * we are at the beginning of a file or when we have chomped a previous data command down to
   * nothing).
   */
  private ADataCommand firstChompedData = null;

  /**
   * Intermediate whitespace-only data commands that we may need to remove.
   * <p>
   * This list is built up as we visit commands and is either processed when we need to remove
   * structural whitespace or cleared if we encounter situations that prohibit whitespace removal.
   */
  private List<ADataCommand> whitespaceData = new ArrayList<ADataCommand>();

  private static boolean isInlineWhitespace(String text) {
    return INLINE_WHITESPACE.matcher(text).matches();
  }

  private static boolean startsWithNewline(String text) {
    return STARTS_WITH_NEWLINE.matcher(text).find();
  }

  private static boolean endsWithNewline(String text) {
    return ENDS_WITH_NEWLINE.matcher(text).find();
  }

  /**
   * Removes leading whitespace (including first newline) from the given string. The text must start
   * with optional whitespace followed by a newline.
   */
  private static String stripLeadingWhitespaceAndNewline(String text) {
    Matcher matcher = LEADING_WHITESPACE_AND_NEWLINE.matcher(text);
    if (!matcher.matches()) {
      throw new IllegalStateException("Text '" + text + "' should have leading whitespace/newline.");
    }
    return matcher.group(1);
  }

  /**
   * Removes trailing whitespace (if present) from the given string.
   */
  private static String stripTrailingWhitespace(String text) {
    Matcher matcher = TRAILING_WHITESPACE.matcher(text);
    if (!matcher.matches()) {
      // The trailing whitespace regex should never fail to match a string.
      throw new AssertionError("Error in regular expression");
    }
    return matcher.group(1);
  }

  /**
   * Remove whitespace (including first newline) from the start of the given data command (replacing
   * it with a Noop command if it becomes empty). Returns a modified data command, or null if all
   * text was removed.
   * <p>
   * The given command can be null at the beginning of the file or if the original data command was
   * entirely consumed by a previous strip operation (remember that data commands can be processed
   * twice, at both the start and end of a whitespace sequence).
   */
  private static ADataCommand stripLeadingWhitespaceAndNewline(ADataCommand data) {
    if (data != null) {
      String text = stripLeadingWhitespaceAndNewline(data.getData().getText());
      if (text.isEmpty()) {
        data.replaceBy(new ANoopCommand());
        // Returning null just means we have chomped the whitespace to nothing.
        data = null;
      } else {
        data.setData(new TData(text));
      }
    }
    return data;
  }

  /**
   * Removes whitespace from the end of the given data command (replacing it with a Noop command if
   * it becomes empty).
   */
  private static void stripTrailingWhitespace(ADataCommand data) {
    if (data != null) {
      String text = stripTrailingWhitespace(data.getData().getText());
      if (text.isEmpty()) {
        data.replaceBy(new ANoopCommand());
      } else {
        data.setData(new TData(text));
      }
    }
  }

  /**
   * Removes all data commands collected while chomping the current line and clears the given list.
   */
  private static void removeWhitespace(List<ADataCommand> whitespaceData) {
    for (ADataCommand data : whitespaceData) {
      data.replaceBy(new ANoopCommand());
    }
    whitespaceData.clear();
  }

  @Override
  public void caseStart(Start node) {
    // Process the hierarchy.
    super.caseStart(node);
    // We might end after processing a non-data node, so deal with any
    // unprocessed whitespace before we exit.
    if (maybeChompWhitespace) {
      stripTrailingWhitespace(firstChompedData);
      removeWhitespace(whitespaceData);
      firstChompedData = null;
    }
    // Verify we have consumed (and cleared) any object references.
    if (firstChompedData != null) {
      throw new IllegalStateException("Unexpected first data node.");
    }
    if (!whitespaceData.isEmpty()) {
      throw new IllegalStateException("Unexpected data nodes.");
    }
  }

  @Override
  public void caseADataCommand(ADataCommand data) {
    final String originalText = data.getData().getText();
    if (maybeChompWhitespace) {
      if (isInlineWhitespace(originalText)) {
        // This data command is whitespace between two commands on the same
        // line, simply chomp it and continue ("Om-nom-nom").
        whitespaceData.add(data);
        return;
      }
      if (startsWithNewline(originalText)) {
        // This data command is at the end of a line that contains only
        // structural commands and whitespace. We remove all whitespace
        // associated with this line by:
        // * Stripping whitespace from the end of the data command at the start
        // of this line.
        // * Removing all intermediate (whitespace only) data commands.
        // * Stripping whitespace from the start of the current data command.
        stripTrailingWhitespace(firstChompedData);
        removeWhitespace(whitespaceData);
        data = stripLeadingWhitespaceAndNewline(data);
        currentLineContainsInlineComplexCommand = false;
      } else {
        // This data command contains some non-whitespace text so we must abort
        // the chomping of this line and output it normally.
        abortWhitespaceChompingForCurrentLine();
      }
    }
    // Test to see if we should start chomping on the next line.
    maybeChompWhitespace = endsWithNewline(originalText);
    // Note that data can be null here if we stripped all the whitespace from
    // it (which means that firstChompedData can be null next time around).
    firstChompedData = maybeChompWhitespace ? data : null;
  }

  /**
   * Helper method to abort whitespace processing for the current line. This method is idempotent on
   * a per line basis, and once it has been called the state is only reset at the start of the next
   * line.
   */
  private void abortWhitespaceChompingForCurrentLine() {
    maybeChompWhitespace = false;
    currentLineContainsInlineComplexCommand = false;
    whitespaceData.clear();
  }

  // ---- Inline commands that prohibit whitespace removal. ----

  @Override
  public void inAAltCommand(AAltCommand node) {
    abortWhitespaceChompingForCurrentLine();
  }

  @Override
  public void inACallCommand(ACallCommand node) {
    abortWhitespaceChompingForCurrentLine();
  }

  @Override
  public void inAEvarCommand(AEvarCommand node) {
    abortWhitespaceChompingForCurrentLine();
  }

  @Override
  public void inALvarCommand(ALvarCommand node) {
    abortWhitespaceChompingForCurrentLine();
  }

  @Override
  public void inANameCommand(ANameCommand node) {
    abortWhitespaceChompingForCurrentLine();
  }

  @Override
  public void inASetCommand(ASetCommand node) {
    abortWhitespaceChompingForCurrentLine();
  }

  @Override
  public void inAUvarCommand(AUvarCommand node) {
    abortWhitespaceChompingForCurrentLine();
  }

  @Override
  public void inAVarCommand(AVarCommand node) {
    abortWhitespaceChompingForCurrentLine();
  }

  // ---- Two part (open/close) commands that can have child commands. ----

  public void enterComplexCommand() {
    currentLineContainsInlineComplexCommand = true;
  }

  public void exitComplexCommand() {
    if (currentLineContainsInlineComplexCommand) {
      abortWhitespaceChompingForCurrentLine();
    }
  }

  @Override
  public void caseAAltCommand(AAltCommand node) {
    enterComplexCommand();
    super.caseAAltCommand(node);
    exitComplexCommand();
  }

  @Override
  public void caseADefCommand(ADefCommand node) {
    enterComplexCommand();
    super.caseADefCommand(node);
    exitComplexCommand();
  }

  @Override
  public void caseAEachCommand(AEachCommand node) {
    enterComplexCommand();
    super.caseAEachCommand(node);
    exitComplexCommand();
  }

  @Override
  public void caseAEscapeCommand(AEscapeCommand node) {
    enterComplexCommand();
    super.caseAEscapeCommand(node);
    exitComplexCommand();
  }

  @Override
  public void caseAIfCommand(AIfCommand node) {
    enterComplexCommand();
    super.caseAIfCommand(node);
    exitComplexCommand();
  }

  @Override
  public void caseALoopCommand(ALoopCommand node) {
    enterComplexCommand();
    super.caseALoopCommand(node);
    exitComplexCommand();
  }

  @Override
  public void caseALoopIncCommand(ALoopIncCommand node) {
    enterComplexCommand();
    super.caseALoopIncCommand(node);
    exitComplexCommand();
  }

  @Override
  public void caseALoopToCommand(ALoopToCommand node) {
    enterComplexCommand();
    super.caseALoopToCommand(node);
    exitComplexCommand();
  }

  @Override
  public void caseAWithCommand(AWithCommand node) {
    enterComplexCommand();
    super.caseAWithCommand(node);
    exitComplexCommand();
  }
}