include/EDoc/CodeBlock.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_CODEBLOCK_H
#define EDOC_CODEBLOCK_H

#include "EDoc/DictionarySpecific.h"
#include "EDoc/FunctionLoc.h"
#include "EDoc/FunctionTypeLoc.h"
#include "EDoc/TryBlock.h"
#include "EDoc/Exception.h"

#include <string>
#include <ostream>
#include <list>
#include <sstream>

namespace EDoc
{
   class PersistenceIFace;
   class IndexedDictionary;
   class Type;
   class Dictionary;
   class Function;
   class PStack;
   class Function;
   
   
   //===========================================================================
   /** \brief Represents a block of code that may call functions, throw
    * exceptions or contain try/catch blocks.
    *
    * A CodeBlock contains a list of:
    *    - function_calls
    *    - originating_exceptions
    *    - function_pointer_calls
    *    - try_blocks
    *    .
    *
    * these are considered "primary" information sources from which the derived
    * information source "possible_function_calls" is obtained.
    */
   class CodeBlock : public DictionarySpecific
   {
   public:
   
      //------------------------------------------------------------------------
      /** \brief Create a new instance that belongs to the given dictionary.
       *
       * \param dict_in See DictionarySpecific::DictionarySpecific()
       */
      CodeBlock(Dictionary* dict_in=NULL);

      //------------------------------------------------------------------------
      /** \brief Copy constructor.
       *
       * New object will belong to the same dictionary as the object being
       * copied from.
       */
      CodeBlock(const CodeBlock& right);

      //------------------------------------------------------------------------
      /** \brief Create a new instance as a copy of another instance 
       * but place this one in a different dictionary.
       */
      CodeBlock(const CodeBlock& right, Dictionary& dict_in);

      //------------------------------------------------------------------------
      /** \brief Assignment operator.
       *
       * Can be used to assign from an object that belongs to a different
       * dictionary. However you must be careful that the StringIdentifiedObject
       * objects that are being copied already exist in this dictionary OR will
       * be populated soon after the assignment.
       */
      CodeBlock& operator=(const CodeBlock& right);
      



      //------------------------------------------------------------------------
      /** \brief Read the contents of this object data from the given 
       * file persistence interface.
       *
       * Use of the PersistenceIFace requires that data be read in the same
       * order it was written (Regardless of the fact that we provide a key
       * which is primarily used for debugging purposes). 
       *
       * \param file The interface to the file from which we will load the data.
       * Using this interface allows us to easily modify the format of the file
       * being read/written without having to modify the reading/writing code.
       *
       * \param idict The IndexedDictionary object being used to load the
       * translation units data from the file. See Dictionary::Read() for more
       * information on how the IndexedDictionary is used.
       */
      void Read(PersistenceIFace& file, IndexedDictionary& idict);

      //------------------------------------------------------------------------
      /** \brief Write the contents of this objects data to the given
       * file persistence interface.
       *
       * Use of the PersistenceIFace requires that data be read in the same
       * order it was written (Regardless of the fact that we provide a key
       * which is primarily used for debugging purposes). 
       *
       * \param file The interface to the file from which we will load the data.
       * Using this interface allows us to easily modify the format of the file
       * being read/written without having to modify the reading/writing code.
       */
      void Write(PersistenceIFace& file) const;

