vxml

Core VXML tree types, parsers, validators, and serializers.

VXML is a generic XML-like tree with two node kinds: element nodes (V) and text nodes (T). The serialized VXML functions validate VXML-format invariants and return Result; the XML, HTML, and JSX-like emitters target their respective output formats and return output directly. This module also includes XML/HTML parsing helpers.

Types

Attr

</>

An attribute on a VXML element node.

pub type Attr {
  Attr(blame: blame.Blame, key: String, val: String)
}

Constructors

Attr(blame: blame.Blame, key: String, val: String)

BadKey

</>

A reason an attribute key cannot be represented in serialized VXML.

pub type BadKey {
  EmptyKey
  IllegalKeyCharacter(String, String)
}

Constructors

```
EmptyKey
```
The key is empty.
```
IllegalKeyCharacter(String, String)
```
Contains the complete key followed by the offending character.

BadLines

</>

A reason a text node’s lines cannot be represented in serialized VXML.

pub type BadLines {
  NoLines
  IllegalLineCharacter(
    line_no: Int,
    char_no: Int,
    content: String,
    character: String,
  )
}

Constructors

```
NoLines
```
The text node contains no lines.
```
IllegalLineCharacter(
  line_no: Int,
  char_no: Int,
  content: String,
  character: String,
)
```
Identifies the line and character within the text node, followed by the complete line content and offending character.

BadTag

</>

A reason an element tag does not satisfy the VXML tag grammar.

pub type BadTag {
  EmptyTag
  MalformedTag(String, String)
}

Constructors

```
EmptyTag
```
The tag is empty.
```
MalformedTag(String, String)
```
Contains the complete tag followed by the required grammar.

BadValue

</>

A reason an attribute value cannot be represented in serialized VXML.

pub type BadValue {
  IllegalValueCharacter(String, String)
  TrailingWhitespace(String, String)
}

Constructors

```
IllegalValueCharacter(String, String)
```
Contains the complete value followed by the offending character.
```
TrailingWhitespace(String, String)
```
Contains the complete value followed by its trailing space or tab.

HTMLEntityNormalizationError

</>

An invalid exception passed to an HTML-entity normalization helper.

pub type HTMLEntityNormalizationError {
  MalformedHTMLEntityException(String)
  UnrecognizedHTMLEntityException(String)
}

Constructors

```
MalformedHTMLEntityException(String)
```
Exception strings must have the form &name;, &#decimal;, or &#xhex;.
```
UnrecognizedHTMLEntityException(String)
```
The exception has entity syntax but is not recognized as an HTML entity.

Line

</>

One line of text inside a VXML text node.

pub type Line {
  Line(blame: blame.Blame, content: String)
}

Constructors

Line(blame: blame.Blame, content: String)

VXML

</>

A generic XML-like tree.

V is an element node. T is a text node containing one or more lines.

pub type VXML {
  V(
    blame: blame.Blame,
    tag: String,
    attrs: List(Attr),
    children: List(VXML),
  )
  T(blame: blame.Blame, lines: List(Line))
}

Constructors

V(
  blame: blame.Blame,
  tag: String,
  attrs: List(Attr),
  children: List(VXML),
)

T(blame: blame.Blame, lines: List(Line))

VXMLInvalidityReason

</>

The invalid part of a VXML value found during validation or serialization.

pub type VXMLInvalidityReason {
  TagIsBad(BadTag)
  AttributeKeyIsBad(BadKey)
  AttributeValueIsBad(BadValue)
  LinesAreBad(BadLines)
}

Constructors

```
TagIsBad(BadTag)
```
```
AttributeKeyIsBad(BadKey)
```
```
AttributeValueIsBad(BadValue)
```
```
LinesAreBad(BadLines)
```

VXMLParseError

</>

An error encountered while parsing serialized VXML.

pub type VXMLParseError {
  AttributeAssignmentMissing(blame: blame.Blame, line: String)
  BadTag(blame: blame.Blame, reason: BadTag)
  BadAttributeKey(blame: blame.Blame, reason: BadKey)
  BadAttributeValue(blame: blame.Blame, reason: BadValue)
  UnexpectedIndentation(
    blame: blame.Blame,
    expected: Int,
    actual: Int,
    line: String,
  )
  TabInIndentation(blame: blame.Blame, line: String)
  TextLineOpeningQuoteMissing(blame: blame.Blame, line: String)
  TextLineClosingQuoteMissing(blame: blame.Blame, line: String)
  TextNodeLinesMissing(blame: blame.Blame)
  NodeMarkerMissing(blame: blame.Blame, line: String)
  ExpectedOneRoot(actual: Int)
}

