src/main/java/net/starlark/java/syntax/NodeVisitor.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 net.starlark.java.syntax;

import java.util.List;

/**
 * A visitor for visiting the nodes of a syntax tree in lexical order (not evaluation order!).
 *
 * <p>Comments are *not* visited.
 *
 * <p>A subclass can change the traversal logic by setting {@link #skipNonSymbolIdentifiers}.
 *
 * <p>Typical usage is for a subclass to just override the {@code visit()} method overloads for the
 * nodes that are relevant to its business logic, and to rely on the default implementations in this
 * class to ensure traversal over the remaining node types. Overriding implementations should
 * remember to traverse children using either {@code super.visit()} on the current node, or explicit
 * calls to {@link #visit(Node)}, {@link #visitAll}, or {@link #visitBlock} on child fields.
 *
 * <p>Contrary to usual Java style, it is *not* recommended to strictly group all overloads of
 * {@code visit()} together, but rather to place helper methods for a specific node type next to its
 * associated {@code visit()} overload. Rationale: The benefit of this style rule is that a reader
 * can rely on the absence of an overload in the immediate vicinity of the method as evidence that
 * no such overload exists. But this isn't helpful in the context of the visitor pattern, where the
 * reader expects there to be many unrelated overloads.
 */
public class NodeVisitor {

  /**
   * If set, we only visit {@link Identifier}s that correspond to a definition or use of a symbol in
   * the current file. Specifically, this omits:
   *
   * <ul>
   *   <li>names of keyword arguments (but not names of keyword parameters!)
   *   <li>field names in dot expressions
   * </ul>
   *
   * <p>Note that {@code Identifier}s in such contexts have no {@link Binding} set for them by the
   * resolver.
   */
  protected boolean skipNonSymbolIdentifiers = false;

  // visit() overloads in this class are ordered by node type, first by category (misc / statement /
  // expression), then alphabetically within category. (Subclasses are not obliged to maintain the
  // same method ordering.)

  /** Entrypoint for visiting a node. Clients should avoid calling node-specific overloads. */
  public void visit(Node node) {
    // Double-dispatch pattern.
    // If a node type is added to the AST but no corresponding overload added to this class, we'll
    // see an infinite recursion in this method.
    node.accept(this);
  }

  // ==== Miscellaneous node types ====

  /**
   * Handles all four Argument node types uniformly. Subclasses should not add an overload for a
   * concrete Argument subclass; it won't be called.
   */
  public void visit(Argument node) {
    if (!skipNonSymbolIdentifiers && node instanceof Argument.Keyword keyword) {
      visit(keyword.getIdentifier());
    }
    visit(node.getValue());
  }

  /**
   * @deprecated Not supported.
   * @throws UnsupportedOperationException always.
   */
  @Deprecated
  public void visit(@SuppressWarnings("unused") Comment node) {
    // No reason we can't support this if we needed to.
    throw new UnsupportedOperationException("NodeVisitor does not support visiting comments");
  }

  // Clause and Entry are handled below next to Comprehension and Dict respectively.

  /**
   * Handles all four Parameter node types uniformly. Subclasses should not add an overload for a
   * concrete Parameter subclass; it won't be called.
   */
  public void visit(Parameter node) {
    if (node.getIdentifier() != null) {
      visit(node.getIdentifier());
    }
    if (node.getType() != null) {
      visit(node.getType());
    }
    if (node.getDefaultValue() != null) {
      visit(node.getDefaultValue());
    }
  }

  public void visit(StarlarkFile node) {
    visitBlock(node.getStatements());
  }

  // ==== Statement nodes ====

  public void visit(AssignmentStatement node) {
    visit(node.getLHS());
    if (node.getType() != null) {
      visit(node.getType());
    }
    visit(node.getRHS());
  }

  public void visit(ExpressionStatement node) {
    visit(node.getExpression());
  }

  public void visit(FlowStatement node) {}

  public void visit(ForStatement node) {
    visit(node.getVars());
    visit(node.getCollection());
    visitBlock(node.getBody());
  }

  public void visit(DefStatement node) {
    visit(node.getIdentifier());
    visitAll(node.getTypeParameters());
    visitAll(node.getParameters());
    if (node.getReturnType() != null) {
      visit(node.getReturnType());
    }
    visitBlock(node.getBody());
  }

  public void visit(IfStatement node) {
    visit(node.getCondition());
    visitBlock(node.getThenBlock());
    if (node.getElseBlock() != null) {
      visitBlock(node.getElseBlock());
    }
  }

