# Parsing XML

The &neon; XML interface is exposed by the `ne_xml.h` header file. This interface gives a wrapper around the standard SAX API used by XML parsers, with an additional abstraction, stacked SAX handlers, and also giving consistent XML Namespace support.

## Introduction to SAX

A SAX-based parser works by emitting a sequence of events to reflect the tokens being parsed from the XML document. For example, parsing the following document fragment:

    <hello>world</hello>

results in the following events:

1. &startelm; "hello"

2. &cdata; "world"

3. &endelm; "hello"

This example demonstrates the three event types used used in the subset of SAX exposed by the &neon; XML interface: &startelm;, &cdata; and &endelm;. In a C API, an event is implemented as a function callback; three callback types are used in &neon;, one for each type of event.

## Stacked SAX handlers

WebDAV property values are represented as fragments of XML, transmitted as parts of larger XML documents over HTTP (notably in the body of the response to a `PROPFIND` request). When &neon; parses such documents, the SAX events generated for these property value fragments may need to be handled by the application, since &neon; has no knowledge of the structure of properties used by the application.

To solve this problem This problem only needs solving because the SAX interface is so inflexible when implemented as C function callbacks; a better approach would be to use an XML parser interface which is not based on callbacks. the &neon; XML interface introduces the concept of a SAX handler. A SAX handler comprises a &startelm;, &cdata; and &endelm; callback; the &startelm; callback being defined such that each handler may accept or decline the &startelm; event. Handlers are composed into a handler stack before parsing a document. When a new &startelm; event is generated by the XML parser, &neon; invokes each &startelm; callback in the handler stack in turn until one accepts the event. The handler which accepts the event will then be subsequently be passed &cdata; events if the element contains character data, followed by an &endelm; event when the element is closed. If no handler in the stack accepts a &startelm; event, the branch of the tree is ignored.

To illustrate, given a handler A, which accepts the `cat` and `age` elements, and a handler B, which accepts the `name` element, the following document:

### An example XML document

    <cat>
      <age>3</age>
      <name>Bob</name>
    </cat>

would be parsed as follows:

1. A &startelm; "cat" → accept

2. A &startelm; "age" → accept

3. A &cdata; "3"

4. A &endelm; "age"

5. A &startelm; "name" → decline

6. B &startelm; "name" → accept

7. B &cdata; "Bob"

8. B &endelm; "name"

9. A &endelm; "cat"

The search for a handler which will accept a &startelm; event begins at the handler of the parent element and continues toward the top of the stack. For the root element, it begins at the base of the stack. In the above example, handler A is at the base, and handler B at the top; if the `name` element had any children, only B's &startelm; would be invoked to accept them.

## Maintaining state

To facilitate communication between independent handlers, a state integer is associated with each element being parsed. This integer is returned by &startelm; callback and is passed to the subsequent &cdata; and &endelm; callbacks associated with the element. The state integer of the parent element is also passed to each &startelm; callback, the value zero used for the root element (which by definition has no parent).

To further extend : if handler A defines that the state of the root element `cat` will be `42`, the event trace would be as follows:

1. A &startelm; (parent = 0, "cat") → accept, state = 42

2. A &startelm; (parent = 42, "age") → accept, state = 50

3. A &cdata; (state = 50, "3")

4. A &endelm; (state = 50, "age")

5. A &startelm; (parent = 42, "name") → decline

6. B &startelm; (parent = 42, "name") → accept, state = 99

7. B &cdata; (state = 99, "Bob")

8. B &endelm; (state = 99, "name")

9. A &endelm; (state = 42, "cat")

To avoid collisions between state integers used by different handlers, the interface definition of any handler includes the range of integers it will use.

## XML namespaces

To support XML namespaces, every element name is represented as a (namespace, name) pair. The &startelm; and &endelm; callbacks are passed namespace and name strings accordingly. If an element in the XML document has no declared namespace, the namespace given will be the empty string, `""`.