Commit | Line | Data |
---|---|---|
fd79ecee DJ |
1 | /* Helper routines for parsing XML using Expat. |
2 | ||
6aba47ca | 3 | Copyright (C) 2006, 2007 Free Software Foundation, Inc. |
fd79ecee DJ |
4 | |
5 | This file is part of GDB. | |
6 | ||
7 | This program is free software; you can redistribute it and/or modify | |
8 | it under the terms of the GNU General Public License as published by | |
9 | the Free Software Foundation; either version 2 of the License, or | |
10 | (at your option) any later version. | |
11 | ||
12 | This program is distributed in the hope that it will be useful, | |
13 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
14 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
15 | GNU General Public License for more details. | |
16 | ||
17 | You should have received a copy of the GNU General Public License | |
18 | along with this program; if not, write to the Free Software | |
19 | Foundation, Inc., 51 Franklin Street, Fifth Floor, | |
20 | Boston, MA 02110-1301, USA. */ | |
21 | ||
22 | ||
23 | #ifndef XML_SUPPORT_H | |
24 | #define XML_SUPPORT_H | |
25 | ||
e776119f DJ |
26 | #include "gdb_obstack.h" |
27 | #include "vec.h" | |
fd79ecee | 28 | |
e776119f DJ |
29 | struct gdb_xml_parser; |
30 | struct gdb_xml_element; | |
31 | struct gdb_xml_attribute; | |
fd79ecee | 32 | |
108546a0 DJ |
33 | /* Support for XInclude. */ |
34 | ||
35 | /* Callback to fetch a new XML file, based on the provided HREF. */ | |
36 | ||
37 | typedef char *(*xml_fetch_another) (const char *href, void *baton); | |
38 | ||
39 | /* Return a new string which is the expansion of TEXT after processing | |
40 | <xi:include> tags. FETCHER will be called (with FETCHER_BATON) to | |
41 | retrieve any new files. DEPTH should be zero on the initial call. | |
42 | ||
43 | On failure, this function uses NAME in a warning and returns NULL. | |
44 | It may throw an exception, but does not for XML parsing | |
45 | problems. */ | |
46 | ||
47 | char *xml_process_xincludes (const char *name, const char *text, | |
48 | xml_fetch_another fetcher, void *fetcher_baton, | |
49 | int depth); | |
50 | ||
51 | /* Return an XML document which was compiled into GDB, from | |
52 | the given FILENAME, or NULL if the file was not compiled in. */ | |
53 | ||
54 | const char *fetch_xml_builtin (const char *filename); | |
55 | ||
56 | /* The text of compiled-in XML documents, from xml-builtin.c | |
57 | (generated). */ | |
58 | extern const char *xml_builtin[][2]; | |
59 | ||
60 | /* Simplified XML parser infrastructure. */ | |
61 | ||
e776119f | 62 | /* A name and value pair, used to record parsed attributes. */ |
fd79ecee | 63 | |
e776119f DJ |
64 | struct gdb_xml_value |
65 | { | |
66 | const char *name; | |
67 | void *value; | |
68 | }; | |
69 | typedef struct gdb_xml_value gdb_xml_value_s; | |
70 | DEF_VEC_O(gdb_xml_value_s); | |
fd79ecee | 71 | |
e776119f | 72 | /* The type of an attribute handler. |
fd79ecee | 73 | |
e776119f DJ |
74 | PARSER is the current XML parser, which should be used to issue any |
75 | debugging or error messages. The second argument is the | |
76 | corresponding attribute description, so that a single handler can | |
77 | be used for multiple attributes; the attribute name is available | |
78 | for error messages and the handler data is available for additional | |
79 | customization (see gdb_xml_parse_attr_enum). VALUE is the string | |
80 | value of the attribute. | |
81 | ||
82 | The returned value should be freeable with xfree, and will be freed | |
83 | after the start handler is called. Errors should be reported by | |
84 | calling gdb_xml_error. */ | |
85 | ||
86 | typedef void *(gdb_xml_attribute_handler) (struct gdb_xml_parser *parser, | |
87 | const struct gdb_xml_attribute *, | |
88 | const char *value); | |
89 | ||
90 | /* Flags for attributes. If no flags are specified, the attribute is | |
91 | required. */ | |
92 | ||
93 | enum gdb_xml_attribute_flag | |
94 | { | |
95 | GDB_XML_AF_NONE, | |
96 | GDB_XML_AF_OPTIONAL = 1 << 0, /* The attribute is optional. */ | |
97 | }; | |
98 | ||
99 | /* An expected attribute and the handler to call when it is | |
100 | encountered. Arrays of struct gdb_xml_attribute are terminated | |
101 | by an entry with NAME == NULL. */ | |
102 | ||
103 | struct gdb_xml_attribute | |
104 | { | |
105 | const char *name; | |
106 | int flags; | |
107 | gdb_xml_attribute_handler *handler; | |
108 | const void *handler_data; | |
109 | }; | |
110 | ||
111 | /* Flags for elements. If no flags are specified, the element is | |
112 | required exactly once. */ | |
113 | ||
114 | enum gdb_xml_element_flag | |
115 | { | |
116 | GDB_XML_EF_NONE, | |
117 | GDB_XML_EF_OPTIONAL = 1 << 0, /* The element is optional. */ | |
118 | GDB_XML_EF_REPEATABLE = 1 << 1, /* The element is repeatable. */ | |
119 | }; | |
120 | ||
121 | /* A handler called at the beginning of an element. | |
122 | ||
123 | PARSER is the current XML parser, which should be used to issue any | |
124 | debugging or error messages. ELEMENT is the current element. | |
125 | USER_DATA is the opaque pointer supplied when the parser was | |
126 | created. ATTRIBUTES is a vector of the values of any attributes | |
127 | attached to this element. | |
128 | ||
129 | The start handler will only be called if all the required | |
130 | attributes were present and parsed successfully, and elements of | |
131 | ATTRIBUTES are guaranteed to be in the same order used in | |
132 | ELEMENT->ATTRIBUTES (not the order from the XML file). Accordingly | |
133 | fixed offsets can be used to find any non-optional attributes as | |
134 | long as no optional attributes precede them. */ | |
135 | ||
136 | typedef void (gdb_xml_element_start_handler) | |
137 | (struct gdb_xml_parser *parser, const struct gdb_xml_element *element, | |
138 | void *user_data, VEC(gdb_xml_value_s) *attributes); | |
139 | ||
140 | /* A handler called at the end of an element. | |
141 | ||
142 | PARSER, ELEMENT, and USER_DATA are as for the start handler. BODY | |
143 | is any accumulated body text inside the element, with leading and | |
144 | trailing whitespace removed. It will never be NULL. */ | |
145 | ||
146 | typedef void (gdb_xml_element_end_handler) | |
147 | (struct gdb_xml_parser *, const struct gdb_xml_element *, | |
148 | void *user_data, const char *body_text); | |
149 | ||
150 | /* An expected element and the handlers to call when it is | |
151 | encountered. Arrays of struct gdb_xml_element are terminated | |
152 | by an entry with NAME == NULL. */ | |
153 | ||
154 | struct gdb_xml_element | |
155 | { | |
156 | const char *name; | |
157 | const struct gdb_xml_attribute *attributes; | |
158 | const struct gdb_xml_element *children; | |
159 | int flags; | |
160 | ||
161 | gdb_xml_element_start_handler *start_handler; | |
162 | gdb_xml_element_end_handler *end_handler; | |
163 | }; | |
164 | ||
165 | /* Initialize and return a parser. Register a cleanup to destroy the | |
166 | parser. */ | |
167 | ||
168 | struct gdb_xml_parser *gdb_xml_create_parser_and_cleanup | |
169 | (const char *name, const struct gdb_xml_element *elements, | |
170 | void *user_data); | |
171 | ||
108546a0 DJ |
172 | /* Associate DTD_NAME, which must be the name of a compiled-in DTD, |
173 | with PARSER. */ | |
174 | ||
175 | void gdb_xml_use_dtd (struct gdb_xml_parser *parser, const char *dtd_name); | |
176 | ||
e776119f DJ |
177 | /* Invoke PARSER on BUFFER. BUFFER is the data to parse, which |
178 | should be NUL-terminated. | |
179 | ||
180 | The return value is 0 for success or -1 for error. It may throw, | |
181 | but only if something unexpected goes wrong during parsing; parse | |
182 | errors will be caught, warned about, and reported as failure. */ | |
183 | ||
184 | int gdb_xml_parse (struct gdb_xml_parser *parser, const char *buffer); | |
185 | ||
186 | /* Issue a debugging message from one of PARSER's handlers. */ | |
187 | ||
188 | void gdb_xml_debug (struct gdb_xml_parser *parser, const char *format, ...) | |
189 | ATTR_FORMAT (printf, 2, 0); | |
190 | ||
191 | /* Issue an error message from one of PARSER's handlers, and stop | |
192 | parsing. */ | |
193 | ||
194 | void gdb_xml_error (struct gdb_xml_parser *parser, const char *format, ...) | |
195 | ATTR_NORETURN ATTR_FORMAT (printf, 2, 0); | |
196 | ||
197 | /* Parse an integer attribute into a ULONGEST. */ | |
198 | ||
199 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_ulongest; | |
200 | ||
201 | /* Map NAME to VALUE. A struct gdb_xml_enum * should be saved as the | |
202 | value of handler_data when using gdb_xml_parse_attr_enum to parse a | |
203 | fixed list of possible strings. The list is terminated by an entry | |
204 | with NAME == NULL. */ | |
205 | ||
206 | struct gdb_xml_enum | |
207 | { | |
208 | const char *name; | |
209 | ULONGEST value; | |
210 | }; | |
211 | ||
212 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_enum; | |
213 | ||
214 | /* Parse an integer string into a ULONGEST and return it, or call | |
215 | gdb_xml_error if it could not be parsed. */ | |
216 | ||
217 | ULONGEST gdb_xml_parse_ulongest (struct gdb_xml_parser *parser, | |
218 | const char *value); | |
fd79ecee DJ |
219 | |
220 | #endif |