Class DataTouchDirective

java.lang.Object
org.ek9lang.compiler.directives.DataTouchDirective
All Implemented Interfaces:
Directive
public class DataTouchDirective extends Object implements Directive
To be used in EK9 source code to assert the DATA-TOUCH verdict for a tracked parameter of the callable on the next line — does this callable, or anything it calls, mutate the structure, and does a reference to it escape? (design docs/tooling/EK9_DATA_TOUCH_ANALYSIS_SPEC.md §8.5). It is the in-source complement to the Java verdict tests: the expected verdict lives beside the method rather than away from the code it describes. 
@DataTouch: PRE_IR_CHECKS: "input": "MUTATES, ESCAPES_VIA"
churnBeforeEscape()
  -> input as Address
Three colon parts — PHASE : "structure" : "verdict" — and, like @Probe, it is LINE-anchored (the directive sits on the line before the declaration and applies to it) rather than name-resolved, because a method lives inside an aggregate and a bare name does not resolve at module scope.

🔑 Pull, not push. Data-touch is never computed on a normal build, so unlike @Complexity or @Verified there is no squirrelled value to read — the directive's presence IS the demand. compiler-main only records this directive (parsed, inert); the analysis runs only when a compiler-services DataTouchDirectiveListener is registered in a data-touch test harness, which is where the verdict is computed and compared. So this directive is inert in every production compile.

The verdict is carried as a RAW STRING because the TouchStatus vocabulary lives in compiler-services and cannot be imported here; the listener owns parsing and validating it (≤1 mutation token, ≤1 escape token; UNTOUCHED/UNKNOWN standalone; order-independent).

  • Constructor Details

    • DataTouchDirective

      public DataTouchDirective(IToken token, CompilationPhase phase, String structure, String expectedVerdict, int lineNumber)
      A new data-touch directive: the tracked parameter and the expected per-axis verdict set, checked for the callable declared on lineNumber.

  • Method Details

    • type

      public DirectiveType type()
      Description copied from interface: Directive
      What s the type of the directive.
      Specified by:
      type in interface Directive

    • isForPhase

      public boolean isForPhase(CompilationPhase phase)
      Description copied from interface: Directive
      Is it for the particular compiler phase.
      Specified by:
      isForPhase in interface Directive

    • getStructure

      public String getStructure()
      The parameter (or "this") being tracked.

    • getExpectedVerdict

      public String getExpectedVerdict()
      The asserted verdict, verbatim as written — a comma-separated set of TouchStatus tokens the listener parses.

    • getDirectiveToken

      public IToken getDirectiveToken()
      Description copied from interface: Directive
      Provide a token from the source, by default if not possible supply synthetic.
      Specified by:
      getDirectiveToken in interface Directive

    • getAppliesToLineNumber

      public int getAppliesToLineNumber()
      Description copied from interface: Directive
      Which line number does this directive apply to.
      Specified by:
      getAppliesToLineNumber in interface Directive

    • toString

      public String toString()
      Overrides:
      toString in class Object