NAME¶
Log::Report::Domain - administer one text-domain
INHERITANCE¶
Log::Report::Domain
is a Log::Report::Minimal::Domain
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>
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|'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->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().
- $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".
- $obj->translator()
Action¶
Extends "Action" in Log::Report::Minimal::Domain.
- Log::Report::Domain->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
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(@_) };
SEE ALSO¶
This module is part of Log-Report distribution version 1.05, built on June 24,
2014. Website:
http://perl.overmeer.net/log-report/
LICENSE¶
Copyrights 2007-2014 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
http://www.perl.com/perl/misc/Artistic.html