      //------------------------------------------------------------------------
      /** \brief Will merge the contents of the given instance into the current
       * instance.
       *
       * GEBERAL INFORMATION ABOUT MERGING
       *
       * Merging is performed between two instances which MAY or MAY NOT belong
       * to different dictionaries. The idea is to create a union of the two
       * instances in a way that is meaningful for the particular object type.
       * For example merging two Type instances will require that the two
       * objects have exactly the same names and throw types, but may have
       * different types in the identical/catchable lists. 
       *
       * Merging will usually be performed starting at instances of
       * StringIdentifiedObject's when doing a Dictionary::Merge() If two of
       * these objects have the same string identifiers it will be eithre
       * possible to merge them or will cause a conflict in which case the merge
       * will fail and throw a MergeException.
       *
       * Each type will have specifics about what it means to merge them and
       * they are documented in the appropiate types documentation.
       *
       *
       *
       * INFORMATION SPECIFIC TO CodeBlock::Merge():
       *
       * This merge differs from others in that it will always be successful in
       * merging the two CodeBlock instances together, however unlike all other
       * Merge() calls this one may return a boolean value indicating if the
       * merge did not have to modify anything in order to produce the union
       * because the two were already equivilant or will return false to
       * indicate that they were not equivilant and the merge was necessary.
       *
       * This information is used by the Function::Merge() in order to resolve
       * linking together multiple implementations of a single function. See
       * Function::Merge() for more information (Especially regarding Vague
       * Linkage of Functions).
       *
       * \return Returns true if the blocks differed and right needed to be
       * merged into current, or false if the two code blocks were identical
       * and no merge needed to take place.
       */
      bool Merge(const CodeBlock& 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 Returns true if the contents of the two instances are the same.
       *
       * This treats two code blocks with the same contents but in a different 
       * order as the equivilant.
       */
      bool operator==(const CodeBlock& right) const;

      //------------------------------------------------------------------------
      /** \brief Returns true if the contents of the two instances differ.
       *
       * \see operator==()
       */
      inline bool operator!=(const CodeBlock& right) const
      {
         return !(*this == right);
      }




      //------------------------------------------------------------------------
      /** \brief Returns an amalgamated list of all function calls and possible
       * function calls.
       *
       * Note: The FunctionLoc::possible flag is set to true if this is a
       * "possible" function call.
       */
      std::list<FunctionLoc> AllFunctionCalls();

      //------------------------------------------------------------------------
      /** \brief This will populate the list of "possible_function_calls" from
       * this objects list of function_pointer_calls.
       *
       * A function pointer call is expanded into 0 or more possible function
       * calls. Basically every function whose prototype matches the function
       * pointer and whose address has been taken at some point in code is added
       * as a possible call. I.e. through the function pointer this code block
       * may possibly call those functions.
       *
       * A possible function call is marked as such with the
       * FunctionLoc::possible flag being set to true.
       *
       * Note: the expansion of calls to virtual functions into additional
       * possible calls is done in Function::ExpandCallGraph() not here.
       */
      void ExpandCallGraph(Function& function);

      //------------------------------------------------------------------------
      /** \brief Adds a possible function call to the possible_function_calls
       * list.
       *
       * This is generally used by the ExpandCallGraph() function.
       */
      void AddPossCall(FunctionLoc func);

      //------------------------------------------------------------------------
      /** \brief Traverses the heirarch of CodeBlock's (Through CatchBlock's 
       * and TryBlock's) and constructs a flat file list of all CodeBlock's
       * within this heirarchy.
       *
       * This can be used by a function to get a list of all blocks of code
       * in the function regardless of the codes heirarchy. This is useful for
       * the user to apply suppressions across an entire function.
       */
      std::list<CodeBlock*> GetAllCodeBlocks();
      
      //------------------------------------------------------------------------
      /** \brief Returns a list of originating exceptions as pointers to the
       * original Exception objects so that their values can be easily modified.
       *
       * This us used by the python wrappers in order to apply suppressions 
       * directly to originating exception objects.
       */
      std::list<EDoc::Exception*> GetOriginatingExceptions();




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

      //------------------------------------------------------------------------
      /** \brief A list of functions that this code block makes direct calls to.
       */
      std::list<FunctionLoc> function_calls;

      //------------------------------------------------------------------------
      /** \brief A list of exceptions that this code block throws directly.
       */
      std::list<Exception> originating_exceptions;

      //------------------------------------------------------------------------
      /** \brief A list of function pointer types that this code block calls.
       */
      std::list<FunctionTypeLoc> function_pointer_calls;

      //------------------------------------------------------------------------
      /** \brief A list of try blocks that are within this code block.
       */
      std::list<TryBlock> try_blocks;


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

      //------------------------------------------------------------------------
      /** \brief A list of functions that may "possibly" be called from this
       * code block indirectly.
       *
       * This is populated when expanding the call graph. It is expanded
       * based on virtual function calls and function pointer calls.
       */
      std::list<FunctionLoc> possible_function_calls;

      //------------------------------------------------------------------------
   };
   //===========================================================================
   typedef CodeBlock* CodeBlockPtr;
   typedef std::list<CodeBlock*> CodeBlockPList;
   
}

#endif // EDOC_CODEBLOCK_H

---