Package org.ek9lang.compiler.common


package org.ek9lang.compiler.common
Common parts of processing that can be reused across various phases.
  • Class
    Description
    The abstract base on most antlr listeners.
    Predicate to see if an aggregate mandated pure in its construction.
    Reviews all the modules and looks for all the 'Programs' that have been defined anywhere.
    Checks if the body of a method/operator is appropriate.
    Test if a symbol is a BARE-defaulted operator, i.e.
    THE canonical fingerprint of a project's declared dependencies (D10, P3; docs/implementation/EK9_P2_P3_PLAN.md §2.1): deps, devDeps and excludeDeps, each turned into its own sorted name=version block (so the result does not depend on HashMap iteration order), the three blocks kept in FIXED slots (deps, devDeps, excludeDeps) separated by "\n" so an entry moving from one dict to another changes the fingerprint even when the dict as a whole is otherwise empty.
    Decides whether a construct's modifier (as open / as abstract) may legally be toggled to a proposed state — the "declaration viability" of the modifier refactoring.
    The four modifier toggle modes.
    Outcome of asking whether a class's modifier (as open / as abstract) may be changed — the "declaration viability" layer used to gate the class-modifier toggle tooling and to decide whether the IDE should even offer the refactor.
    Checks if a symbol should be tracked as a closeable resource.
    THE close operator of an aggregate: the one operator close a call to close resolves to (its own, or inherited), or empty when it has none.
    Used for variable forms of simple code flow analysis.
    Designed to be used in a transient manner when interacting with variables.
    Check to see if any of the compilable sources have errors.
    As and when sources are processed during each phase of the compilation.
    For compiler, errors, warning and other information from the compiler.
    Register this event listener with the compiler to pick up on any warnings of errors during compilation.
    THE one statement of which error codes concern COMPILER DEVELOPMENT rather than writing a program (site-examples spec §6, Steve 2026-10-11, Q5): E50200 to E50390, the codes the development directives report - @Error, @Resolved, @Complexity, @IR, @BYTECODE, @Probe, @Squirrelled, @InputVariety, @Obligations and the rest.
    Just expends the standard reporter to use the EK9Comp message prefix.
    Checks for the containing construct type and whether it is marked as abstract or not.
    The exit code a test DECLARED with "EXIT:<n>", or null when it declared none (IsTestProgram has the encoding contract).
    THE test that an operator was written as default operator X (or added by the bare default operator): the DEFAULTED squirrel, so the compiler wrote its body.
    THE gate for a test construct (assert, assertThrows, assertDoesNotThrow, assertPanic, @Test) that may only appear in a dev source: reports TEST_CONSTRUCT_IN_NON_DEV_SOURCE with the construct's name.
    Loads DI analysis guidance messages from individual .txt resource files listed in a manifest.
    Defines all exit codes used by the EK9 compiler and generated code.
    THE marker line EK9 writes FIRST on stderr when EK9 ITSELF fails - the CLI, the compiler, or the generated ek9.Main entry point rejecting a program's arguments - e.g.
    The code a line names when it is EXACTLY an Ek9FailureMarker (surrounding whitespace aside), else empty.
    A cut down visitor that just deals with packages at a basic level.
    The one-line meaning of a semantic error code, from the compiler's own classification - the caption of an error example (ErrorDirectiveText).
    The classification an @Error directive names (ErrorDirectiveText).
    The error codes the source's @Error directives name, in source order, without repeats (ErrorDirectiveText).
    The phase names the source's @Error directives give, in source order, without repeats (ErrorDirectiveText).
    THE text-level reading of the @Error: PHASE: CLASSIFICATION directive lines in an example SOURCE - for the readers that show an error example to a person or a model, not for the compiler (which parses directives with the grammar and checks them with ErrorDirectiveListener).
    THE loader of the error catalogue's examples (errorExamples/<CODE>/, site-examples spec §6, decisions D2 and D11): for each error code a bad.ek9 that fails with exactly that code (its @Error directive is kept in the source, where the gate reads it) and one or more good*.ek9 that fix it.
    One source of the catalogue.
    One example of a code: a single file (bad.ek9, good_open.ek9) or a directory (bad/, good/) whose files compile together as one workspace.
    We need an error listener for the lexing parsing and also our own tree visiting.
    Fine detail of the error.
    The type of the error.
    The details of an error, position, etc.
    What is the semantic nature of the error.
    Where each directive says its error is, as "<line>:<CLASSIFICATION>" - the line after the directive, counting from 1 - in source order (ErrorDirectiveText).
    The exit code a test program must end with for the test to pass: the one it declared with "EXIT:<n>" (DeclaredTestExitCodeOf), else 0.
    Test if a symbol is externally implemented.
    Facade that combines ANTLR parsing with the ExternSourceVisitor to generate extern representations of EK9 source files.
    Visitor that walks an EK9 parse tree and emits an extern source representation.
    The code named by the FIRST line of a stderr capture (after the JVM's launcher lines) when that line is an Ek9FailureMarker, else empty.
    Maps compiler error codes to their corresponding path in forAI.json.
    Test if a (generic base function) symbol is forward-target dispatched: the closed set of extern abstract function types a built-in invokes through the erased base _call(Any...) path with the argument held RAW — MutexKey (via MutexLock.enter) and Comparator (via PriorityQueue.withComparator/Ek9Sort).
    THE split of an example source into its <?- ... -?> JSON front matter and its EK9 body - the one reader of that format.
    THE EK9 source after an example's FrontMatter, trimmed and without a trailing //EOF; the whole text (likewise trimmed) when there is no front matter.
    THE JSON of an example source's FrontMatter: the text between the markers, trimmed, or null when the text has no well-formed front matter.
    Predicate to check if an aggregate type has a close() operator defined.
    True when the text carries FrontMatter (its FrontMatterJson is there).
    THE shared test for "is this type orderable?" - does it have a REAL <=> operator, one it declares itself or inherits from a real (user) super, as opposed to only the degenerate Any._cmp that EVERY type inherits and which is not value ordering.
    THE shared test for "does this type have a REAL &lt;operator&gt;?" - one it declares itself or inherits from a real (user) super OR from a trait (its own, a super's, or a trait's trait), as opposed to only the degenerate Any.&lt;operator&gt; that EVERY type inherits (e.g.
    Used for double dispatch when visiting nodes.
    THE test that a symbol has no type because the expression it was declared from is already reported (E-7): its readers stay silent rather than adding a 'type not resolved' for every later use.
    THE test that an error code concerns compiler-development directives - the CompilerDevelopmentCodes range (E50200 to E50399).
    Predicate to check if a source file path represents a development source.
    True when the source carries at least one @Error directive - an error example (ErrorDirectiveText).
    THE test for "is this type EXTERNALLY LINKED?" - what CallDetails.isExternTarget states (Steve, 2026-10-28: "extern should be externally linked in some way; defaulted/synthetic methods are not external").
    THE lines the JVM launcher writes on stderr before main runs - Picked up JAVA_TOOL_OPTIONS: ... (and _JAVA_OPTIONS, NOTE: Picked up JDK_JAVA_OPTIONS) whenever such a variable is set.
    THE ORDERING operator family test: <, <=, >, >= and <=> - each delegates (directly, or via DerivedComparisonGenerator) to <=>, so each needs the receiver AND every field type to be orderable.
    THE test of "is this assignment token TYPE a plain one" - :=, =, : or :=?: a simple object-pointer assignment, not a deep or mutating operator (+=, :~:, :^:, :=:).
    THE answer to "is this a @Test program?" (and, with its siblings, what execution group it is in) — use this, do not read the squirrelled key directly.
    Whether this symbol is a test program or a method declared inside one (IsTestProgram has the encoding contract).
    For when we just need to read ek9 files and pull out bits and bobs rather than actually compiling.
    Why the last JustParser.readSourceFile(File, Ek9SourceVisitor) returned false - so a caller says the right thing.
    Access the Symbol for the lhs of the preflow statement.
    Authoritative validator for EK9 locale identifiers used in defines text for "<locale>" blocks.
    THE names of the LocalScopes phase 1 creates, and the only place their text is spelt.
    Loads alternative error messages and DI guidance from a zip file.
    Single source of truth for which access modifier is legal on a method / operator / constructor within a given aggregate genus.
    Useful when attempting to traverse up stacks to find both the method and its parent aggregate.
    Just to enable viewing and printing of nodes.
    THE text of a construct's IR as a person reads it: the NodePrinter rendering, \n-terminated lines.
    THE checks every method and operator declaration gets - call this, never the rules one by one (front-end rationalisation F12/D5, Steve 2026-10-03).
    THE test of "is this assignment token a plain one" - :=, =, : or :=?: a simple object-pointer assignment, not a deep or mutating operator (+=, :~:, :^:, :=:).
    Holds some high level details about an operator.
    Enhanced mapping of EK9 operators to their metadata and method names.
    Maps EK9 operators to their syntactic position (prefix vs suffix/postfix).
    Checks for both abstract and override.
    An immutable snapshot of EK9 main package directives.
    Parses a bit of EK9 source as an instructionBlock — a contiguous run of block statements (the body of a method / function / loop / branch).
    The parse outcome: the block context (may be partial when there are errors) and the error listener so callers can gate on a clean parse.
    Just processes a bit of some EK9 source for a simple or generic type def, to return the context.
    A golden stores what varies from run to run as a {{Placeholder}}; a reader of plain text sees it as a variable (<n>ms, <date>).
    Checks in the context to see if a returning variableDeclaration or a body is defined.
    Constructs like methods and functions may or may not always return a value.
    Check trait specifics on constructors/methods/operators, Allowing missing body but marking as abstract.
    Single source of truth for "Did you mean?" / quick-fix suggestions across the EK9 compiler, IDE, and AI tooling.
    THE inline "Did you mean: X, Y, Z?" text of an error's suggestions, used by ErrorListener.ErrorDetails.toString() (CLI classic mode): the QuickFixSuggestionExtractor list, each as its display text, joined.
    THE question "has every path through the body given this returning variable a NEW value, so the value it was declared with can never be the one returned?" - asked of a returning variable that HAS an initialiser (<- rtn as Integer: Integer()).
    Designed to ensure consistent reporting as part of the command line commands and executions.
    THE measurement of a window of compilation - a phase or a stage of one - used by the verbose PHASE_METRICS and *_STAGE lines so every window is measured the same way.
    THE test that an operation's returning variable is initialised in its declaration (<- rtn as Integer: 0), which on its own is an implementation: such an operation may have no statements at all.
    Loads rich error messages from individual .txt resource files listed in a manifest.
    Provides rich error messages for AI-assisted development.
    The rich message for an error code followed by its [EXAMPLE] section: the error catalogue's compiled failing source and its compiled fixes (ErrorExamples.plainText(String) of ErrorExamples.CATALOGUE), as plain text.
    Designed to be extended by rules and checkers.
    This stack object is only designed to be used when first parsing.
    Just focussed on ensuring that scopes are correct push on to the scope stack.
    The narrow 'produce a semantic diagnostic' surface of ErrorListener.
    Provides source line content for error display formatting.
    Determines whether a CompilableSource corresponds to a given source file name.
    What a page shows of a SourceRegions body: the named region (the whole body when the region is null), with every marker line removed, each elided run replaced by ONE // ... <name> comment at the run's indentation, leading and trailing blank lines dropped, and the result dedented to its least-indented line.
    The "full source" view of a SourceRegions body: every source line with the marker lines removed, and for each region the (zero-based) line of that text it starts on.
    The SourceRegions marker on this line, or null when the line is source.
    The SourceRegions region names declared in a body, in source order.
    Every structural problem in the SourceRegions markers of a body - unbalanced or mismatched markers, a duplicate or malformed region name, an elide inside an elide.
    THE reader of the region and elide markers in a compiled example source (site-examples spec §3.4, decision D5) - every page fragment is cut from a whole, compiled source through here; never parse the markers anywhere else.
    A source with its markers removed, and the line each region starts on.
    The kind of a marker line.
    One marker line: whether it opens or closes, its kind, its name and its indentation.
    A single ranked suggestion that the compiler can offer the user as a possible replacement for an offending token.
    Where the suggestion came from.
    Checks for a type is resolved and is suitable genus and category.
    Models information used in code analysis for various variable states.
    Used as external helper to record symbols and scopes across the parser.
    Function that extracts signature-qualified-name from a symbol.
    Just gets the type from a symbol, or throws a compiler exception if missing.
    The colour, Unicode and emoji capabilities of the terminal this process writes to, detected once (and again by TerminalCapabilities.resetTestMode()) - see TerminalColors, THE formatting functions that read it.
    Terminal color and symbol support with automatic capability detection.
    The sequential execution group a test belongs to (IsTestProgram has the encoding contract).
    Check trait specifics on methods/operators.
    Pass a string of an ek9 typeDef in and use the EK9 parser to just handle the breaking up of a String of a TypeDef into a structure and names.
    Designed to be used in phase3 or after - FULL_RESOLUTION.
    Extracts the fully qualified type name from the symbol.
    THE reading of "was this variable, property or returning variable declared with NO value" - the UNINITIALISED_AT_DECLARATION squirrel that phase 1 sets on name as Type? (and phase 3 on a synthesised returning variable).
    THE test that a symbol is a PROPERTY declared with no value, so every access to it is questionable until a constructor (or a guard) has set it: a VariableSymbol that is a property field and UninitialisedAtDeclaration.
    Used to check if variables within code blocks when declared without being initialised, actually get initialised before they are used.
    Checks if a variable should be processed as a possible uninitialised variable.
    Checks to see if a variable has a specific generic type.
    Checks to see if a property on an aggregate is safe to access.
    Decides whether a member's visibility may legally be changed to a proposed access modifier - the "declaration viability" of a change_visibility refactoring.
    Outcome of asking whether a member's visibility (access modifier) may be changed to a proposed value - the "declaration viability" layer used to gate the change_visibility tooling and to decide whether the IDE should even offer the refactor.
    Groups all the data needed to format a visual error display.
    Formats compiler errors in a visual style similar to Rust/Elm compilers.
    The source with every @Error directive line removed - what a reader would type (ErrorDirectiveText).
    A stderr capture without the JVM's leading launcher lines and with a leading Ek9FailureMarker line removed (the rest unchanged); null is the empty string.
    A child JVM's stderr from its first line that is not a JVM launcher line (IsJvmLauncherLine, which says why); null stays null.