🥮 mooncakes.io

    err_marker

    This is a visualizing tool that locates the source of errors within sequences and outputs formatted results, designed to assist users and developers in quickly identifying input that triggers errors.

    error
    mark
    format
    Download zip
    Author
    Version
    0.2.0
    License
    Apache-2.0
    Repository
    Last updated
    11 minutes ago
    Downloads
    67

    #KCN-judu/err_marker

    #📝 Introduction 介绍

    This is a visualizing tool that locates the source of errors within sequences and outputs formatted results, designed to assist users and developers in quickly identifying input that triggers errors.

    这是一个用于在序列中定位错误来源的可视化工具，并输出格式化结果，旨在帮助用户和开发者快速识别引发错误的输入内容。

    #📖 Manual 手册

    The manual (API, tutorial and design, in English, 简体中文 and 日本語) is in doc/manual; translations live in doc/locale. The roadmap to 0.2.0 is tracked in #5.

    手册（API、教程、设计；英文、简体中文、日本語）位于 doc/manual，译文在 doc/locale。0.2.0 的路线图见 #5。

    #🧪 Usage 用法

    moon add KCN-judu/err_marker@0.2.0

    let report = @err_marker.Report::new(Error, "unknown mode 'sovle'")
      .with_code("E01")
      .with_mark(
        @err_marker.Mark::primary(
          @err_marker.Span::new(3, 4),
          message="did you mean 'solve'?",
        ),
      )
    let args = @err_marker.Sequence::from_args(["sudoku", "export", "a.txt", "sovle", "out.txt"])
    println(report.render(args))

    sudoku export a.txt sovle out.txt
                    ^^^^^ did you mean 'solve'?
