include/EDoc/PropogatingException.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_PROPOGATINGEXCEPTION_H
#define EDOC_PROPOGATINGEXCEPTION_H

#include "EDoc/DictionarySpecific.h"
#include "EDoc/Location.h"
#include "EDoc/FunctionLoc.h"

#include <list>
#include <vector>

namespace EDoc
{
   class Exception;
   class PStack;
   
   //===========================================================================
   /** \brief Represents an exception that propogates out a function.
    *
    * Note this may also represent an exception that originates from the same
    * function (Originating exception) in which case the function in its "from"
    * field is the function that also holds the reference to this propogating
    * exception instance.
    */
   class PropogatingException : public DictionarySpecific
   {
   public:

      //------------------------------------------------------------------------
      /** \brief Constructs a new propogating exception object belonging to
       * the given Dictionary initialising with given values.
       */
      PropogatingException(Dictionary& dict_in, Exception* exception_in, 
         FunctionLoc& from_in);

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

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

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

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

      //------------------------------------------------------------------------
      /** \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).
       *
       * NOTE: Does not look at the rethrow list for equality.
       */
      bool operator==(const PropogatingException& right) const;
      

      //------------------------------------------------------------------------
      /** \brief Returns true if this exception is visible.
       *
       * This will only return true if all of the following are visible:
       *    - PropogatingException::visible - this instance
       *    - Exception::visible - The originating exception for this pe found
       *       in member: exception.
       *    - Type::visible - The type for the originating exception.
       *    .
       */
      bool IsVisible() const;
      


      //------------------------------------------------------------------------
      /** \brief A reference to the exception object that this propogating
       * exception originates from.
       */
      Exception* exception;
      
      //------------------------------------------------------------------------
      /** \brief Has two usages.
       *
       * Usages include:
       *    -# Exception propogates from another function. In this case this
       *       contains the reference to the function from which this exception
       *       comes and ALSO the source code Location where the call to that
       *       function is made.
       *    -# Exception originates from THIS function. This is when a function
       *       directly throws an exception with the C++ throws statement. In
       *       this case the function reference is NULL 
       *       and the Location is the location in source where the exception 
       *       is Dictionary::UNKNOWN_LOCATION
       *    .
       */
      FunctionLoc func;

      //------------------------------------------------------------------------
      /** \brief A list of Exception objects that indicate where in this
       * functions implementation that the current exception may have been
       * "re-thrown".
       *
       * List of the throw ... statements that have been used to rethrow this
       * exception.
       */
      std::list<Exception*> rethrows;

      //------------------------------------------------------------------------
      /** \brief True if this exception is propogated from a "possible" function
       * call and is not a definite propogation.
       */
      // @@@Brendon I dont think this is needed. I could just use func.possible
      // instead!
      bool possible;

      //------------------------------------------------------------------------
      /** \brief True if this exception is visible to the user or false if 
       * this exception will never be displayed to the user.
       *
       * This is used for suppressions.
       */
      bool visible;


      //------------------------------------------------------------------------
      // Data used to flag this propagating exception is the original 
      // substitution exception. This is omitted from certain processing.
      //------------------------------------------------------------------------
      /** \brief 
       */
      bool orig_subst;

      //------------------------------------------------------------------------

   };
   //===========================================================================
   typedef std::list<PropogatingException> PropExcepList;
   typedef std::list<PropogatingException*> PropExcepPList;

}

#endif // EDOC_PROPOGATINGEXCEPTION_H

---