Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Contact Us
Online Help
Domain Status
Man Pages

Virtual Servers

Topology Map

Server Agreement
Year 2038

USA Flag



Man Pages

Manual Reference Pages  -  LOG::REPORT::DOMAIN (3)

.ds Aq ’


Log::Report::Domain - administer one text-domain



   is a Log::Report::Minimal::Domain


 # internal usage
 use Log::Report::Domain;
 my $domain = Log::Report::Domain->new(name => $name);

 # find a ::Domain object
 use Log::Report my-domain;
 my $domain = textdomain my-domain; # find domain config
 my $domain = textdomain;             # config of this package

 # explicit domain configuration
 package My::Package;
 use Log::Report my-domain;         # set textdomain for package

 textdomain $name, %configure;        # set config, once per program
 (textdomain $name)->configure(%configure); # same
 textdomain->configure(%configure);   # same if current package in $name

 # implicit domain configuration
 package My::Package;
 use Log::Report my-domain, %configure;

 # external file for configuration (perl or json format)
 use Log::Report my-domain, config => $filename;

 use Log::Report my-domain;
 textdomain->configure(config => $filename);


Log::Report can handle multiple sets of packages at the same time: in the usual case a program consists of more than one software distribution, each containing a number of packages. Each module in an application belongs to one of these sets, by default the domain set ’default’.

For Log::Report, those packags sets are differentiated via the text-domain value in the use statement:

  use Log::Report my-domain;

There are many things you can configure per (text)domain. This is not only related to translations, but also -for instance- for text formatting configuration. The administration for the configuration is managed in this package.

Extends DESCRIPTION in Log::Report::Minimal::Domain.


Extends METHODS in Log::Report::Minimal::Domain.


Extends Constructors in Log::Report::Minimal::Domain.
Log::Report::Domain-><B>newB>(%options) Create a new Domain object.

 -Option--Defined in                  --Default
  name    Log::Report::Minimal::Domain  <required>

name => STRING


Extends Attributes in Log::Report::Minimal::Domain.
$obj-><B>configureB>(%options) The import is automatically called when the package is compiled. For all but one packages in your distribution, it will only contain the name of the DOMAIN. For one package, it will contain configuration information. These %options are used for all packages which use the same DOMAIN. See chapter Configuring below.

 -Option         --Defined in                  --Default
  config                                         undef
  context_rules                                  undef
  formatter                                      PRINTI
  native_language                                en_US
  translator                                     created internally
  where            Log::Report::Minimal::Domain  <required>

config => FILENAME Read the settings from the file. The parameters found in the file are used as default for the parameters above. This parameter is especially useful for the context_rules, which need to be shared between the running application and xgettext-perl. See readConfig()
context_rules => HASH|OBJECT When rules are provided, the translator will use the msgctxt fields as provided by PO-files (gettext). This parameter is used to initialize a Log::Report::Translator::Context helper object.
formatter => CODE|’PRINTI’|’PRINTP Selects the formatter used for the errors messages. The default is PRINTI, which will use String::Print::printi(): interpolation with curly braces around the variable names. PRINTP uses positional parameters, just like printf, implemented by String::Print::printp().
native_language => CODESET This is the language which you have used to write the translatable and the non-translatable messages in. In case no translation is needed, you still wish the system error messages to be in the same language as the report. Of course, each textdomain can define its own.
translator => Log::Report::Translator|HASH Set the object which will do the translations for this domain.
where => ARRAY
$obj-><B>defaultContextB>() Returns the current default translation context settings as HASH. You should not modify the content of that HASH: change it by called setContext() or updateContext().
$obj-><B>isConfiguredB>() Inherited, see Attributes in Log::Report::Minimal::Domain
$obj-><B>nameB>() Inherited, see Attributes in Log::Report::Minimal::Domain
Log::Report::Domain-><B>readConfigB>($filename) Helper method, which simply parses the content $filename into a HASH to be used as parameters to configure(). The filename must end on ’.pl’, to indicate that it uses perl syntax (can be processed with Perl’s do command) or end on ’.json’. See also chapter Configuring below.

Currently, this file can be in Perl native format (when ending on .pl) or JSON (when it ends with .json). Various modules may explain parts of what can be found in these files, for instance Log::Report::Translator::Context.

$obj-><B>setContextB>(STRING|HASH|ARRAY|PAIRS) Temporary set the default translation context for messages. This is used when the message is created without a _context parameter. The context can be retrieved with defaultContext().

Contexts are totally ignored then there are no context_rules. When you do not wish to change settings, you may simply provide a HASH.


   use Log::Report my-domain, context_rules => {};

$obj-><B>updateContextB>(STRING|HASH|ARRAY|PAIRS) [1.10] Make changes and additions to the active context (see setContext()).


Extends Action in Log::Report::Minimal::Domain.
Log::Report::Domain-><B>interpolateB>( $msgid, [$args] ) Inherited, see Action in Log::Report::Minimal::Domain
$obj-><B>translateB>($message, $language) Translate the $message into the $language.



Configuration of a domain can happen in many ways: either explicitly or implicitly. The explicit form:

   package My::Package;
   use Log::Report my-domain;

   textdomain my-domain, %configuration;

   textdomain->configure(conf => $filename);

The implicit form is (no variables possible, only constants!)

   package My::Package;
   use Log::Report my-domain, %configuration;
   use Log::Report my-domain, conf => /filename;

You can only configure your domain in one place in your program. The textdomain setup is then used for all packages in the same domain.

This also works for Log::Report::Optional, which is a dressed-down version of Log::Report.

configuring your formatter

The PRINTI and PRINTP are special constants for configure(formatter), and will use String::Print functions printi() respectively printp() in their default modus. When you want your own formatter, or configuration of String::Print, you need to pass a code reference.

  my $sp = String::Print->new
    ( modifiers   => ...
    , serializers => ...

  textdomain some-domain
    , formatter => sub { $sp->printi(@_) };

configuring global values

Say, you log for a (Dancer) webserver, where you wish to include the website name in some of the log lines. For this, (ab)use the translation context:

  ### first enabled translation contexts
  use Log::Report my-domain, context_rules => {};
  # or
  use Log::Report my-domain;
  textdomain->configure(context_rules => {});
  ### every time you start working for a different virtual host
  (textdomain my-domain)->setContext(host => $host);

  ### now you can use that in your code
  package My::Package;
  use Log::Report my-domain;
  error __x"in {host} not logged-in {user}", user => $username;


This module is part of Log-Report distribution version 1.13, built on February 03, 2016. Website:


Copyrights 2007-2016 by [Mark Overmeer]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See

Search for    or go to Top of page |  Section 3 |  Main Index

perl v5.20.3 LOG::REPORT::DOMAIN (3) 2016-02-03

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.