Merge pull request #54 from rm5248/LOGCXX-515

[Logcxx-515] Add fmt support

Author: rm5248

src/examples/cpp/CMakeLists.txt

@@ -10,3 +10,12 @@ endforeach()
 configure_file( custom-appender.xml
     ${CMAKE_CURRENT_BINARY_DIR}/custom-appender.xml
     COPYONLY )
+
+# Custom handling for format string example, since it utilizes libfmt
+find_package(fmt QUIET)
+if(${fmt_FOUND})
+    add_executable( format-string format-string.cpp )
+    target_compile_definitions(format-string PRIVATE ${LOG4CXX_COMPILE_DEFINITIONS} ${APR_COMPILE_DEFINITIONS} ${APR_UTIL_COMPILE_DEFINITIONS} )
+    target_include_directories(format-string PRIVATE ${CMAKE_CURRENT_LIST_DIR} $<TARGET_PROPERTY:log4cxx,INCLUDE_DIRECTORIES>)
+    target_link_libraries(format-string PRIVATE log4cxx ${APR_UTIL_LIBRARIES} ${XMLLIB_LIBRARIES} ${APR_LIBRARIES} ${APR_SYSTEM_LIBS} fmt::fmt)
+endif(${fmt_FOUND})

src/examples/cpp/format-string.cpp

@@ -0,0 +1,59 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements.  See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License.  You may obtain a copy of the License at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <stdlib.h>
+#include <log4cxx/basicconfigurator.h>
+#include <locale.h>
+#include <fmt/core.h>
+#include <fmt/color.h>
+#include <fmt/ostream.h>
+#include <iomanip>
+
+using namespace log4cxx;
+using namespace log4cxx::helpers;
+
+struct MyStruct {
+		int x;
+};
+
+std::ostream& operator<<( std::ostream& stream, const MyStruct& mystruct ){
+		stream << "[MyStruct x:" << mystruct.x << "]";
+		return stream;
+}
+
+int main()
+{
+	setlocale(LC_ALL, "");
+
+	BasicConfigurator::configure();
+	LoggerPtr rootLogger = Logger::getRootLogger();
+
+	LOG4CXX_INFO_FMT( rootLogger, "This is a {} mesage", "test" );
+	LOG4CXX_INFO_FMT( rootLogger, fmt::fg(fmt::color::red), "Messages can be colored" );
+	LOG4CXX_INFO_FMT( rootLogger, "We can also align text to the {:<10} or {:>10}", "left", "right" );
+
+	MyStruct mine;
+	LOG4CXX_INFO_FMT( rootLogger, "This custom type {} can also be logged, since it implements operator<<", mine );
+
+	LOG4CXX_INFO( rootLogger, "Numbers can be formatted with excessive operator<<: "
+				  << std::setprecision(3) << 22.456
+				  << " And as hex: "
+				  << std::setbase( 16 ) << 123 );
+	LOG4CXX_INFO_FMT( rootLogger, "Numbers can be formatted with a format string {:.1f} and as hex: {:x}", 22.456, 123 );
+
+	return 0;
+}

src/main/include/log4cxx/logger.h

