There are a number of methods you can implement on your AST nodes to affect how CodeProber interacts with your tool. All APIs should be public Java methods, which CodeProber later accesses via reflection. Some APIs are mandatory, others are optional.

Mandatory API

A small number of methods must be set on the AST nodes, including:

In addition, CodeProber requires one of 5 variants of line/column and child counting methods. It checks for the presence of these accessors in numerical order (Variant 1, Variant 2, …). CodeProber has supports for these multiple variants in order to maximize compatibility with different styles of language implementation. If your are able to chose which variant to support, then variant 1 is preferred.

All line/columns values are expected to start at 1. For example, the top-left corner of a text editor is line 1 column 1. The leftmost column of the second line is line 2 column 1, etc. If you do not have location data for a given node, return 0 in both line and column. Certain features in CodeProber, such as the AST node location tracking, treats line 0 column 0 specially.

Variant 1

Variant 2

Variant 3

Variant 4

Variant 5

This variant automatically assigns line 0 and column 0 to all nodes. This does not provide a good user experience, only use this if absolutely necessary.

Optional API

The following table lists entirely optional APIs. If you are using an API that is not listed here, then it may be deprecated and scheduled for removal. Please open an issue/pull request if you believe the undocumented API you use should be officially maintained.

There are different places where APIs are expected to appear, which are designated by the Where column in the table. Possible places are:

• “ast” - any AST node
• “root” - the root of the AST
• “any” - any datastructure at all. Used when processing results from property evaluation.

Diagnostic class

A common use case for CodeProber is to inspect the result of semantic analysis. The results of such an analysis can both be presented as squiggly lines in the editor, and as text in a probe result area. This is achieved by having a class that implements both the cpr_getOutput and cpr_getDiagnostic APIs, like this:

public class Diagnostic {
    Object humanReadable;
    String diagnostic;

    public Diagnostic(Object humanReadable, String diagnostic) {
      this.humanReadable = humanReadable;
      this.diagnostic = diagnostic;
    }

    public Object cpr_getOutput() { return humanReadable; }
    public String cpr_getDiagnostic() { return diagnostic; }
}

The two fields in Diagnostic represent the probe result area and text editor, respectively. For example (using JastAdd syntax), the following attribute will create a error squiggly line between line 3, column 5 and line 3, column 7:

syn Object Node.demo() = new Diagnostic(
    "This is shown in the probe window"
    String.format("ERR@%d;%d;%s", (3 << 12) + 5, (3 << 12) + 7, "This is shown when the squiggly is hovered")
);

Capture Traces

The cpr_setTraceReceiver API requires a little more explanation.

In the CodeProber settings panel there is a checkbox with the label Capture traces. This allows you to capture information about indirect dependencies of properties. For this to work, the AST root must have a function cpr_setTraceReceiver that looks like this:

public void cpr_setTraceReceiver(java.util.function.Consumer<Object[]> recv) {
  // 'recv' records trace information.
  // You should assign it to a field for later use.
  this.theTraceReceiver = recv;
}

// Later, when something should be added to a trace, call it
// It will be non-null if `Capture traces` is checked.
if (this.theTraceReceiver != null) {
  this.theTraceReceiver.accept(new Object[]{ ... })
}

If recv is called while CodeProber is evaluating a property, then the information there will be visible in the CodeProber UI, if the user has checked Capture traces.

Kinds of trace events

CodeProber will toString the first element in the object array to identify the kinds of trace event. Currently, two types of events are supported, and they match tracing events produced by JastAdd:

COMPUTE_BEGIN

Expected structure:

["COMPUTE_BEGIN", ASTNode node, String attribute, Object params, Object value]

Example invocation to recv in cpr_setTraceReceiver:

recv.accept(new Object[]{ "COMPUTE_BEGIN", someAstNode, "foo()", null, null })

COMPUTE_END

Expected structure:

["COMPUTE_END", ASTNode node, String attribute, Object params, Object value]

Example invocation to recv in cpr_setTraceReceiver:

recv.accept(new Object[]{ "COMPUTE_END", someAstNode, "foo()", null, "ResultValue" })

Tracing locator issues

Tracing can be tricky to get right. You may get errors in the terminal where you started codeprober.jar stating something like:

Failed creating locator for AstNode< [..]

This happens if one of the AST nodes passed to a trace events aren’t attached to the AST anymore. This can happen for example if you mutate the tree through rewrites. You can try toggling the flush tree first checkbox under Capture traces on and off. You can also try changing the cache strategy values back and forth. Some combination of the two might work.

If changing the settings doesn’t work, then you must change which events are reported to CodeProber. Try to avoid setting the ASTNode arguments to nodes that get removed from the tree.

Supporting Tracing In JastAdd

In JastAdd, compile with the flag --tracing=all, and then implement cpr_setTraceReceiver as follows:

public void Program.cpr_setTraceReceiver(final java.util.function.Consumer<Object[]> recv) {
  trace().setReceiver(new ASTState.Trace.Receiver() {
    @Override
    public void accept(ASTState.Trace.Event event, ASTNode node, String attribute, Object params, Object value) {
      recv.accept(new Object[] { event, node, attribute, params, value });
    }
  });
}