gdb/xml-support.h

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