include/EDoc/DictionarySpecific.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_DICTIONARYSPECIFIC_H
#define EDOC_DICTIONARYSPECIFIC_H

#include "EDoc/stdint.h"
#include <string>
#include <iostream>


namespace EDoc
{
   class Dictionary;
   class PStack;
   class ManagedObject;
   
   
   //===========================================================================
   /** \brief Encapsulates functionality common to all dictionary specific
    * types.
    *
    * A dictionary specific type is a type/class which "belongs" to a particular
    * instance of the Dictionary class. Objects that belong to one dictionary
    * can NOT be referenced by object from another dictionary. They need to be
    * specially copied/merged. For this reason there is special processing that
    * occurs for assignment and copies of dictionary specific objects to ensure
    * that these rules are not violated.
    *
    *
    * HISTORY
    *
    * This was done because the other option was to use identifiers and lookups
    * or copies of all the data. Initially this was attempted but processing
    * time and memory usage were enormous, so the method was changed in order to
    * store pointers directly to members. However objects can only store
    * pointers to other members that belong to the same Dictionary instance.
    * This means that when a dictionary object is destroyed along with all
    * objects that "belong" to it, no other objects are invalidated.
    *
    * As a result this class was created in order to simplify management of
    * these objects.
    *
    * All DictionarySpecific objects have functionality to replace pointer
    * references and to validate themselves. 
    *
    * \see See Dictionary.
    */
   class DictionarySpecific
   {
      friend class ManagedObject;
   public:

      //------------------------------------------------------------------------
      /** \brief Create this dictionary specific object belonging to the given
       * dictionary.
       *
       * \param dict_in The dictionary that this object will belong to
       * if NULL then will use the dictionary that can be obtained by:
       * GetCurrentDictionaryAssert()
       */
      DictionarySpecific(Dictionary* dict_in);
   
      //------------------------------------------------------------------------
      /** \brief Destructor.
       */
      virtual ~DictionarySpecific() {}

      //------------------------------------------------------------------------
      /** \brief Replaces all references of pointers referencing remove with
       * pointers to replace.
       *
       * The replacement is used because when after Read()'ing it is possible to
       * have two instances of an object indexed by the same key. The contents
       * of them must be merged and all references to one object be changed to
       * reference the other. Then the now unreferenced object would be deleted.
       * This is a part of the loading phase and is a result of the fact that
       * GCC can generate multiple tree nodes for a single type. Thus when
       * loading we often get the same type multiple times. 
       *
       * \todo As an option in the future we may choose to allow replace to be a
       * NULL pointer. In which case it will completely erase references to a
       * particular object instead of having to replace them with something
       * else. This works for containers, but for non-optional fixed pointers it
       * may cause some problems. Maybe in these cases, we should throw an
       * exception that indicates to the user that they cant just erase that
       * reference, they must at least replace it in some places with something
       * or first erase other nodes that reference it first. This exception
       * would need to include as its data a reference to the object that cant
       * release its reference to "remove".
       */
      virtual size_t ReplaceReferences(PStack& stack, 
         void* remove, void* replace) = 0;

      //------------------------------------------------------------------------
      /** \brief Print the current object to the given stream in a user readable
       * manner.
       *
       * \param out The stream to print to.
       *
       * \param prefix A string prefix to display at the start of every line. As
       * an example this can be used in order to indent the print by passing
       * "\t" as the string.
       */
      virtual std::ostream& Print(std::ostream& out, 
         std::string prefix="") const = 0;

      //------------------------------------------------------------------------
      /** \brief Returns a string representing the current object in a user
       * readable manner.
       *
       * This will return as a string exactly what Print() would display. This
       * is primarily here for use from within python and for debugging.
       */
      std::string ToString(std::string prefix="") const;

      //------------------------------------------------------------------------
      /** \brief Performs internal valtidation on the current object and will
       * throw a BugException if the validation fails.
       *
       * This is primarily used to ensure that all DictionarySpecific objects
       * are internally consistent, not referencing dictionaries that they
       * actually do not belong to. It is also used for a few other validations
       * too that if they fail would indicate a bug in the code somewhere.
       */
      virtual void Validate(PStack& stack, const Dictionary& dict_in) const = 0;

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

   protected:
   
      //------------------------------------------------------------------------
      /** \brief A reference to the dictionary this object belongs to.
       */
      Dictionary& dict;
      
      //------------------------------------------------------------------------
   
   private:
   
      //------------------------------------------------------------------------
      /** \brief COPY DISALLOWED.
       */
      DictionarySpecific(const DictionarySpecific& right);
   
      //------------------------------------------------------------------------
      /** \brief ASSIGNMENT DISALLOWED.
       */
      DictionarySpecific& operator=(const DictionarySpecific& right);

      //------------------------------------------------------------------------
   };
   //===========================================================================
}

namespace std
{
   //===========================================================================
   /** \brief See DictionarySpecific::Print()
    */
   static inline std::ostream& operator<<(std::ostream& out, 
      const EDoc::DictionarySpecific& value)
   {
      return value.Print(out);
   }
   //===========================================================================
}

#endif // EDOC_DICTIONARYSPECIFIC_H

---