Main Page | Class Hierarchy | Class List | File List | Class Members

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 /** @file
00034  * This file contains the definition of the xml::tree_parser class.
00035 **/
00036 
00037 #ifndef _xmlwrapp_tree_parser_h_
00038 #define _xmlwrapp_tree_parser_h_
00039 
00040 // standard includes
00041 #include <cstddef>
00042 #include <string>
00043 
00044 namespace xml {
00045 
00046 // forward declarations
00047 struct tree_impl;
00048 class document;
00049 
00050 /**
00051  * The xml::tree_parser class is used to parse an XML document and generate
00052  * a tree like structure of xml::node objects. After constructing a
00053  * tree_parser, with either a file to parse or some in memory data to parse,
00054  * you can walk the tree using the xml::node interface.
00055 **/
00056 class tree_parser {
00057 public:
00058     typedef std::size_t size_type;
00059 
00060     //####################################################################
00061     /** 
00062      * xml::tree_parser class constructor. Given the name of a file, this
00063      * constructor will parse that file.
00064      *
00065      * There are two options for dealing with XML parsing errors. The
00066      * default it to throw an exception (std::runtime_error). The other
00067      * option is to pass false for the allow_exceptions flag. This will
00068      * prevent an exception from being thrown, instead, a flag will be set
00069      * that you can test with the operator! member function.
00070      *
00071      * No matter what option you choose, this constructor may still throw
00072      * exceptions for memory failure or other non-parsing related failures.
00073      *
00074      * @param filename The name of the file to parse.
00075      * @param allow_exceptions Whether or not you want an exception for parsing errors.
00076      * @author Peter Jones
00077     **/
00078     //####################################################################
00079     tree_parser (const char *filename, bool allow_exceptions=true);
00080 
00081     //####################################################################
00082     /** 
00083      * xml::tree_parser class constructor. Given some data and the size of
00084      * that data, parse that data as XML. To see if the data was parsed
00085      * successfully use operator!.
00086      *
00087      * @param data The XML data to parse.
00088      * @param size The size of the XML data to parse.
00089      * @param allow_exceptions Whether or not you want an exception for parsing errors.
00090      * @author Peter Jones
00091     **/
00092     //####################################################################
00093     tree_parser (const char *data, size_type size, bool allow_exceptions=true);
00094 
00095     //####################################################################
00096     /** 
00097      * xml::tree_parser class destructor.
00098      *
00099      * @author Peter Jones
00100     **/
00101     //####################################################################
00102     ~tree_parser (void);
00103 
00104     //####################################################################
00105     /** 
00106      * Check to see if a xml::tree_parser class is vaild. That is, check to
00107      * see if parsing XML data was successful and the tree_parser holds a
00108      * good XML node tree.
00109      *
00110      * @return True if the tree_parser is NOT VAILD; false if it is vaild.
00111      * @author Peter Jones
00112     **/
00113     //####################################################################
00114     bool operator! (void) const;
00115 
00116     //####################################################################
00117     /** 
00118      * If operator! indicates that there was an error parsing your XML data,
00119      * you can use this member function to get the error message that was
00120      * generated durring parsing.
00121      *
00122      * @return The error message generated durring XML parsing.
00123      * @author Peter Jones
00124     **/
00125     //####################################################################
00126     const std::string& get_error_message (void) const;
00127 
00128     //####################################################################
00129     /** 
00130      * Check to see if there were any warnings from the parser while
00131      * processing the given XML data. If there were, you may want to send
00132      * the same document through xmllint or the event_parser to catch and
00133      * review the warning messages.
00134      *
00135      * @return True if there were any warnings.
00136      * @return False if there were no warnings.
00137      * @author Peter Jones
00138     **/
00139     //####################################################################
00140     bool had_warnings (void) const;
00141 
00142     //####################################################################
00143     /** 
00144      * Get a reference to the xml::document that was generated during the
00145      * XML parsing. You should make sure to only use a reference to the
00146      * document to avoid a deep copy.
00147      *
00148      * @return A reference to the xml::document.
00149      * @author Peter Jones
00150     **/
00151     //####################################################################
00152     xml::document& get_document (void);
00153 
00154     //####################################################################
00155     /** 
00156      * Get a const reference to the xml::document that was generate during
00157      * the XML parsing. You should make sure to only use a reference to the
00158      * document to avoid a deep copy.
00159      *
00160      * @return A const reference to the xml::document.
00161      * @author Peter Jones
00162     **/
00163     //####################################################################
00164     const xml::document& get_document (void) const;
00165 private:
00166     tree_impl *pimpl_; // private implementation
00167 
00168     /* 
00169      * Don't allow anyone to copy construct a xml::tree_parser or allow the
00170      * assignment operator to be called. It is not very useful to copy a
00171      * parser that has already parsed half a document.
00172      */
00173     tree_parser (const tree_parser&);
00174     tree_parser& operator= (const tree_parser&);
00175 }; // end xml::tree_parser class
00176 
00177 } // end xml namespace
00178 #endif

Generated on Tue Oct 19 12:26:03 2004 for xmlwrapp by doxygen 1.3.6