Log::Report::Domain(3pm)

1Log::Report::Domain(3)User Contributed Perl DocumentationLog::Report::Domain(3)
2
3
4

NAME

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

INHERITANCE

9        Log::Report::Domain
10          is a Log::Report::Minimal::Domain
11
12        Log::Report::Domain is extended by
13          Log::Report::Template::Textdomain
14

SYNOPSIS

16        # internal usage
17        use Log::Report::Domain;
18        my $domain = Log::Report::Domain->new(name => $name);
19
20        # find a ::Domain object
21        use Log::Report 'my-domain';
22        my $domain = textdomain 'my-domain'; # find domain config
23        my $domain = textdomain;             # config of this package
24
25        # explicit domain configuration
26        package My::Package;
27        use Log::Report 'my-domain';         # set textdomain for package
28
29        textdomain $name, %configure;        # set config, once per program
30        (textdomain $name)->configure(%configure); # same
31        textdomain->configure(%configure);   # same if current package in $name
32
33        # implicit domain configuration
34        package My::Package;
35        use Log::Report 'my-domain', %configure;
36
37        # external file for configuration (perl or json format)
38        use Log::Report 'my-domain', config => $filename;
39
40        use Log::Report 'my-domain';
41        textdomain->configure(config => $filename);
42

DESCRIPTION

44       Log::Report can handle multiple sets of packages at the same time: in
45       the usual case a program consists of more than one software
46       distribution, each containing a number of packages.  Each module in an
47       application belongs to one of these sets, by default the domain set
48       'default'.
49
50       For "Log::Report", those packags sets are differentiated via the text-
51       domain value in the "use" statement:
52
53         use Log::Report 'my-domain';
54
55       There are many things you can configure per (text)domain.  This is not
56       only related to translations, but also -for instance- for text
57       formatting configuration.  The administration for the configuration is
58       managed in this package.
59
60       Extends "DESCRIPTION" in Log::Report::Minimal::Domain.
61

METHODS

