Yet Another Logging Library

/**
 *  @file       log/msgGroup.hpp
 *  @author     Taka
 *  @date       25sep02
 *  
 *  @copyright  (c) T. Muraoka 1997-2002 (all rights reserved).
 *              Unauthorized use of this code is prohibited.
 *
 *  @brief      Defines the CMessageGroup class.
 * 
 *  @licence    This software is provided 'as-is', without any express 
 *              or implied warranty.
 *
 *              In no event will the author be held liable for any damages 
 *              arising from the use of this software.
 *  
 *              Permission is granted to anyone to use this software 
 *              for any purpose, including commercial applications, 
 *              and to alter it and redistribute it freely, subject to 
 *              the following restrictions: 
 *
 *              - The origin of this software must not be misrepresented; 
 *                you must not claim that you wrote the original software. 
 *                If you use this software in a product, an acknowledgment 
 *                in the product documentation is requested but not required. 
 *
 *              - Altered source versions must be plainly marked as such, 
 *                and must not be misrepresented as being the original software. 
 *                Altered source is encouraged to be submitted back to 
 *                the original author so it can be shared with the community. 
 *                Please share your changes. 
 *
 *              - This notice may not be removed or altered from any 
 *                source distribution. 
 */

#ifndef LOG_MSGGROUP_HPP
#define LOG_MSGGROUP_HPP

#include <iosfwd>
#include <string>

#include "log/common.hpp"

/* --- CLASS DEFINITION: CMessageGroup -------------------------------- */

/// Defines a message group.
/** @class CMessageGroup log/msgGroup.hpp "log/msgGroup.hpp"
 *
 *  A message group is an object that can be used to control a set of 
 *  messages as a single unit. They can be passed as a parameter to the 
 *  LOG_GMSG() macro which will then only log the message if the group
 *  is enabled.
 */

class CMessageGroup 
{

public:                     // --- PUBLIC INTERFACE ---

// constructors:
                            CMessageGroup() ; 
                            CMessageGroup( const std::string& msgGroupName , const std::string& msgGroupDescription="" ) ; 
                            CMessageGroup( int msgGroupId , const std::string& msgGroupName , const std::string& msgGroupDescription="" ) ; 
// destructor:
                            ~CMessageGroup() ;

// message group methods:
                            /// Returns the message group ID.
    int                     msgGroupId() const ;
                            /// Returns the message group name (optional).
    const std::string&      msgGroupName() const ;
                            /// Returns the message group description (optional).
    const std::string&      msgGroupDescription() const ;
                            /// Checks if the message group is enabled.
    bool                    isMsgGroupEnabled() const ;
// message group methods:
                            /// Enables/disables the message group.
    void                    enableMsgGroup( bool enable=true ) ; 

public:                     // --- PUBLIC INTERFACE ---

// message group methods:
                            /// Checks if a message group is enabled.
    static bool             isMsgGroupEnabled( int msgGroupId ) ; 
                            /// Checks if a message group is enabled.
    static bool             isMsgGroupEnabled( const std::string& msgGroupName ) ; 
// message group methods:
                            /// Enables/disables all message groups.
    static void             enableAllMsgGroups( bool enable=true ) ; 
                            /// Enables/disables all message groups.
    static void             disableAllMsgGroups( bool disable=true ) ; 
// message group methods:
                            /// Enables/disables one or more message groups.
    static void             enableMsgGroups( const std::string& msgGroupNames , bool enable=true ) ;
                            /// Dumps all message groups.
    static void             dumpMsgGroups( std::ostream& os , const std::string& prefix ) ; 

// message group methods:
                            /// Finds a CMessageGroup by ID.
    static CMessageGroup*   findMsgGroup( int msgGroupId ) ;
                            /// Finds a CMessageGroup by name.
    static CMessageGroup*   findMsgGroup( const std::string& msgGroupName ) ;

private:                    // --- PRIVATE INTERFACE ---

// copy/assignment (undefined):
                            CMessageGroup( const CMessageGroup& rhs ) ;
    CMessageGroup&          operator=( const CMessageGroup& rhs ) ;

private:                    // --- DATA MEMBERS ---

// data members:
    int                     mMsgGroupId ; ///< Message group ID.
    std::string             mMsgGroupName ; ///< Message group name (optional).
    std::string             mMsgGroupDescription ; ///< Message group description.
// data members:
    bool                    mIsEnabled ; ///< Flags if the message group is enabled 

} ;

/// CMessageGroup inserter.
std::ostream& operator<<( std::ostream& os , const CMessageGroup& msgGroup ) ; 

/* --- MACROS --------------------------------------------------------- */

/** These macros are provided as a convenience to help set up message groups.
 *  Create a header file that uses the DEFINE_MSG_GROUP() macro to define 
 *  each of your message groups and in <B>one</B> source file only, define 
 *  the symbol _IMPLEMENT_MSG_GROUPS to implement the CMessageGroup objects.
 */

#ifdef _IMPLEMENT_MSG_GROUPS
    /** Defines a message group with a name and description. */
    #define DEFINE_MSG_GROUP( msgGroup , name , description ) CMessageGroup msgGroup( name , description ) ; 
    /** Defines a message group with no name nor description. */
    #define DEFINE_UNNAMED_MSG_GROUP( msgGroup ) CMessageGroup msgGroup ; 
    /** Defines a message group with specific ID.
     *  @note Care must be taken to ensure that message group ID's are unique.
     *  Most of the time, any ID will suffice but there are certain situations
     *  where you may want to assign specific values e.g. when dealing with 
     *  message groups across processes.
     */
    #define DEFINE_MSG_GROUP_WITH_ID( msgGroup , id , name , description ) CMessageGroup msgGroup( id , name , description ) ; 
#else 
    #define DEFINE_MSG_GROUP( msgGroup , name , description ) extern CMessageGroup msgGroup ;
    #define DEFINE_UNNAMED_MSG_GROUP( msgGroup ) extern CMessageGroup msgGroup ;
    #define DEFINE_MSG_GROUP_WITH_ID( msgGroup , id , name , description ) extern CMessageGroup msgGroup ;
#endif // IMPLEMENT_MSG_GROUPS

/* -------------------------------------------------------------------- */

#endif // LOG_MSGGROUP_HPP