.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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::Report::Util 3pm" .TH Log::Report::Util 3pm "2022-12-06" "perl v5.36.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::Report::Util \- helpful routines to Log::Report .SH "INHERITANCE" .IX Header "INHERITANCE" .Vb 2 \& Log::Report::Util \& is a Exporter .Ve .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& my ($language, $territory, $charset, $modifier) \& = parse_locale \*(Aqnl_BE.utf\-8@home\*(Aq; \& \& my @take = expand_reasons \*(AqINFO\-ERROR,PANIC\*(Aq; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module collects a few functions and definitions which are shared between different components in the Log::Report infrastructure. They should not be needed for end-user applications, although this man-page may contain some useful background information. .SH "FUNCTIONS" .IX Header "FUNCTIONS" .SS "Reasons" .IX Subsection "Reasons" .IP "\fBexpand_reasons\fR($reasons)" 4 .IX Item "expand_reasons($reasons)" Returns a sub-set of all existing message reason labels, based on the content \f(CW$reasons\fR string. The following rules apply: .Sp .Vb 4 \& REASONS = BLOCK [ \*(Aq,\*(Aq BLOCKS ] | ARRAY\-of\-REASON \& BLOCK = \*(Aq\-\*(Aq TO | FROM \*(Aq\-\*(Aq TO | ONE | SOURCE \& FROM,TO,ONE = \*(AqTRACE\*(Aq | \*(AqASSERT\*(Aq | ,,, | \*(AqPANIC\*(Aq \& SOURCE = \*(AqUSER\*(Aq | \*(AqPROGRAM\*(Aq | \*(AqSYSTEM\*(Aq | \*(AqFATAL\*(Aq | \*(AqALL\*(Aq | \*(AqNONE\*(Aq .Ve .Sp The \s-1SOURCE\s0 specification group all reasons which are usually related to the problem: report about problems caused by the user, reported by the program, or with system interaction. .Sp example: of expended \s-1REASONS\s0 .Sp .Vb 8 \& WARNING\-FAULT # == WARNING,MISTAKE,ERROR,FAULT \& WARNING,INFO # == WARNING,INFO \& \-INFO # == TRACE\-INFO \& ALERT\- # == ALERT,FAILURE,PANIC \& USER # == MISTAKE,ERROR \& ALL # == TRACE\-PANIC \& FATAL # == ERROR,FAULT,FAILURE,PANIC [1.07] \& NONE # == .Ve .IP "\fBis_fatal\fR($reason)" 4 .IX Item "is_fatal($reason)" Returns true if the \f(CW$reason\fR is severe enough to cause an exception (or program termination). .IP "\fBis_reason\fR($name)" 4 .IX Item "is_reason($name)" Returns true if the \s-1STRING\s0 is one of the predefined \s-1REASONS.\s0 .IP "\fBuse_errno\fR($reason)" 4 .IX Item "use_errno($reason)" .SS "Modes" .IX Subsection "Modes" Run-modes are explained in Log::Report::Dispatcher. .IP "\fBmode_accepts\fR($mode)" 4 .IX Item "mode_accepts($mode)" Returns something acceptable by \fBexpand_reasons()\fR .IP "\fBmode_number\fR($name|$mode)" 4 .IX Item "mode_number($name|$mode)" Returns the \f(CW$mode\fR as number. .ie n .IP "\fBmust_show_location\fR($mode, $reason)" 4 .el .IP "\fBmust_show_location\fR($mode, \f(CW$reason\fR)" 4 .IX Item "must_show_location($mode, $reason)" .PD 0 .ie n .IP "\fBmust_show_stack\fR($mode, $reason)" 4 .el .IP "\fBmust_show_stack\fR($mode, \f(CW$reason\fR)" 4 .IX Item "must_show_stack($mode, $reason)" .PD .SS "Other" .IX Subsection "Other" .IP "\fBescape_chars\fR(\s-1STRING\s0)" 4 .IX Item "escape_chars(STRING)" Replace all escape characters into their readable counterpart. For instance, a new-line is replaced by backslash-n. .IP "\fBparse_locale\fR(\s-1STRING\s0)" 4 .IX Item "parse_locale(STRING)" Decompose a locale string. .Sp For simplicity of the caller's code, the capatization of the returned fields is standardized to the preferred, although the match is case\- insensitive as required by the \s-1RFC.\s0 The territory in returned in capitals (\s-1ISO3166\s0), the language is lower-case (\s-1ISO639\s0), the script as upper-case first, the character-set as lower-case, and the modifier and variant unchanged. .Sp In \s-1LIST\s0 context, four elements are returned: language, territory, character-set (codeset), and modifier. Those four are important for the usual unix translationg infrastructure. Only the \*(L"country\*(R" is obligatory, the others can be \f(CW\*(C`undef\*(C'\fR. It may also return \f(CW\*(C`C\*(C'\fR and \f(CW\*(C`POSIX\*(C'\fR. .Sp In \s-1SCALAR\s0 context, a \s-1HASH\s0 is returned which can contain more information: language, script, territory, variant, codeset, and modifiers. The variant (\s-1RFC3066\s0 is probably never used) .ie n .IP "\fBpkg2domain\fR( $package, [$domain, $filename, $line] )" 4 .el .IP "\fBpkg2domain\fR( \f(CW$package\fR, [$domain, \f(CW$filename\fR, \f(CW$line\fR] )" 4 .IX Item "pkg2domain( $package, [$domain, $filename, $line] )" With \f(CW$domain\fR, \f(CW$filename\fR and \f(CW$line\fR, this registers a location where the textdomain is specified. Each \f(CW$package\fR can only belong to one \f(CW$domain\fR. .Sp Without these parameters, the registered domain for the \f(CW$package\fR is returned. .IP "\fBto_html\fR($string)" 4 .IX Item "to_html($string)" [1.02] Escape \s-1HTML\s0 volatile characters. .IP "\fBunescape_chars\fR(\s-1STRING\s0)" 4 .IX Item "unescape_chars(STRING)" Replace all backslash-something escapes by their escape character. For instance, backslash-t is replaced by a tab character. .SH "SEE ALSO" .IX Header "SEE ALSO" This module is part of Log-Report-Optional distribution version 1.07, built on January 15, 2021. Website: \fIhttp://perl.overmeer.net/CPAN/\fR .SH "LICENSE" .IX Header "LICENSE" Copyrights 2013\-2021 by [Mark Overmeer ]. For other contributors see ChangeLog. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See \fIhttp://dev.perl.org/licenses/\fR