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 | ||
b7b030ad TT |
55 | typedef gdb::unique_xmalloc_ptr<char> (*xml_fetch_another) (const char *href, |
56 | void *baton); | |
de584861 | 57 | |
bd8a901f PA |
58 | /* Append the expansion of TEXT after processing <xi:include> tags in |
59 | RESULT. FETCHER will be called (with FETCHER_BATON) to retrieve | |
60 | any new files. DEPTH should be zero on the initial call. | |
de584861 | 61 | |
bd8a901f | 62 | On failure, this function uses NAME in a warning and returns false. |
de584861 PA |
63 | It may throw an exception, but does not for XML parsing |
64 | problems. */ | |
65 | ||
bd8a901f PA |
66 | bool xml_process_xincludes (std::string &result, |
67 | const char *name, const char *text, | |
68 | xml_fetch_another fetcher, void *fetcher_baton, | |
69 | int depth); | |
de584861 | 70 | |
108546a0 DJ |
71 | /* Simplified XML parser infrastructure. */ |
72 | ||
e776119f | 73 | /* A name and value pair, used to record parsed attributes. */ |
fd79ecee | 74 | |
e776119f DJ |
75 | struct gdb_xml_value |
76 | { | |
77 | const char *name; | |
78 | void *value; | |
79 | }; | |
80 | typedef struct gdb_xml_value gdb_xml_value_s; | |
81 | DEF_VEC_O(gdb_xml_value_s); | |
fd79ecee | 82 | |
e776119f | 83 | /* The type of an attribute handler. |
fd79ecee | 84 | |
e776119f DJ |
85 | PARSER is the current XML parser, which should be used to issue any |
86 | debugging or error messages. The second argument is the | |
87 | corresponding attribute description, so that a single handler can | |
88 | be used for multiple attributes; the attribute name is available | |
89 | for error messages and the handler data is available for additional | |
90 | customization (see gdb_xml_parse_attr_enum). VALUE is the string | |
91 | value of the attribute. | |
92 | ||
93 | The returned value should be freeable with xfree, and will be freed | |
94 | after the start handler is called. Errors should be reported by | |
95 | calling gdb_xml_error. */ | |
96 | ||
97 | typedef void *(gdb_xml_attribute_handler) (struct gdb_xml_parser *parser, | |
98 | const struct gdb_xml_attribute *, | |
99 | const char *value); | |
100 | ||
101 | /* Flags for attributes. If no flags are specified, the attribute is | |
102 | required. */ | |
103 | ||
104 | enum gdb_xml_attribute_flag | |
105 | { | |
106 | GDB_XML_AF_NONE, | |
107 | GDB_XML_AF_OPTIONAL = 1 << 0, /* The attribute is optional. */ | |
108 | }; | |
109 | ||
110 | /* An expected attribute and the handler to call when it is | |
111 | encountered. Arrays of struct gdb_xml_attribute are terminated | |
112 | by an entry with NAME == NULL. */ | |
113 | ||
114 | struct gdb_xml_attribute | |
115 | { | |
116 | const char *name; | |
117 | int flags; | |
118 | gdb_xml_attribute_handler *handler; | |
119 | const void *handler_data; | |
120 | }; | |
121 | ||
122 | /* Flags for elements. If no flags are specified, the element is | |
123 | required exactly once. */ | |
124 | ||
125 | enum gdb_xml_element_flag | |
126 | { | |
127 | GDB_XML_EF_NONE, | |
128 | GDB_XML_EF_OPTIONAL = 1 << 0, /* The element is optional. */ | |
129 | GDB_XML_EF_REPEATABLE = 1 << 1, /* The element is repeatable. */ | |
130 | }; | |
131 | ||
132 | /* A handler called at the beginning of an element. | |
133 | ||
134 | PARSER is the current XML parser, which should be used to issue any | |
135 | debugging or error messages. ELEMENT is the current element. | |
136 | USER_DATA is the opaque pointer supplied when the parser was | |
137 | created. ATTRIBUTES is a vector of the values of any attributes | |
138 | attached to this element. | |
139 | ||
140 | The start handler will only be called if all the required | |
141 | attributes were present and parsed successfully, and elements of | |
142 | ATTRIBUTES are guaranteed to be in the same order used in | |
143 | ELEMENT->ATTRIBUTES (not the order from the XML file). Accordingly | |
144 | fixed offsets can be used to find any non-optional attributes as | |
145 | long as no optional attributes precede them. */ | |
146 | ||
147 | typedef void (gdb_xml_element_start_handler) | |
148 | (struct gdb_xml_parser *parser, const struct gdb_xml_element *element, | |
149 | void *user_data, VEC(gdb_xml_value_s) *attributes); | |
150 | ||
151 | /* A handler called at the end of an element. | |
152 | ||
153 | PARSER, ELEMENT, and USER_DATA are as for the start handler. BODY | |
154 | is any accumulated body text inside the element, with leading and | |
155 | trailing whitespace removed. It will never be NULL. */ | |
156 | ||
157 | typedef void (gdb_xml_element_end_handler) | |
158 | (struct gdb_xml_parser *, const struct gdb_xml_element *, | |
159 | void *user_data, const char *body_text); | |
160 | ||
161 | /* An expected element and the handlers to call when it is | |
162 | encountered. Arrays of struct gdb_xml_element are terminated | |
163 | by an entry with NAME == NULL. */ | |
164 | ||
165 | struct gdb_xml_element | |
166 | { | |
167 | const char *name; | |
168 | const struct gdb_xml_attribute *attributes; | |
169 | const struct gdb_xml_element *children; | |
170 | int flags; | |
171 | ||
172 | gdb_xml_element_start_handler *start_handler; | |
173 | gdb_xml_element_end_handler *end_handler; | |
174 | }; | |
175 | ||
efc0eabd PA |
176 | /* Parse a XML document. DOCUMENT is the data to parse, which should |
177 | be NUL-terminated. If non-NULL, use the compiled-in DTD named | |
178 | DTD_NAME to drive the parsing. | |
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_quick (const char *name, const char *dtd_name, | |
185 | const struct gdb_xml_element *elements, | |
186 | const char *document, void *user_data); | |
187 | ||
e776119f DJ |
188 | /* Issue a debugging message from one of PARSER's handlers. */ |
189 | ||
190 | void gdb_xml_debug (struct gdb_xml_parser *parser, const char *format, ...) | |
21047726 | 191 | ATTRIBUTE_PRINTF (2, 3); |
e776119f DJ |
192 | |
193 | /* Issue an error message from one of PARSER's handlers, and stop | |
194 | parsing. */ | |
195 | ||
196 | void gdb_xml_error (struct gdb_xml_parser *parser, const char *format, ...) | |
21047726 | 197 | ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 3); |
e776119f | 198 | |
3d2c1d41 PA |
199 | /* Find the attribute named NAME in the set of parsed attributes |
200 | ATTRIBUTES. Returns NULL if not found. */ | |
201 | ||
202 | struct gdb_xml_value *xml_find_attribute (VEC(gdb_xml_value_s) *attributes, | |
203 | const char *name); | |
204 | ||
e776119f DJ |
205 | /* Parse an integer attribute into a ULONGEST. */ |
206 | ||
207 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_ulongest; | |
208 | ||
209 | /* Map NAME to VALUE. A struct gdb_xml_enum * should be saved as the | |
210 | value of handler_data when using gdb_xml_parse_attr_enum to parse a | |
211 | fixed list of possible strings. The list is terminated by an entry | |
212 | with NAME == NULL. */ | |
213 | ||
214 | struct gdb_xml_enum | |
215 | { | |
216 | const char *name; | |
217 | ULONGEST value; | |
218 | }; | |
219 | ||
123dc839 DJ |
220 | /* A handler_data for yes/no boolean values. */ |
221 | extern const struct gdb_xml_enum gdb_xml_enums_boolean[]; | |
222 | ||
e776119f DJ |
223 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_enum; |
224 | ||
225 | /* Parse an integer string into a ULONGEST and return it, or call | |
226 | gdb_xml_error if it could not be parsed. */ | |
227 | ||
228 | ULONGEST gdb_xml_parse_ulongest (struct gdb_xml_parser *parser, | |
229 | const char *value); | |
fd79ecee | 230 | |
a96d9b2e SDJ |
231 | /* Open FILENAME, read all its text into memory, close it, and return |
232 | the text. If something goes wrong, return NULL and warn. */ | |
233 | ||
b7b030ad TT |
234 | extern gdb::unique_xmalloc_ptr<char> xml_fetch_content_from_file |
235 | (const char *filename, void *baton); | |
a96d9b2e | 236 | |
fd79ecee | 237 | #endif |