diagnostic

Typed diagnostics produced while resolving YAML.

Diagnostics describe semantic YAML issues such as duplicate mapping keys, unknown aliases, invalid directives, and invalid tags. Parse a document, resolve it with yum/yaml.resolve, then inspect the diagnostics kept on the resolved document.

import gleam/list
import yum/yaml
import yum/yaml/diagnostic

pub fn example() {
  let assert Ok(document) = yaml.parse("
name: one
name: two
")
  let assert Ok(document) = yaml.resolve(document)

  let messages =
    document
    |> yaml.diagnostics()
    |> list.map(diagnostic.message)

  assert messages == ["Duplicate mapping key `name`"]
}

Types

Diagnostic

</>

A typed semantic issue found while resolving YAML.

pub type Diagnostic {
  DuplicateMappingKey(
    key: String,
    duplicate: node.Span,
    original: node.Span,
  )
  DuplicateAnchor(
    anchor: String,
    duplicate: node.Span,
    original: node.Span,
  )
  UnknownAlias(alias: String, span: node.Span)
  InvalidTagDirective(span: node.Span)
  InvalidYamlDirective(span: node.Span)
  UnsupportedYamlVersion(version: String, span: node.Span)
  DuplicateYamlDirective(
    duplicate: node.Span,
    original: node.Span,
  )
  UnknownTagHandle(handle: String, span: node.Span)
  InvalidTag(tag: String, span: node.Span)
  InvalidMergeTarget(found: node.KindName, span: node.Span)
}

Constructors

```
DuplicateMappingKey(
  key: String,
  duplicate: node.Span,
  original: node.Span,
)
```
A mapping contains the same scalar key more than once.

The duplicate span points at the repeated key. The original span points at the first matching key.
```
DuplicateAnchor(
  anchor: String,
  duplicate: node.Span,
  original: node.Span,
)
```
A document contains the same anchor name more than once.

The duplicate span points at the repeated anchor. The original span points at the first matching anchor.
```
UnknownAlias(alias: String, span: node.Span)
```
An alias references an anchor that has not been seen earlier in the document.
```
InvalidTagDirective(span: node.Span)
```
A TAG directive is malformed.
```
InvalidYamlDirective(span: node.Span)
```
A YAML directive is malformed.
```
UnsupportedYamlVersion(version: String, span: node.Span)
```
A YAML directive declares a version this package does not support.

DuplicateYamlDirective(duplicate: node.Span, original: node.Span)

A document contains more than one YAML directive.

```
UnknownTagHandle(handle: String, span: node.Span)
```
A node tag uses a handle that has not been declared for the document.

InvalidTag(tag: String, span: node.Span)

A node tag is malformed.

InvalidMergeTarget(found: node.KindName, span: node.Span)

A merge key points at a value that is not a mapping.

</>

A secondary source location related to a diagnostic.

pub type Related {
  FirstMappingKey(span: node.Span)
  FirstAnchor(span: node.Span)
  FirstYamlDirective(span: node.Span)
}

Constructors

```
FirstMappingKey(span: node.Span)
```
The first occurrence of a duplicate mapping key.
```
FirstAnchor(span: node.Span)
```
The first occurrence of a duplicate anchor.
```
FirstYamlDirective(span: node.Span)
```
The first occurrence of a duplicate YAML directive.

Severity

</>

How serious a diagnostic is.

pub type Severity {
  Warning
  DiagnosticError
}

Constructors

```
Warning
```
A non-fatal diagnostic.

Resolution can still succeed when a diagnostic has this severity.
```
DiagnosticError
```
A fatal diagnostic.

Resolution returns an error when any diagnostic has this severity.

Values

collect

</>

pub fn collect(value: node.Node) -> List(Diagnostic)

Collects non-fatal diagnostics for a parsed YAML node tree.

errors

</>

pub fn errors(diagnostics: List(Diagnostic)) -> List(Diagnostic)

Keeps only fatal diagnostics.

has_errors

</>

pub fn has_errors(diagnostics: List(Diagnostic)) -> Bool

Returns True when any diagnostic is fatal.

is_error

</>

pub fn is_error(diagnostic: Diagnostic) -> Bool

Returns True when a diagnostic is fatal.

message

</>

pub fn message(diagnostic: Diagnostic) -> String

Renders a human-readable diagnostic message.

</>

pub fn related(diagnostic: Diagnostic) -> List(Related)

Returns related source locations for a diagnostic.

related_message

</>

pub fn related_message(related: Related) -> String

Renders a human-readable related-location message.

related_span

</>

pub fn related_span(related: Related) -> node.Span

Returns the source span for a related location.

severity

</>

pub fn severity(diagnostic: Diagnostic) -> Severity

Returns the severity for a diagnostic variant.

span

</>

pub fn span(diagnostic: Diagnostic) -> node.Span

Returns the primary source span for a diagnostic.

warnings

</>

pub fn warnings(
  diagnostics: List(Diagnostic),
) -> List(Diagnostic)

Keeps only warning diagnostics.