# TBMANLIB_Xml Package
{: .no_toc }

**Author:** woeoio. **Version:** 1.0.0.1

The **TBMANLIB_Xml** contributed package reads, changes and writes XML documents. It has the shape of a small DOM. A [**cXml**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md) object holds a document as a tree of [**cXmlNode**](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md) objects, finds elements by a path such as `library/book` or by an XPath expression, and reads and writes the document as a string or as a UTF-8 file. The [**mXml**](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md) module holds the node types, the error numbers and two functions that convert between strings and UTF-8 bytes, and the [**mXPath**](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md) module evaluates the XPath expressions. The package is written in twinBASIC and calls two functions of the Windows API for the conversion. This section documents version 1.0.0.1, published under the MIT licence.

```tb check_build check_run
Dim x As New cXml
x.CreateNew "library"
x.SetAttribute "library", "city", "Oslo"

Dim book As cXmlNode
Set book = x.AddElement("library", "book")
book.SetAttribute "id", "1"
x.SetElementText "library/book", "Dune"

Dim y As New cXml
y.Parse x.ToXmlString()
Debug.Print y.GetAttribute("library", "city")
Debug.Print y.GetElementText("library/book")
Debug.Print y.ToXmlString(False)
' Output:
' Oslo
' Dune
' <library city="Oslo"><book id="1">Dune</book></library>
```

