core/library/textual/xml_parser.h

   1 #ifndef XML_PARSER_CLASS
   2 #define XML_PARSER_CLASS
   3
   4 /*****************************************************************************\
   5 *                                                                             *
   6 *  Name   : xml_parser                                                        *
   7 *  Author : Chris Koeritz                                                     *
   8 *                                                                             *
   9 *******************************************************************************
  10 * Copyright (c) 2007-$now By Author.  This program is free software; you can  *
  11 * redistribute it and/or modify it under the terms of the GNU General Public  *
  12 * License as published by the Free Software Foundation; either version 2 of   *
  13 * the License or (at your option) any later version.  This is online at:      *
  14 *     http://www.fsf.org/copyleft/gpl.html                                    *
  15 * Please send any updates to: fred@gruntose.com                               *
  16 \*****************************************************************************/
  17
  18 #include <basis/contracts.h>
  19
  20 // forward.
  21 #include <basis/astring.h>
  22 #include <structures/string_table.h>
  23
  24 namespace textual {
  25
  26 //! Parses XML input and invokes a callback for the different syntactic pieces.
  27
  28 // hmmm, could this be the first class ever named this?  perhaps it should be
  29 // in a textual namespace.  -->after current sprint.
  30
  31 class xml_parser
  32 {
  33 public:
  34   xml_parser(const basis::astring &to_parse);
  35   virtual ~xml_parser();
  36
  37   DEFINE_CLASS_NAME("xml_parser");
  38
  39   //! the possible ways that operations here can complete.
  40   enum outcomes {
  41     OKAY = basis::common::OKAY
  42 //uhhh...
  43   };
  44
  45   static const char *outcome_name(const basis::outcome &to_name);
  46     //!< reports the string version of "to_name".
  47
  48   void reset(const basis::astring &to_parse);
  49     //!< throws out any accumulated information and uses "to_parse" instead.
  50
  51   basis::outcome parse();
  52     //!< starts the parsing process on the current string.
  53     /*!< this will cause callbacks to be invoked for each of the xml syntactic
  54     elements. */
  55
  56   virtual basis::outcome header_callback(basis::astring &header_name,
  57           structures::string_table &attributes);
  58     //!< invoked when a well-formed xml header is seen in the input stream.
  59     /*!< the following applies to all of the callbacks: the derived method must
  60     return an outcome, which will be used by the parser.  if the outcome is
  61     OKAY, then parsing will continue.  any other outcome will cause parsing
  62     to stop and will become the return value of the parse() method. */
  63
  64   virtual basis::outcome tag_open_callback(basis::astring &tag_name,
  65           structures::string_table &attributes);
  66     //!< an xml tag has been opened in the input stream.
  67
  68   virtual basis::outcome tag_close_callback(basis::astring &tag_name);
  69     //!< an xml tag was closed in the input stream.
  70
  71   virtual basis::outcome content_callback(basis::astring &content);
  72     //!< invoked when plain text content is found inside an opened tag.
  73
  74 private:
  75   basis::astring *_xml_stream;  // the stringful of xml information.
  76
  77 };
  78
  79 } //namespace.
  80
  81 #endif
  82