/usr/share/perl5/Log/Report/Domain.pod is in liblog-report-perl 1.05-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 | =encoding utf8
=head1 NAME
Log::Report::Domain - administer one text-domain
=head1 INHERITANCE
Log::Report::Domain
is a Log::Report::Minimal::Domain
=head1 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);
=head1 DESCRIPTION
L<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 C<Log::Report>, those packags sets are differentiated via the
text-domain value in the C<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 L<"DESCRIPTION" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"DESCRIPTION">.
=head1 METHODS
Extends L<"METHODS" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"METHODS">.
=head2 Constructors
Extends L<"Constructors" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"Constructors">.
=over 4
=item Log::Report::Domain-E<gt>B<new>(%options)
Create a new Domain object.
-Option--Defined in --Default
name Log::Report::Minimal::Domain <required>
=over 2
=item name => STRING
=back
=back
=head2 Attributes
Extends L<"Attributes" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"Attributes">.
=over 4
=item $obj-E<gt>B<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 L</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>
=over 2
=item 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 C<context_rules>, which need to be shared between the
running application and F<xgettext-perl>. See L<readConfig()|Log::Report::Domain/"Attributes">
=item context_rules => HASH|OBJECT
When rules are provided, the translator will use the C<msgctxt> fields
as provided by PO-files (gettext). This parameter is used to initialize
a L<Log::Report::Translator::Context|Log::Report::Translator::Context> helper object.
=item formatter => CODE|'PRINTI'|'PRINTP'
Selects the formatter used for the errors messages. The default is C<PRINTI>,
which will use L<String::Print::printi()|String::Print/"FUNCTIONS">: interpolation with curly
braces around the variable names. C<PRINTP> uses positional parameters,
just like C<printf>, implemented by L<String::Print::printp()|String::Print/"FUNCTIONS">.
=item 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.
=item translator => L<Log::Report::Translator|Log::Report::Translator>|HASH
Set the object which will do the translations for this domain.
=item where => ARRAY
=back
=item $obj-E<gt>B<contextRules>()
=item $obj-E<gt>B<defaultContext>()
Returns the current default translation context settings as HASH. You should
not modify the content of that HASH: change it by called L<setContext()|Log::Report::Domain/"Attributes">.
=item $obj-E<gt>B<isConfigured>()
Inherited, see L<Log::Report::Minimal::Domain/"Attributes">
=item $obj-E<gt>B<name>()
Inherited, see L<Log::Report::Minimal::Domain/"Attributes">
=item $obj-E<gt>B<nativeLanguage>()
=item $obj-E<gt>B<readConfig>($filename)
=item Log::Report::Domain-E<gt>B<readConfig>($filename)
Helper method, which simply parses the content $filename into a HASH to be
used as parameters to L<configure()|Log::Report::Domain/"Attributes">. The filename must end on '.pl',
to indicate that it uses perl syntax (can be processed with Perl's C<do>
command) or end on '.json'. See also chapter L</Configuring> below.
Currently, this file can be in Perl native format (when ending on C<.pl>)
or JSON (when it ends with C<.json>). Various modules may explain parts
of what can be found in these files, for instance
L<Log::Report::Translator::Context|Log::Report::Translator::Context>.
=item $obj-E<gt>B<setContext>(STRING|HASH|ARRAY|PAIRS)
Temporary set the default translation context for messages. This is used
when the message is created without a C<_context> parameter. The context
can be retrieved with L<defaultContext()|Log::Report::Domain/"Attributes">.
Contexts are totally ignored then there are no C<context_rules>.
=item $obj-E<gt>B<translator>()
=back
=head2 Action
Extends L<"Action" in Log::Report::Minimal::Domain|Log::Report::Minimal::Domain/"Action">.
=over 4
=item Log::Report::Domain-E<gt>B<interpolate>( $msgid, [$args] )
Inherited, see L<Log::Report::Minimal::Domain/"Action">
=item $obj-E<gt>B<translate>($message, $language)
Translate the $message into the $language.
=back
=head1 DETAILS
=head2 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 L<Log::Report::Optional|Log::Report::Optional>, which is a dressed-down
version of L<Log::Report|Log::Report>.
=head3 configuring your formatter
The C<PRINTI> and C<PRINTP> are special constants for L<configure(formatter)|Log::Report::Domain/"Attributes">,
and will use L<String::Print|String::Print> functions C<printi()> respectively C<printp()>
in their default modus. When you want your own formatter, or configuration
of C<String::Print>, you need to pass a code reference.
my $sp = String::Print->new
( modifiers => ...
, serializers => ...
);
textdomain 'some-domain'
, formatter => sub { $sp->printi(@_) };
=head1 SEE ALSO
This module is part of Log-Report distribution version 1.05,
built on June 24, 2014. Website: F<http://perl.overmeer.net/log-report/>
=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>
|