1 /* Helper routines for parsing XML using Expat.
3 Copyright (C) 2006, 2007 Free Software Foundation, Inc.
5 This file is part of GDB.
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.
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.
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. */
26 #include "gdb_obstack.h"
29 struct gdb_xml_parser
;
30 struct gdb_xml_element
;
31 struct gdb_xml_attribute
;
33 /* A name and value pair, used to record parsed attributes. */
40 typedef struct gdb_xml_value gdb_xml_value_s
;
41 DEF_VEC_O(gdb_xml_value_s
);
43 /* The type of an attribute handler.
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.
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. */
57 typedef void *(gdb_xml_attribute_handler
) (struct gdb_xml_parser
*parser
,
58 const struct gdb_xml_attribute
*,
61 /* Flags for attributes. If no flags are specified, the attribute is
64 enum gdb_xml_attribute_flag
67 GDB_XML_AF_OPTIONAL
= 1 << 0, /* The attribute is optional. */
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. */
74 struct gdb_xml_attribute
78 gdb_xml_attribute_handler
*handler
;
79 const void *handler_data
;
82 /* Flags for elements. If no flags are specified, the element is
83 required exactly once. */
85 enum gdb_xml_element_flag
88 GDB_XML_EF_OPTIONAL
= 1 << 0, /* The element is optional. */
89 GDB_XML_EF_REPEATABLE
= 1 << 1, /* The element is repeatable. */
92 /* A handler called at the beginning of an element.
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.
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. */
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
);
111 /* A handler called at the end of an element.
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. */
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
);
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. */
125 struct gdb_xml_element
128 const struct gdb_xml_attribute
*attributes
;
129 const struct gdb_xml_element
*children
;
132 gdb_xml_element_start_handler
*start_handler
;
133 gdb_xml_element_end_handler
*end_handler
;
136 /* Initialize and return a parser. Register a cleanup to destroy the
139 struct gdb_xml_parser
*gdb_xml_create_parser_and_cleanup
140 (const char *name
, const struct gdb_xml_element
*elements
,
143 /* Invoke PARSER on BUFFER. BUFFER is the data to parse, which
144 should be NUL-terminated.
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. */
150 int gdb_xml_parse (struct gdb_xml_parser
*parser
, const char *buffer
);
152 /* Issue a debugging message from one of PARSER's handlers. */
154 void gdb_xml_debug (struct gdb_xml_parser
*parser
, const char *format
, ...)
155 ATTR_FORMAT (printf
, 2, 0);
157 /* Issue an error message from one of PARSER's handlers, and stop
160 void gdb_xml_error (struct gdb_xml_parser
*parser
, const char *format
, ...)
161 ATTR_NORETURN
ATTR_FORMAT (printf
, 2, 0);
163 /* Parse an integer attribute into a ULONGEST. */
165 extern gdb_xml_attribute_handler gdb_xml_parse_attr_ulongest
;
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. */
178 extern gdb_xml_attribute_handler gdb_xml_parse_attr_enum
;
180 /* Parse an integer string into a ULONGEST and return it, or call
181 gdb_xml_error if it could not be parsed. */
183 ULONGEST
gdb_xml_parse_ulongest (struct gdb_xml_parser
*parser
,