/*
 * Copyright (c) 1999-2000, Eric Moon.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions, and the following disclaimer.
 *
 * 2. 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.
 *
 * 3. The name of the author may not be used to endorse or promote products
 *    derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR "AS IS" AND ANY EXPRESS OR
 * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
 * OF TITLE, NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR 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.
 */


// Importer.h
//
// * PURPOSE
//   Given a stream of XML parser events, produce the object[s]
//   represented by the markup.
//
// * HISTORY
//   e.moon             30jun99   Moved actual object-building responsibility
//                      to IPersistent; this class is now internal
//                      to Cortex::XML.
//   e.moon             28jun99         Begun.  [was 'Importer']

#ifndef __Importer_H__
#define __Importer_H__

#include <list>
#include <String.h>

#include "ImportContext.h"
#include "XML.h"
#include "expat.h"

#include "cortex_defs.h"
__BEGIN_CORTEX_NAMESPACE

class Importer {

public:                                                                                                 // *** ctor/dtor
        virtual ~Importer();
        
        // constructs a format-guessing Importer (uses the
        // DocumentType registry)
        Importer(
                std::list<BString>&                                             errors);
        
        // the Importer takes ownership of the given context!
        Importer(
                ImportContext*                                                  context);
        
        // constructs a manual Importer; the given root
        // object is populated
        Importer(
                std::list<BString>&                                             errors,
                IPersistent*                                                            rootObject,
                XML::DocumentType*                                      docType);

        // the Importer takes ownership of the given context!
        Importer(
                ImportContext*                                                  context,
                IPersistent*                                                            rootObject,
                XML::DocumentType*                                      docType);

public:                                                                                                 // *** accessors

        // the import context
        const ImportContext& context() const;
        
        // matched document type
        XML::DocumentType* docType() const;
        
        // completed object (available if
        // context().state() == ImportContext::COMPLETE, or
        // if a root object was provided to the ctor)
        IPersistent* target() const;
                
public:                                                                                                 // *** operations

        // put the importer into 'identify mode'
        // (disengaged once the first element is encountered)
        void setIdentifyMode();

        // prepare to read the document after an identify cycle
        void reset();

        // handle a buffer; return false if an error occurs
        bool parseBuffer(
                const char*                                                                     buffer,
                uint32                                                                                  length,
                bool                                                                                            last);
        
public:                                                                                                 // *** internal operations

        // create & initialize parser
        void initParser();
        
        // clean up the parser
        void freeParser();
                
public:                                                                                                 // *** XML parser event hooks

        virtual void xmlElementStart(
                const char*                                                                     name,
                const char**                                                            attributes);
                
        virtual void xmlElementEnd(
                const char*                                                                     name);
                
        virtual void xmlProcessingInstruction(
                const char*                                                                     target,
                const char*                                                                     data);

        // not 0-terminated
        virtual void xmlCharacterData(
                const char*                                                                     data,
                int32                                                                                           length);
                
        // not 0-terminated
        virtual void xmlDefaultData(
                const char*                                                                     data,
                int32                                                                                           length);
                        
private:                                                                                                // *** implementation

        XML_Parser                                                                              m_parser;
        XML::DocumentType*                                              m_docType;
        
        // if true, the importer is being used to identify the
        // document type -- it should halt as soon as the first
        // element is encountered.
        bool                                                                                                    m_identify;
        
        ImportContext* const                                    m_context;

        // the constructed object: if no rootObject was provided
        // in the ctor, this is only filled in once the document
        // end tag has been encountered.        
        IPersistent*                                                                    m_rootObject;
};

__END_CORTEX_NAMESPACE
#endif /*__Importer_H__*/