nxsreader.h

//  Copyright (C) 1999-2003 Paul O. Lewis
//
//  This file is part of NCL (Nexus Class Library) version 2.0.
//
//  NCL is free software; you can redistribute it and/or modify
//  it under the terms of the GNU General Public License as published by
//  the Free Software Foundation; either version 2 of the License, or
//  (at your option) any later version.
//
//  NCL 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 General Public License for more details.
//
//  You should have received a copy of the GNU General Public License
//  along with NCL; if not, write to the Free Software Foundation, Inc.,
//  59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
//

#ifndef NCL_NXSREADER_H
#define NCL_NXSREADER_H

#include "ncl/nxsdefs.h"
#include "ncl/nxsstring.h"
#include "ncl/nxsexception.h"
#include "ncl/nxstoken.h"

class NxsBlock;
class NxsBlockFactory;
class NxsTaxaBlockFactory;
class NxsAssumptionsBlockAPI;
class NxsCharactersBlockAPI;
class NxsTaxaBlockAPI;
class NxsTreesBlockAPI;

typedef std::list<NxsBlock *> BlockReaderList;
typedef std::map<std::string, BlockReaderList> BlockTypeToBlockList;


class NxsReader
    {
        static void installNCLSignalHandler();
        static void uninstallNCLSignalHandler();
    public:
        enum WarningHandlingMode
            {
            IGNORE_WARNINGS,  
            WARNINGS_TO_STDERR, 
            WARNINGS_TO_STDOUT, 
            WARNINGS_ARE_ERRORS 
            };
        enum NxsWarnLevel
            {
            UNCOMMON_SYNTAX_WARNING = 0,  
            SKIPPING_CONTENT_WARNING = 1, 
            OVERWRITING_CONTENT_WARNING = 2, 
            DEPRECATED_WARNING = 3, 
            AMBIGUOUS_CONTENT_WARNING = 4, 
            ILLEGAL_CONTENT_WARNING = 5, 
            PROBABLY_INCORRECT_CONTENT_WARNING = 6, 
            FATAL_WARNING = 7, 
            SUPPRESS_WARNINGS_LEVEL = 8 
            };

        static void setNCLCatchesSignals(bool);
        static bool getNCLCatchesSignals();
        static unsigned getNumSignalIntsCaught();
        static void setNumSignalsIntsCaught(unsigned);


                        NxsReader();
        virtual         ~NxsReader();


        // functions to add and remove Block reader objects or factories for block readers.
        virtual void    Add(NxsBlock *newBlock);
        void            Detach(NxsBlock *newBlock);
        virtual void    AddFactory(NxsBlockFactory *);
        void            RemoveFactory(NxsBlockFactory *);

        // trigger for NEXUS parsing.
        virtual void    Execute(NxsToken& token, bool notifyStartStop = true);

        // shortcuts for calling execute...
        void            ReadFilepath(const char *filename);
        void            ReadFilestream(std::istream & inf);
        void            ReadStringAsNexusContent(const std::string & s);

        virtual void    DebugReportBlock(NxsBlock &nexusBlock);

        const char      *NCLNameAndVersion();
        const char      *NCLCopyrightNotice();
        const char      *NCLHomePageURL();

        // hooks for subclasses to specialize the behavior
        virtual void    ExecuteStarting();
        virtual void    ExecuteStopping();
        virtual bool    EnteringBlock(NxsString blockName);
        virtual void    ExitingBlock(NxsString blockName);
        virtual void    OutputComment(const NxsString &comment);
        virtual void    SkippingDisabledBlock(NxsString blockName);
        virtual void    SkippingBlock(NxsString blockName);

        virtual void    NexusWarn(const std::string &s, NxsWarnLevel warnLevel, file_pos pos, long line, long col)
            {
            if (warnLevel >= PROBABLY_INCORRECT_CONTENT_WARNING)
                {
                NxsString e(s.c_str());
                throw NxsException(e, pos, line, col);
                }
            }
        void    NexusWarnToken(const std::string &m, NxsWarnLevel warnLevel, const ProcessedNxsToken &token)
            {
            NexusWarn(m , warnLevel, token.GetFilePosition(), token.GetLineNumber(), token.GetColumnNumber());
            }
        void    NexusWarnToken(const std::string &m, NxsWarnLevel warnLevel, const NxsToken &token)
            {
            NexusWarn(m , warnLevel, token.GetFilePosition(), token.GetFileLine(), token.GetFileColumn());
            }

        virtual void    NexusError(NxsString msg, file_pos pos, long line, long col);



        virtual void            ClearUsedBlockList();
        NxsBlock               *CreateBlockFromFactories(const std::string & currBlockName, NxsToken &token, NxsBlockFactory **sourceOfBlock = NULL);
        BlockReaderList         GetUsedBlocksInOrder();
        BlockReaderList         GetBlocksFromLastExecuteInOrder();
        BlockTypeToBlockList    GetUsedBlocks();
        std::set<NxsBlock*>     GetSetOfAllUsedBlocks();

        NxsTaxaBlockAPI         *GetLastStoredTaxaBlock();
        NxsCharactersBlockAPI   *GetLastStoredCharactersBlock();
        NxsTreesBlockAPI        *GetLastStoredTreesBlock();


        NxsTaxaBlockAPI         *GetTaxaBlockByTitle(const char *title, unsigned *nMatches);
        NxsCharactersBlockAPI   *GetCharBlockByTitle(const char *title, unsigned *nMatches);
        NxsTreesBlockAPI        *GetTreesBlockByTitle(const char *title, unsigned *nMatches);

        NxsTaxaBlockFactory     *GetTaxaBlockFactory();
        //NxsCharactersBlockFactory     *GetCharBlockFactory();
        //NxsTreesBlockFactory  *GetTreesBlockFactory();

        void            SetTaxaBlockFactory(NxsTaxaBlockFactory *);
        //void          SetCharBlockFactory(NxsCharactersBlockFactory *);
        //void          SetTreesBlockFactory(NxsTreesBlockFactory *);

        virtual void    DeleteBlocksFromFactories();
        unsigned        RemoveBlockFromUsedBlockList(NxsBlock *);

        virtual void    ClearContent();

        virtual void AddReadBlock(const NxsString &blockID, NxsBlock *block)
            {
            this->BlockReadHook(blockID, block);
            }

        void cullIdenticalTaxaBlocks(bool v=true)
            {
            this->destroyRepeatedTaxaBlocks = v;
            }
        std::vector<std::string> GetAllTitlesForBlock(const NxsBlock *b) const;


        void SetAlwaysReportStatusMessages(bool v) {
            this->alwaysReportStatusMessages = v;
        }
        void SetWarningOutputLevel(NxsWarnLevel lev) {
            currentWarningLevel = lev;
        }
        NxsWarnLevel GetWarningOutputLevel() const {
            return currentWarningLevel;
        }

        virtual void statusMessage(const std::string & m) const;

        bool            BlockListEmpty();
        unsigned        PositionInBlockList(NxsBlock *b);

        void            Reassign(NxsBlock *oldb, NxsBlock *newb);

        void AssignBlockPriority(NxsBlock *b, int priorityLevel);
        int GetBlockPriority(NxsBlock *b) const;
        void DemoteBlocks(int priorityLevel=-1);
    protected:
        static          BlockReaderList parseFileWithReader(NxsReader & reader, const char *filepath, bool parsePrivateBlocks=true, bool storeTokenInfo=true);
        static bool nclCatchesSignals; // default False;
        typedef void (*SignalHandlerFuncPtr) (int);
        static SignalHandlerFuncPtr prevSignalCatcher; // the signal handler that was installed before NCL's signal handler
        static unsigned numSigIntsCaught;
        static bool prevSignalStored ;

        void            CoreExecutionTasks(NxsToken& token, bool notifyStartStop = true);


        void            AddBlockToUsedBlockList(const std::string &, NxsBlock *, NxsToken *);
        bool            BlockIsASingeltonReader(NxsBlock *) const ;
        void            BlockReadHook(const NxsString &currBlockName, NxsBlock *currBlock, NxsToken *token = NULL );
        bool            ExecuteBlock(NxsToken &token, const NxsString &currBlockName, NxsBlock *currBlock, NxsBlockFactory * sourceOfBlock);
        NxsBlock       *FindBlockOfTypeByTitle(const std::string &btype, const char *title, unsigned *nMatches);
        NxsBlock       *FindBlockByTitle(const BlockReaderList & chosenBlockList, const char *title, unsigned *nMatches);
        BlockReaderList FindAllBlocksByTitle(const BlockReaderList & chosenBlockList, const char *title);
        NxsBlock       *GetLastStoredBlockByID(const std::string &key);
        NxsTaxaBlockAPI *GetOriginalTaxaBlock(const NxsTaxaBlockAPI *) const;
        bool            IsRepeatedTaxaBlock(const NxsTaxaBlockAPI *) const;
        void            NewBlockTitleCheckHook(const std::string &blockname, NxsBlock *p, NxsToken *token);
        bool            ReadUntilEndblock(NxsToken &token, const std::string & currBlockName);
        void            RegisterAltTitle(const NxsBlock * b, std::string t);
        std::set<NxsBlock *> RemoveBlocksFromFactoriesFromUsedBlockLists();
        virtual void    PostBlockReadingHook(NxsBlock &);


        NxsBlock        *blockList; /* pointer to first block in list of blocks */
        NxsBlock        *currBlock; /* pointer to current block in list of blocks */
        typedef std::list<NxsBlockFactory *> BlockFactoryList;
        NxsTaxaBlockFactory *taxaBlockFactory;
        BlockFactoryList factories; /* list of pointers to factories capable of creating NxsBlock objects*/
        bool destroyRepeatedTaxaBlocks;
        NxsWarnLevel currentWarningLevel;
        bool alwaysReportStatusMessages;

    private:

        BlockReaderList FindAllBlocksByTitleNoPrioritization(const BlockReaderList & chosenBlockList, const char *title);

        BlockReaderList blocksInOrder;
        std::map<NxsBlock *, int> blockPriorities;

        BlockReaderList lastExecuteBlocksInOrder;
        BlockTypeToBlockList blockTypeToBlockList;
        typedef std::pair<unsigned, std::list<std::string> > NxsBlockTitleHistory;
        typedef std::map<std::string, NxsBlockTitleHistory > NxsBlockTitleHistoryMap;
        NxsBlockTitleHistoryMap blockTitleHistoryMap;
        std::map<const NxsBlock *, std::list<std::string> > blockTitleAliases; // to deal with culling blocks and then using the titles of culled copies


    };

