/*
 * $Id: eaxp.h,v 1.12 2006/10/20 12:41:21 matti Exp $
 *
 * EAXP - Lightweight XML SAX parser for Symbian Environments
 * Copyright (C) 2004-2006 Matti Dahlbom
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * Contact: Matti Dahlbom <matti at 777-team.org>
 */

#ifndef __EAXP_PARSER_H
#define __EAXP_PARSER_H

#include <e32base.h>

_LIT( KStrTrue, "true" );
_LIT( KStrFalse, "false" );

namespace Eaxp 
    {

    /**
    * Replaces all carriage returns and newlines with whitespace characters and 
    * removes any leading/trailing whitespaces, and replaces all consequental 
    * whitespaces within the string with a single whitespace.
    */
    void XMLStringTrim(TPtr aPtr);

    /**
    * Element attribute.<p />
    *
    * @author Matti Dahlbom
    * @version $Name: EAXP_20102006 $, $Revision: 1.12 $
    */
    class CAttribute : public CBase
    {
        public:
            static CAttribute* NewL( const TDesC& aName, 
                                     const TDesC& aNamespace, 
                                     const TDesC& aValue );
            ~CAttribute();

            IMPORT_C const TDesC& GetName() const;
            IMPORT_C const TDesC& GetNamespace() const;
            IMPORT_C const TDesC& GetValue() const;
        private:
            CAttribute();
            void ConstructL(const TDesC &aName, const TDesC &aNamespace, const TDesC &aValue);

            // attribute name
            HBufC *iName;

            // attribute name space
            HBufC *iNamespace;

            // attribute value
            HBufC *iValue;
    };
    }

using namespace Eaxp;

/**
 * Attribute list type
 */
typedef RPointerArray<Eaxp::CAttribute> RAttributeList;

/**
 * The SAX event listener.<p />
 *
 * @author Matti Dahlbom
 * @version $Name: EAXP_20102006 $, $Revision: 1.12 $
 */
class MSAXEventListener
{
    public:
        virtual void StartElement( const TDesC& aName, 
                                   const TDesC& aNamespace, 
                                   const RAttributeList& aAttrList ) = 0;
        virtual void EndElement( const TDesC& aName,
                                 const TDesC& aNamespace ) = 0;
        virtual void FreeText( const TDesC& aText ) = 0;
        virtual void ParsingError( const TDesC& aReason ) = 0;
        virtual void Comment( const TDesC& aCommentText ) = 0;
};

struct TEscapedCharMapping 
{
    TBuf<8> iEscape;
    TChar iChar;
};

// parser constants
const TUint KEquals         = '=';
const TUint KLessThan       = '<';
const TUint KGreaterThan    = '>';
const TUint KNewline        = '\n';
const TUint KCarriageReturn = '\r';
const TUint KTab            = '\t';
const TUint KSlash          = '/';
const TUint KWhitespace     = ' ';
const TUint KColon          = ':';
const TUint KDoubleQuote    = '\"';
const TUint KApostrophe     = '\'';
const TUint KQuestionMark   = '?';
const TUint KAmpersand      = '&';
const TUint KSemicolon      = ';';
const TUint KLeftBracket    = '[';
const TUint KRightBracket   = ']';
const TUint KDash           = '-';

// CDATA section tokens
_LIT(KCDataSectionStart, "![CDATA[");
_LIT(KCDataSectionEnd, "]]");

// Comment node tokens
_LIT( KCommentSectionStart, "!--" );
_LIT( KCommentSectionEnd, "--" );

// parser core states
enum TCoreParserState {
    ECoreNullState = 1,
    ECoreParsingElement, 
    ECoreParsingFreeText
};

// attribute list parsing states
enum TAttrParserState {
    EAttrNullState = 1,
    EAttrParsingAttrName,
    EAttrParsingAttrValue
};

// parsing error leave code
const TInt KErrParsingError = 167899;

/**
 * The EAXP SAX parser.<p />
 *
 * @author Matti Dahlbom
 * @version $Name: EAXP_20102006 $, $Revision: 1.12 $
 */
class CEAXPParser : public CBase
{
    public:
        /**
         * Constructs a new parser
         *
         * @aListener SAX event listener
         */
        IMPORT_C static CEAXPParser* NewL( MSAXEventListener& aListener );

        /**
         * Constructs a new parser. Leaves the instance on the cleanup stack.
         *
         * @aListener SAX event listener
         */
        IMPORT_C static CEAXPParser* NewLC( MSAXEventListener& aListener );

        /**
         * Destructor. Deallocates all parser resources.
         */
        ~CEAXPParser();

        /**
         * Parses the given XML document. The method returns ETrue if the parsing was 
         * successful and EFalse if not. If there is a more serious error, the method
         * leaves with the given leave code.<P>
         *
         * As the parsing advances, the methods of the given 
         * <code>MSAXEventListener</code> get called.<P>
         *
         * @param aDocument XML document
         * @return whether parsing succeeded or not
         */
        IMPORT_C TBool ParseL(const TDesC &aDocument);

        /**
         * Convenience method for parsing 8-bit content (read from a file, for example).<p />
         */
        IMPORT_C TBool ParseL( const TDesC8& aDocument );

    private:
        CEAXPParser(MSAXEventListener &aListener);
        void ConstructL();
        void AllocateDefaultSizeBuffersL();
        void AddEscapeMappingL(const TDesC &aEscape, TChar aChar);
        
        void ParseImplL();
        void ProcessElementL(const TLex &aLex);
        void ProcessCDATASectionL(TLex &aLex);
        void ProcessCommentSectionL( TLex& aLex );
        TPtrC FindElementNameL(const TPtrC &aElement, TInt &aEndOffset);
        void ParseNameL(const TPtrC &aNameBuf, TPtrC &aName, TPtrC &aNamespace);
        void ParseAttributeListL(const TPtrC &aAttrBuf, RAttributeList &aAttrList,
                                 TBool &aEndElement);
        void IllegalCharacterMetL(TChar aChar);
        void ValidateSizeAndCopyL(HBufC **aTo, const TDesC &aFrom);
        void ValidateSizeL(HBufC **aBuf, TInt aSize);
        void UnescapeL(const TPtrC &aFrom, TBool aTrim = EFalse);
        TChar FindEscapeL(const TPtrC &aEscape);

        // SAX event listener
        MSAXEventListener &iListener;

        // the document being parsed
        TPtrC iDocument;

        // line number being parsed
        TInt iLineNum;

        // core parser state
        TCoreParserState iCoreState;

        // paring error reason buffer
        TBuf<128> iErrorReason;

        // attribute parsing resources
        HBufC *iAttrName;
        HBufC *iAttrValue;

        // free text buffer
        HBufC *iFreeText;

        // unescape buffer
        HBufC *iUnescapeBuffer;

        // escape character mapping table
        TEscapedCharMapping *iEscapedCharMap; 
        TInt iEscapeMapCapacity;
        TInt iNumEscapeMappings;
};

#endif