include/cinder/Xml.h

Go to the documentation of this file.

/*
 Copyright (c) 2010, The Cinder Project
 All rights reserved.
 
 This code is designed for use with the Cinder C++ library, http://libcinder.org

 Redistribution and use in source and binary forms, with or without modification, are permitted provided that
 the following conditions are met:

    * Redistributions of source code must retain the above copyright notice, this list of conditions and
    the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and
    the following disclaimer in the documentation and/or other materials provided with the distribution.

 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED
 WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 POSSIBILITY OF SUCH DAMAGE.
*/

#pragma once

#include "cinder/Cinder.h"
#include "cinder/Stream.h"
#include "cinder/DataSource.h"
#include "cinder/DataTarget.h"
#include "cinder/Exception.h"
#include "cinder/Utilities.h"

#include <string>
#include <vector>

namespace rapidxml {
    template<class Ch> class xml_document;
    template<class Ch> class xml_node;
};

namespace cinder {

class XmlTree {
  public:

    typedef std::list<std::unique_ptr<XmlTree> > Container;

    class ConstIter {
      public:
        ConstIter( const Container *sequence );
        ConstIter( const Container *sequence, Container::const_iterator iter );
        ConstIter( const XmlTree &root, const std::string &filterPath, bool caseSensitive = false, char separator = '/' );

        const XmlTree&      operator*() const { return **mIterStack.back(); }
        const XmlTree*      operator->() const { return &(**mIterStack.back()); }

        ConstIter& operator++() {
            increment();
            return *this;
        }
        
        const ConstIter operator++(int) {
            ConstIter prev( *this );
            ++(*this);
            return prev; 
        }
        
        bool operator!=( const ConstIter &rhs ) { return ( mSequenceStack.back() != rhs.mSequenceStack.back() ) || ( mIterStack.back() != rhs.mIterStack.back() ); }
        bool operator==( const ConstIter &rhs ) { return ( mSequenceStack.back() == rhs.mSequenceStack.back() ) && ( mIterStack.back() == rhs.mIterStack.back() ); }
        
      protected:
        void    increment();
        void    setToEnd( const Container *seq );
        bool    isDone() const;
        
        std::vector<const Container*>               mSequenceStack;
        std::vector<Container::const_iterator>      mIterStack;
        std::vector<std::string>                    mFilter;
        bool                                        mCaseSensitive;
    };

    class Iter : public XmlTree::ConstIter {
      public:
        Iter( Container *sequence )
            : ConstIter( sequence )
        {}
        
        Iter( Container *sequence, Container::iterator iter )
            : ConstIter( sequence, iter )
        {}
    
        Iter( XmlTree &root, const std::string &filterPath, bool caseSensitive, char separator )
            : ConstIter( root, filterPath, caseSensitive, separator )
        {}

        
        XmlTree&        operator*() const { return const_cast<XmlTree&>(**mIterStack.back()); }
        XmlTree*        operator->() const { return const_cast<XmlTree*>( &(**mIterStack.back()) ); }

        Iter& operator++() {
            increment();
            return *this;
        }
        
        const Iter operator++(int) {
            Iter prev( *this );
            ++(*this);
            return prev; 
        }
        
        bool operator!=( const Iter &rhs ) { return ( mSequenceStack.back() != rhs.mSequenceStack.back() ) || ( mIterStack.back() != rhs.mIterStack.back() ); }
        bool operator==( const Iter &rhs ) { return ( mSequenceStack.back() == rhs.mSequenceStack.back() ) && ( mIterStack.back() == rhs.mIterStack.back() ); }

    };

    class Attr {
      public:
        Attr( XmlTree *xml, const std::string &name, const std::string &value )
            : mXml( xml ), mName( name ), mValue( value )
        {}

        operator const std::string&() const { return mValue; }
        template<typename T>
        Attr&   operator=( const T& val ) { mValue = toString( val ); mXml->setAttribute( mName, mValue ); return *this; }
        
        bool    operator==( const char *rhs ) const { return mValue == rhs; }
        bool    operator==( const std::string &rhs ) const { return mValue == rhs; }
        bool    operator!=( const char *rhs ) const { return mValue != rhs; }
        bool    operator!=( const std::string &rhs ) const { return mValue != rhs; }
        
        template<typename T>
        T       as() const { return fromString<T>( mValue ); }
        
        bool    empty() const { return mValue.empty(); }
        
        const std::string&      getName() const { return mName; }
        std::string             getValue() const { return mValue; }
        template<typename T>
        T                       getValue() const { return fromString<T>( mValue ); }
        
