gdb/xml-support.c

   1 /* Helper routines for parsing XML using Expat.
   2
   3    Copyright (C) 2006
   4    Free Software Foundation, Inc.
   5
   6    This file is part of GDB.
   7
   8    This program is free software; you can redistribute it and/or modify
   9    it under the terms of the GNU General Public License as published by
  10    the Free Software Foundation; either version 2 of the License, or
  11    (at your option) any later version.
  12
  13    This program is distributed in the hope that it will be useful,
  14    but WITHOUT ANY WARRANTY; without even the implied warranty of
  15    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16    GNU General Public License for more details.
  17
  18    You should have received a copy of the GNU General Public License
  19    along with this program; if not, write to the Free Software
  20    Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21    Boston, MA 02110-1301, USA.  */
  22
  23 #include "defs.h"
  24 #include "gdbcmd.h"
  25
  26 /* Debugging flag.  */
  27 static int debug_xml;
  28
  29 /* The contents of this file are only useful if XML support is
  30    available.  */
  31 #ifdef HAVE_LIBEXPAT
  32
  33 #include "exceptions.h"
  34 #include "xml-support.h"
  35
  36 #include "gdb_expat.h"
  37 #include "gdb_string.h"
  38 #include "safe-ctype.h"
  39
  40 /* A parsing level -- used to keep track of the current element
  41    nesting.  */
  42 struct scope_level
  43 {
  44   /* Elements we allow at this level.  */
  45   const struct gdb_xml_element *elements;
  46
  47   /* The element which we are within.  */
  48   const struct gdb_xml_element *element;
  49
  50   /* Mask of which elements we've seen at this level (used for
  51      optional and repeatable checking).  */
  52   unsigned int seen;
  53
  54   /* Body text accumulation.  */
  55   struct obstack *body;
  56 };
  57 typedef struct scope_level scope_level_s;
  58 DEF_VEC_O(scope_level_s);
  59
  60 /* The parser itself, and our additional state.  */
  61 struct gdb_xml_parser
  62 {
  63   XML_Parser expat_parser;      /* The underlying expat parser.  */
  64
  65   const char *name;             /* Name of this parser.  */
  66   void *user_data;              /* The user's callback data, for handlers.  */
  67
  68   VEC(scope_level_s) *scopes;   /* Scoping stack.  */
  69
  70   struct gdb_exception error;   /* A thrown error, if any.  */
  71   int last_line;                /* The line of the thrown error, or 0.  */
  72 };
  73
  74 /* Process some body text.  We accumulate the text for later use; it's
  75    wrong to do anything with it immediately, because a single block of
  76    text might be broken up into multiple calls to this function.  */
  77
  78 static void
  79 gdb_xml_body_text (void *data, const XML_Char *text, int length)
  80 {
  81   struct gdb_xml_parser *parser = data;
  82   struct scope_level *scope = VEC_last (scope_level_s, parser->scopes);
  83
  84   if (scope->body == NULL)
  85     {
  86       scope->body = XZALLOC (struct obstack);
  87       obstack_init (scope->body);
  88     }
  89
  90   obstack_grow (scope->body, text, length);
  91 }
  92
  93 /* Issue a debugging message from one of PARSER's handlers.  */
  94
  95 void
  96 gdb_xml_debug (struct gdb_xml_parser *parser, const char *format, ...)
  97 {
  98   int line = XML_GetCurrentLineNumber (parser->expat_parser);
  99   va_list ap;
 100   char *message;
 101
 102   if (!debug_xml)
 103     return;
 104
 105   va_start (ap, format);
 106   message = xstrvprintf (format, ap);
 107   if (line)
 108     fprintf_unfiltered (gdb_stderr, "%s (line %d): %s\n",
 109                         parser->name, line, message);
 110   else
 111     fprintf_unfiltered (gdb_stderr, "%s: %s\n",
 112                         parser->name, message);
 113   xfree (message);
 114 }
 115
 116 /* Issue an error message from one of PARSER's handlers, and stop
 117    parsing.  */
 118
 119 void
 120 gdb_xml_error (struct gdb_xml_parser *parser, const char *format, ...)
 121 {
 122   int line = XML_GetCurrentLineNumber (parser->expat_parser);
 123   va_list ap;
 124
 125   parser->last_line = line;
 126   va_start (ap, format);
 127   throw_verror (XML_PARSE_ERROR, format, ap);
 128 }
 129
 130 /* Clean up a vector of parsed attribute values.  */
 131
 132 static void
 133 gdb_xml_values_cleanup (void *data)
 134 {
 135   VEC(gdb_xml_value_s) **values = data;
 136   struct gdb_xml_value *value;
 137   int ix;
 138
 139   for (ix = 0; VEC_iterate (gdb_xml_value_s, *values, ix, value); ix++)
 140     xfree (value->value);
 141   VEC_free (gdb_xml_value_s, *values);
 142 }
 143
 144 /* Handle the start of an element.  DATA is our local XML parser, NAME
 145    is the element, and ATTRS are the names and values of this
 146    element's attributes.  */
 147
 148 static void
 149 gdb_xml_start_element (void *data, const XML_Char *name,
 150                        const XML_Char **attrs)
 151 {
 152   struct gdb_xml_parser *parser = data;
 153   struct scope_level *scope = VEC_last (scope_level_s, parser->scopes);
 154   struct scope_level new_scope;
 155   const struct gdb_xml_element *element;
 156   const struct gdb_xml_attribute *attribute;
 157   VEC(gdb_xml_value_s) *attributes = NULL;
 158   unsigned int seen;
 159   struct cleanup *back_to;
 160
 161   back_to = make_cleanup (gdb_xml_values_cleanup, &attributes);
 162
 163   /* Push an error scope.  If we return or throw an exception before
 164      filling this in, it will tell us to ignore children of this
 165      element.  */
 166   memset (&new_scope, 0, sizeof (new_scope));
 167   VEC_safe_push (scope_level_s, parser->scopes, &new_scope);
 168
 169   gdb_xml_debug (parser, _("Entering element <%s>"), name);
 170
 171   /* Find this element in the list of the current scope's allowed
 172      children.  Record that we've seen it.  */
 173
 174   seen = 1;
 175   for (element = scope->elements; element && element->name;
 176        element++, seen <<= 1)
 177     if (strcmp (element->name, name) == 0)
 178       break;
 179
 180   if (element == NULL || element->name == NULL)
 181     {
 182       gdb_xml_debug (parser, _("Element <%s> unknown"), name);
 183       do_cleanups (back_to);
 184       return;
 185     }
 186
 187   if (!(element->flags & GDB_XML_EF_REPEATABLE) && (seen & scope->seen))
 188     gdb_xml_error (parser, _("Element <%s> only expected once"), name);
 189
 190   scope->seen |= seen;
 191
 192   for (attribute = element->attributes;
 193        attribute != NULL && attribute->name != NULL;
 194        attribute++)
 195     {
 196       const char *val = NULL;
 197       const XML_Char **p;
 198       void *parsed_value;
 199       struct gdb_xml_value new_value;
 200
 201       for (p = attrs; *p != NULL; p += 2)
 202         if (!strcmp (attribute->name, p[0]))
 203           {
 204             val = p[1];
 205             break;
 206           }
 207
 208       if (*p != NULL && val == NULL)
 209         {
 210           gdb_xml_debug (parser, _("Attribute \"%s\" missing a value"),
 211                          attribute->name);
 212           continue;
 213         }
 214
 215       if (*p == NULL && !(attribute->flags & GDB_XML_AF_OPTIONAL))
 216         {
 217           gdb_xml_error (parser, _("Required attribute \"%s\" of "
 218                                    "<%s> not specified"),
 219                          attribute->name, element->name);
 220           continue;
 221         }
 222
 223       if (*p == NULL)
 224         continue;
 225
 226       gdb_xml_debug (parser, _("Parsing attribute %s=\"%s\""),
 227                      attribute->name, val);
 228
 229       if (attribute->handler)
 230         parsed_value = attribute->handler (parser, attribute, val);
 231       else
 232         parsed_value = xstrdup (val);
 233
 234       new_value.name = attribute->name;
 235       new_value.value = parsed_value;
 236       VEC_safe_push (gdb_xml_value_s, attributes, &new_value);
 237     }
 238
 239   /* Check for unrecognized attributes.  */
 240   if (debug_xml)
 241     {
 242       const XML_Char **p;
 243
 244       for (p = attrs; *p != NULL; p += 2)
 245         {
 246           for (attribute = element->attributes;
 247                attribute != NULL && attribute->name != NULL;
 248                attribute++)
 249             if (strcmp (attribute->name, *p) == 0)
 250               break;
 251
 252           if (attribute == NULL || attribute->name == NULL)
 253             gdb_xml_debug (parser, _("Ignoring unknown attribute %s"), *p);
 254         }
 255     }
 256
 257   /* Call the element handler if there is one.  */
 258   if (element->start_handler)
 259     element->start_handler (parser, element, parser->user_data, attributes);
 260
 261   /* Fill in a new scope level.  */
 262   scope = VEC_last (scope_level_s, parser->scopes);
 263   scope->element = element;
 264   scope->elements = element->children;
 265
 266   do_cleanups (back_to);
 267 }
 268
 269 /* Wrapper for gdb_xml_start_element, to prevent throwing exceptions
 270    through expat.  */
 271
 272 static void
 273 gdb_xml_start_element_wrapper (void *data, const XML_Char *name,
 274                                const XML_Char **attrs)
 275 {
 276   struct gdb_xml_parser *parser = data;
 277   volatile struct gdb_exception ex;
 278
 279   if (parser->error.reason < 0)
 280     return;
 281
 282   TRY_CATCH (ex, RETURN_MASK_ALL)
 283     {
 284       gdb_xml_start_element (data, name, attrs);
 285     }
 286   if (ex.reason < 0)
 287     {
 288       parser->error = ex;
 289       XML_StopParser (parser->expat_parser, XML_FALSE);
 290     }
 291 }
 292
 293 /* Handle the end of an element.  DATA is our local XML parser, and
 294    NAME is the current element.  */
 295
 296 static void
 297 gdb_xml_end_element (void *data, const XML_Char *name)
 298 {
 299   struct gdb_xml_parser *parser = data;
 300   struct scope_level *scope = VEC_last (scope_level_s, parser->scopes);
 301   const struct gdb_xml_element *element;
 302   unsigned int seen;
 303   char *body;
 304
 305   gdb_xml_debug (parser, _("Leaving element <%s>"), name);
 306
 307   for (element = scope->elements, seen = 1;
 308        element != NULL && element->name != NULL;
 309        element++, seen <<= 1)
 310     if ((scope->seen & seen) == 0
 311         && (element->flags & GDB_XML_EF_OPTIONAL) == 0)
 312       gdb_xml_error (parser, _("Required element <%s> is missing"),
 313                      element->name);
 314
 315   /* Call the element processor. */
 316   if (scope->body == NULL)
 317     body = "";
 318   else
 319     {
 320       int length;
 321
 322       length = obstack_object_size (scope->body);
 323       obstack_1grow (scope->body, '\0');
 324       body = obstack_finish (scope->body);
 325
 326       /* Strip leading and trailing whitespace.  */
 327       while (length > 0 && ISSPACE (body[length-1]))
 328         body[--length] = '\0';
 329       while (*body && ISSPACE (*body))
 330         body++;
 331     }
 332
 333   if (scope->element != NULL && scope->element->end_handler)
 334     scope->element->end_handler (parser, scope->element, parser->user_data,
 335                                  body);
 336
 337   /* Pop the scope level.  */
 338   if (scope->body)
 339     {
 340       obstack_free (scope->body, NULL);
 341       xfree (scope->body);
 342     }
 343   VEC_pop (scope_level_s, parser->scopes);
 344 }
 345
 346 /* Wrapper for gdb_xml_end_element, to prevent throwing exceptions
 347    through expat.  */
 348
 349 static void
 350 gdb_xml_end_element_wrapper (void *data, const XML_Char *name)
 351 {
 352   struct gdb_xml_parser *parser = data;
 353   volatile struct gdb_exception ex;
 354
 355   if (parser->error.reason < 0)
 356     return;
 357
 358   TRY_CATCH (ex, RETURN_MASK_ALL)
 359     {
 360       gdb_xml_end_element (data, name);
 361     }
 362   if (ex.reason < 0)
 363     {
 364       parser->error = ex;
 365       XML_StopParser (parser->expat_parser, XML_FALSE);
 366     }
 367 }
 368
 369 /* Free a parser and all its associated state.  */
 370
 371 static void
 372 gdb_xml_cleanup (void *arg)
 373 {
 374   struct gdb_xml_parser *parser = arg;
 375   struct scope_level *scope;
 376   int ix;
 377
 378   XML_ParserFree (parser->expat_parser);
 379
 380   /* Clean up the scopes.  */
 381   for (ix = 0; VEC_iterate (scope_level_s, parser->scopes, ix, scope); ix++)
 382     if (scope->body)
 383       {
 384         obstack_free (scope->body, NULL);
 385         xfree (scope->body);
 386       }
 387   VEC_free (scope_level_s, parser->scopes);
 388
 389   xfree (parser);
 390 }
 391
 392 /* Initialize and return a parser.  Register a cleanup to destroy the
 393    parser.  */
 394
 395 struct gdb_xml_parser *
 396 gdb_xml_create_parser_and_cleanup (const char *name,
 397                                    const struct gdb_xml_element *elements,
 398                                    void *user_data)
 399 {
 400   struct gdb_xml_parser *parser;
 401   struct scope_level start_scope;
 402
 403   /* Initialize the parser.  */
 404   parser = XZALLOC (struct gdb_xml_parser);
 405   parser->expat_parser = XML_ParserCreateNS (NULL, '!');
 406   if (parser->expat_parser == NULL)
 407     {
 408       xfree (parser);
 409       nomem (0);
 410     }
 411
 412   parser->name = name;
 413
 414   parser->user_data = user_data;
 415   XML_SetUserData (parser->expat_parser, parser);
 416
 417   /* Set the callbacks.  */
 418   XML_SetElementHandler (parser->expat_parser, gdb_xml_start_element_wrapper,
 419                          gdb_xml_end_element_wrapper);
 420   XML_SetCharacterDataHandler (parser->expat_parser, gdb_xml_body_text);
 421
 422   /* Initialize the outer scope.  */
 423   memset (&start_scope, 0, sizeof (start_scope));
 424   start_scope.elements = elements;
 425   VEC_safe_push (scope_level_s, parser->scopes, &start_scope);
 426
 427   make_cleanup (gdb_xml_cleanup, parser);
 428
 429   return parser;
 430 }
 431
 432 /* Invoke PARSER on BUFFER.  BUFFER is the data to parse, which
 433    should be NUL-terminated.
 434
 435    The return value is 0 for success or -1 for error.  It may throw,
 436    but only if something unexpected goes wrong during parsing; parse
 437    errors will be caught, warned about, and reported as failure.  */
 438
 439 int
 440 gdb_xml_parse (struct gdb_xml_parser *parser, const char *buffer)
 441 {
 442   enum XML_Status status;
 443   const char *error_string;
 444
 445   status = XML_Parse (parser->expat_parser, buffer, strlen (buffer), 1);
 446
 447   if (status == XML_STATUS_OK && parser->error.reason == 0)
 448     return 0;
 449
 450   if (parser->error.reason == RETURN_ERROR
 451       && parser->error.error == XML_PARSE_ERROR)
 452     {
 453       gdb_assert (parser->error.message != NULL);
 454       error_string = parser->error.message;
 455     }
 456   else if (status == XML_STATUS_ERROR)
 457     {
 458       enum XML_Error err = XML_GetErrorCode (parser->expat_parser);
 459       error_string = XML_ErrorString (err);
 460     }
 461   else
 462     {
 463       gdb_assert (parser->error.reason < 0);
 464       throw_exception (parser->error);
 465     }
 466
 467   if (parser->last_line != 0)
 468     warning (_("while parsing %s (at line %d): %s"), parser->name,
 469              parser->last_line, error_string);
 470   else
 471     warning (_("while parsing %s: %s"), parser->name, error_string);
 472
 473   return -1;
 474 }
 475
 476 /* Parse a field VALSTR that we expect to contain an integer value.
 477    The integer is returned in *VALP.  The string is parsed with an
 478    equivalent to strtoul.
 479
 480    Returns 0 for success, -1 for error.  */
 481
 482 static int
 483 xml_parse_unsigned_integer (const char *valstr, ULONGEST *valp)
 484 {
 485   const char *endptr;
 486   ULONGEST result;
 487
 488   if (*valstr == '\0')
 489     return -1;
 490
 491   result = strtoulst (valstr, &endptr, 0);
 492   if (*endptr != '\0')
 493     return -1;
 494
 495   *valp = result;
 496   return 0;
 497 }
 498
 499 /* Parse an integer string into a ULONGEST and return it, or call
 500    gdb_xml_error if it could not be parsed.  */
 501
 502 ULONGEST
 503 gdb_xml_parse_ulongest (struct gdb_xml_parser *parser, const char *value)
 504 {
 505   ULONGEST result;
 506
 507   if (xml_parse_unsigned_integer (value, &result) != 0)
 508     gdb_xml_error (parser, _("Can't convert \"%s\" to an integer"), value);
 509
 510   return result;
 511 }
 512
 513 /* Parse an integer attribute into a ULONGEST.  */
 514
 515 void *
 516 gdb_xml_parse_attr_ulongest (struct gdb_xml_parser *parser,
 517                              const struct gdb_xml_attribute *attribute,
 518                              const char *value)
 519 {
 520   ULONGEST result;
 521   void *ret;
 522
 523   if (xml_parse_unsigned_integer (value, &result) != 0)
 524     gdb_xml_error (parser, _("Can't convert %s=\"%s\" to an integer"),
 525                    attribute->name, value);
 526
 527   ret = xmalloc (sizeof (result));
 528   memcpy (ret, &result, sizeof (result));
 529   return ret;
 530 }
 531
 532 /* Map NAME to VALUE.  A struct gdb_xml_enum * should be saved as the
 533    value of handler_data when using gdb_xml_parse_attr_enum to parse a
 534    fixed list of possible strings.  The list is terminated by an entry
 535    with NAME == NULL.  */
 536
 537 void *
 538 gdb_xml_parse_attr_enum (struct gdb_xml_parser *parser,
 539                          const struct gdb_xml_attribute *attribute,
 540                          const char *value)
 541 {
 542   const struct gdb_xml_enum *enums = attribute->handler_data;
 543   void *ret;
 544
 545   for (enums = attribute->handler_data; enums->name != NULL; enums++)
 546     if (strcmp (enums->name, value) == 0)
 547       break;
 548
 549   if (enums->name == NULL)
 550     gdb_xml_error (parser, _("Unknown attribute value %s=\"%s\""),
 551                  attribute->name, value);
 552
 553   ret = xmalloc (sizeof (enums->value));
 554   memcpy (ret, &enums->value, sizeof (enums->value));
 555   return ret;
 556 }
 557
 558 #endif /* HAVE_LIBEXPAT */
 559
 560 static void
 561 show_debug_xml (struct ui_file *file, int from_tty,
 562                 struct cmd_list_element *c, const char *value)
 563 {
 564   fprintf_filtered (file, _("XML debugging is %s.\n"), value);
 565 }
 566
 567 void _initialize_xml_support (void);
 568
 569 void
 570 _initialize_xml_support (void)
 571 {
 572   add_setshow_boolean_cmd ("xml", class_maintenance, &debug_xml,
 573                            _("Set XML parser debugging."),
 574                            _("Show XML parser debugging."),
 575                            _("When set, debugging messages for XML parsers "
 576                              "are displayed."),
 577                            NULL, show_debug_xml,
 578                            &setdebuglist, &showdebuglist);
 579 }