.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Log::Any::Adapter::TAP 3" .TH Log::Any::Adapter::TAP 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Log::Any::Adapter::TAP \- Logging adapter suitable for use in TAP testcases .SH VERSION .IX Header "VERSION" version 0.003003 .SH DESCRIPTION .IX Header "DESCRIPTION" When running testcases, you probably want to see some of your logging output. One sensible approach is to have all \f(CW\*(C`warn\*(C'\fR and more serious messages emitted as \f(CW\*(C`diag\*(C'\fR output on STDERR, and less serious messages emitted as \f(CW\*(C`note\*(C'\fR comments on STDOUT. .PP So, thats what this logging adapter does. Simply say .PP .Vb 1 \& use Log::Any::Adapter \*(AqTAP\*(Aq; .Ve .PP at the start of your testcase, and now you have your logging output as part of your TAP stream. .PP By default, \f(CW\*(C`debug\*(C'\fR and \f(CW\*(C`trace\*(C'\fR are suppressed, but you can enable them with "TAP_LOG_FILTER" or the "filter" attribute. See below. .SH ENVIRONMENT .IX Header "ENVIRONMENT" .SS TAP_LOG_FILTER .IX Subsection "TAP_LOG_FILTER" Specify the default filter value. See attribute "filter" for details. .PP You may also specify defaults per-category, using this syntax: .PP .Vb 1 \& $default_level,$package_1=$level,...,$package_n=$level .Ve .PP So, for example: .PP .Vb 1 \& TAP_LOG_FILTER=trace,MyPackage=none,NoisyPackage=warn prove \-lv .Ve .SS TAP_LOG_ORIGIN .IX Subsection "TAP_LOG_ORIGIN" Set this variable to 1 to show which category the message came from, or 2 to see the file and line number it came from, or 3 to see both. .SS TAP_LOG_SHOW_USAGE .IX Subsection "TAP_LOG_SHOW_USAGE" Defaults to true, which prints a TAP comment briefing the user about these environment variables when Log::Any::Adapter::TAP is first loaded. .PP Set TAP_LOG_SHOW_USAGE=0 to suppress this message. .SH ATTRIBUTES .IX Header "ATTRIBUTES" .SS filter .IX Subsection "filter" .Vb 2 \& use Log::Any::Adapter \*(AqTAP\*(Aq, filter => \*(Aqinfo\*(Aq; \& use Log::Any::Adapter \*(AqTAP\*(Aq, filter => \*(Aqdebug+3\*(Aq; .Ve .PP Messages with a log level equal to or less than the filter are suppressed. .PP Defaults to "TAP_LOG_FILTER", or \f(CW\*(C`debug\*(C'\fR which suppresses \f(CW\*(C`debug\*(C'\fR and \f(CW\*(C`trace\*(C'\fR messages. .PP Filter may be: .IP \(bu 4 Any of the log level names or level aliases defined in Log::Any. .IP \(bu 4 \&\f(CW\*(C`none\*(C'\fR or \f(CW\*(C`undef\*(C'\fR, to filter nothing (print all log levels). .IP \(bu 4 A value of \f(CW\*(C`all\*(C'\fR, to filter everything (print nothing). .PP The filter level may end with a \f(CW\*(C`+N\*(C'\fR or \f(CW\*(C`\-N\*(C'\fR indicating an offset from the named level. The numeric values increase with importance of the message, so \f(CW\*(C`debug\-1\*(C'\fR is equivalent to \f(CW\*(C`trace\*(C'\fR and \f(CW\*(C`debug+1\*(C'\fR is equivalent to \f(CW\*(C`info\*(C'\fR. This differs from syslog, where increasing numbers are less important. (why did they choose that??) .SS "dumper (DEPRECATED, unusable in Log::Any >= 0.9)" .IX Subsection "dumper (DEPRECATED, unusable in Log::Any >= 0.9)" .Vb 1 \& use Log::Any::Adapter \*(AqTAP\*(Aq, dumper => sub { my $val=shift; ... }; .Ve .PP This feature lets you use a custom dumper in the printf-style logging functions. However, these are no longer handled by the adapter in new versions of Log::Any, so you need to use a custom Proxy class in your log-producing module. .SH METHODS .IX Header "METHODS" .SS new .IX Subsection "new" See "new" in Log::Any::Adapter::Base. Accepts the above attributes. .SS write_msg .IX Subsection "write_msg" .Vb 1 \& $self\->write_msg( $level_name, $message_string ) .Ve .PP This is an internal method which all the other logging methods call. You can override it if you want to create a derived logger that handles line wrapping differently, or write to different file handles. .SS default_dumper .IX Subsection "default_dumper" .Vb 2 \& $dumper= $class\->default_dumper; \& $string = $dumper\->( $perl_data ); .Ve .PP Default value for the 'dumper' attribute. .PP This returns a coderef which can dump a value in "some human readable format". Currently it uses Data::Dumper with a max depth of 4. Do not depend on this default; it is only for human consumption, and might change to a more friendly format in the future. .SH "LOGGING METHODS" .IX Header "LOGGING METHODS" This module has all the standard logging methods from "LOG LEVELS" in Log::Any. .PP Note that the regular logging methods are only specified to take a single string. This module in the past supported passing objects as additional parameters, and having them stringified with a custom dumper, caatching exceptions thrown during stringification. With the new Log::Any design, these things are decided in the producing module, so these features are no longer possible. .PP If this module does receive multiple arguments or have its printf-formatting methods called, it does the following: .PP For regular logging functions (i.e. \f(CW\*(C`warn\*(C'\fR, \f(CW\*(C`info\*(C'\fR) the arguments are stringified and concatenated. Errors during stringify or printing are not caught. .PP For printf-like logging functions (i.e. \f(CW\*(C`warnf\*(C'\fR, \f(CW\*(C`infof\*(C'\fR) reference arguments are passed to \f(CW\*(C`$self\->dumper\*(C'\fR before passing them to sprintf. Errors are not caught here either. .PP For any log level below \f(CW\*(C`info\*(C'\fR, errors ARE caught with an \f(CW\*(C`eval\*(C'\fR and printed as a warning. This is to prevent sloppy debugging code from ever crashing a production system. Also, references are passed to \f(CW\*(C`$self\->dumper\*(C'\fR even for the regular methods. .SH AUTHOR .IX Header "AUTHOR" Michael Conrad .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" This software is copyright (c) 2016 by Michael Conrad. .PP This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.