typedef NxsBlock NexusBlock;
typedef NxsReader Nexus;

class ExceptionRaisingNxsReader : public NxsReader
    {
    public:
        ExceptionRaisingNxsReader(NxsReader::WarningHandlingMode mode=NxsReader::WARNINGS_TO_STDERR)
            :warnMode(mode),
            warningToErrorThreshold(PROBABLY_INCORRECT_CONTENT_WARNING)
            {}
        void NexusError(NxsString msg, file_pos pos, long line, long col)
            {
            throw NxsException(msg, pos, line, col);
            }
        virtual void NexusWarn(const std::string & msg, NxsWarnLevel level, file_pos pos, long line, long col);

        void SkippingBlock(NxsString blockName);
        void SkippingDisabledBlock(NxsString blockName);
        void SetWarningToErrorThreshold(int t)
            {
            warningToErrorThreshold = t;
            }
        virtual void ClearContent()
            {
            NxsReader::ClearContent();
            }
    private:
        NxsReader::WarningHandlingMode warnMode;
        int warningToErrorThreshold;
    };

class DefaultErrorReportNxsReader : public NxsReader
    {
    public:
        static BlockReaderList parseFile(const char *filepath, std::ostream * stdOutstream, std::ostream * errOutstream, bool parsePrivateBlocks=true, bool storeTokenInfo=true);
        DefaultErrorReportNxsReader(std::ostream * stdOutstream, 
                                    std::ostream * errOutstream) 
            :NxsReader(),
            stdOut(stdOutstream),
            errOut(errOutstream)
            {
            }

        virtual ~DefaultErrorReportNxsReader() {}

        virtual bool EnteringBlock(NxsString )
            {
            return true;
            }

        void SkippingBlock(NxsString blockName)
            {
            if (stdOut != 0L)
                {
                *stdOut << "[!Skipping unknown block (" << blockName << ")...]\n";
                stdOut->flush();
                }
            }

        void SkippingDisabledBlock(NxsString blockName)
            {
            if (stdOut != 0L)
                {
                *stdOut << "[!Skipping disabled block (" << blockName << ")...]\n";
                stdOut->flush();
                }
            }

        void NexusWarn(const std::string & msg, 
                        NxsWarnLevel warnLevel, 
                        file_pos pos, long line, long col)
            {
            if (warnLevel < currentWarningLevel)
                return;
            if (warnLevel >= PROBABLY_INCORRECT_CONTENT_WARNING)
                {
                NxsString e(msg.c_str());
                throw NxsException(e, pos, line, col);
                }
            if (errOut != 0)
                {
                *errOut << "\nWarning:  ";
                if (line > 0 || pos > 0)
                    *errOut << "at line " << line << ", column " << col << " (file position " << pos << "):\n";
                *errOut  << msg << std::endl;
                }
            else if (stdOut != 0L)
                {
                *stdOut << "\nWarning:  ";
                if (line > 0 || pos > 0)
                    *stdOut << "at line " << line << ", column " << col << " (file position " << pos << "):\n";
                *stdOut  << msg << std::endl;
                }
            }

        void NexusError(NxsString msg, file_pos pos, long line, long col)
            {
            NexusWarn(msg, NxsReader::FATAL_WARNING, pos, line, col);
            throw NxsException(msg, pos, line, col);
            }

        std::ostream * stdOut;
        std::ostream * errOut;
    };

inline BlockTypeToBlockList NxsReader::GetUsedBlocks()
    {
    return blockTypeToBlockList;
    }

inline bool NxsReader::IsRepeatedTaxaBlock(const NxsTaxaBlockAPI * testB) const
    {
    return (GetOriginalTaxaBlock(testB) != NULL);
    }


inline BlockReaderList NxsReader::GetUsedBlocksInOrder()
    {
    return blocksInOrder;
    }

inline BlockReaderList NxsReader::GetBlocksFromLastExecuteInOrder()
    {
    return lastExecuteBlocksInOrder;
    }

inline NxsTaxaBlockFactory * NxsReader::GetTaxaBlockFactory()
    {
    return this->taxaBlockFactory;
    }



#endif

---