mooncakes.io

marianoguerra/shrubbery/error does not have a README file

ShrubberyError

pub(all) suberror ShrubberyError {
  ShrubberyError(Diagnostic)
}

A shrubbery source was rejected.

One error type for the whole library. Diagnostic carries the structure, so nothing is lost by there being a single constructor.

ShrubberyError::diagnostic

source

fn ShrubberyError::diagnostic(self : ShrubberyError) -> Diagnostic

The diagnostic inside an error.

Diagnostic

source

pub(all) struct Diagnostic {
  kind : ErrorKind
  span : @marianoguerra/shrubbery/basic.Span
Span
  severity : @marianoguerra/error-report.Severity
Severity
  related : Array[(@marianoguerra/shrubbery/basic.Span
Span, String)]
}

A rejected source, with the span it was rejected at.

The data a consumer reads. related carries the second place worth looking — the opener that was never closed, the | an alternative was expected to line up with — which the reference does not record and which is most of what makes an indentation complaint answerable.

Diagnostic::new

source

fn Diagnostic::new(kind : ErrorKind, span : @marianoguerra/shrubbery/basic.Span
Span, severity? : @marianoguerra/error-report.Severity
Severity, related? : Array[(@marianoguerra/shrubbery/basic.Span
Span, String)]) -> Diagnostic

Diagnostic::raise_

source

fn[T] Diagnostic::raise_(self : Diagnostic) -> T raise ShrubberyError

Raise this diagnostic.

Diagnostic::to_report

source

fn Diagnostic::to_report(self : Diagnostic, source : @marianoguerra/error-report.SourceId
SourceId) -> @marianoguerra/error-report.Report
Report

Turn a diagnostic into a renderable report.

This is the only function in the library that mentions error-report. Keeping it to one is what makes that library's eventual spin-out a rename rather than an untangling, and tools/boundary-check.sh gates the other half of the arrangement. If a second call site appears, the question to ask is whether the thing it needs belongs in Diagnostic instead.

ErrorKind

source

pub(all) enum ErrorKind {
  ReadError
  ExpectedSExp(keyword~ : Bool)
  ExpectedSExpClose(keyword~ : Bool)
  ExpectedSExpOnlyWhitespace(keyword~ : Bool)
  SExpMustNotBePair
  IncomparableIndentation
  WrongIndentation(missing_colon_hint~ : Bool)
  AltBeforeGroupColumn
  DidNotFindMatching(expected~ : String)
  UnexpectedCloser(found~ : String)
  ExpectedCloser(expected~ : String, found~ : String)
  ExpectedQuoteAfterGuillemet
  ExpectedParenAfterGuillemet
  ExpectedGuillemetClose
  MisplacedComma(paren_immed~ : Bool)
  MissingCommaBeforeGroup
  MisplacedSemicolon
  MultiGroupSpliceNotAllowed
  EmptyBlock(after~ : String, could_empty_if_start~ : Bool)
  NoTermsAfterGuillemet
  UnnecessaryColonBeforeBar
  MisplacedBar
  MisplacedGuillemet
  NotOnSameLine(preceding~ : String)
  MisplacedGroupComment
  NoGroupForTermComment
  ContinuationFollowedByToken
  MissingTermAfterAt
  WhitespaceAfterAt
  InvalidAfterAt
  AtArgCannotStartBracket
  MissingCloserForAtContent
  AtCommentOutsideBody
  EmptyGroupAfterAt
  BlockAfterMidGroupAt
  SecondGroupAfterAt
} derive(Eq)

Every way a shrubbery source can be rejected.

A closed enum with the parameters spelled out, rather than a string: a consumer that wants to react to a particular failure — an editor offering a fix, a test asserting on a case — matches on the constructor and never parses prose. reference_text reproduces the Racket wording verbatim, which is what the error-parity oracle compares, and Diagnostic::to_report is free to say something better without breaking it.

ErrorKind::code

source

fn ErrorKind::code(self : ErrorKind) -> String

A stable identifier for this failure.

Stable is the operative word: it is what a test asserts on and what a consumer suppresses by, so it has to survive rewording the message — which is exactly why it is not derived from one.

ErrorKind::reference_text

source

fn ErrorKind::reference_text(self : ErrorKind) -> String

What the reference says, byte for byte.

This is the measuring instrument, not the message: the error-parity oracle compares it against Racket's exn-message, so it must not be improved. If a wording here reads oddly — a another, below, is upstream's typo — that is the point.