silk.schema.report.

Show the problems a schema found, as source snippets, one line each, or JSON.

When to use#

Call SchemaReport.write with the silk.schema.issue.SchemaErrors from silk.schema.json.SchemaJson.decodeAll, or SchemaReport.writeOne with the one SchemaError from SchemaJson.decode, and the input they were read from. Pick ReportOptions.snippet for a terminal, ReportOptions.line for logs and editors' problem matchers, and ReportOptions.json for tools and for sending the problems back to a model.

Details#

A report cuts the found value out of the input by its span, at most 40 bytes of its first line, and counts lines and columns only while it writes: lines and columns start at 1, and columns count characters, as editors do. ReportOptions.redacted writes only the kind of each found value, such as got text, for input that may hold secrets. A snippet shows at most about 80 characters of a long line, around the problem.

The snippet form looks like this:

TEXT
 --> server.json:3:11 at port
  |
3 |   "port": 0,
  |           ^ expected an integer from 1 to 65535, got 0

The line form writes server.json:3:11: port: expected an integer from 1 to 65535, got 0, and the JSON form writes one object, {"problems": [...], "dropped": 0}, whose paths are JSON Pointers into the input.

Examples#

Write every problem of a config#

silk
import silk.collections.list { List }
import silk.core.effect { Effect }
import silk.core.result { Result }
import silk.io.writer { Writer, WriterError }
import silk.mem.allocator { Allocator, OutOfMemoryError }
import silk.schema.issue { SchemaErrors }
import silk.schema.json { SchemaJson }
import silk.schema.report { ReportOptions, SchemaReport }
import silk.schema.schema { Schema, Spec }

struct Server {
  pub port: u16,
  pub workers: u8,
}

impl Schema for Server {
  static fn spec() -> Spec<Server> {
    return Spec<Server>.of() |> Spec<Server>.between("port", 1, 65535)
  }
}

struct Capture {
  bytes: [u8; 512],
  length: usize,
}

impl Writer for Capture {
  effect fn writeAll(self: &mut Self, val: &[u8]) -> () ! WriterError ? &mut Writer {
    let mut at: usize = 0
    while at < val.length {
      if self.length < 512 { self.bytes[self.length] = val[at] }
      self.length = self.length + 1
      at = at + 1
    }
    return ()
  }
  effect fn flush(self: &mut Self) -> () ! WriterError ? &mut Writer { return () }
}

effect fn check() -> usize ! OutOfMemoryError | WriterError ? &mut Allocator {
  let input = b"{\"port\": 0, \"workers\": 300}"
  let mut capture = Capture {bytes: [0; 512], length: 0}
  match move run Effect.result(SchemaJson.decodeAll<Server>(input)) {
    Result<Server, SchemaErrors | OutOfMemoryError>.Failure {error} => match move error {
      SchemaErrors problems => {
        run SchemaReport.write(&problems, input, "server.json", ReportOptions.line()) |> Effect.provideMut<Writer>(&mut capture)
      }
      OutOfMemoryError {} => { fail OutOfMemoryError {} }
    }
    _ => {}
  }
  // server.json:1:10: port: expected an integer from 1 to 65535, got 0
  // server.json:1:24: workers: expected an integer from 0 to 255, got 300
  return capture.length
}

pub effect fn main() -> i32 ! OutOfMemoryError | WriterError {
  let mut allocator = Allocator.systemAllocatorProvider()
  let written = run check() |> Effect.provideMut<Allocator>(&mut allocator)
  return if written > 0 { 0 } else { 1 }
}

Import as SchemaReport with import silk.schema.report { SchemaReport }.

Public declarations: 4.

ReportStyle#

silk
pub enum ReportStyle

How a report lays out each problem.

Snippet#

silk
Snippet

The line of input with a caret under the problem, for a terminal.

Line#

silk
Line

One line per problem, source:line:column: path: message, for logs and problem matchers.

Json#

silk
Json

One JSON object that lists the problems, for tools and models.

ReportOptions#

silk
pub struct ReportOptions

How SchemaReport.write writes problems.

Field style#

silk
pub style: ReportStyle

The layout.

Field redact#

silk
pub redact: bool

Whether to write only the kind of each found value, never its text.

Implementation Copy for ReportOptions#

silk
impl Copy for ReportOptions

Implementation ReportOptions#

silk
impl ReportOptions

Associated function snippet#

silk
pub fn snippet() -> ReportOptions

Returns options for source snippets.

Associated function line#

silk
pub fn line() -> ReportOptions

Returns options for one line per problem.

Associated function json#

silk
pub fn json() -> ReportOptions

Returns options for one JSON object.

Method redacted#

silk
pub fn redacted(self: Self) -> ReportOptions

Returns the same options, but writing only the kind of each found value.

MAX_QUOTED#

silk
pub const MAX_QUOTED: usize

The most bytes of a found value a report quotes.

SchemaReport#

silk
pub struct SchemaReport

Writes schema problems for a person or a tool.

Implementation SchemaReport#

silk
impl SchemaReport

Associated function write#

silk
pub effect fn write(errors: &SchemaErrors, input: &[u8], source: string, options: ReportOptions) -> () ! WriterError ? &mut Writer

Writes every problem in errors, read from input, to the ambient Writer. source names the input, such as a file name, in each location.

Errors#

  • WriterError if the Writer fails.

Associated function writeOne#

silk
pub effect fn writeOne(error: &SchemaError, input: &[u8], source: string, options: ReportOptions) -> () ! WriterError ? &mut Writer

Writes one problem, as SchemaReport.write does.

Errors#

  • WriterError if the Writer fails.

Category: Data formats.

Profiles: aarch64-apple-darwin, aarch64-unknown-linux-gnu, aarch64-unknown-linux-gnu-no-libc, x86_64-unknown-linux-gnu, x86_64-unknown-linux-gnu-no-libc, wasm32-unknown-unknown, wasm32-wasip1, wasm32-wasip2, x86_64-pc-windows-msvc, wasm64-unknown-unknown.

View the source of this page