        void                    setValue( const std::string &value ) { mValue = value; }
        template<typename T>
        void                    setValue( const T &value ) { mValue = boost::lexical_cast<std::string>( value ); }

      private:
        XmlTree         *mXml;
        std::string     mName, mValue;
    };

    class ParseOptions {
      public:
        ParseOptions() : mParseComments( false ), mCollapseCData( true ), mIgnoreDataChildren( true ) {}
        
        ParseOptions& parseComments( bool parse = true ) { mParseComments = parse; return *this; }
        ParseOptions& collapseCData( bool collapse = true ) { mCollapseCData = collapse; return *this; }
        ParseOptions& ignoreDataChildren( bool ignore = true ) { setIgnoreDataChildren( ignore ); return *this; }
        
        bool    getParseComments() const { return mParseComments; }
        void    setParseComments( bool parseComments = true ) { mParseComments = parseComments; }
        bool    getCollapseCData() const { return mCollapseCData; }
        void    setCollapseCData( bool collapseCData = true ) { mCollapseCData = collapseCData; }
        bool    getIgnoreDataChildren() const { return mIgnoreDataChildren; }
        void    setIgnoreDataChildren( bool ignore = true ) { mIgnoreDataChildren = ignore; }
        
      private:
        bool    mParseComments, mCollapseCData, mIgnoreDataChildren;
    };

    typedef enum { NODE_UNKNOWN, NODE_DOCUMENT, NODE_ELEMENT, NODE_CDATA, NODE_COMMENT, NODE_DATA } NodeType;

    XmlTree() : mParent( 0 ), mNodeType( NODE_ELEMENT ) {}

    XmlTree( const XmlTree &rhs );
    XmlTree& operator=( const XmlTree &rhs );
    
    explicit XmlTree( DataSourceRef dataSource, ParseOptions parseOptions = ParseOptions() ) {
        loadFromDataSource( dataSource, this, parseOptions );
    }

    explicit XmlTree( const std::string &xmlString, ParseOptions parseOptions = ParseOptions() );

    explicit XmlTree( const std::string &tag, const std::string &value, XmlTree *parent = 0, NodeType type = NODE_ELEMENT )
        : mTag( tag ), mValue( value ), mParent( parent ), mNodeType( type )
    {}

    static XmlTree      createDoc() { return XmlTree( "", "", 0, NODE_DOCUMENT ); }

    NodeType                    getNodeType() const { return mNodeType; }
    void                        setNodeType( NodeType type ) { mNodeType = type; }
    bool                        isDocument() const { return mNodeType == NODE_DOCUMENT; }
    bool                        isElement() const { return mNodeType == NODE_ELEMENT; }
    bool                        isCData() const { return mNodeType == NODE_CDATA; }
    bool                        isComment() const { return mNodeType == NODE_COMMENT; }

    const std::string&          getTag() const { return mTag; }
    void                        setTag( const std::string &tag ) { mTag = tag; }
    
    std::string                 getValue() const { return mValue; }
    template<typename T>
    T                           getValue() const { return boost::lexical_cast<T>( mValue ); }
    template<typename T>
    T                           getValue( const T &defaultValue ) const { try { return boost::lexical_cast<T>( mValue ); } catch( ... ) { return defaultValue; } }

    void                        setValue( const std::string &value ) { mValue = value; }
    template<typename T>
    void                        setValue( const T &value ) { mValue = boost::lexical_cast<std::string>( value ); }

    bool                        hasParent() const { return mParent != NULL; }
    XmlTree&                    getParent() { return *mParent; }
    const XmlTree&              getParent() const { return *mParent; }
    
    Iter                        find( const std::string &relativePath, bool caseSensitive = false, char separator = '/' ) { return Iter( *this, relativePath, caseSensitive, separator ); }
    ConstIter                   find( const std::string &relativePath, bool caseSensitive = false, char separator = '/' ) const { return ConstIter( *this, relativePath, caseSensitive, separator ); }
    bool                        hasChild( const std::string &relativePath, bool caseSensitive = false, char separator = '/' ) const;

    XmlTree&                    getChild( const std::string &relativePath, bool caseSensitive = false, char separator = '/' );
    const XmlTree&              getChild( const std::string &relativePath, bool caseSensitive = false, char separator = '/' ) const;
    Container&          getChildren() { return mChildren; }
    const Container&    getChildren() const { return mChildren; }

    std::list<Attr>&            getAttributes() { return mAttributes; }
    const std::list<Attr>&      getAttributes() const { return mAttributes; }

    const Attr&                 getAttribute( const std::string &attrName ) const;

