include/EDoc/Exception.h

Go to the documentation of this file.

/*******************************************************************************

   Copyright (C) 2007 by Brendon Costa

   This library is free software; you can redistribute it and/or modify 
   it under the terms of the "LGPL Like" License defined in the file COPYING 
   that should have been distributed along with this source.

   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.  

   You should have received a copy of the "LGPL Like" License 
   along with this library; see the file COPYING. if not, it can be 
   obtained from the EDoc++ website: 
   http://edoc.sourceforge.net/license.html

*******************************************************************************/
#ifndef EDOC_EXCEPTION_H
#define EDOC_EXCEPTION_H

#include "EDoc/DictionarySpecific.h"
#include "EDoc/TypeLoc.h"

#include <list>

namespace EDoc
{
   class Function;
   class PropogatingException;
   class PStack;
   
   //===========================================================================
   /** \brief Represents a throw statement in C++ code.
    *
    * This exception object is generated for any code that contains a throw
    * statement. Rethrows are also represented with this class using a type with
    * name "...".
    *
    * All throw statements that generate a new exception are also called
    * "Originating Exceptions". Originating exceptions are the source of
    * propogating exceptions, this terminology is important to remember when
    * reading code or documentation about EDoc.
    *
    * An exception instance will include primary data about the type in a
    * TypeLoc instance called type. This stores a reference to the type of the
    * exception being thrown ("..." type for rethrow exceptions) and location
    * information indicating at what line and in which source file this throw
    * statement can be found.
    */
   class Exception : public DictionarySpecific
   {
      friend class PropogatingException;
   public:

      //------------------------------------------------------------------------
      /** \brief See CodeBlock::CodeBlock(Dictionary* dict_in=NULL)
       */
      Exception(Dictionary* dict_in=NULL);

      //------------------------------------------------------------------------
      /** \brief See CodeBlock::CodeBlock(const CodeBlock& right)
       */
      Exception(const Exception& right);

      //------------------------------------------------------------------------
      /** \brief See CodeBlock::CodeBlock(const CodeBlock& right, 
       * Dictionary& dict_in)
       */
      Exception(const Exception& right, Dictionary& dict_in);

      //------------------------------------------------------------------------
      /** \brief See CodeBlock::operator=()
       */
      Exception& operator=(const Exception& right);



      //------------------------------------------------------------------------
      /** \brief See CodeBlock::Read()
       */
      void Read(PersistenceIFace& file, IndexedDictionary& idict);

      //------------------------------------------------------------------------
      /** \brief See CodeBlock::Write()
       */
      void Write(PersistenceIFace& file) const;

      //------------------------------------------------------------------------
      /** \brief See DictionarySpecific::ReplaceReferences()
       */
      virtual size_t ReplaceReferences(PStack& stack, 
         void* remove, void* replace);

      //------------------------------------------------------------------------
      /** \brief See DictionarySpecific::Print()
       */
      virtual std::ostream& Print(std::ostream& out, 
         std::string prefix="") const;

      //------------------------------------------------------------------------
      /** \brief See DictionarySpecific::Validate()
       */
      virtual void Validate(PStack& stack, const Dictionary& dict_in) const;

      //------------------------------------------------------------------------
      /** \brief Equivilance operator (Works across dictionaries).
       *
       * \return Returns true if the type being thrown is the same and the
       * location it is being thrown from is also the same.
       */
      bool operator==(const Exception& right) const;


      //------------------------------------------------------------------------
      // Public Primary Data values.
      //------------------------------------------------------------------------

      //------------------------------------------------------------------------
      /** \brief Stores the type and location in the source from which it is
       * thrown.
       */
      TypeLoc type;
      

      //------------------------------------------------------------------------
      // Suppression Data values.
      //------------------------------------------------------------------------

      //------------------------------------------------------------------------
      /** \brief True if this exception is visible to the user or false if 
       * this exception will never be shown to the user.
       *
       * This is used for suppressions.
       */
      // @@@Brendon Add to doxygen suppressions group?
      bool visible;

      //------------------------------------------------------------------------
      /** \brief True if this exception was created automatically by EDoc++
       * as a throw spec exception.
       *
       * I.e. This is an exception that does not actually exist in the code
       * but represents wnat is possible based on the functions specifiers.
       */
      bool auto_throw_spec;

      //------------------------------------------------------------------------
      // Public Derived Data values.
      //------------------------------------------------------------------------

      //------------------------------------------------------------------------
      /** \brief Function from which exception originates.
       *
       * This is populated by Dictionary::CalculatePropogatingExceptions() but
       * NULL before then.
       */
      Function* function;

      //------------------------------------------------------------------------
   };
   //===========================================================================
   typedef std::list<Exception> ExcepList;
   typedef std::list<Exception*> ExcepPList;
}

#endif // EDOC_EXCEPTION_H

---