Class ErrorExamples

java.lang.Object
org.ek9lang.compiler.common.ErrorExamples
public final class ErrorExamples extends Object
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. Every reader of the catalogue goes through here - ek9 -h <CODE> and -E3 (the plain-text exampleSection(String), through RichErrorMessages.getRichMessageWithExample(String)), the site's publisher (EK9_ERROR_EXAMPLES, error: references) and the gates (ErrorExamplesTest under -Psite, the structure checks in the default suite, the codes-without-bad.ek9 ratchet). One home, three renderings: never copy an example into a page or a message.

The catalogue sits in compiler-main beside richErrorMessages/, which it completes: the rich message is the ONLY prose for a code (D12), this is its only code. It is read from the CLASSPATH through error-examples-manifest.txt, one <CODE>/<file>.ek9 per line, so the shipped jar, the build-time publisher and the tests see exactly the same files. Within a code the manifest's order is the order of the fixes.

A source is the Q&A format: an optional <?- ... -?> front matter split by THE shared FrontMatter; a good source's carries "fixes": "<CODE>" and an optional "title". Modules are error.e07235.bad, error.e07235.good and error.e07235.good.<suffix> for good_<suffix>.ek9.

Directory examples (site-examples spec §3.1, lane site-multifile). An error that exists only ACROSS files (E11066: constants in three files of one module) or needs a dev/ @Test program (E81011, E81012) is a DIRECTORY in place of the file: bad/ (and good/, good_<suffix>/) holding several files, and perhaps a dev/ subdirectory, compiled together as ONE workspace - the Q&A's QA####_dev_ companions and the site's project directories are the precedent, and the dev rule is the ordinary IsDevSource. Each file is listed in the manifest (E11066/bad/constants1.ek9). An ErrorExamples.ExampleUnit is one example, a file or a directory: the failing example of a directory is the ONE file carrying the @Error directive, checked exactly WITH its companions (which carry none, and must report nothing). Module names are unique per example: the files of one directory may share a module (that is what E11066 is about), and every module of a directory starts error.<code>.<unit>.

The parseButFailCompile corpus (decided in lane L0e). The catalogue never REFERENCES a compiler-main test fixture - the fixtures are not in the shipped jar, so ek9 -h could not show one - and never COPIES one. A fixture whose every @Error directive names one code is MOVED here (with git mv, history kept) to be that code's bad.ek9, and its exact-directive check moves with it to ErrorExamplesTest; a fixture that mixes codes stays where it is, because it tests how rules interact, and the catalogue's own minimal source for those codes is a different source, not a duplicate. The codes-without-bad.ek9 ratchet names each code's single-code fixtures as move candidates. A fixture DIRECTORY that teaches one code moves the same way, to be the code's bad/.

  • Field Details

    • ROOT

      public static final String ROOT
      The classpath root of the catalogue.
      See Also:

    • MANIFEST_NAME

      public static final String MANIFEST_NAME
      The manifest's file name: one <CODE>/<file>.ek9 per line.
      See Also:

    • BAD

      public static final String BAD
      The file name of a code's failing example.
      See Also:

    • BAD_UNIT

      public static final String BAD_UNIT
      The name of a code's failing example: the file bad.ek9, or the directory bad/.
      See Also:

    • GOOD_PREFIX

      public static final String GOOD_PREFIX
      The name prefix of a code's fixes (good.ek9, good_<suffix>.ek9, good/).
      See Also:

    • CLI_RUN

      public static final String CLI_RUN
      THE marker of a test-runner example (spec §6, Q6): the codes ek9 -t reports - not the compiler, so no @Error directive can express them - are demonstrated by running the binary. The failing example's main source (and the fix's) carries this in its front matter, "cliRun": "-t greeting.ek9": the arguments of the run, in the example's own directory. The failing example reports exactly its code (and no other E8xxxx), the fix reports none, and the scrubbed output of each run is the golden <unit>.out beside the example.
      See Also:

  • Constructor Details

    • ErrorExamples

      public ErrorExamples()
      The error catalogue.

    • ErrorExamples

      public ErrorExamples(String root)
      A catalogue in the same layout under another classpath root - the gates' own harness fixtures use it.
      Parameters:
      root - a classpath directory ending in /, holding error-examples-manifest.txt

  • Method Details

    • catalogue

      public static ErrorExamples catalogue()
      The shared instance over the shipped catalogue.

    • root

      public String root()
      The classpath root this catalogue is read from.

    • manifest

      public List<String> manifest()
      The manifest's paths, in order (blank lines and # comments skipped).

    • load

      public ErrorExamples.ErrorExample load(String path)
      The source at a catalogue-relative path; only a path the manifest lists is part of the catalogue.
      Throws:
      IllegalArgumentException - when the manifest does not list it, or it is not <CODE>/<path>.ek9

    • loadAll

      public List<ErrorExamples.ErrorExample> loadAll()
      Every source in the manifest, in its order (the companion files and goldens of a runner example are not).

    • loadEveryFile

      public List<ErrorExamples.ErrorExample> loadEveryFile()
      Every file in the manifest - sources, runner companions and goldens - in its order.

    • codes

      public Set<String> codes()
      The codes that have at least one example, in manifest order.

    • forCode

      public List<ErrorExamples.ErrorExample> forCode(String code)
      A code's examples, file by file: its failing example first, then its fixes, as units(String) orders them; empty when it has none.

    • units

      public List<ErrorExamples.ExampleUnit> units(String code)
      A code's examples, one per file or directory: the failing example first, then the fixes in manifest order. Within a directory the failing file comes first, then the others in manifest order, those under dev/ last.

    • badOf

      public ErrorExamples.ExampleUnit badOf(String code)
      A code's failing example.
      Throws:
      IllegalArgumentException - when the catalogue holds none for it

    • exampleSection

      public static String exampleSection(String code)
      The [EXAMPLE] section of ek9 -h <CODE> and -E3: the compiled failing source and each compiled fix, as plain text (site-examples spec §6, rendering 3 - the one that reaches a model with no web access). Empty when the catalogue holds nothing for the code.

    • plainText

      public String plainText(String code)
      This catalogue's [EXAMPLE] section for a code; empty when it holds nothing for it. A directory example is introduced once and each of its files is named before it is shown, the failing file first.

    • plainPlaceholders

      public static String plainPlaceholders(String capture)
      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>).

    • expandExampleTokens

      public static String expandExampleTokens(String text)
      THE expansion of the example tokens in a rich message, over the shipped catalogue: see expandTokens(String). The rich-message and message-pack loaders call it, so no hand-written code needs to live in a message.

    • expandTokens

      public String expandTokens(String text)
      Replace every line {{EK9_EXAMPLE error:<CODE>/<file>.ek9[#region]}} with that compiled source of this catalogue - or the named region of it - as a reader is shown it (ErrorExamples.ErrorExample.shown(String)), each line indented as the token is. A token is a whole line, never part of prose.
      Throws:
      IllegalStateException - when a token names a source or region the catalogue does not hold, or is not a whole line - a token must never reach a reader

    • resource

      public Optional<String> resource(String classpathPath)
      A classpath resource's text, if it exists.