From 270d909696a753af022df72a404c73f2895b4a02 Mon Sep 17 00:00:00 2001 From: Siri Hansen Date: Thu, 28 Jun 2018 14:52:11 +0200 Subject: [logger] Allow report callback with two arguments returning a string If the report callback is a fun of arity 2, then the second argument is a map with the keys 'encoding', 'depth' and 'chars_limit', and the fun must return a string which is size limited according to the given depth and chars_limit. If the report callback is a fun of arity 1, then it must return a tuple containing a format string and a list of arguments. The formatter will produce the string, and limit it's size. --- lib/kernel/doc/src/logger.xml | 21 ++++++++++++++++++++- lib/kernel/doc/src/logger_chapter.xml | 18 +++++++++++++++++- lib/kernel/doc/src/logger_formatter.xml | 13 +++++++++---- 3 files changed, 46 insertions(+), 6 deletions(-) (limited to 'lib/kernel/doc') diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index 8bf62a6b39..f1830a8224 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -227,7 +227,10 @@ logger:error("error happened because: ~p", [Reason]). % Without macro a report(), the report_cb key can be associated with a fun (report callback) that converts the report to a format - string and arguments. See + string and arguments, or directly to a string. See the + type definition + of report_cb(), + and section Log Message in the User's Guide for more information about report callbacks.

@@ -259,6 +262,22 @@ logger:error("error happened because: ~p", [Reason]). % Without macro

+ + + +

A fun which converts a report() + to a format string and arguments, or directly to a string. + See section Log + Message in the User's Guide for more + information.

+ + + + + +

+ + diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml index 23a289f2ee..dc68d5c761 100644 --- a/lib/kernel/doc/src/logger_chapter.xml +++ b/lib/kernel/doc/src/logger_chapter.xml @@ -194,10 +194,26 @@ the log event's metadata. The report callback is a convenience function that the formatter can use - to convert the report to a format string and arguments. The + to convert the report to a format string and arguments, or + directly to a string. The formatter can also use its own conversion function, if no callback is provided, or if a customized formatting is desired.

+

The report callback must be a fun with one or two + arguments. If it takes one argument, this is the report + itself, and the fun returns a format string and arguments:

+ 
fun((logger:report()) -> {io:format(),[term()]})
+

If it takes two arguments, the first is the report, and the + second is a map containing extra data that allows direct + coversion to a string:

+ 
fun((logger:report(),logger:report_cb_config()) -> unicode:chardata())
+
+

The fun must obey the encoding, depth + and chars_limit parameters provided in the second + argument, as the formatter can not do anything useful of these + parameters with the returned string. This variant is used when + the formatting of the report depends on the size and encoding + parameters.

Example, format string and arguments:

logger:error("The file does not exist: ~ts",[Filename])

Example, string:

diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml index a482d02293..9226d19834 100644 --- a/lib/kernel/doc/src/logger_formatter.xml +++ b/lib/kernel/doc/src/logger_formatter.xml @@ -82,6 +82,13 @@ in STDLIB.

Defaults to unlimited.

+ encoding = + unicode:encoding() + +

This parameter must reflect the encoding of the device + that the handler prints to.

+

Defaults to utf8

+ legacy_header = boolean()

If set to true a header field is added to @@ -105,7 +112,8 @@ by chars_limit or depth, it is truncated.

Defaults to unlimited.

 - report_cb = fun((logger:report()) -> {io:format(), [term()]}) + report_cb = + logger:report_cb()

A report callback is used by the formatter to transform log messages on report form to a format string and @@ -119,9 +127,6 @@ both the default report callback, and any report callback found in metadata. That is, all reports are converted by this configured function.

-

The value must be a function with arity 1, - returning {Format,Args}, and it will be called - with a report as only argument.

 single_line = boolean() -- cgit v1.2.3