Debian Codegraph @

deps/libneon/doc/html/xml.html

raw
1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Parsing XML</title><link rel="stylesheet" type="text/css" href="../manual.css"><meta name="generator" content="DocBook XSL Stylesheets V1.76.1"><link rel="home" href="index.html" title="neon HTTP/WebDAV client library"><link rel="up" href="api.html" title="Chapter 2. The neon C language interface"><link rel="prev" href="api.html" title="Chapter 2. The neon C language interface"><link rel="next" href="ref.html" title="neon API reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Parsing XML</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="api.html">Prev</a> </td><th width="60%" align="center">Chapter 2. The neon C language interface</th><td width="20%" align="right"> <a accesskey="n" href="ref.html">Next</a></td></tr></table><hr></div><div class="sect1" title="Parsing XML"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="xml"></a>Parsing XML</h2></div></div></div><p>The neon XML interface is exposed by the
2 <code class="filename">ne_xml.h</code> header file. This interface gives a
3 wrapper around the standard <a class="ulink" href="http://www.saxproject.org/" target="_top">SAX</a> API used by XML
4 parsers, with an additional abstraction, <em class="firstterm">stacked SAX
5 handlers</em>, and also giving consistent <a class="ulink" href="http://www.w3.org/TR/REC-xml-names" target="_top">XML Namespace</a> support.</p><div class="sect2" title="Introduction to SAX"><div class="titlepage"><div><div><h3 class="title"><a name="xml-sax"></a>Introduction to SAX</h3></div></div></div><p>A SAX-based parser works by emitting a sequence of
6 <em class="firstterm">events</em> to reflect the tokens being parsed
7 from the XML document. For example, parsing the following document
8 fragment:
9
10 </p><pre class="programlisting">
11 &lt;hello&gt;world&lt;/hello&gt;
12 </pre><p>
13
14 results in the following events:
15
16 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><span class="emphasis"><em>start-element</em></span> "hello"</li><li class="listitem"><span class="emphasis"><em>character-data</em></span> "world"</li><li class="listitem"><span class="emphasis"><em>end-element</em></span> "hello"</li></ol></div><p>
17
18 This example demonstrates the three event types used used in the
19 subset of SAX exposed by the neon XML interface: <span class="emphasis"><em>start-element</em></span>,
20 <span class="emphasis"><em>character-data</em></span> and <span class="emphasis"><em>end-element</em></span>. In a C API, an <span class="quote">“<span class="quote">event</span>”</span> is
21 implemented as a function callback; three callback types are used in
22 neon, one for each type of event.</p></div><div class="sect2" title="Stacked SAX handlers"><div class="titlepage"><div><div><h3 class="title"><a name="xml-stacked"></a>Stacked SAX handlers</h3></div></div></div><p>WebDAV property values are represented as fragments of XML,
23 transmitted as parts of larger XML documents over HTTP (notably in
24 the body of the response to a <code class="literal">PROPFIND</code> request).
25 When neon parses such documents, the SAX events generated for
26 these property value fragments may need to be handled by the
27 application, since neon has no knowledge of the structure of
28 properties used by the application.</p><p>To solve this problem<sup>[<a name="foot.xml.sax" href="#ftn.foot.xml.sax" class="footnote">1</a>]</sup> the neon XML interface introduces
29 the concept of a <em class="firstterm">SAX handler</em>. A SAX handler
30 comprises a <span class="emphasis"><em>start-element</em></span>, <span class="emphasis"><em>character-data</em></span> and <span class="emphasis"><em>end-element</em></span> callback; the
31 <span class="emphasis"><em>start-element</em></span> callback being defined such that each handler may
32 <span class="emphasis"><em>accept</em></span> or <span class="emphasis"><em>decline</em></span> the
33 <span class="emphasis"><em>start-element</em></span> event. Handlers are composed into a <em class="firstterm">handler
34 stack</em> before parsing a document. When a new <span class="emphasis"><em>start-element</em></span>
35 event is generated by the XML parser, neon invokes each <span class="emphasis"><em>start-element</em></span>
36 callback in the handler stack in turn until one accepts the event.
37 The handler which accepts the event will then be subsequently be
38 passed <span class="emphasis"><em>character-data</em></span> events if the element contains character data,
39 followed by an <span class="emphasis"><em>end-element</em></span> event when the element is closed. If no
40 handler in the stack accepts a <span class="emphasis"><em>start-element</em></span> event, the branch of the
41 tree is ignored.</p><p>To illustrate, given a handler A, which accepts the
42 <code class="literal">cat</code> and <code class="literal">age</code> elements, and a
43 handler B, which accepts the <code class="literal">name</code> element, the
44 following document:
45
46 </p><div class="example"><a name="xml-example"></a><p class="title"><b>Example 2.1. An example XML document</b></p><div class="example-contents"><pre class="programlisting">
47 &lt;cat&gt;
48 &lt;age&gt;3&lt;/age&gt;
49 &lt;name&gt;Bob&lt;/name&gt;
50 &lt;/cat&gt;
51 </pre></div></div><p><br class="example-break">
52
53 would be parsed as follows:
54
55 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">A <span class="emphasis"><em>start-element</em></span> "cat" → <span class="emphasis"><em>accept</em></span></li><li class="listitem">A <span class="emphasis"><em>start-element</em></span> "age" → <span class="emphasis"><em>accept</em></span></li><li class="listitem">A <span class="emphasis"><em>character-data</em></span> "3"</li><li class="listitem">A <span class="emphasis"><em>end-element</em></span> "age"</li><li class="listitem">A <span class="emphasis"><em>start-element</em></span> "name" → <span class="emphasis"><em>decline</em></span></li><li class="listitem">B <span class="emphasis"><em>start-element</em></span> "name" → <span class="emphasis"><em>accept</em></span></li><li class="listitem">B <span class="emphasis"><em>character-data</em></span> "Bob"</li><li class="listitem">B <span class="emphasis"><em>end-element</em></span> "name"</li><li class="listitem">A <span class="emphasis"><em>end-element</em></span> "cat"</li></ol></div><p>The search for a handler which will accept a <span class="emphasis"><em>start-element</em></span> event
56 begins at the handler of the parent element and continues toward the
57 top of the stack. For the root element, it begins at the base of
58 the stack. In the above example, handler A is at the base, and
59 handler B at the top; if the <code class="literal">name</code> element had any
60 children, only B's <span class="emphasis"><em>start-element</em></span> would be invoked to accept
61 them.</p></div><div class="sect2" title="Maintaining state"><div class="titlepage"><div><div><h3 class="title"><a name="xml-state"></a>Maintaining state</h3></div></div></div><p>To facilitate communication between independent handlers, a
62 <em class="firstterm">state integer</em> is associated with each element
63 being parsed. This integer is returned by <span class="emphasis"><em>start-element</em></span> callback and
64 is passed to the subsequent <span class="emphasis"><em>character-data</em></span> and <span class="emphasis"><em>end-element</em></span> callbacks
65 associated with the element. The state integer of the parent
66 element is also passed to each <span class="emphasis"><em>start-element</em></span> callback, the value zero
67 used for the root element (which by definition has no
68 parent).</p><p>To further extend <a class="xref" href="xml.html#xml-example" title="Example 2.1. An example XML document">Example 2.1, “An example XML document”</a>: if handler A
69 defines that the state of the root element <code class="sgmltag-element">cat</code>
70 will be <code class="literal">42</code>, the event trace would be as
71 follows:
72
73 </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem">A <span class="emphasis"><em>start-element</em></span> (parent = 0, "cat") →
74 <span class="emphasis"><em>accept</em></span>, state = 42
75 </li><li class="listitem">A <span class="emphasis"><em>start-element</em></span> (parent = 42, "age") →
76 <span class="emphasis"><em>accept</em></span>, state = 50
77 </li><li class="listitem">A <span class="emphasis"><em>character-data</em></span> (state = 50, "3")</li><li class="listitem">A <span class="emphasis"><em>end-element</em></span> (state = 50, "age")</li><li class="listitem">A <span class="emphasis"><em>start-element</em></span> (parent = 42, "name") →
78 <span class="emphasis"><em>decline</em></span></li><li class="listitem">B <span class="emphasis"><em>start-element</em></span> (parent = 42, "name") →
79 <span class="emphasis"><em>accept</em></span>, state = 99</li><li class="listitem">B <span class="emphasis"><em>character-data</em></span> (state = 99, "Bob")</li><li class="listitem">B <span class="emphasis"><em>end-element</em></span> (state = 99, "name")</li><li class="listitem">A <span class="emphasis"><em>end-element</em></span> (state = 42, "cat")</li></ol></div><p>To avoid collisions between state integers used by different
80 handlers, the interface definition of any handler includes the range
81 of integers it will use.</p></div><div class="sect2" title="XML namespaces"><div class="titlepage"><div><div><h3 class="title"><a name="xml-ns"></a>XML namespaces</h3></div></div></div><p>To support XML namespaces, every element name is represented
82 as a <span class="emphasis"><em>(namespace, name)</em></span> pair. The <span class="emphasis"><em>start-element</em></span>
83 and <span class="emphasis"><em>end-element</em></span> callbacks are passed namespace and name strings
84 accordingly. If an element in the XML document has no declared
85 namespace, the namespace given will be the empty string,
86 <code class="literal">""</code>.</p></div><div class="footnotes"><br><hr width="100" align="left"><div class="footnote"><p><sup>[<a id="ftn.foot.xml.sax" href="#foot.xml.sax" class="para">1</a>] </sup>This
87 <span class="quote">“<span class="quote">problem</span>”</span> only needs solving because the SAX interface
88 is so inflexible when implemented as C function callbacks; a better
89 approach would be to use an XML parser interface which is not based
90 on callbacks.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="api.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 2. The neon C language interface </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> neon API reference</td></tr></table></div></body></html>