  public void visit(LoadStatement node) {
    for (LoadStatement.Binding binding : node.getBindings()) {
      visit(binding.getLocalName());
      // We don't visit the original name.
      //
      // Currently, our AST doesn't distinguish between the case when the local name is omitted,
      // versus the case where it is given explicitly and exactly matches the original name. This
      // means that, if we visited both names here, we would end up double-visiting something that
      // often only appears once in the program source.
      //
      // TODO(bazel-team): Disambiguate these cases in LoadStatement.Binding, then visit it here,
      // but ONLY if skipNonSymbolIdentifiers is not set. Mind that subclasses might need updating
      // to continue to avoid traversing the original name.
    }
  }

  public void visit(ReturnStatement node) {
    if (node.getResult() != null) {
      visit(node.getResult());
    }
  }

  public void visit(TypeAliasStatement node) {
    visit(node.getIdentifier());
    visitAll(node.getParameters());
    visit(node.getDefinition());
  }

  public void visit(VarStatement node) {
    visit(node.getIdentifier());
    visit(node.getType());
  }

  // ==== Expression nodes ====

  public void visit(BinaryOperatorExpression node) {
    visit(node.getX());
    visit(node.getY());
  }

  public void visit(CallExpression node) {
    visit(node.getFunction());
    visitAll(node.getArguments());
  }

  public void visit(CastExpression node) {
    visit(node.getType());
    visit(node.getValue());
  }

  public void visit(Comprehension node) {
    visit(node.getBody());
    for (Comprehension.Clause clause : node.getClauses()) {
      if (clause instanceof Comprehension.For) {
        visit((Comprehension.For) clause);
      } else {
        visit((Comprehension.If) clause);
      }
    }
  }

  public void visit(Comprehension.For node) {
    visit(node.getVars());
    visit(node.getIterable());
  }

  public void visit(Comprehension.If node) {
    visit(node.getCondition());
  }

  public void visit(ConditionalExpression node) {
    visit(node.getThenCase());
    visit(node.getCondition());
    if (node.getElseCase() != null) {
      visit(node.getElseCase());
    }
  }

  public void visit(DictExpression node) {
    visitAll(node.getEntries());
  }

  public void visit(DictExpression.Entry node) {
    visit(node.getKey());
    visit(node.getValue());
  }

  public void visit(DotExpression node) {
    visit(node.getObject());
    if (!skipNonSymbolIdentifiers) {
      visit(node.getField());
    }
  }

  public void visit(Ellipsis node) {}

  public void visit(@SuppressWarnings("unused") FloatLiteral node) {}

  public void visit(Identifier node) {}

  public void visit(IndexExpression node) {
    visit(node.getObject());
    visit(node.getKey());
  }

  public void visit(@SuppressWarnings("unused") IntLiteral node) {}

  public void visit(IsInstanceExpression node) {
    visit(node.getValue());
    visit(node.getType());
  }

  public void visit(LambdaExpression node) {
    visitAll(node.getParameters());
    visit(node.getBody());
  }

  public void visit(ListExpression node) {
    visitAll(node.getElements());
  }

  public void visit(SliceExpression node) {
    visit(node.getObject());
    if (node.getStart() != null) {
      visit(node.getStart());
    }
    if (node.getStop() != null) {
      visit(node.getStop());
    }
    if (node.getStep() != null) {
      visit(node.getStep());
    }
  }

  public void visit(@SuppressWarnings("unused") StringLiteral node) {}

  public void visit(UnaryOperatorExpression node) {
    visit(node.getX());
  }

  public void visit(TypeApplication node) {
    visit(node.getConstructor());
    visitAll(node.getArguments());
  }

  // ==== Helpers for sequences of nodes ====

  /**
   * Visits a sequence of nodes (e.g. a list of arguments).
   *
   * <p>See {@link #visitBlock} for a common case.
   */
  // Final because this method is called across completely different categories of nodes, so it is
  // usually a mistake to attempt to override it.
  public final void visitAll(List<? extends Node> nodes) {
    for (Node node : nodes) {
      visit(node);
    }
  }

  /** Convenience/readability method for visiting a block of statements (e.g. an if branch). */
  // Previously this method was non-final and it was recommended to override it to perform an action
  // for every block. However, this is error-prone if the subclass inadvertently calls visitAll()
  // rather than visitBlock() in one of its other overrides. No one seems to be overriding either
  // method, so we made both of them final to avoid this potential problem.
  public final void visitBlock(List<Statement> statements) {
    visitAll(statements);
  }
}