src/main/java/com/google/devtools/build/lib/syntax/StarlarkFile.java

// Copyright 2014 The Bazel Authors. All rights reserved.
//
// 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.devtools.build.lib.syntax;

import com.google.common.collect.ImmutableList;
import com.google.common.hash.HashCode;
import com.google.devtools.build.lib.events.Event;
import java.io.IOException;
import java.util.Collections;
import java.util.List;
import javax.annotation.Nullable;

/**
 * Syntax tree for a Starlark file, such as a Bazel BUILD or .bzl file.
 *
 * <p>Call {@link #parse} to parse a file. Parser errors are recorded in the syntax tree (see {@link
 * #errors}), which may be incomplete.
 */
public final class StarlarkFile extends Node {

  private final ImmutableList<Statement> statements;
  private final ImmutableList<Comment> comments;
  final List<Event> errors; // appended to by ValidationEnvironment
  private final List<Event> stringEscapeEvents;
  @Nullable private final String contentHashCode;

  private StarlarkFile(
      ImmutableList<Statement> statements,
      List<Event> errors,
      String contentHashCode,
      Lexer.LexerLocation location,
      ImmutableList<Comment> comments,
      List<Event> stringEscapeEvents) {
    this.statements = statements;
    this.comments = comments;
    this.errors = errors;
    this.stringEscapeEvents = stringEscapeEvents;
    this.contentHashCode = contentHashCode;
    this.setLocation(location);
  }

  private static StarlarkFile create(
      List<Statement> preludeStatements,
      Parser.ParseResult result,
      String contentHashCode,
      boolean allowImportInternal) {
    ImmutableList.Builder<Statement> statementsbuilder =
        ImmutableList.<Statement>builder().addAll(preludeStatements);

    if (allowImportInternal) {
      for (Statement stmt : result.statements) {
        if (stmt instanceof LoadStatement) {
          statementsbuilder.add(LoadStatement.allowLoadingOfInternalSymbols((LoadStatement) stmt));
        } else {
          statementsbuilder.add(stmt);
        }
      }
    } else {
      statementsbuilder.addAll(result.statements);
    }
    ImmutableList<Statement> statements = statementsbuilder.build();
    return new StarlarkFile(
        statements,
        result.errors,
        contentHashCode,
        result.location,
        ImmutableList.copyOf(result.comments),
        result.stringEscapeEvents);
  }

  /**
   * Extract a subtree containing only statements from {@code firstStatement} (included) up to
   * {@code lastStatement} excluded.
   */
  public StarlarkFile subTree(int firstStatement, int lastStatement) {
    ImmutableList<Statement> statements = this.statements.subList(firstStatement, lastStatement);
    return new StarlarkFile(
        statements,
        errors,
        null,
        (Lexer.LexerLocation) this.statements.get(firstStatement).getStartLocation(),
        ImmutableList.of(),
        stringEscapeEvents);
  }

  /**
   * Returns an unmodifiable view of the list of scanner, parser, and (perhaps) resolver errors
   * accumulated in this Starlark file.
   */
  public List<Event> errors() {
    return Collections.unmodifiableList(errors);
  }

  /** Returns errors().isEmpty(). */
  public boolean ok() {
    return errors.isEmpty();
  }

  /**
   * Appends string escaping errors to {@code errors}. The Lexer diverts such errors into a separate
   * bucket as they should be selectively reported depending on a StarlarkSemantics, to which the
   * lexer/parser does not have access. This function is called by ValidationEnvironment, which has
   * access to a StarlarkSemantics and can thus decide whether to respect or ignore these events.
   *
   * <p>Naturally this function should be called at most once.
   */
  void addStringEscapeEvents() {
    errors.addAll(stringEscapeEvents);
  }

  /** Returns an (immutable, ordered) list of statements in this BUILD file. */
  public ImmutableList<Statement> getStatements() {
    return statements;
  }

  /** Returns an (immutable, ordered) list of comments in this BUILD file. */
  public ImmutableList<Comment> getComments() {
    return comments;
  }

  @Override
  public String toString() {
    return "<StarlarkFile with " + statements.size() + " statements>";
  }

  @Override
  public void accept(NodeVisitor visitor) {
    visitor.visit(this);
  }

  /**
   * Parse the specified file, returning its syntax tree with the preludeStatements inserted at the
   * front of its statement list.
   */
  public static StarlarkFile parseWithPrelude(
      ParserInput input, List<Statement> preludeStatements) {
    Parser.ParseResult result = Parser.parseFile(input);
    return create(
        preludeStatements, result, /* contentHashCode= */ null, /*allowImportInternal=*/ false);
  }

  /**
   * Parse the specified build file, returning its AST. All load statements parsed that way will be
   * exempt from visibility restrictions.
   */
  // TODO(adonovan): make LoadStatement.allowInternal publicly settable, and delete this.
  public static StarlarkFile parseVirtualBuildFile(
      ParserInput input, List<Statement> preludeStatements) {
    Parser.ParseResult result = Parser.parseFile(input);
    return create(
        preludeStatements, result, /* contentHashCode= */ null, /*allowImportInternal=*/ true);
  }

  // TODO(adonovan): make the digest publicly settable, and delete this.
  public static StarlarkFile parseWithDigest(ParserInput input, byte[] digest) throws IOException {
    Parser.ParseResult result = Parser.parseFile(input);
    return create(
        /* preludeStatements= */ ImmutableList.of(),
        result,
        HashCode.fromBytes(digest).toString(),
        /* allowImportInternal= */ false);
  }

  /**
   * Parse a Starlark file.
   *
   * <p>A syntax tree is always returned, even in case of error. Errors are recorded in the tree.
   * Example usage:
   *
   * <pre>
   * StarlarkFile file = StarlarkFile.parse(input);
   * if (!file.ok()) {
   *    Event.replayEventsOn(handler, file.errors());
   *    ...
   * }
   * </pre>
   */
  public static StarlarkFile parse(ParserInput input) {
    Parser.ParseResult result = Parser.parseFile(input);
    return create(
        /* preludeStatements= */ ImmutableList.of(),
        result,
        /* contentHashCode= */ null,
        /* allowImportInternal=*/ false);
  }

  /**
   * Returns a hash code calculated from the string content of the source file of this AST.
   */
  @Nullable public String getContentHashCode() {
    return contentHashCode;
  }
}