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