    const Attr                  operator[]( const std::string &attrName ) const {  if( hasAttribute( attrName ) ) return getAttribute(attrName); else return Attr( const_cast<XmlTree*>( this ), attrName, "" ); }
    Attr                        operator[]( const std::string &attrName ) {  if( hasAttribute( attrName ) ) return getAttribute(attrName); else return Attr( this, attrName, "" ); }

    const XmlTree&              operator/( const std::string &childName ) const { return getChild( childName ); }
    XmlTree&                    operator/( const std::string &childName ) { return getChild( childName ); }

    template<typename T>
    T                           getAttributeValue( const std::string &attrName ) const { return getAttribute( attrName ).getValue<T>(); }
    template<typename T>
    T                           getAttributeValue( const std::string &attrName, const T &defaultValue ) const {
            if( hasAttribute( attrName ) ) {
                try {
                    return getAttribute( attrName ).getValue<T>();
                }
                catch(...) {
                    return defaultValue;
                }
            }
            else return defaultValue;
    }

    XmlTree&                    setAttribute( const std::string &attrName, const std::string &value );
    template<typename T>
    XmlTree&                    setAttribute( const std::string &attrName, const T &value ) { return setAttribute( attrName, boost::lexical_cast<std::string>( value ) ); }
    bool                        hasAttribute( const std::string &attrName ) const;
    std::string                 getPath( char separator = '/' ) const;
    
    Iter                        begin() { return Iter( &mChildren ); }
    Iter                        begin( const std::string &filterPath, bool caseSensitive = false, char separator = '/' ) { return Iter( *this, filterPath, caseSensitive, separator ); }    
    ConstIter                   begin() const { return ConstIter( &mChildren ); }
    ConstIter                   begin( const std::string &filterPath, bool caseSensitive = false, char separator = '/' ) const { return ConstIter( *this, filterPath, caseSensitive, separator ); } 
    Iter                        end() { return Iter( &mChildren, mChildren.end() ); }
    ConstIter                   end() const { return ConstIter( &mChildren, mChildren.end() ); }
    void                        push_back( const XmlTree &newChild );

    std::string                 getDocType() const { return mDocType; }
    void                        setDocType( const std::string &docType ) { mDocType = docType; }

    friend std::ostream& operator<<( std::ostream &out, const XmlTree &xml );
    void                        write( DataTargetRef target, bool createDocument = true );

    class Exception : public cinder::Exception {
    };
    
    class ExcChildNotFound : public XmlTree::Exception {
      public:
        ExcChildNotFound( const XmlTree &node, const std::string &childPath ) throw();
      
        virtual const char* what() const throw() { return mMessage; }
      
      private:
        char mMessage[2048];
    };

    class ExcAttrNotFound : public XmlTree::Exception {
      public:
        ExcAttrNotFound( const XmlTree &node, const std::string &attrName ) throw();
              
        virtual const char* what() const throw() { return mMessage; }
      
      private:
        char mMessage[2048];
    };

    class ExcUnknownNodeType : public cinder::Exception {
    };

    std::shared_ptr<rapidxml::xml_document<char> >  createRapidXmlDoc( bool createDocument = false ) const; 

  private:
    XmlTree*    getNodePtr( const std::string &relativePath, bool caseSensitive, char separator ) const;
    void        appendRapidXmlNode( rapidxml::xml_document<char> &doc, rapidxml::xml_node<char> *parent ) const;

    static Container::const_iterator    findNextChildNamed( const Container &sequence, Container::const_iterator firstCandidate, const std::string &searchTag, bool caseSensitive );

    NodeType                    mNodeType;
    std::string                 mTag;
    std::string                 mValue;
    std::string                 mDocType; // only used on NodeType::NODE_DOCUMENT
    XmlTree                     *mParent;
    Container                   mChildren;
    std::list<Attr>             mAttributes;
    
    static void     loadFromDataSource( DataSourceRef dataSource, XmlTree *result, const ParseOptions &parseOptions );
};

std::ostream& operator<<( std::ostream &out, const XmlTree &xml );

} // namespace cinder

namespace std {

template<>
struct iterator_traits<cinder::XmlTree::Iter> {
    typedef cinder::XmlTree         value_type;
    typedef ptrdiff_t               difference_type;
    typedef forward_iterator_tag    iterator_category;
    typedef cinder::XmlTree*        pointer;
    typedef cinder::XmlTree&        reference;
};

template<>
struct iterator_traits<cinder::XmlTree::ConstIter> {
    typedef cinder::XmlTree         value_type;
    typedef ptrdiff_t               difference_type;
    typedef forward_iterator_tag    iterator_category;
    typedef const cinder::XmlTree*  pointer;
    typedef const cinder::XmlTree&  reference;
};

} // namespace std