Constructors

AttributeAssignmentMissing(blame: blame.Blame, line: String)

An attribute line contains no = assignment marker.

```
BadTag(blame: blame.Blame, reason: BadTag)
```
An element has a tag that does not satisfy the VXML tag grammar.

BadAttributeKey(blame: blame.Blame, reason: BadKey)

An attribute key is invalid.

BadAttributeValue(blame: blame.Blame, reason: BadValue)

An attribute value is invalid.

UnexpectedIndentation(
  blame: blame.Blame,
  expected: Int,
  actual: Int,
  line: String,
)

A line is indented more deeply than its current syntactic position permits.

```
TabInIndentation(blame: blame.Blame, line: String)
```
A tab occurs where serialized VXML permits only space-based indentation.

TextLineOpeningQuoteMissing(blame: blame.Blame, line: String)

A text line does not begin with the VXML line delimiter.

TextLineClosingQuoteMissing(blame: blame.Blame, line: String)

A text line does not end with the VXML line delimiter.

```
TextNodeLinesMissing(blame: blame.Blame)
```
A text-node marker is not followed by any text lines.

NodeMarkerMissing(blame: blame.Blame, line: String)

A node line does not begin with the <> marker.

```
ExpectedOneRoot(actual: Int)
```
A singular parser received a number of roots other than one.

VXMLParsePathError

</>

An I/O or document error encountered while parsing a VXML file.

pub type VXMLParsePathError {
  IOError(simplifile.FileError)
  DocumentError(VXMLParseError)
}

Constructors

```
IOError(simplifile.FileError)
```
Reading the path failed.
```
DocumentError(VXMLParseError)
```
The file was read but its contents were not valid serialized VXML.

VXMLSerializationError

</>

A serialized-VXML failure with the valid output produced before it.

pub type VXMLSerializationError {
  VXMLSerializationError(
    partial: List(io_lines.OutputLine),
    blame: blame.Blame,
    reason: VXMLInvalidityReason,
  )
}

Constructors

VXMLSerializationError(
  partial: List(io_lines.OutputLine),
  blame: blame.Blame,
  reason: VXMLInvalidityReason,
)

VXMLValidationError

</>

A VXML tree-validation failure and the provenance of the invalid value.

pub type VXMLValidationError {
  VXMLValidationError(
    blame: blame.Blame,
    reason: VXMLInvalidityReason,
  )
}

Constructors

VXMLValidationError(
  blame: blame.Blame,
  reason: VXMLInvalidityReason,
)

XMLParseError

</>

An error encountered while parsing XML-like input.

pub type XMLParseError {
  XMLParseError(blame: blame.Blame, message: String)
}

Constructors

XMLParseError(blame: blame.Blame, message: String)

Values

annotate_blames

</>

pub fn annotate_blames(vxml: VXML) -> VXML

Adds structural descriptions to blame comments throughout a VXML tree. This is intended for diagnostic tables. Blame identities and tree contents are otherwise unchanged.

html_entities_to_unicode

</>

pub fn html_entities_to_unicode(
  vxml: VXML,
  except exceptions: List(String),
) -> Result(VXML, HTMLEntityNormalizationError)

Decodes recognized HTML entities in text lines and attribute values.

Exceptions should be supplied as literal HTML entity strings, such as &ensp; or  ; exact occurrences of those spellings are preserved.

html_invisible_entities

</>

pub const html_invisible_entities: List(String)

HTML invisible entities commonly worth keeping visible in source text.

html_layout_entities

</>

pub const html_layout_entities: List(String)

HTML spacing and invisible entities commonly worth keeping as entities.

html_repair

</>

pub fn html_repair(content: String) -> String

Applies the package’s best-effort HTML repairs for XML-oriented parsing.

html_repair_close_void_tags

</>

pub fn html_repair_close_void_tags(content: String) -> String

Converts common HTML void-element openings to self-closing XML syntax.

html_repair_escape_non_entity_ampersands

</>

pub fn html_repair_escape_non_entity_ampersands(
  content: String,
) -> String

Escapes ampersands that do not begin a known HTML entity.

