vxml/blame

Source provenance for VXML trees.

Blame values attach origin information to VXML nodes, attributes, and lines. Source blame can be movable or anchored, which lets parsers and transformation pipelines preserve useful locations while slicing or moving text.

Types

Blame

</>

Provenance for a VXML node, attribute, or line.

pub type Blame {
  Src(
    comments: List(String),
    path: String,
    line_no: Int,
    char_no: Int,
    cursor: SourceCursor,
  )
  Des(comments: List(String), name: String, line_no: Int)
  Ext(comments: List(String), name: String)
  NoBlame(comments: List(String))
}

Constructors

Src(
  comments: List(String),
  path: String,
  line_no: Int,
  char_no: Int,
  cursor: SourceCursor,
)

A position in source input, optionally movable as text is transformed.

Des(comments: List(String), name: String, line_no: Int)

A value introduced by maintained transformation code.

```
Ext(comments: List(String), name: String)
```
A value attributed to named external or manually maintained code.
```
NoBlame(comments: List(String))
```
A value without identifiable provenance.

BlameTableMarginColumnsMinMax

</>

Minimum and maximum widths for one optional blame-table margin.

pub type BlameTableMarginColumnsMinMax {
  BlameTableMarginColumnsMinMax(min: Int, max: Int)
}

Constructors

```
BlameTableMarginColumnsMinMax(min: Int, max: Int)
```
Constrains a table margin column. A maximum of zero suppresses the column entirely.

SourceCursor

</>

Whether a source position can move when text is sliced or shifted.

pub type SourceCursor {
  Movable
  Anchored
}

Constructors

```
Movable
```
May be advanced when text before the blamed position is removed or split.
```
Anchored
```
Is left unchanged when code attempts to advance the source position.

Values

advance

</>

pub fn advance(blame: Blame, by: Int) -> Blame

Advances movable source blame by a character offset.

append_comment

</>

pub fn append_comment(blame: Blame, comment: String) -> Blame

Adds a comment after existing blame comments.

blame_digest

</>

pub fn blame_digest(blame: Blame) -> String

Renders a short human-readable blame label.

blamed_strings_annotated_table

</>

pub fn blamed_strings_annotated_table(
  lines: List(#(Blame, String)),
  banner: String,
  blame_digest_margin: BlameTableMarginColumnsMinMax,
  comments_margin: BlameTableMarginColumnsMinMax,
) -> List(String)

Renders blamed strings as lines of a provenance-annotated table.

A margin whose maximum is zero is omitted. banner labels the content column.

clear_comments

</>

pub fn clear_comments(blame: Blame) -> Blame

Removes comments while preserving the main blame identity.

comments_digest

</>

pub fn comments_digest(blame: Blame) -> String

Renders blame comments as a compact bracketed list.

no_blame

</>

pub const no_blame: Blame

A blame value with no provenance or comments.

path_contains

</>

pub fn path_contains(blame: Blame, s: String) -> Bool

Returns whether source blame has a path containing the given substring.

prepend_comment

</>

pub fn prepend_comment(blame: Blame, comment: String) -> Blame

Adds a comment before existing blame comments.

set_anchored

</>

pub fn set_anchored(blame: Blame) -> Blame

Marks source blame as anchored.