| 1 | /* Helper routines for parsing XML using Expat. |
| 2 | |
| 3 | Copyright (C) 2006-2013 Free Software Foundation, Inc. |
| 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 3 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, see <http://www.gnu.org/licenses/>. */ |
| 19 | |
| 20 | |
| 21 | #ifndef XML_SUPPORT_H |
| 22 | #define XML_SUPPORT_H |
| 23 | |
| 24 | #include "gdb_obstack.h" |
| 25 | #include "vec.h" |
| 26 | #include "xml-utils.h" |
| 27 | |
| 28 | struct gdb_xml_parser; |
| 29 | struct gdb_xml_element; |
| 30 | struct gdb_xml_attribute; |
| 31 | |
| 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 | |
| 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 | |
| 46 | /* The text of compiled-in XML documents, from xml-builtin.c |
| 47 | (generated). */ |
| 48 | |
| 49 | extern const char *xml_builtin[][2]; |
| 50 | |
| 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 | |
| 57 | /* Return a new string which is the expansion of TEXT after processing |
| 58 | <xi:include> tags. FETCHER will be called (with FETCHER_BATON) to |
| 59 | retrieve any new files. DEPTH should be zero on the initial call. |
| 60 | |
| 61 | On failure, this function uses NAME in a warning and returns NULL. |
| 62 | It may throw an exception, but does not for XML parsing |
| 63 | problems. */ |
| 64 | |
| 65 | char *xml_process_xincludes (const char *name, const char *text, |
| 66 | xml_fetch_another fetcher, void *fetcher_baton, |
| 67 | int depth); |
| 68 | |
| 69 | /* Simplified XML parser infrastructure. */ |
| 70 | |
| 71 | /* A name and value pair, used to record parsed attributes. */ |
| 72 | |
| 73 | struct gdb_xml_value |
| 74 | { |
| 75 | const char *name; |
| 76 | void *value; |
| 77 | }; |
| 78 | typedef struct gdb_xml_value gdb_xml_value_s; |
| 79 | DEF_VEC_O(gdb_xml_value_s); |
| 80 | |
| 81 | /* The type of an attribute handler. |
| 82 | |
| 83 | PARSER is the current XML parser, which should be used to issue any |
| 84 | debugging or error messages. The second argument is the |
| 85 | corresponding attribute description, so that a single handler can |
| 86 | be used for multiple attributes; the attribute name is available |
| 87 | for error messages and the handler data is available for additional |
| 88 | customization (see gdb_xml_parse_attr_enum). VALUE is the string |
| 89 | value of the attribute. |
| 90 | |
| 91 | The returned value should be freeable with xfree, and will be freed |
| 92 | after the start handler is called. Errors should be reported by |
| 93 | calling gdb_xml_error. */ |
| 94 | |
| 95 | typedef void *(gdb_xml_attribute_handler) (struct gdb_xml_parser *parser, |
| 96 | const struct gdb_xml_attribute *, |
| 97 | const char *value); |
| 98 | |
| 99 | /* Flags for attributes. If no flags are specified, the attribute is |
| 100 | required. */ |
| 101 | |
| 102 | enum gdb_xml_attribute_flag |
| 103 | { |
| 104 | GDB_XML_AF_NONE, |
| 105 | GDB_XML_AF_OPTIONAL = 1 << 0, /* The attribute is optional. */ |
| 106 | }; |
| 107 | |
| 108 | /* An expected attribute and the handler to call when it is |
| 109 | encountered. Arrays of struct gdb_xml_attribute are terminated |
| 110 | by an entry with NAME == NULL. */ |
| 111 | |
| 112 | struct gdb_xml_attribute |
| 113 | { |
| 114 | const char *name; |
| 115 | int flags; |
| 116 | gdb_xml_attribute_handler *handler; |
| 117 | const void *handler_data; |
| 118 | }; |
| 119 | |
| 120 | /* Flags for elements. If no flags are specified, the element is |
| 121 | required exactly once. */ |
| 122 | |
| 123 | enum gdb_xml_element_flag |
| 124 | { |
| 125 | GDB_XML_EF_NONE, |
| 126 | GDB_XML_EF_OPTIONAL = 1 << 0, /* The element is optional. */ |
| 127 | GDB_XML_EF_REPEATABLE = 1 << 1, /* The element is repeatable. */ |
| 128 | }; |
| 129 | |
| 130 | /* A handler called at the beginning of an element. |
| 131 | |
| 132 | PARSER is the current XML parser, which should be used to issue any |
| 133 | debugging or error messages. ELEMENT is the current element. |
| 134 | USER_DATA is the opaque pointer supplied when the parser was |
| 135 | created. ATTRIBUTES is a vector of the values of any attributes |
| 136 | attached to this element. |
| 137 | |
| 138 | The start handler will only be called if all the required |
| 139 | attributes were present and parsed successfully, and elements of |
| 140 | ATTRIBUTES are guaranteed to be in the same order used in |
| 141 | ELEMENT->ATTRIBUTES (not the order from the XML file). Accordingly |
| 142 | fixed offsets can be used to find any non-optional attributes as |
| 143 | long as no optional attributes precede them. */ |
| 144 | |
| 145 | typedef void (gdb_xml_element_start_handler) |
| 146 | (struct gdb_xml_parser *parser, const struct gdb_xml_element *element, |
| 147 | void *user_data, VEC(gdb_xml_value_s) *attributes); |
| 148 | |
| 149 | /* A handler called at the end of an element. |
| 150 | |
| 151 | PARSER, ELEMENT, and USER_DATA are as for the start handler. BODY |
| 152 | is any accumulated body text inside the element, with leading and |
| 153 | trailing whitespace removed. It will never be NULL. */ |
| 154 | |
| 155 | typedef void (gdb_xml_element_end_handler) |
| 156 | (struct gdb_xml_parser *, const struct gdb_xml_element *, |
| 157 | void *user_data, const char *body_text); |
| 158 | |
| 159 | /* An expected element and the handlers to call when it is |
| 160 | encountered. Arrays of struct gdb_xml_element are terminated |
| 161 | by an entry with NAME == NULL. */ |
| 162 | |
| 163 | struct gdb_xml_element |
| 164 | { |
| 165 | const char *name; |
| 166 | const struct gdb_xml_attribute *attributes; |
| 167 | const struct gdb_xml_element *children; |
| 168 | int flags; |
| 169 | |
| 170 | gdb_xml_element_start_handler *start_handler; |
| 171 | gdb_xml_element_end_handler *end_handler; |
| 172 | }; |
| 173 | |
| 174 | /* Initialize and return a parser. Register a cleanup to destroy the |
| 175 | parser. */ |
| 176 | |
| 177 | struct gdb_xml_parser *gdb_xml_create_parser_and_cleanup |
| 178 | (const char *name, const struct gdb_xml_element *elements, |
| 179 | void *user_data); |
| 180 | |
| 181 | /* Associate DTD_NAME, which must be the name of a compiled-in DTD, |
| 182 | with PARSER. */ |
| 183 | |
| 184 | void gdb_xml_use_dtd (struct gdb_xml_parser *parser, const char *dtd_name); |
| 185 | |
| 186 | /* Invoke PARSER on BUFFER. BUFFER is the data to parse, which |
| 187 | should be NUL-terminated. |
| 188 | |
| 189 | The return value is 0 for success or -1 for error. It may throw, |
| 190 | but only if something unexpected goes wrong during parsing; parse |
| 191 | errors will be caught, warned about, and reported as failure. */ |
| 192 | |
| 193 | int gdb_xml_parse (struct gdb_xml_parser *parser, const char *buffer); |
| 194 | |
| 195 | /* Parse a XML document. DOCUMENT is the data to parse, which should |
| 196 | be NUL-terminated. If non-NULL, use the compiled-in DTD named |
| 197 | DTD_NAME to drive the parsing. |
| 198 | |
| 199 | The return value is 0 for success or -1 for error. It may throw, |
| 200 | but only if something unexpected goes wrong during parsing; parse |
| 201 | errors will be caught, warned about, and reported as failure. */ |
| 202 | |
| 203 | int gdb_xml_parse_quick (const char *name, const char *dtd_name, |
| 204 | const struct gdb_xml_element *elements, |
| 205 | const char *document, void *user_data); |
| 206 | |
| 207 | /* Issue a debugging message from one of PARSER's handlers. */ |
| 208 | |
| 209 | void gdb_xml_debug (struct gdb_xml_parser *parser, const char *format, ...) |
| 210 | ATTRIBUTE_PRINTF (2, 0); |
| 211 | |
| 212 | /* Issue an error message from one of PARSER's handlers, and stop |
| 213 | parsing. */ |
| 214 | |
| 215 | void gdb_xml_error (struct gdb_xml_parser *parser, const char *format, ...) |
| 216 | ATTRIBUTE_NORETURN ATTRIBUTE_PRINTF (2, 0); |
| 217 | |
| 218 | /* Find the attribute named NAME in the set of parsed attributes |
| 219 | ATTRIBUTES. Returns NULL if not found. */ |
| 220 | |
| 221 | struct gdb_xml_value *xml_find_attribute (VEC(gdb_xml_value_s) *attributes, |
| 222 | const char *name); |
| 223 | |
| 224 | /* Parse an integer attribute into a ULONGEST. */ |
| 225 | |
| 226 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_ulongest; |
| 227 | |
| 228 | /* Map NAME to VALUE. A struct gdb_xml_enum * should be saved as the |
| 229 | value of handler_data when using gdb_xml_parse_attr_enum to parse a |
| 230 | fixed list of possible strings. The list is terminated by an entry |
| 231 | with NAME == NULL. */ |
| 232 | |
| 233 | struct gdb_xml_enum |
| 234 | { |
| 235 | const char *name; |
| 236 | ULONGEST value; |
| 237 | }; |
| 238 | |
| 239 | /* A handler_data for yes/no boolean values. */ |
| 240 | extern const struct gdb_xml_enum gdb_xml_enums_boolean[]; |
| 241 | |
| 242 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_enum; |
| 243 | |
| 244 | /* Parse an integer string into a ULONGEST and return it, or call |
| 245 | gdb_xml_error if it could not be parsed. */ |
| 246 | |
| 247 | ULONGEST gdb_xml_parse_ulongest (struct gdb_xml_parser *parser, |
| 248 | const char *value); |
| 249 | |
| 250 | /* Simple printf to obstack function. Current implemented formatters: |
| 251 | %s - grow an xml escaped text in OBSTACK. */ |
| 252 | |
| 253 | extern void obstack_xml_printf (struct obstack *obstack, |
| 254 | const char *format, ...) |
| 255 | ATTRIBUTE_PRINTF_2; |
| 256 | |
| 257 | /* Open FILENAME, read all its text into memory, close it, and return |
| 258 | the text. If something goes wrong, return NULL and warn. */ |
| 259 | |
| 260 | extern char *xml_fetch_content_from_file (const char *filename, |
| 261 | void *baton); |
| 262 | |
| 263 | #endif |