@@ -1770,6 +1770,17 @@ Logs a message to a specified logger with a specified level.
 			::log4cxx::helpers::MessageBuffer oss_; \
 			logger->forcedLog(level, oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
 
+/**
+Logs a message to a specified logger with a specified level, formatting utilizing libfmt
+
+@param logger the logger to be used.
+@param level the level to log.
+@param ... The format string and message to log
+*/
+#define LOG4CXX_LOG_FMT(logger, level, ...) do { \
+		if (logger->isEnabledFor(level)) {\
+			logger->forcedLog(level, fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
+
 /**
 Logs a message to a specified logger with a specified level.
 
@@ -1793,8 +1804,19 @@ Logs a message to a specified logger with the DEBUG level.
 		if (LOG4CXX_UNLIKELY(logger->isDebugEnabled())) {\
 			::log4cxx::helpers::MessageBuffer oss_; \
 			logger->forcedLog(::log4cxx::Level::getDebug(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
+
+/**
+Logs a message to a specified logger with the DEBUG level, formatting with libfmt
+
+@param logger the logger to be used.
+@param ... The format string and message to log
+*/
+#define LOG4CXX_DEBUG_FMT(logger, ...) do { \
+		if (LOG4CXX_UNLIKELY(logger->isDebugEnabled())) {\
+			logger->forcedLog(::log4cxx::Level::getDebug(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
 #else
 #define LOG4CXX_DEBUG(logger, message)
+#define LOG4CXX_DEBUG_FMT(logger, ...)
 #endif
 
 #if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 5000
@@ -1808,8 +1830,19 @@ Logs a message to a specified logger with the TRACE level.
 		if (LOG4CXX_UNLIKELY(logger->isTraceEnabled())) {\
 			::log4cxx::helpers::MessageBuffer oss_; \
 			logger->forcedLog(::log4cxx::Level::getTrace(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
+
+/**
+Logs a message to a specified logger with the TRACE level, formatting with libfmt.
+
+@param logger the logger to be used.
+@param ... The format string and message to log
+*/
+#define LOG4CXX_TRACE_FMT(logger, ...) do { \
+		if (LOG4CXX_UNLIKELY(logger->isTraceEnabled())) {\
+			logger->forcedLog(::log4cxx::Level::getTrace(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
 #else
 #define LOG4CXX_TRACE(logger, message)
+#define LOG4CXX_TRACE_FMT(logger, ...)
 #endif
 
 #if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 20000
@@ -1823,8 +1856,20 @@ Logs a message to a specified logger with the INFO level.
 		if (logger->isInfoEnabled()) {\
 			::log4cxx::helpers::MessageBuffer oss_; \
 			logger->forcedLog(::log4cxx::Level::getInfo(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
+
+/**
+Logs a message to a specified logger with the INFO level, formatting with libfmt.
+
+@param logger the logger to be used.
+@param message the message string to log.
+@param ... The format string and message to log
+*/
+#define LOG4CXX_INFO_FMT(logger, ...) do { \
+		if (logger->isInfoEnabled()) {\
+			logger->forcedLog(::log4cxx::Level::getInfo(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
 #else
 #define LOG4CXX_INFO(logger, message)
+#define LOG4CXX_INFO_FMT(logger, ...)
 #endif
 
 #if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 30000
@@ -1838,8 +1883,19 @@ Logs a message to a specified logger with the WARN level.
 		if (logger->isWarnEnabled()) {\
 			::log4cxx::helpers::MessageBuffer oss_; \
 			logger->forcedLog(::log4cxx::Level::getWarn(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
+
+/**
+Logs a message to a specified logger with the WARN level, formatting with libfmt
+
+@param logger the logger to be used.
+@param ... The format string and message to log
+*/
+#define LOG4CXX_WARN_FMT(logger, ...) do { \
+		if (logger->isWarnEnabled()) {\
+			logger->forcedLog(::log4cxx::Level::getWarn(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
 #else
 #define LOG4CXX_WARN(logger, message)
+#define LOG4CXX_WARN_FMT(logger, ...)
 #endif
 
 #if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 40000
@@ -1854,6 +1910,16 @@ Logs a message to a specified logger with the ERROR level.
 			::log4cxx::helpers::MessageBuffer oss_; \
 			logger->forcedLog(::log4cxx::Level::getError(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
 
+/**
+Logs a message to a specified logger with the ERROR level, formatting with libfmt
+
+@param logger the logger to be used.
+@param ... The format string and message to log
+*/
+#define LOG4CXX_ERROR_FMT(logger, ...) do { \
+		if (logger->isErrorEnabled()) {\
+			logger->forcedLog(::log4cxx::Level::getError(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
+
 /**
 Logs a error if the condition is not true.
 
@@ -1866,9 +1932,22 @@ Logs a error if the condition is not true.
 			::log4cxx::helpers::MessageBuffer oss_; \
 			logger->forcedLog(::log4cxx::Level::getError(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
 
+/**
+Logs a error if the condition is not true, formatting with libfmt
+
+@param logger the logger to be used.
+@param condition condition
+@param ... The format string and message to log
+*/
+#define LOG4CXX_ASSERT_FMT(logger, condition, ...) do { \
+		if (!(condition) && logger->isErrorEnabled()) {\
+			logger->forcedLog(::log4cxx::Level::getError(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
+
 #else
 #define LOG4CXX_ERROR(logger, message)
+#define LOG4CXX_ERROR_FMT(logger, ...)
 #define LOG4CXX_ASSERT(logger, condition, message)
+#define LOG4CXX_ASSERT_FMT(logger, condition, ...)
 #endif
 
 #if !defined(LOG4CXX_THRESHOLD) || LOG4CXX_THRESHOLD <= 50000
@@ -1882,8 +1961,19 @@ Logs a message to a specified logger with the FATAL level.
 		if (logger->isFatalEnabled()) {\
 			::log4cxx::helpers::MessageBuffer oss_; \
 			logger->forcedLog(::log4cxx::Level::getFatal(), oss_.str(oss_ << message), LOG4CXX_LOCATION); }} while (0)
+
+/**
+Logs a message to a specified logger with the FATAL level, formatting with libfmt
+
+@param logger the logger to be used.
+@param ... The format string and message to log
+*/
+#define LOG4CXX_FATAL_FMT(logger, ...) do { \
+		if (logger->isFatalEnabled()) {\
+			logger->forcedLog(::log4cxx::Level::getFatal(), fmt::format( __VA_ARGS__ ), LOG4CXX_LOCATION); }} while (0)
 #else
 #define LOG4CXX_FATAL(logger, message)
+#define LOG4CXX_FATAL_FMT(logger, ...)
 #endif
 
 /**

src/site/markdown/usage.md

@@ -797,6 +797,40 @@ This will output data similar to the following:
 0 [0x7fd1eed63bc0] INFO root null - Some important information: [MyStruct x:90]
 ~~~
 
+# Logging with {fmt} {#logging-with-fmt}
+
+One issue with utilizing log4cxx and its ostream style of logging is that log
+statements can be very awkward if you need to precisely format something:
+
+~~~{.cpp}
+LOG4CXX_INFO( rootLogger, "Numbers can be formatted with excessive operator<<: "
+			  << std::setprecision(3) << 22.456
+			  << " And as hex: "
+			  << std::setbase( 16 ) << 123 );
+~~~
+
+This leads to very awkward code to read and write, especially as iostreams don't
+support positional arguments at all.
+
+In order to get around this, one popular library(that has been standardized as
+part of C++20) is [{fmt}](https://fmt.dev/latest/index.html).  Supporting
+positional arguments and printf-like formatting, it makes for much clearer
+code like the following:
+
+~~~{.cpp}
+LOG4CXX_INFO_FMT( rootLogger, "Numbers can be formatted with a format string {:.1f} and as hex: {:x}", 22.456, 123 );
+~~~
+
+Note that log4cxx does not include a copy of {fmt}, so you must include the
+correct headers and linker flags in order to use the `LOG4CXX_[level]_FMT`
+family of macros.
+
+As with the standard logger macros, these macros will also be compiled out
+if the `LOG4CXX_THRESHOLD` macro is set to a level that will compile out
+the non-FMT macros.
+
+A full example can be seen in the src/examples/cpp/format-string.cpp file.
+
 # Conclusions {#conclusions}
 
 Apache Log4cxx is a popular logging package written in C++. One of its