include/EDoc/TranslationUnit.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_TRANSLATIONUNIT_H
#define EDOC_TRANSLATIONUNIT_H

#include "EDoc/stdint.h"
#include <string>
#include <list>
#include <vector>


namespace EDoc
{
   class File;
   
   //===========================================================================
   /** \brief Represents a translation unit in code.
    *
    * Translation unit instances when created remain around for the entire
    * duration of the program execution. 
    *
    * A translation unit instance should be created for every new translation
    * unit encounteded from a .edc file. This is how we ensure uniqueness of
    * translation units. We assign an integer identifier to a translation unit
    * when it is created that is used throught the execution of the program, but
    * not stored in any .edc files. It is assumed that in a single execution
    * there are NO DUPLICATE TRANSLATION UNITS CREATED/LOADED. This is an
    * important limitation. 
    *
    *
    * In order to create a new translation unit use the Create() function().
    *
    *
    * HISTORY
    *
    * Before this class was created a translation unit was identified by the
    * main_input_source as supplied by GCC. However this can be have the same
    * name for different translation units that are linked together. So we
    * created this to ensure that every translation unit encountered is
    * considered unique and so there is no consideration that we can load a
    * single translation unit twice in a single execution of EDoc.
    */
   class TranslationUnit
   {
   public:
      
      //------------------------------------------------------------------------
      /** \brief NOT TO BE USED.
       *
       * This was created specifically because I have yet to find out how to get
       * SWIG to work when there is no default constructor for a class.
       */
      TranslationUnit();
      
      //------------------------------------------------------------------------
      /** \brief returns the TranslationUnit instance for the special 
       * "unknown" translation unit.
       *
       * This is primarily used whena translation unit instance is required for
       * hand crafted special objects like 
       * Dictionary::SUBSTITUTION_EXCEPTION_TYPE
       */
      static TranslationUnit* GetUnknown();

      //------------------------------------------------------------------------
      /** \brief Create a new translation unit.
       *
       * \param name_in Is a string that identifies the translation unit but is
       * not necessarily unique. This is usually the .c or .cpp file name that
       * was used to compile the translation unit.
       */
      static TranslationUnit* Create(std::string name_in);
      
      //------------------------------------------------------------------------
      /** \brief Returns the name of the main code file used to compile this
       * translation unit.
       */
      const std::string& GetName() const;

      //------------------------------------------------------------------------
      /** \brief Returns the unique identified for this translation unit.
       *
       * Unique within a single execution of EDoc. A translation unit will not
       * necessarily have the same identifier between EDoc executions.
       */
      uint32_t GetID() const;
      
      //------------------------------------------------------------------------
      /** \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.
       */
      std::ostream& Print(std::ostream& out, std::string prefix="") const;

      //------------------------------------------------------------------------
      /** \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;
      
      //------------------------------------------------------------------------

   private:

      //------------------------------------------------------------------------
      /** \brief The id that will be used for the next translation units unique
       * id.
       */
      static uint32_t next_id;

      //------------------------------------------------------------------------
      /** \brief A list of all translation units created during this program
       * execution.
       */
      static std::list<TranslationUnit> translation_units;

      //------------------------------------------------------------------------
      /** \brief The unknown translation unit instance.
       */
      static TranslationUnit* UNKNOWN;

      //------------------------------------------------------------------------
      /** \brief Constructor.
       *
       * Private so onlt Create() can be used to create translation unit
       * instances.
       */
      TranslationUnit(std::string name_in, uint32_t id_in);
      
      //------------------------------------------------------------------------
      /** \brief The unique id of this translation unit.
       */
      uint32_t id;

      //------------------------------------------------------------------------
      /** \brief The not-necessarily unique name given to this translation unit.
       */
      std::string name;

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

   };
   //===========================================================================
   typedef std::vector<TranslationUnit*> TUnitPVec;
   
}

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

#endif // EDOC_TRANSLATIONUNIT_H

---