// $Id$
//
-// Copyright (C) 2007
-// Fraunhofer Institut fuer offene Kommunikationssysteme (FOKUS)
-// Kompetenzzentrum fuer Satelitenkommunikation (SatCom)
+// Copyright (C) 2007
+// Fraunhofer Institute for Open Communication Systems (FOKUS)
+// Competence Center NETwork research (NET), St. Augustin, GERMANY
// Stefan Bund <g0dil@berlios.de>
//
// This program is free software; you can redistribute it and/or modify
/** \file
\brief Log public header */
-#ifndef HH_Log_
-#define HH_Log_ 1
+#ifndef HH_SENF_Utils_Logger_Log_
+#define HH_SENF_Utils_Logger_Log_ 1
// Custom includes
#include <boost/preprocessor/seq/size.hpp>
/** \defgroup logging Logging commands
- The logging library provides several commands to create log messages. All these macro commands
+ The logging library provides several commands to create %log messages. All these macro commands
take a variable number of arguments. Since this is not supported in a usable way by the C++
preprocessor, the arguments are encoded into a <a
href="http://www.boost.org/libs/preprocessor/doc/index.html">Boost.Preprocessor</a> like
SENF_LOG( (senf::log::Debug)(senf::log::NOTICE)(FroblizerArea)("The log message") );
\endcode
- For each log message, the following information is needed:
- \li The <em>log stream</em>,
- \li the <em>log area</em>,
- \li the <em>log level</em>,
- \li and the log message itself
+ The argument is comprised of a sequence of parameters and the %log message itself.
+ The parameters are
+ - the <em>%log stream</em>,
+ - the <em>%log area</em>,
+ - the <em>%log level</em>.
- These parameters may be specified <i>in arbitrary order</i> and even multiple times in the
- parameter sequence. If some argument type occurs multiple times, the last occurrence wins. If
- any one of the parameters is not specified, it's current default value will be used.
+ These parameters are optional and may be specified <i>in arbitrary order</i> (with the %log
+ message always being the last sequence element) and even multiple times in the parameter
+ sequence. If some argument type occurs multiple times, the last occurrence wins. If any one of
+ the parameters is not specified, it's current default value will be used.
This current default value is set using \ref SENF_LOG_DEFAULT_STREAM, \ref SENF_LOG_DEFAULT_AREA
and \ref SENF_LOG_DEFAULT_LEVEL respectively. These macros set the default stream, area and/or
- level of the current scope. The logging library defines the global defaults for these values to
- be \c senf::log::Debug (\e stream), senf::log::DefaultArea (\e area), and senf::log::NONE (\e
- level).
+ level <em>of the current scope</em>. They may be used with a class declaration to set defaults
+ for all class members or within a function or member body to set the default for that member
+ only. They may be used only \e once within each scope.
- The log level senf::log::NONE is special. If the log level is set to this value, the log level
+ The logging library defines the global defaults for stream, area and level to be \c
+ senf::log::Debug, senf::log::DefaultArea, and senf::log::NONE respectively.
+
+ The %log level senf::log::NONE is special. If the %log level is set to this value, the %log level
will be set from the stream provided default value.
All these parameters must be <em>compile time constants</em> (they are all types, so it's
- difficult form them to be something else).
+ difficult for them to be something else).
+
+ \section logging_aliases Aliases
+
+ To further simplify logging commands, aliases may be defined within any scope. An alias is an
+ arbitrary collection of %log parameters:
+ \code
+ SENF_LOG_DEFINE_ALIAS( VerboseDebug, (senf::log::Debug)(senf::log::VERBOSE) );
+ \endcode
+ Within %log statements, aliases may be used like normal parameters. They will be substituted for
+ the parameter sequence they represent:
+ \code
+ SENF_LOG( (VerboseDebug)("Debug message") )
+ // is equivalent to
+ SENF_LOG( (senf::log::Debug)(senf::log::VERBOSE)("Debug message") )
+ \endcode
+ Aliases may be used together with other parameters, even with further aliases in any order.
*/
-///\ingroup logging
+///\addtogroup logging
///\{
///\name Generating log messages
\hideinitializer
*/
#define SENF_LOG_TPL(args) \
- SENF_LOG_BLOCK_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)), \
- { log << BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args); })
+ SENF_LOG_BLOCK_TPL_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)), \
+ { log << BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args); })
/** \brief Enable block based on logging parameters
\hideinitializer
*/
#define SENF_LOG_BLOCK_TPL(args) \
- SENF_LOG_BLOCK_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)), \
- BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args))
+ SENF_LOG_BLOCK_TPL_( SENF_LOG_MERGE_PARAMETERS_TPL(BOOST_PP_SEQ_POP_BACK(args)), \
+ BOOST_PP_SEQ_ELEM(BOOST_PP_DEC(BOOST_PP_SEQ_SIZE(args)),args))
///\}
///\}