include/EDoc/NotificationIFace.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_NOTIFICATIONIFACE_H
#define EDOC_NOTIFICATIONIFACE_H

#include "EDoc/stdint.h"
#include "EDoc/exceptions.h"
#include "EDoc/utils.h"

#include <string>
#include <map>
#include <list>

namespace EDoc
{
   class Function; 
   class File;
   class Type;
   class PropogatingException;
   class FunctionType;

   //===========================================================================
   /** \brief Enumerates the event types that exist.
    */
   enum EventType
   {
      EVENT_ERROR,
      EVENT_WARNING
   };
   
   typedef uint32_t EventCode;
   
   //===========================================================================
   /** \brief Notifies user of errors/warnings.
    *
    * This provides functionality for notifying users of errors and warnings. It
    * also provides a facility to filter out some warnings/errors by registering
    * a callback function pointer that returns false if the message to be
    * suppressed.
    */
   class NotificationIFace
   {
   public:
   
      //------------------------------------------------------------------------
      /** \brief Constructor.
       *
       * By default filter allows ALL events to be shown.
       */
      NotificationIFace()
      {
         filter = &NotificationIFace::AllowEverythingFilter;
         filter_data = NULL;
      }
      
      //------------------------------------------------------------------------
      /** \brief Destructor.
       */
      virtual ~NotificationIFace() {}

      //------------------------------------------------------------------------
      /** \brief Is called upon an event to be displayed to the user.
       *
       * NOTE Should use the macro EDOC_NOTIFICATION() NOT call this function
       * directly.
       *
       * The additional parameters are used in filtering. They are not used to
       * generate any message text. Any of these parameters can be NULL, but it
       * is preferrable that if data is associated with the event then it should
       * be passed along so that the filtering functions can better identify
       * individual events for filtering purposes.
       *
       * As an example while running EDoc it may produce anumber of WUNIMPL
       * warning events for a series of functions that are used but not
       * implemented. You may wish to suppress all these WUNIMPL messages for a
       * certain list of function names, in which case the filter function would
       * check the function parameter, or it could choose to filter out all
       * WUNIMPL messages where the function was declared in the &lt;builtin&gt;
       * file. This would allow those WUNIMPL's to be suppressed but all others 
       * would still be emitted.
       */
      virtual void Event(EventCode code, 
         const char* source_file, 
         unsigned int source_line, 
         std::string message,
         const Function* function, 
         const File* file, 
         uint32_t line, 
         const File* rfile, 
         uint32_t rline, 
         const Type* type, 
         const PropogatingException* prop_exc,
         const FunctionType* function_type,
         const char* extra) = 0;

      //------------------------------------------------------------------------
      /** \brief Function pointer type for the filter callback function.
       *
       * \see RegisterFilter()
       */
      typedef bool (*AllowEventFP)(void* filter_data,
         EventCode code, 
         std::string ev_name,
         EventType ev_type,
         const Function* function, 
         const File* file, 
         uint32_t line, 
         const File* rfile, 
         uint32_t rline, 
         const Type* type, 
         const PropogatingException* prop_exc,
         const FunctionType* function_type,
         const char* extra);
      
      //------------------------------------------------------------------------
      /** \brief The default filter that filters out no events at all.
       *
       * \see RegisterFilter()
       */
      static bool AllowEverythingFilter(void* EDOC_UNUSED(filter_data),
         EventCode EDOC_UNUSED(code),
         std::string EDOC_UNUSED(ev_name),
         EventType EDOC_UNUSED(ev_type),
         const Function* EDOC_UNUSED(function),
         const File* EDOC_UNUSED(file),
         uint32_t EDOC_UNUSED(line),
         const File* EDOC_UNUSED(rfile),
         uint32_t EDOC_UNUSED(rline),
         const Type* EDOC_UNUSED(type),
         const PropogatingException* EDOC_UNUSED(prop_exc),
         const FunctionType* EDOC_UNUSED(function_type),
         const char* EDOC_UNUSED(extra))
      {
         return true;
      }
      
      //------------------------------------------------------------------------
      /** \brief Set the filter callback function.
       *
       * The callback function should return true if the event is to be
       * processed and false if the event is to be suppressed. 
       *
       * \param fp The function pointer that is to be called whenever an event
       * is being generated by the Event() function being called.
       *
       * \param data This is some optional additional data that is passed to the
       * function pointer when it is called. This can store anything. It was
       * primarily added because additional data is required for the callback
       * that executes a python function in the suppressions file.
       */
      virtual void RegisterFilter(AllowEventFP fp, void* data)
      {
         filter = fp;
         filter_data = data;
      }
   
      //------------------------------------------------------------------------

   protected:
   
      //------------------------------------------------------------------------
      /** \brief The currently registered function pointer.
       */
      AllowEventFP filter;

      //------------------------------------------------------------------------
      /** \brief Data associated function pointer.
       */
      void* filter_data;

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

   //===========================================================================
   /** \brief Returns a reference to the global notifier.
    */
   NotificationIFace* GetGlobalNotifier();

   //===========================================================================
   /** \brief Returns a reference to the global notifier or throws a
    * BugException if it is not set.
    */
   NotificationIFace* GetGlobalNotifierAssert();

   //===========================================================================
   /** \brief Sets the global notifier.
    *
    * Should be called once upon startup of the application.
    */
   void SetGlobalNotifier(NotificationIFace* gn);
   
   //===========================================================================
   /** \brief Define the standard set of errors and warnings used by EDoc.
    */
   enum Events
   {
      #define EDOC_EVENT_ITEM(Type, Name, Description) Name,
      #include "EDoc/events.inc"
      #undef EDOC_EVENT_ITEM
      EV_UNDEFINED
   };

}

//==============================================================================
/** \brief Macro used to generate notification events.
 *
 * This should be used instead of calling NotificationIFace::Event() directly.
 */
#define EDOC_NOTIFICATION(Code, Message, IdFunction, IDFile, IdLine, \
   IDRFile, IdRLine, IdType, IdPropogatingException, IdFunctionType, \
   Extra) \
{ \
   std::ostringstream stream_kjhgbvk791; \
   stream_kjhgbvk791 << Message; \
   ::EDoc::GetGlobalNotifierAssert()->Event((::EDoc::EventCode)Code, \
      __FILE__, __LINE__, \
      stream_kjhgbvk791.str(), IdFunction, IDFile, IdLine, IDRFile, IdRLine, \
      IdType, IdPropogatingException, IdFunctionType, Extra); \
}

#endif // EDOC_NOTIFICATIONIFACE_H

---