> [!WARNING] 1.0.0.1
> The parser reads some valid XML wrongly and raises no error, and for some text it never returns. [Defects in version 1.0.0.1](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#defects) lists the cases: self-closing elements, entities in text, tags with both kinds of quote or with line breaks, processing instructions, and comments, CDATA sections and DOCTYPE declarations in some positions.

> [!WARNING] 1.0.0.1
> The XPath engine reads some valid expressions wrongly and raises no error: the step `..`, axes such as `ancestor::`, positions after `//`, and the operators `and` and `or`. [Defects in version 1.0.0.1](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md#defects) lists the cases.

## What the package reads and writes

A document is read from a string by [**Parse**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#parse), from a file by [**LoadFromFile**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#loadfromfile), or started with [**CreateNew**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#createnew). The package supports:

- elements and their attributes, with attribute values in double or single quotes;
- text, comments and CDATA sections, each held as a node. Text that is only spaces is left out, and text that has a line break or a tab in it is kept;
- the `version` and `encoding` of the XML declaration, which are read, kept and written;
- reading and setting an element's text and attributes, adding and removing elements, copying a document ([**Clone**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#clone)) and appending one to another ([**Merge**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#merge));
- finding nodes by a path of names ([**SelectElement**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#selectelement)) or by an XPath expression ([**XPath**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#xpath)), in the part of XPath 1.0 that [**mXPath**](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md) reads;
- writing the document compactly or with line breaks and indentation, with `&`, `<`, `>`, `"` and `'` escaped;
- files in UTF-8. A byte order mark is accepted when a file is read and always written.

The package does not support, in version 1.0.0.1:

- DTDs and schemas. A DOCTYPE declaration is not read, and nothing is validated against a DTD or a schema. [**Validate**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#validate) only checks that elements and attributes have names;
- most of XPath. The [**XPath**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#xpath) methods read a part of XPath 1.0, described on the page of the [**mXPath**](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md) module: there is no union, no attribute step, no ancestor or sibling axis, and few functions. The other members that take a path read a list of element names separated by `/`, with no positions, attributes or wildcards; see [Paths](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#paths);
- namespaces. A prefix is part of an element's or attribute's name, and no namespace is resolved;
- entities defined in a DTD, and character references such as `&#65;`. The five predefined entities are decoded in attribute values and not in text;
- processing instructions, which are skipped, and the `standalone` pseudo-attribute of the declaration;
- encodings other than UTF-8 in files, whatever the declaration says;
- checking that text is well formed. [**Parse**](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#parse) accepts text that is not XML, elements that are not closed and end tags that name another element.

The [**ParseOption**](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#parseoption) enumeration, with members such as **PreserveWhitespace** and **ValidateOnParse**, is declared by the module, but no member of the package reads it.

## Failures

No member of the package ends a program with an error of its own. A member that cannot do its work returns **False**, **Nothing**, an empty string or an empty collection, and in the IDE writes a line that names the member to the Debug Console, for example `Parse failed: XML string cannot be empty`. The error stays in the **Err** object after the call. The error numbers are constants of [**mXml**](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#constants), and only [**ERR_EMPTY_DOCUMENT**](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#err_empty_document) is used. [Reporting failures](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#reporting-failures) has the details. The two functions of [**mXPath**](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md#selectnodes) are the exception: they handle no error, and the error of an evaluation reaches the program that called them.

## Classes and modules

- [cXml](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md) -- holds an XML document, reads it from a string or a file, finds, changes and adds elements by path, finds nodes by an XPath expression, and writes it as a string or a file
  - [Document](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#document) -- returns the document node
  - [Encoding](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#encoding) -- returns or sets the encoding name of the declaration
  - [Initialized](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#initialized) -- returns whether the object holds a document
  - [RootElement](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#rootelement) -- returns the root element
  - [Version](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#version) -- returns or sets the XML version of the declaration
  - [XmlString](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#xmlstring) -- returns or sets the text of the document that was last read
  - [New](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#new) -- creates an object
  - [AddElement](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#addelement) -- adds an empty element as the last child of an element
  - [Clone](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#clone) -- returns a copy of the document
  - [CreateNew](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#createnew) -- replaces the document with a new one that has a root element
  - [GetAttribute](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#getattribute) -- returns an attribute of an element
  - [GetElementText](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#getelementtext) -- returns the text inside an element
  - [LoadFromFile](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#loadfromfile) -- reads a document from a file
  - [Merge](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#merge) -- appends the content of another document
  - [Parse](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#parse) -- reads a document from a string
  - [RemoveAttribute](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#removeattribute) -- removes an attribute
  - [RemoveElement](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#removeelement) -- removes an element
  - [SaveToFile](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#savetofile) -- writes the document to a file
  - [SelectElement](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#selectelement) -- returns the element that a path selects
  - [SelectElements](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#selectelements) -- returns every node with a given name
  - [SetAttribute](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#setattribute) -- sets an attribute
  - [SetElementText](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#setelementtext) -- replaces the text of an element
  - [ToXmlString](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#toxmlstring) -- returns the document as text
  - [Validate](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#validate) -- checks that every element and attribute has a name
  - [XPath](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#xpath) -- returns the nodes that an XPath expression selects
  - [XPathAttribute](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#xpathattribute) -- returns an attribute of the first node that an XPath expression selects
  - [XPathFromRoot](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#xpathfromroot) -- returns the nodes that an XPath expression selects, starting at the root element
  - [XPathSingle](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#xpathsingle) -- returns the first node that an XPath expression selects
  - [XPathText](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#xpathtext) -- returns the text of the first node that an XPath expression selects
- [cXmlNode](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md) -- one node of a document: an element, text, a CDATA section, a comment or the document itself
  - [Attributes](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#attributes) -- holds the attributes as a list of names and values
  - [ChildNodes](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#childnodes) -- holds the nodes directly inside the node
  - [Name](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#name) -- returns or sets the name
  - [NodeType](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#nodetype) -- returns or sets the kind of node
  - [Parent](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#parent) -- returns the node that holds this one
  - [Text](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#text) -- returns the text directly inside the node
  - [Value](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#value) -- returns or sets the text of a text node, a CDATA section or a comment
  - [New](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#new) -- creates a node
  - [GetAttribute](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#getattribute) -- returns the value of an attribute
  - [GetChildNode](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#getchildnode) -- returns the first child with a given name
  - [GetChildNodesByName](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#getchildnodesbyname) -- returns all the children with a given name
  - [RemoveAttribute](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#removeattribute) -- removes an attribute
  - [SetAttribute](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#setattribute) -- sets the value of an attribute
  - [XPath](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#xpath) -- returns the nodes that an XPath expression selects, starting at the node
  - [XPathAttribute](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#xpathattribute) -- returns an attribute of the first node that an XPath expression selects
  - [XPathSingle](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#xpathsingle) -- returns the first node that an XPath expression selects
  - [XPathText](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md#xpathtext) -- returns the text directly inside the first node that an XPath expression selects
- [mXml](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md) -- the node types, the parse options, the error numbers, the defaults and the UTF-8 conversion functions
  - [XmlNodeType](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#xmlnodetype) -- the kinds of node
  - [ParseOption](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#parseoption) -- four flags that no member reads
  - [ERR_BASE](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#err_base) and the other [error numbers](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#constants) -- the base of the package's error numbers, and the numbers
  - [DEFAULT_XML_VERSION](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#default_xml_version), [DEFAULT_ENCODING](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#default_encoding) and [DEFAULT_INDENT](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#default_indent) -- the defaults
  - [StringToUTF8Bytes](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#stringtoutf8bytes) -- converts a string to UTF-8 bytes
  - [UTF8BytesToString](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md#utf8bytestostring) -- converts UTF-8 bytes to a string
- [mXPath](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md) -- the XPath engine behind the **XPath** methods
  - [SelectNodes](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md#selectnodes) -- returns the nodes that an XPath expression selects
  - [SelectSingleNode](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md#selectsinglenode) -- returns the first node that an XPath expression selects

## The test module

The package also contains **mXmlTests**, a module of unit tests for **cXml**, which has no page of its own here. **mXmlTests.RunAllTests** runs 119 checks and writes a line for each to the Debug Console: `[PASS]` or `[FAIL]` and the check's message, grouped under the name of the test. It ends with a summary of the totals, the pass rate and a closing line; in version 1.0.0.1 all 119 pass. Each test is also a public **Sub** of the module that can be run alone.

The checks compare one value at a time and do not exercise the cases listed under [Defects in version 1.0.0.1](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md#defects): the test of self-closing tags tests that the output contains `/>`, and the namespace test tests that **Parse** returns **True**. The eight XPath tests test the forms that [**mXPath**](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md) reads, and none of the cases listed under its [defects](/tB/Packages/Contributed/TBMANLIB_Xml/mXPath.md#defects). The file tests write `test_output.xml` and `test_output_pretty.xml` in the current folder, and leave them there.

## See Also

- [cXml](/tB/Packages/Contributed/TBMANLIB_Xml/cXml.md) class -- the document
- [cXmlNode](/tB/Packages/Contributed/TBMANLIB_Xml/cXmlNode.md) class -- the nodes
- [mXml](/tB/Packages/Contributed/TBMANLIB_Xml/mXml.md) module -- constants, enumerations and UTF-8 conversion
- [Experimental Packages](/tB/Packages/Experimental/index.md) -- the packages from TWINSERV that are not yet ready for use in a program

## Test cases

The notes and warnings of this section are checked by the test cases in [TBMANLIB_Xml-tests.twinproj](TBMANLIB_Xml-tests.twinproj), a twinBASIC project. It uses TBMANLIB_Xml as a [linked package](/Features/Packages/Linked.md#manual-management): put the package's `.twinpack` in `%APPDATA%\twinBASIC\packages`, then run the project, and each case prints whether it passes.
