kex docs Standard Library

TaggedValidation

module TaggedValidation

Diagnostics returned by compile-time validators for tagged literals.

A tagged literal ( re\d+ , sqlSELECT ... ) can be checked while your program is compiled rather than when it runs. The compiler finds the checker by name: a tag foo is validated by a function named validateFoo taking the literal's text and returning a list of Issue values. An empty list means the literal is fine.

let validateHex(source: String) -> [TaggedValidation.Issue] do
  match source.chars.findIndex { |c| !c.digit? && !c.in?('a'..'f') } do
    Just(offset) => [TaggedValidation.fatalAt(offset, "not a hex digit")]
    None         => []
  end
end

A Fatal issue stops the build with the message, pointing the caret at the offset; a Warn reports without stopping.

Byte offsets are zero-based and relative to the cooked literal body.

fatal

fatal(message: String) -> Issue

A fatal issue about the literal as a whole, with no particular position.

Parameters
message
what is wrong

Returns the diagnostic

Examples
TaggedValidation.fatal("an empty pattern matches nothing")

fatalAt

fatalAt(offset: Integer, message: String) -> Issue

A fatal issue at one offset in the literal.

The offset is where the caret points in the compiler's error, so use the position the underlying checker reported.

Parameters
offset
the zero-based byte offset in the literal body
message
what is wrong

Returns the diagnostic

Examples
TaggedValidation.fatalAt(3, "missing closing parenthesis")

Reporting what a checker found

match Kex.Intrinsic.Regex.validate(source) do
  Just((offset, message)) => [TaggedValidation.fatalAt(offset, message)]
  None                    => []
end

fatalBetween

fatalBetween : Integer -> Integer -> String -> Issue

A fatal issue spanning a range of the literal.

Parameters
start
the first byte offset of the span
finish
the offset just past its end
message
what is wrong

Returns the diagnostic

Examples
TaggedValidation.fatalBetween(0, 4, "this group can never match")

warn

warn(message: String) -> Issue

A warning about the literal as a whole. Reported, but the build continues.

Parameters
message
what is questionable

Returns the diagnostic

Examples
TaggedValidation.warn("this pattern is very slow on long inputs")

warnAt

warnAt(offset: Integer, message: String) -> Issue

A warning at one offset in the literal.

Parameters
offset
the zero-based byte offset in the literal body
message
what is questionable

Returns the diagnostic

Examples
TaggedValidation.warnAt(7, "redundant escape")

warnBetween

warnBetween : Integer -> Integer -> String -> Issue

A warning spanning a range of the literal.

Parameters
start
the first byte offset of the span
finish
the offset just past its end
message
what is questionable

Returns the diagnostic

Examples
TaggedValidation.warnBetween(2, 6, "this alternation is always taken")

type ByteSpan

Where in the literal an issue applies: a single offset, or a range.

Both are byte offsets into the literal body, counted from zero.

Variants

  • At(Integer)
  • Between(Integer, Integer)

type Issue

One diagnostic about a tagged literal.

Fatal stops the build; Warn reports and lets it continue. The span is optional: an issue about the literal as a whole carries None.

Variants

  • Fatal(ByteSpan?, String)
  • Warn(ByteSpan?, String)