IF Commons GitHub

xml

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-formats FR-004

XML as a typed tree of elements and text, written with every value escaped (no document is a template of values) and read with no outside package (commons 0001-formats FR-004). The reader takes elements, attributes in either quote, the five named entities and character references, CDATA, comments, processing instructions and the XML declaration, checks that every element is closed by its own name, and refuses a document type with an internal subset, so no entity is ever expanded (no "billion laughs", no external entity). Names are kept as written (dc:title); the finders match a name with or without its prefix. Taken from erga's lib/ts/xml, whose reader was @std/xml.

import { el, readXml, textOf, writeXml } from "./xml.ts";
const doc = writeXml(el("note", [el("to", ["Ada & Charles"])], [["lang", "en"]]));
// '<?xml version="1.0" encoding="UTF-8"?>\n<note lang="en"><to>Ada &amp; Charles</to></note>'
const back = readXml(doc);
if (back.kind === "ok") textOf(back.value); // "Ada & Charles"

Source: commons/formats/src/xml.ts

15 of 19 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

attributefunction
function attribute(n: XmlNode | undefined, name: string): string | undefined

An attribute's value, by its name with or without a prefix.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

childfunction
function child(n: XmlNode, name: string): XmlElement | undefined

The first child element named name.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

childrenfunction
function children(n: XmlNode, name: string): readonly XmlElement[]

The child elements of a node named name (with or without a prefix).

Imported by 13 tests of the run (13 passed, 0 failed): the library's results

descendantsfunction
function descendants(n: XmlNode, name: string): readonly XmlElement[]

Every element below a node named name, in document order.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

elfunction
function el(name: string, children?: readonly XmlChild[], attributes?: readonly (readonly [string, string])[]): XmlElement

An element.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

escapeXmlfunction
function escapeXml(s: string): string

A value as XML text or an attribute's value: &, <, >, " and ' escaped, and the characters XML 1.0 forbids removed.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

formatXmlErrorfunction
function formatXmlError(e: XmlError): string

An XML error as one line: 3:14: expected a name.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

leaffunction
function leaf(name: string, value: string | number | boolean | undefined): XmlElement | undefined

An element holding one value, or nothing where the value is absent.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

localNamefunction
function localName(name: string): string

A name without its prefix: title for dc:title.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

readXmlfunction
function readXml(text: string, options?: ReadXmlOptions): Result<XmlElement, XmlError>

A document read: its root element; or where and why it is not XML this reader takes.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

textOffunction
function textOf(n: XmlNode | undefined): string

All the text a node holds.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

writeNodefunction
function writeNode(n: XmlNode): string

A node as XML text, with no declaration.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

writeXmlfunction
function writeXml(root: XmlElement): string

A whole document: the XML declaration, then its root.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

ReadXmlOptionstypeno test imports it
type ReadXmlOptions = { readonly keepWhitespace?: boolean };

How to read: whether text that is only white space between elements is kept (it is dropped by default).

XmlChildtypeno test imports it
type XmlChild = XmlNode | string | number | boolean | undefined;

What an element may be given as a child: a node, or a value written as text; undefined gives nothing.

XmlElementtype
type XmlElement = {
  readonly kind: "element";
  readonly name: string;
  readonly attributes: readonly (readonly [string, string])[];
  readonly children: readonly XmlNode[];
};

An element: its name as written, its attributes in order, and its children.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

XmlErrortypeno test imports it
type XmlError = { readonly kind: "xml"; readonly line: number; readonly column: number; readonly message: string };

Where a text stops being XML this reader takes, and why. Lines and columns count from 1.

XmlNodetype
type XmlNode = XmlElement | XmlText;

A node of an XML document.

Imported by 8 tests of the run (8 passed, 0 failed): the library's results

XmlTexttypeno test imports it
type XmlText = { readonly kind: "text"; readonly text: string };

Text, its entities and references already replaced.

Titles, headings, exports, tables, columns and requirements. Esc closes.