.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man v6.0.2 (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 .\" .\" Required to disable full justification in groff 1.23.0. .if n .ds AD l .\" ======================================================================== .\" .IX Title "Log::Report::Util 3" .TH Log::Report::Util 3 2025-12-12 "perl v5.42.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 an 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 SOURCE 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 REASONS .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 \f(CW\*(C`true\*(C'\fR 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 \f(CW\*(C`true\*(C'\fR if the STRING is one of the predefined REASONS. .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)" .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)" .SS Other .IX Subsection "Other" .IP \fBescape_chars\fR(STRING) 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(STRING) 4 .IX Item "parse_locale(STRING)" Decompose a locale string. .Sp For simplicity of the caller\*(Aqs code, the capatization of the returned fields is standardized to the preferred, although the match is case\- insensitive as required by the RFC. The territory in returned in capitals (ISO3166), the language is lower\-case (ISO639), the script as upper\-case first, the character\-set as lower\-case, and the modifier and variant unchanged. .Sp In LIST context, four elements are returned: language, territory, character\-set (codeset), and modifier. Those four are important for the usual unix translationg infrastructure. Only the "country" 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 SCALAR context, a HASH is returned which can contain more information: language, script, territory, variant, codeset, and modifiers. The variant (RFC3066 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 HTML volatile characters. .IP \fBunescape_chars\fR(STRING) 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 DIAGNOSTICS .IX Header "DIAGNOSTICS" .IP "Error: reason \*(Aq$begin\*(Aq more serious than \*(Aq$end\*(Aq in \*(Aq$reasons" 4 .IX Item "Error: reason '$begin' more serious than '$end' in '$reasons" Cast by \fBexpand_reasons()\fR .IP "Error: unknown locale language in locale \`$locale\*(Aq" 4 .IX Item "Error: unknown locale language in locale `$locale'" Cast by \fBparse_locale()\fR .ie n .IP "Error: unknown reason $which in \*(Aq$reasons\*(Aq" 4 .el .IP "Error: unknown reason \f(CW$which\fR in \*(Aq$reasons\*(Aq" 4 .IX Item "Error: unknown reason $which in '$reasons'" Cast by \fBexpand_reasons()\fR .ie n .IP "Error: unknown reason $which in \*(Aq$reasons\*(Aq" 4 .el .IP "Error: unknown reason \f(CW$which\fR in \*(Aq$reasons\*(Aq" 4 .IX Item "Error: unknown reason $which in '$reasons'" Cast by \fBexpand_reasons()\fR .SH "SEE ALSO" .IX Header "SEE ALSO" This module is part of Log\-Report\-Optional version 1.08, built on September 08, 2025. Website: \fIhttp://perl.overmeer.net/CPAN/\fR .SH LICENSE .IX Header "LICENSE" For contributors see file ChangeLog. .PP This software is copyright (c) 2013\-2025 by Mark Overmeer. .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.