2 * UCW Library -- A simple XML parser
4 * (c) 2007--2008 Pavel Charvat <pchar@ucw.cz>
5 * (c) 2015 Martin Mares <mj@ucw.cz>
7 * This software may be freely distributed and used according to the terms
8 * of the GNU Lesser General Public License.
11 #ifndef _UCW_XML_XML_H
12 #define _UCW_XML_XML_H
14 #include <ucw/clists.h>
15 #include <ucw/slists.h>
16 #include <ucw/mempool.h>
17 #include <ucw/fastbuf.h>
19 #ifdef CONFIG_UCW_CLEAN_ABI
20 #define xml_attr_find ucw_xml_attr_find
21 #define xml_attr_value ucw_xml_attr_value
22 #define xml_cleanup ucw_xml_cleanup
23 #define xml_def_find_entity ucw_xml_def_find_entity
24 #define xml_def_resolve_entity ucw_xml_def_resolve_entity
25 #define xml_error ucw_xml_error
26 #define xml_fatal ucw_xml_fatal
27 #define xml_init ucw_xml_init
28 #define xml_merge_chars ucw_xml_merge_chars
29 #define xml_merge_dom_chars ucw_xml_merge_dom_chars
30 #define xml_next ucw_xml_next
31 #define xml_next_state ucw_xml_next_state
32 #define xml_normalize_white ucw_xml_normalize_white
33 #define xml_parse ucw_xml_parse
34 #define xml_push_fastbuf ucw_xml_push_fastbuf
35 #define xml_reset ucw_xml_reset
36 #define xml_row ucw_xml_row
37 #define xml_skip_element ucw_xml_skip_element
38 #define xml_warn ucw_xml_warn
42 struct xml_dtd_entity;
46 XML_ERR_WARN = 1000, /* Warning */
47 XML_ERR_ERROR = 2000, /* Recoverable error */
48 XML_ERR_FATAL = 3000, /* Unrecoverable error */
53 XML_STATE_EOF, /* EOF or a fatal error */
54 XML_STATE_START, /* Initial state */
55 XML_STATE_XML_DECL, /* XML_PULL_XML_DECL */
56 XML_STATE_DOCTYPE_DECL, /* XML_PULL_DOCTYPE_DECL */
57 XML_STATE_CHARS, /* XML_PULL_CHARS */
58 XML_STATE_STAG, /* XML_PULL_STAG */
59 XML_STATE_ETAG, /* XML_PULL_ETAG */
60 XML_STATE_COMMENT, /* XML_PULL_COMMENT */
61 XML_STATE_PI, /* XML_PULL_PI */
64 XML_STATE_CHARS_BEFORE_STAG,
65 XML_STATE_CHARS_BEFORE_ETAG,
66 XML_STATE_CHARS_BEFORE_CDATA,
67 XML_STATE_CHARS_BEFORE_COMMENT,
68 XML_STATE_CHARS_BEFORE_PI,
69 XML_STATE_PROLOG_COMMENT,
71 XML_STATE_EPILOG_COMMENT,
76 XML_PULL_XML_DECL = 0x00000001, /* Stop after the XML declaration */
77 XML_PULL_DOCTYPE_DECL = 0x00000002, /* Stop in the doctype declaration (before optional internal subset) */
78 XML_PULL_CHARS = 0x00000004,
79 XML_PULL_STAG = 0x00000008,
80 XML_PULL_ETAG = 0x00000010,
81 XML_PULL_COMMENT = 0x00000020,
82 XML_PULL_PI = 0x00000040,
83 XML_PULL_ALL = 0xffffffff,
87 /* Enable reporting of various events via SAX and/or PULL interface */
88 XML_REPORT_COMMENTS = 0x00000001, /* Report comments */
89 XML_REPORT_PIS = 0x00000002, /* Report processing instructions */
90 XML_REPORT_CHARS = 0x00000004, /* Report characters */
91 XML_REPORT_TAGS = 0x00000008, /* Report element starts/ends */
92 XML_REPORT_MISC = XML_REPORT_COMMENTS | XML_REPORT_PIS,
93 XML_REPORT_ALL = XML_REPORT_MISC | XML_REPORT_CHARS | XML_REPORT_TAGS,
95 /* Enable construction of DOM for these types */
96 XML_ALLOC_COMMENTS = 0x00000010, /* Create comment nodes */
97 XML_ALLOC_PIS = 0x00000020, /* Create processing instruction nodes */
98 XML_ALLOC_CHARS = 0x00000040, /* Create character nodes */
99 XML_ALLOC_TAGS = 0x00000080, /* Create element nodes */
100 XML_ALLOC_MISC = XML_ALLOC_COMMENTS | XML_ALLOC_PIS,
101 XML_ALLOC_ALL = XML_ALLOC_MISC | XML_ALLOC_CHARS | XML_ALLOC_TAGS,
103 /* Other parameters */
104 XML_VALIDATING = 0x00000100, /* Validate everything (not fully implemented!) */
105 XML_PARSE_DTD = 0x00000200, /* Enable parsing of DTD */
106 XML_NO_CHARS = 0x00000400, /* The current element must not contain character data (filled automaticaly if using DTD) */
107 XML_ALLOC_DEFAULT_ATTRS = 0x00000800, /* Allocate default attribute values so they can be found by XML_ATTR_FOR_EACH */
108 XML_NAMESPACES = 0x00001000, /* Parse namespaces, use xml_ns_enable() to set this */
110 /* Internals, do not change! */
111 XML_EMPTY_ELEM_TAG = 0x00010000, /* The current element match EmptyElemTag */
112 XML_VERSION_1_1 = 0x00020000, /* XML version is 1.1, otherwise 1.0 */
113 XML_HAS_EXTERNAL_SUBSET = 0x00040000, /* The document contains a reference to external DTD subset */
114 XML_HAS_INTERNAL_SUBSET = 0x00080000, /* The document contains an internal subset */
115 XML_HAS_DTD = XML_HAS_EXTERNAL_SUBSET | XML_HAS_INTERNAL_SUBSET,
116 XML_SRC_EOF = 0x00100000, /* EOF reached */
117 XML_SRC_EXPECTED_DECL = 0x00200000, /* Just before optional or required XMLDecl/TextDecl */
118 XML_SRC_DOCUMENT = 0x00400000, /* The document entity */
119 XML_SRC_EXTERNAL = 0x00800000, /* An external entity */
129 #define XML_NODE_FOR_EACH(var, node) CLIST_FOR_EACH(struct xml_node *, var, (node)->sons)
130 #define XML_ATTR_FOR_EACH(var, node) SLIST_FOR_EACH(struct xml_attr *, var, (node)->attrs)
133 cnode n; /* Node for list of parent's sons */
134 uint type; /* XML_NODE_x */
135 struct xml_node *parent; /* Parent node */
137 * If namespaces are enabled, node->name points to the local part of the name
138 * and node->ns is the resolved namespace ID.
140 * However, the namespace prefix is kept in memory just before the local part,
141 * so you can use xml_node_qname() to find out the full qualified name.
142 * The same applies to attributes, but the function is xml_attr_qname().
144 char *name; /* Element name / PI target */
145 clist sons; /* Children nodes */
148 char *text; /* PI text / Comment / CDATA */
149 uint len; /* Text length in bytes */
152 uint ns; /* Namespace ID */
153 struct xml_dtd_elem *dtd; /* Element DTD */
154 slist attrs; /* Link list of element attributes */
157 void *user; /* User-defined (initialized to NULL) */
161 snode n; /* Node for elem->attrs */
162 uint hash; /* Internal hash of ns + name */
163 struct xml_node *elem; /* Parent element */
164 struct xml_dtd_attr *dtd; /* Attribute DTD */
165 uint ns; /* Namespace ID */
166 char *name; /* Attribute name without NS prefix */
167 char *val; /* Attribute value */
168 void *user; /* User-defined (initialized to NULL) */
171 #define XML_BUF_SIZE 32 /* At least 8 -- hardcoded */
174 struct xml_source *next; /* Link list of pending fastbufs (xml_context.sources) */
175 struct fastbuf *fb; /* Source fastbuf */
176 struct fastbuf *wrapped_fb; /* Original wrapped fastbuf (needed for cleanup) */
177 struct fastbuf wrap_fb; /* Fbmem wrapper */
178 u32 buf[2 * XML_BUF_SIZE]; /* Read buffer with Unicode values and categories */
179 u32 *bptr, *bstop; /* Current state of the buffer */
180 uint row; /* File position */
181 char *expected_encoding; /* Initial encoding before any transformation has been made (expected in XMLDecl/TextDecl) */
182 char *fb_encoding; /* Encoding of the source fastbuf */
183 char *decl_encoding; /* Encoding read from the XMLDecl/TextDecl */
184 uint refill_cat1; /* Character categories, which should be directly passed to the buffer */
185 uint refill_cat2; /* Character categories, which should be processed as newlines (possibly in some built-in
187 void (*refill)(struct xml_context *ctx); /* Callback to decode source characters to the buffer */
188 unsigned short *refill_in_to_x; /* Libucw-charset input table */
189 uint saved_depth; /* Saved ctx->depth */
190 uint pending_0xd; /* The last read character is 0xD */
195 char *err_msg; /* Last error message */
196 enum xml_error err_code; /* Last error code */
197 void *throw_buf; /* Where to jump on error */
198 void (*h_warn)(struct xml_context *ctx); /* Warning callback */
199 void (*h_error)(struct xml_context *ctx); /* Recoverable error callback */
200 void (*h_fatal)(struct xml_context *ctx); /* Unrecoverable error callback */
202 /* Memory management */
203 struct mempool *pool; /* DOM pool */
204 struct mempool *stack; /* Stack pool (freed as soon as possible) */
205 struct xml_stack *stack_list; /* See xml_push(), xml_pop() */
206 uint flags; /* XML_FLAG_x (restored on xml_pop()) */
207 uint depth; /* Nesting level (for checking of valid source nesting -> valid pushes/pops on memory pools) */
208 struct fastbuf chars; /* Character data / attribute value */
209 struct mempool_state chars_state; /* Mempool state before the current character block has started */
210 char *chars_trivial; /* If not empty, it will be appended to chars */
213 struct xml_source *src; /* Current source */
214 u32 *bptr, *bstop; /* Buffer with preprocessed characters (validated UCS-4 + category flags) */
215 uint cat_chars; /* Unicode range of supported characters (cdata, attribute values, ...) */
216 uint cat_unrestricted; /* Unrestricted characters (may appear in document/external entities) */
217 uint cat_new_line; /* New line characters */
218 uint cat_name; /* Characters that may appear in names */
219 uint cat_sname; /* Characters that may begin a name */
221 /* SAX-like interface */
222 void (*h_document_start)(struct xml_context *ctx); /* Called before entering prolog */
223 void (*h_document_end)(struct xml_context *ctx); /* Called after leaving epilog */
224 void (*h_xml_decl)(struct xml_context *ctx); /* Called after the XML declaration */
225 void (*h_doctype_decl)(struct xml_context *ctx); /* Called in the doctype declaration (before optional internal subset) */
226 void (*h_comment)(struct xml_context *ctx); /* Called after a comment (only with XML_REPORT_COMMENTS) */
227 void (*h_pi)(struct xml_context *ctx); /* Called after a processing instruction (only with XML_REPORT_PIS) */
228 void (*h_stag)(struct xml_context *ctx); /* Called after STag or EmptyElemTag (only with XML_REPORT_TAGS) */
229 void (*h_etag)(struct xml_context *ctx); /* Called before ETag or after EmptyElemTag (only with XML_REPORT_TAGS) */
230 void (*h_chars)(struct xml_context *ctx); /* Called after some characters (only with XML_REPORT_CHARS) */
231 void (*h_block)(struct xml_context *ctx, char *text, uint len); /* Called for each continuous block of characters not reported by h_cdata() (only with XML_REPORT_CHARS) */
232 void (*h_cdata)(struct xml_context *ctx, char *text, uint len); /* Called for each CDATA section (only with XML_REPORT_CHARS) */
233 void (*h_ignorable)(struct xml_context *ctx, char *text, uint len); /* Called for ignorable whitespace (content in tags without #PCDATA) */
234 void (*h_dtd_start)(struct xml_context *ctx); /* Called just after the DTD structure is initialized */
235 void (*h_dtd_end)(struct xml_context *ctx); /* Called after DTD subsets subsets */
236 struct xml_dtd_entity *(*h_find_entity)(struct xml_context *ctx, char *name); /* Called when needed to resolve a general entity */
237 void (*h_resolve_entity)(struct xml_context *ctx, struct xml_dtd_entity *ent); /* User should push source fastbuf for a parsed external entity (either general or parameter) */
240 struct xml_node *dom; /* DOM root */
241 struct xml_node *node; /* Current DOM node */
244 struct mempool *ns_pool; /* Memory pool for NS definitions */
245 const char **ns_by_id; /* A growing array translating NS IDs to their names */
246 void *ns_by_name; /* Hash table translating NS names to their IDs */
247 void *ns_by_prefix; /* Hash table translating current prefixes to NS IDs, allocated from xml->stack */
248 struct xml_ns_prefix *ns_prefix_stack; /* A stack of prefix definitions, allocated from xml->stack */
249 uint ns_default; /* Current default namespace */
253 char *doctype; /* The document type (or NULL if unknown) */
254 char *system_id; /* DTD external id */
255 char *public_id; /* DTD public id */
256 struct xml_dtd *dtd; /* The DTD structure (or NULL) */
257 uint state; /* Current state for the PULL interface (XML_STATE_x) */
258 uint pull; /* Parameters for the PULL interface (XML_PULL_x) */
261 /* Initialize XML context */
262 void xml_init(struct xml_context *ctx);
264 /* Clean up all internal structures */
265 void xml_cleanup(struct xml_context *ctx);
267 /* Reuse XML context, equivalent to xml_cleanup() and xml_init() */
268 void xml_reset(struct xml_context *ctx);
270 /* Add XML source (fastbuf will be automatically closed) */
271 struct xml_source *xml_push_fastbuf(struct xml_context *ctx, struct fastbuf *fb);
273 /* Parse without the PULL interface, return XML_ERR_x code (zero on success) */
274 uint xml_parse(struct xml_context *ctx);
276 /* Parse with the PULL interface, return XML_STATE_x (zero on EOF or fatal error) */
277 uint xml_next(struct xml_context *ctx);
279 /* Equivalent to xml_next, but with temporarily changed ctx->pull value */
280 uint xml_next_state(struct xml_context *ctx, uint pull);
282 /* May be called on XML_STATE_STAG to skip it's content; can return XML_STATE_ETAG or XML_STATE_EOF on fatal error */
283 uint xml_skip_element(struct xml_context *ctx);
285 /* Returns the current row number in the document entity */
286 uint xml_row(struct xml_context *ctx);
288 /* Finds a qualified name (including namespace prefix) of a given element node. */
289 char *xml_node_qname(struct xml_context *ctx, struct xml_node *node);
291 /* Finds a qualified name (including namespace prefix) of a given attribute. */
292 char *xml_attr_qname(struct xml_context *ctx, struct xml_attr *node);
294 /* Finds a given attribute value in a XML_NODE_ELEM node */
295 struct xml_attr *xml_attr_find(struct xml_context *ctx, struct xml_node *node, char *name);
297 /* The same, but namespace-aware */
298 struct xml_attr *xml_attr_find_ns(struct xml_context *ctx, struct xml_node *node, uint ns, char *name);
300 /* Similar to xml_attr_find, but it deals also with default values */
301 char *xml_attr_value(struct xml_context *ctx, struct xml_node *node, char *name);
303 /* The same, but namespace-aware */
304 char *xml_attr_value_ns(struct xml_context *ctx, struct xml_node *node, uint ns, char *name);
306 /* The default value of h_find_entity(), knows <, >, &, ' and " */
307 struct xml_dtd_entity *xml_def_find_entity(struct xml_context *ctx, char *name);
309 /* The default value of h_resolve_entity(), throws an error */
310 void xml_def_resolve_entity(struct xml_context *ctx, struct xml_dtd_entity *ent);
312 /* Remove leading/trailing spaces and replaces sequences of spaces to a single space character (non-CDATA attribute normalization) */
313 uint xml_normalize_white(struct xml_context *ctx, char *value);
315 /* Merge character contents of a given element to a single string (not recursive) */
316 char *xml_merge_chars(struct xml_context *ctx, struct xml_node *node, struct mempool *pool);
318 /* Merge character contents of a given subtree to a single string */
319 char *xml_merge_dom_chars(struct xml_context *ctx, struct xml_node *node, struct mempool *pool);
321 /* Public part of error handling */
322 void xml_warn(struct xml_context *ctx, const char *format, ...);
323 void xml_error(struct xml_context *ctx, const char *format, ...);
324 void NONRET xml_fatal(struct xml_context *ctx, const char *format, ...);
326 /* Request processing of namespaces */
327 void xml_ns_enable(struct xml_context *ctx);
329 /* Looks up namespace by its ID, dies on an invalid ID */
330 const char *xml_ns_by_id(struct xml_context *ctx, uint ns);
332 /* Looks up namespace by its name and returns its ID. Creates a new ID if necessary. */
333 uint xml_ns_by_name(struct xml_context *ctx, const char *name);
335 /* Well-known namespaces */
336 #define XML_NS_NONE 0 /* This element has no namespace */
337 #define XML_NS_XMLNS 1 /* xmlns: */
338 #define XML_NS_XML 2 /* xml: */