error[E01]: unknown mode 'sovle'

    • Positions are element indices for arguments and arrays, and character indices for strings. Columns follow Unicode 18.0.0, so CJK text and emoji line up. 位置对参数和数组是元素下标，对字符串是字符下标；列宽遵循 Unicode 18.0.0，中日韩文字和 emoji 都能对齐。
    • Several marks (^ primary, - secondary), messages, notes, codes, severities and optional ANSI colour. 支持多处标记、说明、附注、错误码、严重级别和可选的 ANSI 颜色。
    • KCN-judu/err_marker/cursor: terminal column arithmetic. 终端列宽计算。
    • KCN-judu/err_marker/error_report: conversion to marianoguerra/error-report. 转换为 error-report 的报告。
    • ErrorData::mark (0.1) is deprecated; see "Migrating from 0.1" in the tutorial. ErrorData::mark（0.1）已弃用，迁移方法见教程中的 "Migrating from 0.1"。

    #📄 License 许可证

    Apache-2.0.

    ErrorData

    source
    pub struct ErrorData {
      err_type : String?
      err_msg : String
      err_pos : Int
      err_offset : Int
    }

    ErrorData::make

    source
    fn ErrorData::make(err_type? : String?, err_msg : String, err_pos? : Int, err_offset? : Int) -> ErrorData

    ErrorData::mark

    source
    #deprecated("Use `Report::render` instead (see the section Migrating from 0.1 in the manual)")
    fn[T : Show] ErrorData::mark(self : ErrorData, seq : Sequence[T], marker? : Char, gen_msg? : (String?, String) -> String) -> String

    Renders the sequence, a marker line under the span and the message, in the compact layout of Report::render.

    Kept for one release (0.2.x) for compatibility; use Report::render. The 0.1 units are kept: the span is err_pos to err_pos + err_offset, both included; for a string sequence the positions are UTF-16 offsets, and every character the span touches is marked; a negative err_pos means no position; a negative err_offset counts as 0. The last line is gen_msg(err_type, err_msg), and marker is the marker character.

    Mark

    source
    pub struct Mark {
      span : Span
      style : Style
      message : String?
      priority : Int
    } derive(Eq, 
    Debug    )

    A place to mark: a span, a style, an optional message shown next to or under the marker, and a priority that decides overlaps (higher wins).

    Mark::equal

    source
    fn Mark::equal(Mark, Mark) -> Bool

    Mark::primary

    source
    fn Mark::primary(span : Span, message? : String) -> Mark

    A primary mark (^) on span, with an optional message.

    Mark::secondary

    source
    fn Mark::secondary(span : Span, message? : String) -> Mark

    A secondary mark (-) on span, with an optional message.

    Mark::with_priority

    source
    fn Mark::with_priority(self : Mark, priority : Int) -> Mark

    The same mark with another priority.

    Report

    source
    pub struct Report {
      severity : Severity
      code : String?
      message : String
      marks : Array[Mark]
      notes : Array[String]
    } derive(Eq, 
    Debug    )

    An error report: a severity, an optional code, a message, marks on the sequence and notes printed after the header.

    Report::equal

    source
    fn Report::equal(Report, Report) -> Bool

    Report::new

    source
    fn Report::new(severity : Severity, message : String) -> Report

    A report with no code, marks or notes.

    Report::render

    source
    fn[T : Show] Report::render(self : Report, seq : Sequence[T], model? : 
    Model    , color? : Bool) -> String

    Renders the report on seq in the compact layout:

    1. the line of text that holds the primary mark (the whole text if there are no marks), with tabs expanded by model;
    2. a marker row: ^ under primary marks and - under secondary marks; where marks overlap, the winner is decided by priority, then the later start, then the earlier end, then primary over secondary, then the message (so the result does not depend on the order of the marks); the message of the mark that ends rightmost follows the markers on the same row;
    3. the other messages, each under the start of its mark, on as few rows as possible (greedy by left end point);
    4. the header severity[code]: message, with at line:column (1-based) of the primary mark when the text has several lines;
    5. one note: ... line per note.

    Marks whose start lies on another line than the primary mark are not drawn. Positions are element indices for array sequences and Unicode scalar indices for string sequences; spans are clamped to the sequence and snapped outward to grapheme clusters. Widths follow Unicode 18.0.0 through model. With color, ANSI SGR colours are used (ECMA-48).

    Report::with_code

    source
    fn Report::with_code(self : Report, code : String) -> Report

    The same report with a code, shown as error[CODE].

    Report::with_mark

    source
    fn Report::with_mark(self : Report, mark : Mark) -> Report

    The same report with one more mark.

    Report::with_note

    source
    fn Report::with_note(self : Report, note : String) -> Report

    The same report with one more note.

    Sequence

    source
    type Sequence[T]

    Generic sequence that can hold either an array of elements or a string of characters.

    Constructors:

    • Arr(Array[T], String) : Array-based sequence with a join separator for string representation.
    • Str(String) : String-based sequence of characters.

    Sequence::from_args

    source
    fn Sequence::from_args(args : Array[String]) -> Sequence[String]

    A command-line argument vector as a sequence: elements joined by a space, quoted when needed so the line can be split back into arguments.

    Sequence::from_array

    source
    fn[T] Sequence::from_array(arr : Array[T], join? : String) -> Sequence[T]

    Sequence::from_string

    source
    fn Sequence::from_string(str : String) -> Sequence[Char]

    Sequence::locate

    source
    fn[T : Show] Sequence::locate(self : Sequence[T], span : Span) -> (Int, Int)

    Where span lands in rendered(), as Unicode scalar indices (start, end): element spans become the hull of their elements, then the span is clamped to the text and snapped outward to grapheme clusters, as Report::render does.

    Sequence::rendered

    source
    fn[T : Show] Sequence::rendered(self : Sequence[T]) -> String

    The text that Report::render draws for this sequence: a string as it is, or the elements of an array (quoted when needed) joined by the separator.

    Severity

    source
    pub(all) enum Severity {
      Help
      Note
      Warning
      Error
    } derive(Compare, Eq, 
    Debug    )

    How serious a report is. Ordered Help < Note < Warning < Error.

    Severity::compare

    source
    fn Severity::compare(Severity, Severity) -> Int

    Severity::equal

    source
    fn Severity::equal(Severity, Severity) -> Bool

    Severity::name

    source
    fn Severity::name(self : Severity) -> String

    The lower-case name used in rendered headers: "error", "warning", "note" or "help".

    Span

    source
    pub struct Span {
      start : Int
      end : Int
    } derive(Eq, 
    Debug    )

    A half-open interval [start, end) of positions in a sequence: element indices for an array sequence, Unicode scalar indices for a string sequence. Valid by construction: 0 <= start <= end.

    Span::equal

    source
    fn Span::equal(Span, Span) -> Bool

    Span::new

    source
    fn Span::new(start : Int, end : Int) -> Span

    The span [start, end). A negative end point counts as 0, and an end before start counts as start.

    Span::point

    source
    fn Span::point(at : Int) -> Span

    The insertion point [at, at), drawn as one marker: "something is missing here".

    Style

    source
    pub(all) enum Style {
      Primary
      Secondary
    } derive(Eq, 
    Debug    )

    Whether a mark is the main place of the report (drawn with ^) or a related place (drawn with -).

    Style::equal

    source
    fn Style::equal(Style, Style) -> Bool

    utf16_to_scalar

    source
    fn utf16_to_scalar(text : String, offset : Int) -> Int

    The Unicode scalar index of UTF-16 offset offset in text: the number of scalars that start before it. An offset inside a surrogate pair counts that pair as not yet passed. Offsets are clamped to [0, text.length()].

    Source Files