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