aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src
diff options
context:
space:
mode:
authorSiri Hansen <[email protected]>2018-06-28 14:52:11 +0200
committerSiri Hansen <[email protected]>2018-07-13 12:20:26 +0200
commit270d909696a753af022df72a404c73f2895b4a02 (patch)
tree83a8d9635dc7dc3320724c24dbfbaa106e0be806 /lib/kernel/doc/src
parentc606b5659908618a4e54a1ac7af90f8f4e78c2c8 (diff)
downloadotp-270d909696a753af022df72a404c73f2895b4a02.tar.gz
otp-270d909696a753af022df72a404c73f2895b4a02.tar.bz2
otp-270d909696a753af022df72a404c73f2895b4a02.zip
[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.
Diffstat (limited to 'lib/kernel/doc/src')
-rw-r--r--lib/kernel/doc/src/logger.xml21
-rw-r--r--lib/kernel/doc/src/logger_chapter.xml18
-rw-r--r--lib/kernel/doc/src/logger_formatter.xml13
3 files changed, 46 insertions, 6 deletions
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 <seealso marker="#type-report"><c>report()</c></seealso>,
the <c>report_cb</c> 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 <seealso marker="#type-report_cb"><c>report_cb()</c></seealso>,
+ and
section <seealso marker="logger_chapter#log_message">Log
Message</seealso> in the User's Guide for more
information about report callbacks.</p>
@@ -260,6 +263,22 @@ logger:error("error happened because: ~p", [Reason]). % Without macro
</desc>
</datatype>
<datatype>
+ <name name="report_cb"/>
+ <desc>
+ <p>A fun which converts a <seealso marker="#type-report"><c>report()</c>
+ </seealso> to a format string and arguments, or directly to a string.
+ See section <seealso marker="logger_chapter#log_message">Log
+ Message</seealso> in the User's Guide for more
+ information.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="report_cb_config"/>
+ <desc>
+ <p></p>
+ </desc>
+ </datatype>
+ <datatype>
<name name="timestamp"/>
<desc>
<p>A timestamp produced
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 <seealso marker="#metadata">metadata</seealso>.
The report callback is a convenience function that
the <seealso marker="#formatters">formatter</seealso> 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.</p>
+ <p>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:</p>
+ <pre>fun((<seealso marker="logger#type-report"><c>logger:report()</c></seealso>) -> {<seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso>,[term()]})</pre>
+ <p>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:</p>
+ <pre>fun((<seealso marker="logger#type-report"><c>logger:report()</c></seealso>,<seealso marker="logger#type-report_cb_config"><c>logger:report_cb_config()</c></seealso>) -> <seealso marker="stdlib:unicode#type-chardata"><c>unicode:chardata()</c></seealso>)
+ </pre>
+ <p>The fun must obey the <c>encoding</c>, <c>depth</c>
+ and <c>chars_limit</c> 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.</p>
<p>Example, format string and arguments:</p>
<code>logger:error("The file does not exist: ~ts",[Filename])</code>
<p>Example, string:</p>
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.</p>
<p>Defaults to <c>unlimited</c>.</p>
</item>
+ <tag><c>encoding = </c><seealso marker="stdlib:unicode#type-encoding">
+ <c>unicode:encoding()</c></seealso></tag>
+ <item>
+ <p>This parameter must reflect the encoding of the device
+ that the handler prints to.</p>
+ <p>Defaults to <c>utf8</c></p>
+ </item>
<tag><c>legacy_header = boolean()</c></tag>
<item>
<p>If set to <c>true</c> a header field is added to
@@ -105,7 +112,8 @@
by <c>chars_limit</c> or <c>depth</c>, it is truncated.</p>
<p>Defaults to <c>unlimited</c>.</p>
</item>
- <tag><c>report_cb = fun((</c><seealso marker="logger#type-report"><c>logger:report()</c></seealso><c>) -> {</c><seealso marker="stdlib:io#type-format"><c>io:format()</c></seealso><c>, [term()]})</c></tag>
+ <tag><c>report_cb = </c><seealso marker="logger#type-report_cb">
+ <c>logger:report_cb()</c></seealso></tag>
<item>
<p>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.</p>
- <p>The value must be a function with arity 1,
- returning <c>{Format,Args}</c>, and it will be called
- with a report as only argument.</p>
</item>
<tag><c>single_line = boolean()</c></tag>
<item>