html_repair_expand_boolean_attrs

</>

pub fn html_repair_expand_boolean_attrs(
  content: String,
) -> String

Gives common bare HTML boolean attributes empty assigned values.

html_repair_remove_attrs_from_closing_tags

</>

pub fn html_repair_remove_attrs_from_closing_tags(
  content: String,
) -> String

Removes attributes from malformed closing tags.

html_spacing_entities

</>

pub const html_spacing_entities: List(String)

HTML spacing entities commonly worth keeping visible in source text.

html_syntax_entities

</>

pub const html_syntax_entities: List(String)

HTML syntax entities commonly worth excluding from broad normalization.

html_to_vxml

</>

pub fn html_to_vxml(
  content: String,
  filename: String,
) -> Result(VXML, XMLParseError)

Parses best-effort repaired HTML into VXML.

The parser applies html_repair, permits unquoted attribute values, and preserves recognized HTML character-reference spellings in text and attribute values.

input_lines_to_vxml

</>

pub fn input_lines_to_vxml(
  lines: List(io_lines.InputLine),
) -> Result(VXML, VXMLParseError)

Parses input lines containing exactly one VXML root.

Blank physical lines are ignored. Any root count other than one returns ExpectedOneRoot.

input_lines_to_vxmls

</>

pub fn input_lines_to_vxmls(
  lines: List(io_lines.InputLine),
) -> Result(List(VXML), VXMLParseError)

Parses input lines containing zero or more VXML roots.

Blank physical lines are ignored.

path_to_vxml

</>

pub fn path_to_vxml(
  path: String,
) -> Result(VXML, VXMLParsePathError)

Parses a path containing exactly one VXML root.

Returns IOError when reading fails and DocumentError when parsing fails. A root count other than one is a DocumentError(ExpectedOneRoot(..)).

path_to_vxmls

</>

pub fn path_to_vxmls(
  path: String,
) -> Result(List(VXML), VXMLParsePathError)

Parses a path containing zero or more VXML roots.

Returns IOError when reading fails and DocumentError when parsing fails.

string_to_vxml

</>

pub fn string_to_vxml(
  source: String,
  filename: String,
) -> Result(VXML, VXMLParseError)

Parses a string containing exactly one VXML root.

filename is recorded in source blame and has no other semantic effect. Blank physical lines are ignored. Any root count other than one returns ExpectedOneRoot.

string_to_vxmls

</>

pub fn string_to_vxmls(
  source: String,
  filename: String,
) -> Result(List(VXML), VXMLParseError)

Parses a string containing zero or more VXML roots.

filename is recorded in source blame and has no other semantic effect. Blank physical lines are ignored.

unicode_to_named_html_entities

</>

pub fn unicode_to_named_html_entities(
  vxml: VXML,
  except exceptions: List(String),
) -> Result(VXML, HTMLEntityNormalizationError)

Encodes Unicode characters in text lines and attribute values as named HTML entities whenever glentities has a named entity for the character.

Exceptions should be supplied as literal HTML entity strings, such as &ensp;; their decoded Unicode characters are preserved.

validate

</>

pub fn validate(vxml: VXML) -> Result(Nil, VXMLValidationError)

Validates a complete VXML tree against the VXML text-format rules.

This checks element tags, attribute keys and values, text contents, and the requirement that every text node contain at least one line. Leading spaces and tabs in attribute values are preserved; trailing spaces and tabs are rejected.

validate_key

</>

pub fn validate_key(key: String) -> Result(String, BadKey)

Validates an attribute key for the VXML text format.

validate_tag

</>

pub fn validate_tag(tag: String) -> Result(String, BadTag)

Validates an element tag for the VXML text format.

validate_value

</>

pub fn validate_value(value: String) -> Result(String, BadValue)

Validates an attribute value for the VXML text format.

vxml_indent

</>

pub const vxml_indent: Int

The number of spaces per level in serialized VXML.

vxml_line_delimiter

</>

pub const vxml_line_delimiter: String

The delimiter surrounding text-line contents in serialized VXML.

vxml_table

</>

pub fn vxml_table(
  vxml: VXML,
  banner: String,
  indent: Int,
) -> Result(String, VXMLSerializationError)

Renders one VXML tree as a blame-annotated diagnostic table.

vxml_to_html

</>

pub fn vxml_to_html(
  vxml: VXML,
  starting_indent: Int,
  indentation: Int,
) -> String

