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 | |
e776119f | 33 | /* A name and value pair, used to record parsed attributes. */ |
fd79ecee | 34 | |
e776119f DJ |
35 | struct gdb_xml_value |
36 | { | |
37 | const char *name; | |
38 | void *value; | |
39 | }; | |
40 | typedef struct gdb_xml_value gdb_xml_value_s; | |
41 | DEF_VEC_O(gdb_xml_value_s); | |
fd79ecee | 42 | |
e776119f | 43 | /* The type of an attribute handler. |
fd79ecee | 44 | |
e776119f DJ |
45 | PARSER is the current XML parser, which should be used to issue any |
46 | debugging or error messages. The second argument is the | |
47 | corresponding attribute description, so that a single handler can | |
48 | be used for multiple attributes; the attribute name is available | |
49 | for error messages and the handler data is available for additional | |
50 | customization (see gdb_xml_parse_attr_enum). VALUE is the string | |
51 | value of the attribute. | |
52 | ||
53 | The returned value should be freeable with xfree, and will be freed | |
54 | after the start handler is called. Errors should be reported by | |
55 | calling gdb_xml_error. */ | |
56 | ||
57 | typedef void *(gdb_xml_attribute_handler) (struct gdb_xml_parser *parser, | |
58 | const struct gdb_xml_attribute *, | |
59 | const char *value); | |
60 | ||
61 | /* Flags for attributes. If no flags are specified, the attribute is | |
62 | required. */ | |
63 | ||
64 | enum gdb_xml_attribute_flag | |
65 | { | |
66 | GDB_XML_AF_NONE, | |
67 | GDB_XML_AF_OPTIONAL = 1 << 0, /* The attribute is optional. */ | |
68 | }; | |
69 | ||
70 | /* An expected attribute and the handler to call when it is | |
71 | encountered. Arrays of struct gdb_xml_attribute are terminated | |
72 | by an entry with NAME == NULL. */ | |
73 | ||
74 | struct gdb_xml_attribute | |
75 | { | |
76 | const char *name; | |
77 | int flags; | |
78 | gdb_xml_attribute_handler *handler; | |
79 | const void *handler_data; | |
80 | }; | |
81 | ||
82 | /* Flags for elements. If no flags are specified, the element is | |
83 | required exactly once. */ | |
84 | ||
85 | enum gdb_xml_element_flag | |
86 | { | |
87 | GDB_XML_EF_NONE, | |
88 | GDB_XML_EF_OPTIONAL = 1 << 0, /* The element is optional. */ | |
89 | GDB_XML_EF_REPEATABLE = 1 << 1, /* The element is repeatable. */ | |
90 | }; | |
91 | ||
92 | /* A handler called at the beginning of an element. | |
93 | ||
94 | PARSER is the current XML parser, which should be used to issue any | |
95 | debugging or error messages. ELEMENT is the current element. | |
96 | USER_DATA is the opaque pointer supplied when the parser was | |
97 | created. ATTRIBUTES is a vector of the values of any attributes | |
98 | attached to this element. | |
99 | ||
100 | The start handler will only be called if all the required | |
101 | attributes were present and parsed successfully, and elements of | |
102 | ATTRIBUTES are guaranteed to be in the same order used in | |
103 | ELEMENT->ATTRIBUTES (not the order from the XML file). Accordingly | |
104 | fixed offsets can be used to find any non-optional attributes as | |
105 | long as no optional attributes precede them. */ | |
106 | ||
107 | typedef void (gdb_xml_element_start_handler) | |
108 | (struct gdb_xml_parser *parser, const struct gdb_xml_element *element, | |
109 | void *user_data, VEC(gdb_xml_value_s) *attributes); | |
110 | ||
111 | /* A handler called at the end of an element. | |
112 | ||
113 | PARSER, ELEMENT, and USER_DATA are as for the start handler. BODY | |
114 | is any accumulated body text inside the element, with leading and | |
115 | trailing whitespace removed. It will never be NULL. */ | |
116 | ||
117 | typedef void (gdb_xml_element_end_handler) | |
118 | (struct gdb_xml_parser *, const struct gdb_xml_element *, | |
119 | void *user_data, const char *body_text); | |
120 | ||
121 | /* An expected element and the handlers to call when it is | |
122 | encountered. Arrays of struct gdb_xml_element are terminated | |
123 | by an entry with NAME == NULL. */ | |
124 | ||
125 | struct gdb_xml_element | |
126 | { | |
127 | const char *name; | |
128 | const struct gdb_xml_attribute *attributes; | |
129 | const struct gdb_xml_element *children; | |
130 | int flags; | |
131 | ||
132 | gdb_xml_element_start_handler *start_handler; | |
133 | gdb_xml_element_end_handler *end_handler; | |
134 | }; | |
135 | ||
136 | /* Initialize and return a parser. Register a cleanup to destroy the | |
137 | parser. */ | |
138 | ||
139 | struct gdb_xml_parser *gdb_xml_create_parser_and_cleanup | |
140 | (const char *name, const struct gdb_xml_element *elements, | |
141 | void *user_data); | |
142 | ||
143 | /* Invoke PARSER on BUFFER. BUFFER is the data to parse, which | |
144 | should be NUL-terminated. | |
145 | ||
146 | The return value is 0 for success or -1 for error. It may throw, | |
147 | but only if something unexpected goes wrong during parsing; parse | |
148 | errors will be caught, warned about, and reported as failure. */ | |
149 | ||
150 | int gdb_xml_parse (struct gdb_xml_parser *parser, const char *buffer); | |
151 | ||
152 | /* Issue a debugging message from one of PARSER's handlers. */ | |
153 | ||
154 | void gdb_xml_debug (struct gdb_xml_parser *parser, const char *format, ...) | |
155 | ATTR_FORMAT (printf, 2, 0); | |
156 | ||
157 | /* Issue an error message from one of PARSER's handlers, and stop | |
158 | parsing. */ | |
159 | ||
160 | void gdb_xml_error (struct gdb_xml_parser *parser, const char *format, ...) | |
161 | ATTR_NORETURN ATTR_FORMAT (printf, 2, 0); | |
162 | ||
163 | /* Parse an integer attribute into a ULONGEST. */ | |
164 | ||
165 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_ulongest; | |
166 | ||
167 | /* Map NAME to VALUE. A struct gdb_xml_enum * should be saved as the | |
168 | value of handler_data when using gdb_xml_parse_attr_enum to parse a | |
169 | fixed list of possible strings. The list is terminated by an entry | |
170 | with NAME == NULL. */ | |
171 | ||
172 | struct gdb_xml_enum | |
173 | { | |
174 | const char *name; | |
175 | ULONGEST value; | |
176 | }; | |
177 | ||
178 | extern gdb_xml_attribute_handler gdb_xml_parse_attr_enum; | |
179 | ||
180 | /* Parse an integer string into a ULONGEST and return it, or call | |
181 | gdb_xml_error if it could not be parsed. */ | |
182 | ||
183 | ULONGEST gdb_xml_parse_ulongest (struct gdb_xml_parser *parser, | |
184 | const char *value); | |
fd79ecee DJ |
185 | |
186 | #endif |