xmlwrapp
xmlwrapp/tree_parser.h
Go to the documentation of this file.
00001 /*
00002  * Copyright (C) 2001-2003 Peter J Jones (pjones@pmade.org)
00003  * All Rights Reserved
00004  * 
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions
00007  * are met:
00008  * 
00009  * 1. Redistributions of source code must retain the above copyright
00010  *    notice, this list of conditions and the following disclaimer.
00011  * 2. Redistributions in binary form must reproduce the above copyright
00012  *    notice, this list of conditions and the following disclaimer in
00013  *    the documentation and/or other materials provided with the
00014  *    distribution.
00015  * 3. Neither the name of the Author nor the names of its contributors
00016  *    may be used to endorse or promote products derived from this software
00017  *    without specific prior written permission.
00018  * 
00019  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS''
00020  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
00021  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
00022  * PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR
00023  * OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
00024  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00025  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
00026  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
00027  * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00028  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
00029  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00030  * SUCH DAMAGE.
00031  */
00032 
00033 /**
00034     @file
00035 
00036     This file contains the definition of the xml::tree_parser class.
00037  */
00038 
00039 #ifndef _xmlwrapp_tree_parser_h_
00040 #define _xmlwrapp_tree_parser_h_
00041 
00042 // xmlwrapp includes
00043 #include "xmlwrapp/init.h"
00044 
00045 // standard includes
00046 #include <cstddef>
00047 #include <string>
00048 
00049 namespace xml
00050 {
00051 
00052 // forward declarations
00053 class document;
00054 
00055 namespace impl
00056 {
00057 struct tree_impl;
00058 }
00059 
00060 /**
00061     The xml::tree_parser class is used to parse an XML document and generate
00062     a tree like structure of xml::node objects.
00063 
00064     After constructing a tree_parser, with either a file to parse or some in
00065     memory data to parse, you can walk the tree using the xml::node interface.
00066  */
00067 class tree_parser
00068 {
00069 public:
00070     typedef std::size_t size_type;
00071 
00072     /**
00073         xml::tree_parser class constructor. Given the name of a file, this
00074         constructor will parse that file.
00075 
00076         There are two options for dealing with XML parsing errors. The
00077         default it to throw an exception (std::runtime_error). The other
00078         option is to pass false for the allow_exceptions flag. This will
00079         prevent an exception from being thrown, instead, a flag will be set
00080         that you can test with the operator! member function.
00081 
00082         No matter what option you choose, this constructor may still throw
00083         exceptions for memory failure or other non-parsing related failures.
00084 
00085         @param filename The name of the file to parse.
00086         @param allow_exceptions Whether or not you want an exception for parsing errors.
00087      */
00088     tree_parser(const char *filename, bool allow_exceptions = true);
00089 
00090     /**
00091         xml::tree_parser class constructor. Given some data and the size of
00092         that data, parse that data as XML. To see if the data was parsed
00093         successfully use operator!.
00094 
00095         @param data The XML data to parse.
00096         @param size The size of the XML data to parse.
00097         @param allow_exceptions Whether or not you want an exception
00098                                 for parsing errors.
00099      */
00100     tree_parser(const char *data, size_type size, bool allow_exceptions = true);
00101 
00102     ~tree_parser();
00103 
00104     /**
00105         Check to see if a xml::tree_parser class is vaild. That is, check to
00106         see if parsing XML data was successful and the tree_parser holds a
00107         good XML node tree.
00108 
00109         @return True if the tree_parser is NOT VAILD; false if it is vaild.
00110      */
00111     bool operator!() const;
00112 
00113     /**
00114         If operator! indicates that there was an error parsing your XML data,
00115         you can use this member function to get the error message that was
00116         generated during parsing.
00117 
00118         @return The error message generated durring XML parsing.
00119      */
00120     const std::string& get_error_message() const;
00121 
00122     /**
00123         Check to see if there were any warnings from the parser while
00124         processing the given XML data. If there were, you may want to send
00125         the same document through xmllint or the event_parser to catch and
00126         review the warning messages.
00127 
00128         @return True if there were any warnings.
00129         @return False if there were no warnings.
00130      */
00131     bool had_warnings() const;
00132 
00133     /**
00134         Get a reference to the xml::document that was generated during the
00135         XML parsing. You should make sure to only use a reference to the
00136         document to avoid a deep copy.
00137 
00138         @return A reference to the xml::document.
00139      */
00140     xml::document& get_document();
00141 
00142     /**
00143         Get a const reference to the xml::document that was generate during
00144         the XML parsing. You should make sure to only use a reference to the
00145         document to avoid a deep copy.
00146 
00147         @return A const reference to the xml::document.
00148      */
00149     const xml::document& get_document() const;
00150 
00151 private:
00152     impl::tree_impl *pimpl_; // private implementation
00153 
00154     // Don't allow anyone to copy construct a xml::tree_parser or allow the
00155     // assignment operator to be called. It is not very useful to copy a
00156     // parser that has already parsed half a document.
00157     tree_parser(const tree_parser&);
00158     tree_parser& operator=(const tree_parser&);
00159 };
00160 
00161 } // end xml namespace
00162 
00163 #endif // _xmlwrapp_tree_parser_h_