]> git.ipfire.org Git - thirdparty/binutils-gdb.git/blob - gdb/xml-support.h
Copyright updates for 2007.
[thirdparty/binutils-gdb.git] / gdb / xml-support.h
1 /* Helper routines for parsing XML using Expat.
2
3 Copyright (C) 2006, 2007 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 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
26 #include "gdb_obstack.h"
27 #include "vec.h"
28
29 struct gdb_xml_parser;
30 struct gdb_xml_element;
31 struct gdb_xml_attribute;
32
33 /* A name and value pair, used to record parsed attributes. */
34
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);
42
43 /* The type of an attribute handler.
44
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);
185
186 #endif