# gizmodel/sql/types/xml

PostgreSQL's xml type: well-formedness, a node tree, XPath 1.0 and serialization (PostgreSQL's xml.c over libxml2). Values stay text; a function parses its argument when it needs the tree. Callers turn the error texts here into the SQLSTATEs of the function (func.giz).

```gizlang
import * as Xml from "gizmodel/sql/types/xml";
```

## Functions

### `xmlCheck`

```gizlang
function xmlCheck(text: string, document: bool): string
```

Whether `text` is well-formed XML: "" when it is, else libxml's message. A bad declaration is
"invalid XML declaration".

Effects: fail, alloc.

### `xmlIsDocument`

```gizlang
function xmlIsDocument(text: string): bool
```

Whether a parsed value is a document: one element at the top, beside comments, processing instructions and a
DOCTYPE.

Effects: fail, alloc.

### `xmlDeclaration`

```gizlang
function xmlDeclaration(text: string): Vec<string>
```

The parts of the XML declaration at the start of `text`: [version, standalone, rest].

Effects: fail, alloc.

### `xmlEscape`

```gizlang
function xmlEscape(s: string): string
```

`s` escaped as XML text: &, < and >, and a carriage return.

Effects: fail, alloc.

### `xmlAttrEscape`

```gizlang
function xmlAttrEscape(s: string): string
```

`s` escaped as a double-quoted attribute value: also ", and tab, line feed and carriage return as references.

Effects: fail, alloc.

### `xmlIndent`

```gizlang
function xmlIndent(text: string, document: bool): string throws string
```

`text` serialized by XMLSERIALIZE ... INDENT: elements whose children hold no text print one child per line,
indented by two spaces. A document ends with a line break and keeps its declaration; content drops it.

Effects: fail, alloc.

### `namespacePairs`

```gizlang
function namespacePairs(text: string): Vec<string>
```

The namespace pairs [prefix, uri, ...] of PostgreSQL's ARRAY[ARRAY[prefix, uri], ...] text.

Effects: fail, alloc.

### `xpathEval`

```gizlang
function xpathEval(path: string, doc: string, ns: Vec<string>): Vec<string> throws string
```

The result of XPath `path` over `doc`: [kind, items...] where kind is "nodes" (each item the XML of a node:
an element with the namespaces it uses, an attribute's or a text's escaped value), or "bool", "num" or "str"
with one item. `ns`: namespace pairs. A namespace error in the document refuses it.

Effects: fail, alloc.

### `xmlTablePack`

```gizlang
function xmlTablePack(rowPath: string, doc: string, ns: Vec<string>, asXml: Vec<bool>, paths: Vec<string>): string throws string
```

XMLTABLE: every cell of the rows `rowPath` selects in `doc`, as one text, so a query reads the document once.
`asXml[c]` and `paths[c]` describe column c. The text is the row count (10 digits), then for each cell in row order
11 characters (v or n for none, and the 10-digit end of its data), then the data.

Effects: fail, alloc.

### `xmlTableRows`

```gizlang
function xmlTableRows(packed: string): i64
```

The number of rows in a text made by xmlTablePack.

Effects: fail, alloc.

### `xmlTablePick`

```gizlang
function xmlTablePick(packed: string, k: i64, c: i64, columns: i64): Option<string>
```

Cell `c` of row `k` (from 1) of `columns` columns in a text made by xmlTablePack: none past the rows or for an empty
result.

Effects: fail, alloc.

### `xmlName`

```gizlang
function xmlName(ident: string): string
```

An SQL identifier as an XML name (PostgreSQL's map_sql_identifier_to_xml_name): a character no name may hold
there becomes _xHHHH_, as do a leading colon and the _ of _x.

Effects: fail, alloc.

