---
name: "Log::Report::Util"
section: "3pm"
platform: "linux"
package: "perl-log-report-optional"
version: "1.08-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/Log::Report::Util"
---

# Log::Report::Util(3pm)

helpful routines to Log::Report

## NAME

Log::Report::Util - helpful routines to Log::Report

## INHERITANCE

```
 Log::Report::Util
   is an Exporter
```

## SYNOPSIS

```
  my ($language, $territory, $charset, $modifier)
     = parse_locale 'nl_BE.utf-8@home';
  my @take = expand_reasons 'INFO-ERROR,PANIC';
```

## 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.

## FUNCTIONS

### Reasons

- **expand\_reasons**($reasons)

  Returns a sub-set of all existing message reason labels, based on the content `$reasons` string. The following rules apply:

  ```
    REASONS     = BLOCK [ ',' BLOCKS ] | ARRAY-of-REASON
    BLOCK       = '-' TO | FROM '-' TO | ONE | SOURCE
    FROM,TO,ONE = 'TRACE' | 'ASSERT' | ,,, | 'PANIC'
    SOURCE      = 'USER' | 'PROGRAM' | 'SYSTEM' | 'FATAL' | 'ALL' | 'NONE'
  ```

  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.

  example: of expended REASONS

  ```
    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          # ==
  ```

- **is\_fatal**($reason)

  Returns `"true"` if the `$reason` is severe enough to cause an exception (or program termination).

- **is\_reason**($name)

  Returns `"true"` if the STRING is one of the predefined REASONS.

- **use\_errno**($reason)

  ### Modes

Run-modes are explained in Log::Report::Dispatcher.

- **mode\_accepts**($mode)

  Returns something acceptable by **expand\_reasons()**

- **mode\_number**($name\|$mode)

  Returns the `$mode` as number.

- **must\_show\_location**($mode, $reason)

  - **must\_show\_stack**($mode, $reason)

  ### Other

- **escape\_chars**(STRING)

  Replace all escape characters into their readable counterpart.  For instance, a new-line is replaced by backslash-n.

- **parse\_locale**(STRING)

  Decompose a locale string.

  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 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.

  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 `"undef"`.  It may also return `"C"` and `"POSIX"`.

  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)

- **pkg2domain**( $package, \[$domain, $filename, $line\] )

  With `$domain`, `$filename` and `$line`, this registers a location where the textdomain is specified.  Each `$package` can only belong to one `$domain`.

  Without these parameters, the registered domain for the `$package` is returned.

- **to\_html**($string)

  \[1.02\] Escape HTML volatile characters.

- **unescape\_chars**(STRING)

  Replace all backslash-something escapes by their escape character. For instance, backslash-t is replaced by a tab character.

## DIAGNOSTICS

- Error: reason '$begin' more serious than '$end' in '$reasons

  Cast by **expand\_reasons()**

- Error: unknown locale language in locale \`$locale'

  Cast by **parse\_locale()**

- Error: unknown reason $which in '$reasons'

  Cast by **expand\_reasons()**

- Error: unknown reason $which in '$reasons'

  Cast by **expand\_reasons()**

## SEE ALSO

This module is part of Log-Report-Optional version 1.08, built on September 08, 2025. Website: *http://perl.overmeer.net/CPAN/*

## LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2013-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.