oracular (3) Log::Report::Domain.3pm.gz
NAME
Log::Report::Domain - administer one text-domain
INHERITANCE
Log::Report::Domain
is a Log::Report::Minimal::Domain
Log::Report::Domain is extended by
Log::Report::Template::Textdomain
SYNOPSIS
# 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);
DESCRIPTION
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.
METHODS
Extends "METHODS" in Log::Report::Minimal::Domain.
Constructors
Extends "Constructors" in Log::Report::Minimal::Domain.
Log::Report::Domain->new(%options)
Create a new Domain object.
-Option--Defined in --Default
name Log::Report::Minimal::Domain <required>
name => STRING
Attributes
Extends "Attributes" in Log::Report::Minimal::Domain.
$obj->configure(%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|HASH|'PRINTI'
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.
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->contextRules()
$obj->defaultContext()
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->isConfigured()
Inherited, see "Attributes" in Log::Report::Minimal::Domain
$obj->name()
Inherited, see "Attributes" in Log::Report::Minimal::Domain
$obj->nativeLanguage()
$obj->readConfig($filename)
Log::Report::Domain->readConfig($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->setContext(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.
example:
use Log::Report 'my-domain', context_rules => {};
$obj->translator()
$obj->updateContext(STRING|HASH|ARRAY|PAIRS)
[1.10] Make changes and additions to the active context (see setContext()).
Action
Extends "Action" in Log::Report::Minimal::Domain.
$obj->interpolate( $msgid, [$args] )
Inherited, see "Action" in Log::Report::Minimal::Domain
$obj->translate($message, $language)
Translate the $message into the $language.
DETAILS
Configuring
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(%configuration);
textdomain->configure(\%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 own formatter
[0.91] The "PRINTI" is a special constants for configure(formatter), and will use String::Print function
printi(), with the standard tricks.
textdomain 'some-domain'
formatter =>
{ class => 'String::Print' # default
, method => 'sprinti' # default
, %options # constructor options for the class
);
When you want your own formatter, or configuration of "String::Print", you need to pass a CODE. Be aware
that you may loose magic added by Log::Report and other layers, like Log::Report::Template:
textdomain 'some-domain'
, formatter => \&my_formatter;
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 => {});
# or
textdomain 'my-domain'
, content_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 {_context.host} not logged-in {user}", user => $username;
SEE ALSO
This module is part of Log-Report distribution version 1.37, built on June 28, 2024. Website:
http://perl.overmeer.net/CPAN/
LICENSE
Copyrights 2007-2024 by [Mark Overmeer <markov@cpan.org>]. 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 http://dev.perl.org/licenses/