/*

* Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

* 

* Description: This file contains the header file of the 

* CStifItemParser.

*

*/

#ifndef STIF_ITEM_PARSER_H

#define STIF_ITEM_PARSER_H

//  INCLUDES

#include <f32file.h>

#include <e32std.h>

#include <e32base.h>

// CONSTANTS

const TInt KMaxTag = 256; // A tag maximum length

// MACROS

// None

// DATA TYPES

// None

// FUNCTION PROTOTYPES

// None

// FORWARD DECLARATIONS

// None

// CLASS DECLARATION

// DESCRIPTION

// CStifItemParser is a STIF Test Framework StifParser class.

// Class contains a configuration file parsing operations.

class CStifItemParser

        :public CBase

    {

    public:     // Enumerations

        // Parsing type can be given when parsing string(GetString and

        // GetNextString). This enumeration indicates parsing type.

        // ENormalParsing:

        //      - Indicates normal parsing without any modifications to

        //        parsed information

        // EQuoteStyleParsing:

        //      - Indicates special parsing. This style of parsing gives to

        //        quote(" ") characters special meaning.

        //      - Information between quotes is handled as a one string. Quotes

        //        not included to information.

        enum TParsingType

            {

            ENormalParsing,     // Mode on(Default)

            EQuoteStyleParsing, // Mode off

            };

    private:    // Enumerations

    public:     // Constructors and destructor

        /**

        * Two-phased constructor.

        */

        IMPORT_C static CStifItemParser* NewL( TPtrC aSection,

                                                TInt aStartPos,

                                                TInt aLength );

        /**

        * Destructor.

        */

        ~CStifItemParser();

    public:     // New functions

        /**

        * Get a string with a tag.

        * Returns an error code and a reference to the parsed string.

         *If start tag is empty the first string will be parsed and returned.

        */

        IMPORT_C TInt GetString( const TDesC& aTag, TPtrC& aString );

        /**

        * Get next string.

        * Returns an error code and a reference to the parsed string.

        * GetString or GetInt or GetChar must be called before call

        * GetNextString method.

        */

        IMPORT_C TInt GetNextString( TPtrC& aString );

        /**

        * Get next string with a tag.

        * Returns an error code and a reference to the parsed string.

        * If start tag is empty the next string will be parsed and returned.

        * GetString or GetInt or GetChar must be called before call

        * GetNextString method.

        */

        IMPORT_C TInt GetNextString( const TDesC& aTag, TPtrC& aString );

        /**

        * Get a integer(TInt) with a tag.

        * Returns an error code and a reference to the parsed integer.

        * If start tag is empty the first integer will be parsed and returned.

        */

        IMPORT_C TInt GetInt( const TDesC& aTag, TInt& aInteger );

        /**

        * Get next integer(TInt).

        * Returns an error code and a reference to the parsed integer.

        * GetString or GetInt or GetChar must be called before call

        * GetNextInt method.

        */

        IMPORT_C TInt GetNextInt( TInt& aInteger );

        /**

        * Get next integer(TInt) with a tag.

        * Returns an error code and a reference to the parsed integer.

        * If start tag is empty the next integer will be parsed and returned.

        * GetString or GetInt or GetChar must be called before call

        * GetNextInt method.

        */

        IMPORT_C TInt GetNextInt( const TDesC& aTag, TInt& aInteger );

        /**

        * Get a integer(TUint) with a tag.

        * Returns an error code and a reference to the parsed integer.

        * If start tag is empty the first integer will be parsed and returned.

        * With TRadix parameter can convert a number into different

        * presentation(EBinary, EOctal, EDecimal and EHex).

        */

        IMPORT_C TInt GetInt( const TDesC& aTag,

                                TUint& aInteger,

                                TRadix aRadix = EDecimal );

        /**

        * Get next integer(TUint).

        * Returns an error code and a reference to the parsed integer.

        * GetString or GetInt or GetChar must be called before call

        * GetNextInt method.

        * With TRadix parameter can convert a number into different

        * presentation(EBinary, EOctal, EDecimal and EHex).

        */

        IMPORT_C TInt GetNextInt( TUint& aInteger,

                                    TRadix aRadix = EDecimal );

        /**

        * Get next integer(TUint) with a tag.

        * Returns an error code and a reference to the parsed integer.

        * If start tag is empty the next integer will be parsed and returned.

        * GetString or GetInt or GetChar must be called before call

        * GetNextInt method.

        * With TRadix parameter can convert a number into different

        * presentation(EBinary, EOctal, EDecimal and EHex).

        */

        IMPORT_C TInt GetNextInt( const TDesC& aTag,

                                    TUint& aInteger,

                                    TRadix aRadix = EDecimal );

        /**

        * Get a character with a tag.

        * Returns an error code and a reference to the parsed character.

        * If start tag is empty the first character will be parsed and

        * returned.

        */

        IMPORT_C TInt GetChar( const TDesC& aTag, TChar& aCharacter );

        /**

        * Get next character.

        * Returns an error code and a reference to the parsed character.

        * GetString or GetInt or GetChar must be called before call

        * GetNextChar method.

        */

        IMPORT_C TInt GetNextChar( TChar& aCharacter );

        /**

        * Get next character with a tag.

        * Returns an error code and a reference to the parsed character.

        * If start tag is empty the next character will be parsed and returned.

        * GetString or GetInt or GetChar must be called before call

        * GetNextChar method.

        */

        IMPORT_C TInt GetNextChar( const TDesC& aTag, TChar& aCharacter );

        /**

        * Get remaining strings.

        * Returns an error code and a reference to the remainder of the 

        * parsed line.

        * Note: This method does not support the quote(TParsingType) feature,

        * only GetString and GetNextString methods include support.

        */

        IMPORT_C TInt Remainder( TPtrC& aString );

        /**

        * Parsing type can be given when parsing string(GetString and

        * GetNextString). See TParsingType enumeration for more

        * inforamtion.

        */

        IMPORT_C TInt SetParsingType( CStifItemParser::TParsingType aType );

        /**

        * Get current parsing type. Please see TParsingType enumeration for

        * more inforamtion.

        */

        IMPORT_C CStifItemParser::TParsingType ParsingType();

    public:     // Functions from base classes

    protected:  // New functions

    protected:  // Functions from base classes

    private:

        /**

        * C++ default constructor.

        */

        CStifItemParser( TPtrC aSection,

                            TInt aStartPos,

                            TInt aLength );

        /**

        * By default Symbian OS constructor is private.

        */

        void ConstructL();

        /**

        * Generig start and end position parser for given data.

        * Returns an error code.

        */

        TInt ParseStartAndEndPos( TPtrC aSection,

                                    const TDesC& aStartTag,

                                    TInt& aStartPos,

                                    TInt& aEndPos,

                                    TInt& aLength,

                                    TInt& aExtraEndPos );

    public:     // Data

    protected:  // Data

    private:    // Data

        /**

        * Parsed section with GetItemLineL() or GetNextItemLineL() method.

        */

        TPtrC                           iItemLineSection;

        /**

        * Indicates position where start the parsing.

        */

        TInt                            iItemSkipAndMarkPos;

        /**

        * Indicator is GetString(), GetInt() or GetChar() called.

        */

        TBool                           iGetMethodsIndicator;

        /**

        * Parsing type indicator for GetString and GetNextString use.

        */

        CStifItemParser::TParsingType   iParsingType;

    public:     // Friend classes

        /**

        * For testing operations to get length information.

        */

        friend class CTestParser;

    protected:  // Friend classes

    private:    // Friend classes

    };

#endif      // STIF_ITEM_PARSER_H

// End of File