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

// Copyright 2018 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.devtools.build.lib.events.Location;
import java.util.Collection;
import java.util.function.Predicate;
import javax.annotation.Nullable;

/** A context in which debugging can occur. Implemented by Skylark environments. */
public interface Debuggable {

  /** Evaluates a Skylark statement in the adapter's environment. */
  Object evaluate(String statement) throws EvalException, InterruptedException;

  /**
   * Returns the stack frames corresponding of the context's current (paused) state.
   *
   * <p>For all stack frames except the innermost, location information is retrieved from the
   * current context. The innermost frame's location must be supplied as {@code currentLocation} by
   * the caller.
   */
  Collection<DebugFrame> listFrames(Location currentLocation);

  /**
   * Given a requested stepping behavior, returns a predicate over the context that tells the
   * debugger when to pause.
   *
   * <p>The predicate will return true if we are at the next statement where execution should pause,
   * and it will return false if we are not yet at that statement. No guarantee is made about the
   * predicate's return value after we have reached the desired statement.
   *
   * <p>A null return value indicates that no further pausing should occur.
   */
  @Nullable
  ReadyToPause stepControl(Stepping stepping);

  /**
   * When stepping, this determines whether or not the context has yet reached a state for which
   * execution should be paused.
   *
   * <p>A single instance is only useful for advancing by one pause. A new instance may be required
   * after that.
   */
  interface ReadyToPause extends Predicate<Environment> {}

  /** Describes the stepping behavior that should occur when execution of a thread is continued. */
  enum Stepping {
    /** Continue execution without stepping. */
    NONE,
    /**
     * If the thread is paused on a statement that contains a function call, step into that
     * function. Otherwise, this is the same as OVER.
     */
    INTO,
    /**
     * Step over the current statement and any functions that it may call, stopping at the next
     * statement in the same frame. If no more statements are available in the current frame, same
     * as OUT.
     */
    OVER,
    /**
     * Continue execution until the current frame has been exited and then pause. If we are
     * currently in the outer-most frame, same as NONE.
     */
    OUT,
  }
}