Serializes one VXML node to an HTML string.

vxml_to_html_output_lines

</>

pub fn vxml_to_html_output_lines(
  vxml: VXML,
  starting_indent: Int,
  indentation: Int,
) -> List(io_lines.OutputLine)

Serializes one VXML node to HTML output lines.

vxml_to_jsx

</>

pub fn vxml_to_jsx(
  vxml: VXML,
  starting_indent: Int,
  indentation: Int,
) -> String

Serializes one VXML node to a JSX-like string.

vxml_to_jsx_output_lines

</>

pub fn vxml_to_jsx_output_lines(
  vxml: VXML,
  starting_indent: Int,
  indentation: Int,
) -> List(io_lines.OutputLine)

Serializes one VXML node to JSX-like output lines.

vxml_to_output_lines

</>

pub fn vxml_to_output_lines(
  vxml: VXML,
) -> Result(List(io_lines.OutputLine), VXMLSerializationError)

Serializes one VXML node to VXML text-format output lines.

vxml_to_string

</>

pub fn vxml_to_string(
  vxml: VXML,
) -> Result(String, VXMLSerializationError)

Serializes one VXML node to the VXML text format.

vxml_to_xml

</>

pub fn vxml_to_xml(
  vxml: VXML,
  starting_indent: Int,
  indentation: Int,
) -> String

Serializes one VXML node to XML.

vxml_to_xml_output_lines

</>

pub fn vxml_to_xml_output_lines(
  vxml: VXML,
  starting_indent: Int,
  indentation: Int,
) -> List(io_lines.OutputLine)

Serializes one VXML node to XML output lines.

Element-only content is indented. Mixed content remains compact so that formatting does not introduce text whitespace.

vxmls_to_html

</>

pub fn vxmls_to_html(
  vxmls: List(VXML),
  starting_indent: Int,
  indentation: Int,
) -> String

Serializes VXML nodes to one HTML string in the same order.

vxmls_to_html_output_lines

</>

pub fn vxmls_to_html_output_lines(
  vxmls: List(VXML),
  starting_indent: Int,
  indentation: Int,
) -> List(io_lines.OutputLine)

Serializes VXML nodes to HTML output lines in the same order.

vxmls_to_jsx

</>

pub fn vxmls_to_jsx(
  vxmls: List(VXML),
  starting_indent: Int,
  indentation: Int,
) -> String

Serializes VXML nodes to one JSX-like string in the same order.

vxmls_to_jsx_output_lines

</>

pub fn vxmls_to_jsx_output_lines(
  vxmls: List(VXML),
  starting_indent: Int,
  indentation: Int,
) -> List(io_lines.OutputLine)

Serializes VXML nodes to JSX-like output lines in the same order.

vxmls_to_output_lines

</>

pub fn vxmls_to_output_lines(
  vxmls: List(VXML),
) -> Result(List(io_lines.OutputLine), VXMLSerializationError)

Serializes VXML nodes to VXML text-format output lines in the same order.

vxmls_to_string

</>

pub fn vxmls_to_string(
  vxmls: List(VXML),
) -> Result(String, VXMLSerializationError)

Serializes VXML nodes to the VXML text format in the same order.

vxmls_to_xml

</>

pub fn vxmls_to_xml(
  vxmls: List(VXML),
  starting_indent: Int,
  indentation: Int,
) -> String

Serializes VXML nodes to XML.

vxmls_to_xml_output_lines

</>

pub fn vxmls_to_xml_output_lines(
  vxmls: List(VXML),
  starting_indent: Int,
  indentation: Int,
) -> List(io_lines.OutputLine)

Serializes VXML nodes to XML output lines.

xml_input_lines_to_vxml

</>

pub fn xml_input_lines_to_vxml(
  lines: List(io_lines.InputLine),
) -> Result(VXML, XMLParseError)

Parses XML-like input lines into VXML.

Tag and attribute names must satisfy XML’s Name grammar. Attribute values must be quoted. Character references are decoded in text and values.

xml_to_vxml

</>

pub fn xml_to_vxml(
  content: String,
  filename: String,
) -> Result(VXML, XMLParseError)

Parses an XML-like string into VXML.

filename is recorded in source blame. Tag and attribute names must satisfy XML’s Name grammar. Attribute values must be quoted, and character references are decoded in text and values.