63       Extends "METHODS" in Log::Report::Minimal::Domain.
64
65   Constructors
66       Extends "Constructors" in Log::Report::Minimal::Domain.
67
68       Log::Report::Domain->new(%options)
69           Create a new Domain object.
70
71            -Option--Defined in                  --Default
72             name    Log::Report::Minimal::Domain  <required>
73
74           name => STRING
75
76   Attributes
77       Extends "Attributes" in Log::Report::Minimal::Domain.
78
79       $obj->configure(%options)
80           The import is automatically called when the package is compiled.
81           For all but one packages in your distribution, it will only contain
82           the name of the DOMAIN.  For one package, it will contain
83           configuration information.  These %options are used for all
84           packages which use the same DOMAIN.  See chapter "Configuring"
85           below.
86
87            -Option         --Defined in                  --Default
88             config                                         undef
89             context_rules                                  undef
90             formatter                                      PRINTI
91             native_language                                'en_US'
92             translator                                     created internally
93             where            Log::Report::Minimal::Domain  <required>
94
95           config => FILENAME
96             Read the settings from the file.  The parameters found in the
97             file are used as default for the parameters above.  This
98             parameter is especially useful for the "context_rules", which
99             need to be shared between the running application and xgettext-
100             perl.  See readConfig()
101
102           context_rules => HASH|OBJECT
103             When rules are provided, the translator will use the "msgctxt"
104             fields as provided by PO-files (gettext).  This parameter is used
105             to initialize a Log::Report::Translator::Context helper object.
106
107           formatter => CODE|HASH|'PRINTI'
108             Selects the formatter used for the errors messages.  The default
109             is "PRINTI", which will use String::Print::printi():
110             interpolation with curly braces around the variable names.
111
112           native_language => CODESET
113             This is the language which you have used to write the
114             translatable and the non-translatable messages in.  In case no
115             translation is needed, you still wish the system error messages
116             to be in the same language as the report.  Of course, each
117             textdomain can define its own.
118
119           translator => Log::Report::Translator|HASH
120             Set the object which will do the translations for this domain.
121
122           where => ARRAY
123       $obj->contextRules()
124       $obj->defaultContext()
125           Returns the current default translation context settings as HASH.
126           You should not modify the content of that HASH: change it by called
127           setContext() or updateContext().
128
129       $obj->isConfigured()
130           Inherited, see "Attributes" in Log::Report::Minimal::Domain
131
132       $obj->name()
133           Inherited, see "Attributes" in Log::Report::Minimal::Domain
134
135       $obj->nativeLanguage()
136       $obj->readConfig($filename)
137       Log::Report::Domain->readConfig($filename)
138           Helper method, which simply parses the content $filename into a
139           HASH to be used as parameters to configure(). The filename must end
140           on '.pl', to indicate that it uses perl syntax (can be processed
141           with Perl's "do" command) or end on '.json'.  See also chapter
142           "Configuring" below.
143
144           Currently, this file can be in Perl native format (when ending on
145           ".pl") or JSON (when it ends with ".json").  Various modules may
146           explain parts of what can be found in these files, for instance
147           Log::Report::Translator::Context.
148
149       $obj->setContext(STRING|HASH|ARRAY|PAIRS)
150           Temporary set the default translation context for messages.  This
151           is used when the message is created without a "_context" parameter.
152           The context can be retrieved with defaultContext().
153
154           Contexts are totally ignored then there are no "context_rules".
155           When you do not wish to change settings, you may simply provide a
156           HASH.
157
158           example:
159
160              use Log::Report 'my-domain', context_rules => {};
161
162       $obj->translator()
163       $obj->updateContext(STRING|HASH|ARRAY|PAIRS)
164           [1.10] Make changes and additions to the active context (see
165           setContext()).
166
167   Action
168       Extends "Action" in Log::Report::Minimal::Domain.
169
170       $obj->interpolate( $msgid, [$args] )
171           Inherited, see "Action" in Log::Report::Minimal::Domain
172
173       $obj->translate($message, $language)
174           Translate the $message into the $language.
175

DETAILS

177   Configuring
178       Configuration of a domain can happen in many ways: either explicitly or
179       implicitly.  The explicit form:
180
181          package My::Package;
182          use Log::Report 'my-domain';
183
184          textdomain 'my-domain', %configuration;
185          textdomain->configure(%configuration);
186          textdomain->configure(\%configuration);
187
188          textdomain->configure(conf => $filename);
189
190       The implicit form is (no variables possible, only constants!)
191
192          package My::Package;
193          use Log::Report 'my-domain', %configuration;
194          use Log::Report 'my-domain', conf => '/filename';
195
196       You can only configure your domain in one place in your program.  The
197       textdomain setup is then used for all packages in the same domain.
198
199       This also works for Log::Report::Optional, which is a dressed-down
200       version of Log::Report.
201
202       configuring your own formatter
203
204       [0.91] The "PRINTI" is a special constants for configure(formatter),
205       and will use String::Print function printi(), with the standard tricks.
206
207         textdomain 'some-domain'
208           formatter =>
209             { class     => 'String::Print'    # default
210             , method    => 'sprinti'          # default
211             , %options    # constructor options for the class
212             );
213
214       When you want your own formatter, or configuration of "String::Print",
215       you need to pass a CODE.  Be aware that you may loose magic added by
216       Log::Report and other layers, like Log::Report::Template:
217
218         textdomain 'some-domain'
219           , formatter => \&my_formatter;
220
221       configuring global values
222
223       Say, you log for a (Dancer) webserver, where you wish to include the
224       website name in some of the log lines.  For this, (ab)use the
225       translation context:
226
227         ### first enabled translation contexts
228         use Log::Report 'my-domain', context_rules => {};
229         # or
230         use Log::Report 'my-domain';
231         textdomain->configure(context_rules => {});
232         # or
233         textdomain 'my-domain'
234           , content_rules => {};
235
236         ### every time you start working for a different virtual host
237         (textdomain 'my-domain')->setContext(host => $host);
238
239         ### now you can use that in your code
240         package My::Package;
241         use Log::Report 'my-domain';
242         error __x"in {_context.host} not logged-in {user}", user => $username;
243

LICENSE

249       Copyrights 2007-2023 by [Mark Overmeer <markov@cpan.org>]. For other
250       contributors see ChangeLog.
251
252       This program is free software; you can redistribute it and/or modify it
253       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
254
255
256
257perl v5.38.0                      2023-10-27            Log::Report::Domain(3)