Commit | Line | Data |
---|---|---|
fd79ecee DJ |
1 | /* Helper routines for parsing XML using Expat. |
2 | ||
61baf725 | 3 | Copyright (C) 2006-2017 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 | |
a9762ec7 | 9 | the Free Software Foundation; either version 3 of the License, or |
fd79ecee DJ |
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 | |
a9762ec7 | 18 | along with this program. If not, see <http://www.gnu.org/licenses/>. */ |
fd79ecee DJ |
19 | |
20 | ||
21 | #ifndef XML_SUPPORT_H | |
22 | #define XML_SUPPORT_H | |
23 | ||
e776119f DJ |
24 | #include "gdb_obstack.h" |
25 | #include "vec.h" | |
d26e3629 | 26 | #include "xml-utils.h" |
fd79ecee | 27 | |
e776119f DJ |
28 | struct gdb_xml_parser; |
29 | struct gdb_xml_element; | |
30 | struct gdb_xml_attribute; | |
fd79ecee | 31 | |
108546a0 DJ |
32 | /* Return an XML document which was compiled into GDB, from |
33 | the given FILENAME, or NULL if the file was not compiled in. */ | |
34 | ||
35 | const char *fetch_xml_builtin (const char *filename); | |
36 | ||
05a4558a DJ |
37 | /* A to_xfer_partial helper function which reads XML files which were |
38 | compiled into GDB. The target may call this function from its own | |
39 | to_xfer_partial handler, after converting object and annex to the | |
40 | appropriate filename. */ | |
41 | ||
42 | LONGEST xml_builtin_xfer_partial (const char *filename, | |
43 | gdb_byte *readbuf, const gdb_byte *writebuf, | |
44 | ULONGEST offset, LONGEST len); | |
45 | ||
108546a0 DJ |
46 | /* The text of compiled-in XML documents, from xml-builtin.c |
47 | (generated). */ | |
de584861 | 48 | |
108546a0 DJ |
49 | extern const char *xml_builtin[][2]; |
50 | ||
de584861 PA |
51 | /* Support for XInclude. */ |
52 | ||
53 | /* Callback to fetch a new XML file, based on the provided HREF. */ | |
54 | ||
55 | typedef char *(*xml_fetch_another) (const char *href, void *baton); | |
56 | ||
bd8a901f PA |
57 | /* Append the expansion of TEXT after processing <xi:include> tags in |
58 | RESULT. FETCHER will be called (with FETCHER_BATON) to retrieve | |
59 | any new files. DEPTH should be zero on the initial call. | |
de584861 | 60 | |
bd8a901f | 61 | On failure, this function uses NAME in a warning and returns false. |
de584861 PA |
62 | It may throw an exception, but does not for XML parsing |
63 | problems. */ | |
64 | ||
bd8a901f PA |
65 | bool xml_process_xincludes (std::string &result, |
66 | const char *name, const char *text, | |
67 | xml_fetch_another fetcher, void *fetcher_baton, | |
68 | int depth); | |
de584861 | 69 | |
108546a0 DJ |
70 | /* Simplified XML parser infrastructure. */ |
71 | ||
e776119f | 72 | /* A name and value pair, used to record parsed attributes. */ |
fd79ecee | 73 | |
e776119f DJ |
74 | struct gdb_xml_value |
75 | { | |
76 | const char *name; | |
77 | void *value; | |
78 | }; | |
79 | typedef struct gdb_xml_value gdb_xml_value_s; | |
80 | DEF_VEC_O(gdb_xml_value_s); | |
fd79ecee | 81 | |
e776119f | 82 | /* The type of an attribute handler. |
fd79ecee | 83 | |
e776119f DJ |
84 | PARSER is the current XML parser, which should be used to issue any |
85 | debugging or error messages. The second argument is the | |
86 | corresponding attribute description, so that a single handler can | |
87 | be used for multiple attributes; the attribute name is available | |
88 | for error messages and the handler data is available for additional | |
89 | customization (see gdb_xml_parse_attr_enum). VALUE is the string | |
90 | value of the attribute. | |
91 | ||
92 | The returned value should be freeable with xfree, and will be freed | |
93 | after the start handler is called. Errors should be reported by | |
94 | calling gdb_xml_error. */ | |
95 | ||
96 | typedef void *(gdb_xml_attribute_handler) (struct gdb_xml_parser *parser, | |
97 | const struct gdb_xml_attribute *, | |
98 | const char *value); | |
99 | ||
100 | /* Flags for attributes. If no flags are specified, the attribute is | |
101 | required. */ | |
102 | ||
103 | enum gdb_xml_attribute_flag | |
104 | { | |
105 | GDB_XML_AF_NONE, | |
106 | GDB_XML_AF_OPTIONAL = 1 << 0, /* The attribute is optional. */ | |
107 | }; | |
108 | ||
109 | /* An expected attribute and the handler to call when it is | |
110 | encountered. Arrays of struct gdb_xml_attribute are terminated | |
111 | by an entry with NAME == NULL. */ | |
112 | ||
113 | struct gdb_xml_attribute | |
114 | { | |
115 | const char *name; | |
116 | int flags; | |
117 | gdb_xml_attribute_handler *handler; | |
118 | const void *handler_data; | |
119 | }; | |
120 | ||
121 | /* Flags for elements. If no flags are specified, the element is | |
122 | required exactly once. */ | |
123 | ||
124 | enum gdb_xml_element_flag | |
125 | { | |
126 | GDB_XML_EF_NONE, | |
127 | GDB_XML_EF_OPTIONAL = 1 << 0, /* The element is optional. */ | |
128 | GDB_XML_EF_REPEATABLE = 1 << 1, /* The element is repeatable. */ | |
129 | }; | |
130 | ||
131 | /* A handler called at the beginning of an element. | |
132 | ||
133 | PARSER is the current XML parser, which should be used to issue any | |
134 | debugging or error messages. ELEMENT is the current element. | |
135 | USER_DATA is the opaque pointer supplied when the parser was | |
136 | created. ATTRIBUTES is a vector of the values of any attributes | |
137 | attached to this element. | |
138 | ||
139 | The start handler will only be called if all the required | |
140 | attributes were present and parsed successfully, and elements of | |
141 | ATTRIBUTES are guaranteed to be in the same order used in | |
142 | ELEMENT->ATTRIBUTES (not the order from the XML file). Accordingly | |
143 | fixed offsets can be used to find any non-optional attributes as | |
144 | long as no optional attributes precede them. */ | |
145 | ||
146 | typedef void (gdb_xml_element_start_handler) | |
147 | (struct gdb_xml_parser *parser, const struct gdb_xml_element *element, | |
148 | void *user_data, VEC(gdb_xml_value_s) *attributes); | |
149 | ||
150 | /* A handler called at the end of an element. | |
151 | ||
152 | PARSER, ELEMENT, and USER_DATA are as for the start handler. BODY | |
153 | is any accumulated body text inside the element, with leading and | |
154 | trailing whitespace removed. It will never be NULL. */ | |
155 | ||
156 | typedef void (gdb_xml_element_end_handler) | |
157 | (struct gdb_xml_parser *, const struct gdb_xml_element *, | |
158 | void *user_data, const char *body_text); | |
159 | ||
160 | /* An expected element and the handlers to call when it is | |
161 | encountered. Arrays of struct gdb_xml_element are terminated | |
162 | by an entry with NAME == NULL. */ | |
163 | ||
164 | struct gdb_xml_element | |
165 | { | |
166 | const char *name; | |
167 | const struct gdb_xml_attribute *attributes; | |
168 | const struct gdb_xml_element *children; | |
169 | int flags; | |
170 | ||
171 | gdb_xml_element_start_handler *start_handler; | |
172 | gdb_xml_element_end_handler *end_handler; | |
173 | }; | |
174 | ||
efc0eabd PA |
175 | /* Parse a XML document. DOCUMENT is the data to parse, which should |
176 | be NUL-terminated. If non-NULL, use the compiled-in DTD named | |
177 | DTD_NAME to drive the parsing. | |
178 | ||
179 | The return value is 0 for success or -1 for error. It may throw, | |
180 | but only if something unexpected goes wrong during parsing; parse | |
181 | errors will be caught, warned about, and reported as failure. */ | |
182 | ||
183 | int gdb_xml_parse_quick (const char *name, const char *dtd_name, | |
184 | const struct gdb_xml_element *elements, | |
185 | const char *document, void *user_data); | |
186 | ||
e776119f DJ |
187 | /* Issue a debugging message from one of PARSER's handlers. */ |
188 | ||
189 | void gdb_xml_debug (struct gdb_xml_parser *parser, const char *format, ...) | |
21047726 | 190 | ATTRIBUTE_PRINTF (2, 3); |
e776119f DJ |
191 | |
192 | /* Issue an error message from one of PARSER's handlers, and stop | |
193 | parsing. */ | |
194 | ||
195 | void gdb_xml_error (struct gdb_xml_parser *parser, const char *format, ...) | |
21047726 | 196 | ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3); |
e776119f | 197 | |
3d2c1d41 PA |
198 | /* Find the attribute named NAME in the set of parsed attributes |
199 | ATTRIBUTES. Returns NULL if not found. */ | |
200 | ||
201 | struct gdb_xml_value *xml_find_attribute (VEC(gdb_xml_value_s) *attributes, | |
202 | const char *name); | |
203 | ||
e776119f DJ |
204 | /* Parse an integer attribute into a ULONGEST. */ |
205 | ||
206 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_ulongest; | |
207 | ||
208 | /* Map NAME to VALUE. A struct gdb_xml_enum * should be saved as the | |
209 | value of handler_data when using gdb_xml_parse_attr_enum to parse a | |
210 | fixed list of possible strings. The list is terminated by an entry | |
211 | with NAME == NULL. */ | |
212 | ||
213 | struct gdb_xml_enum | |
214 | { | |
215 | const char *name; | |
216 | ULONGEST value; | |
217 | }; | |
218 | ||
123dc839 DJ |
219 | /* A handler_data for yes/no boolean values. */ |
220 | extern const struct gdb_xml_enum gdb_xml_enums_boolean[]; | |
221 | ||
e776119f DJ |
222 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_enum; |
223 | ||
224 | /* Parse an integer string into a ULONGEST and return it, or call | |
225 | gdb_xml_error if it could not be parsed. */ | |
226 | ||
227 | ULONGEST gdb_xml_parse_ulongest (struct gdb_xml_parser *parser, | |
228 | const char *value); | |
fd79ecee | 229 | |
a96d9b2e SDJ |
230 | /* Open FILENAME, read all its text into memory, close it, and return |
231 | the text. If something goes wrong, return NULL and warn. */ | |
232 | ||
233 | extern char *xml_fetch_content_from_file (const char *filename, | |
234 | void *baton); | |
235 | ||
fd79ecee | 236 | #endif |