Debian Codegraph @

deps/libneon/doc/parsing-xml.txt

raw
1
2 Requirements for XML parsing in neon
3 ------------------------------------
4
5 Before describing the interface given in neon for parsing XML, here
6 are the requirements which it must satisfy:
7
8 1. to support using either libxml or expat as the underlying parser
9 2. to allow "independent" sections to handle parsing one XML
10 document
11 3. to map element namespaces/names to an integer for easier
12 comparison.
13
14 A description of requirement (2) is useful since it is the "hard"
15 requirement, and adds most of the complexity of interface: WebDAV
16 PROPFIND responses are made up of a large boilerplate XML
17
18 <multistatus><response><propstat><prop>...</prop></propstat> etc.
19
20 neon should handle the parsing of these standard elements, and expose
21 the meaning of the response using a convenient interface. But, within
22 the <prop> elements, there may also be fragments of XML: neon can
23 never know how to parse these, since they are property- and hence
24 application-specific. The simplest example of this is the
25 DAV:resourcetype property.
26
27 So there is requirement (2) that two "independent" sections of code
28 can handle the parsing of one XML document.
29
30 Callback-based XML parsing
31 --------------------------
32
33 There are two ways of parsing XML documents commonly used:
34
35 1. Build an in-memory tree of the document
36 2. Use callbacks
37
38 Where practical, using callbacks is more efficient than building a
39 tree, so this is what neon uses. The standard interface for
40 callback-based XML parsing is called SAX, so understanding the SAX
41 interface is useful to understanding the XML parsing interface
42 provided by neon.
43
44 The SAX interface works by registering callbacks which are called *as
45 the XML is parsed*. The most important callbacks are for 'start
46 element' and 'end element'. For instance, if the XML document below is
47 parsed by a SAX-like interface:
48
49 <hello>
50 <foobar></foobar>
51 </hello>
52
53 Say we have registered callbacks "startelm" for 'start element' and
54 "endelm" for 'end element'. Simplified somewhat, the callbacks will
55 be called in this order, with these arguments:
56
57 1. startelm("hello")
58 2. startelm("foobar")
59 3. endelm("foobar")
60 4. endelm("hello")
61
62 See the expat 'xmlparse.h' header for a more complete definition of a
63 SAX-like interface.
64
65 The hip_xml interface
66 ---------------------
67
68 The hip_xml interface satisfies requirement (2) by introducing the
69 "handler" concept. A handler is made up of these things:
70
71 - a set of XML elements
72 - a callback to validate an element
73 - a callback which is called when an element is opened
74 - a callback which is called when an element is closed
75 - (optionally, a callback which is called for CDATA)
76
77 Registering a handler essentially says:
78
79 "If you encounter any of this set of elements, I want these
80 callbacks to be called."
81
82 Handlers are kept in a STACK inside hip_xml. The first handler
83 registered becomes the BASE of the stack, subsequent handlers are
84 PUSHed on top.
85
86 During XML parsing, the handler which is used for an XML element is
87 recorded. When a new element is started, the search for a handler for
88 this element begins at the handler used for the parent element, and
89 carries on up the stack. For the root element, the search always
90 starts at the BASE of the stack.
91
92 A user's guide to hip_xml
93 -------------------------
94
95 The first thing to do when using hip_xml is to know what set of XML
96 elements you are going to be parsing. This can usually be done by
97 looking at the DTD provided for the documents you are going to be
98 parsing. The DTD is also very useful in writing the 'validate'
99 callback function, since it can tell you what parent/child pairs are
100 valid, and which aren't.
101
102 In this example, we'll parse XML documents which look like:
103
104 <T:list-of-things xmlns:T="http://things.org/">
105 <T:a-thing>foo</T:a-thing>
106 <T:a-thing>bar</T:a-thing>
107 </T:list-of-things>
108
109 So, given the set of elements, declare the element id's and the
110 element array:
111
112 #define ELM_listofthings (HIP_ELM_UNUSED)
113 #define ELM_a_thing (HIP_ELM_UNUSED + 1)
114
115 const static struct my_elms[] = {
116 { "http://things.org/", "list-of-things", ELM_listofthings, 0 },
117 { "http://things.org/", "a-thing", ELM_a_thing, HIP_XML_CDATA },
118 { NULL }
119 };
120
121 This declares we know about two elements: list-of-things, and a-thing,
122 and that the 'a-thing' element contains character data.
123
124 The definition of the validation callback is very simple:
125
126 static int validate(hip_xml_elmid parent, hip_xml_elmid child)
127 {
128 /* Only allow 'list-of-things' as the root element. */
129 if (parent == HIP_ELM_root && child == ELM_listofthings ||
130 parent = ELM_listofthings && child == ELM_a_thing) {
131 return HIP_XML_VALID;
132 } else {
133 return HIP_XML_INVALID;
134 }
135 }
136
137 For this example, we can ignore the start-element callback, and just
138 use the end-element callback:
139
140 static int endelm(void *userdata, const struct hip_xml_elm *s,
141 const char *cdata)
142 {
143 printf("Got a thing: %s\n", cdata);
144 return 0;
145 }
146
147 This endelm callback just prints the cdata which was contained in the
148 "a-thing" element.
149
150 Now, on to parsing. A new parser object is created for parsing each
151 XML document. Creating a new parser object is as simple as:
152
153 hip_xml_parser *parser;
154
155 parser = hip_xml_create();
156
157 Next register the handler, passing NULL as the start-element callback,
158 and also as userdata, which we don't use here.
159
160 hip_xml_push_handler(parser, my_elms,
161 validate, NULL, endelm,
162 NULL);
163
164 Finally, call hip_xml_parse, passing the chunks of XML document to the
165 hip_xml as you get them. The output should be:
166
167 Got a thing: foo
168 Got a thing: bar
169
170 for the XML document.