Class LocationBasedInternalName

java.lang.Object
org.ek9lang.compiler.support.LocationBasedInternalName
public final class LocationBasedInternalName extends Object
Generates deterministic internal names using SHA-256 hashing.

Two variants are provided:

  • generate(String, String, IToken, String...) — includes relative source file name, line and position in the hash. Use when the declaration point is stable (e.g. aspect proxy register statements that are in user code, not shifted by compiler directives).
  • generate(String, String...) — uses only semantic context strings. Use when line numbers may shift (e.g. dynamic functions where @IR directives inserted above shift the declaration line).

Both produce stable names across compilations (unlike UUID-based names). Callers must pass a relative source name (not an absolute path) to ensure consistent hashes across different build environments.

  • Method Summary

    Modifier and Type
    Method
    Description
    static String
    generate(String prefix, String... context)
    Generate a deterministic internal name from semantic context only.
    static String
    generate(String prefix, String relativeSourceName, IToken sourceToken, String... additionalContext)
    Generate a deterministic internal name from a relative source file and token location.
    static int
    ordinalWithinSource(org.antlr.v4.runtime.ParserRuleContext ctx, Class<? extends org.antlr.v4.runtime.ParserRuleContext> kind)
    THE position-independent identity for a dynamic construct: its index among the constructs of the same KIND in the same source file, in document order.

    Methods inherited from class Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • ordinalWithinSource

      public static int ordinalWithinSource(org.antlr.v4.runtime.ParserRuleContext ctx, Class<? extends org.antlr.v4.runtime.ParserRuleContext> kind)
      THE position-independent identity for a dynamic construct: its index among the constructs of the same KIND in the same source file, in document order.

      Hash inputs are rename triggers - every extra input is another way for a name to change while the construct itself did not. So the pair (relativeFile, ordinal) is deliberately the WHOLE identity: it is the smallest thing that is both unique and reproducible.

      • Unique - one source file is parsed sequentially, so ordinals are distinct within it; the file name separates files; a module is a set of files, so no intra-module collision. Note this is why the ENCLOSING scope is NOT an input: method FQNs are not unique under OVERLOADING, so (enclosingFqn, ordinal) would collide for a dynamic construct declared at the same index in two overloads of one method.
      • Reproducible - a pure function of the parse tree, so it does not depend on the order sources are compiled in (they are processed in parallel), nor on any mutable counter. Being idempotent matters: a counter would hand out a DIFFERENT ordinal if a symbol were ever created twice for one context, whereas re-deriving from the tree cannot.
      • Position-independent - no line or column, so inserting, resizing or deleting anything above the declaration cannot rename it. That is the whole point: an @IR directive for a dynamic construct lives in the SAME file ABOVE it, so a line-based name is self-referential - regenerating the directive moves the declaration, which renames the symbol the directive names, which can never settle.
      Parameters:
      ctx - the dynamic construct's parse context
      kind - the context class to count - dynamic functions and dynamic classes are counted separately, so adding one cannot renumber the other
      Returns:
      the 0-based index of ctx among same-kind contexts in its source

    • generate

      public static String generate(String prefix, String relativeSourceName, IToken sourceToken, String... additionalContext)
      Generate a deterministic internal name from a relative source file and token location. Includes the relative source file name, line number, and character position in the hash.
      Parameters:
      prefix - The name prefix (e.g. "_AspectProxy_")
      relativeSourceName - The relative source file path (not absolute, for environment stability)
      sourceToken - The source token providing line and position
      additionalContext - Optional additional strings to include in the hash
      Returns:
      A deterministic name like _AspectProxy_A1B2C3...

    • generate

      public static String generate(String prefix, String... context)
      Generate a deterministic internal name from semantic context only. Does NOT include line numbers, so names remain stable when source lines shift (e.g. when @IR directives are added above the declaration).
      Parameters:
      prefix - The name prefix (e.g. "_Function_")
      context - One or more context strings that uniquely identify the construct (e.g. source file name, enclosing function FQN, super function name)
      Returns:
      A deterministic name like _Function_A1B2C3...