.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Log::Report::Domain 3pm" .TH Log::Report::Domain 3pm "2018-07-29" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Log::Report::Domain \- administer one text\-domain .SH "INHERITANCE" .IX Header "INHERITANCE" .Vb 2 \& Log::Report::Domain \& is a Log::Report::Minimal::Domain \& \& Log::Report::Domain is extended by \& Log::Report::Template::Textdomain .Ve .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 3 \& # internal usage \& use Log::Report::Domain; \& my $domain = Log::Report::Domain\->new(name => $name); \& \& # find a ::Domain object \& use Log::Report \*(Aqmy\-domain\*(Aq; \& my $domain = textdomain \*(Aqmy\-domain\*(Aq; # find domain config \& my $domain = textdomain; # config of this package \& \& # explicit domain configuration \& package My::Package; \& use Log::Report \*(Aqmy\-domain\*(Aq; # 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 \*(Aqmy\-domain\*(Aq, %configure; \& \& # external file for configuration (perl or json format) \& use Log::Report \*(Aqmy\-domain\*(Aq, config => $filename; \& \& use Log::Report \*(Aqmy\-domain\*(Aq; \& textdomain\->configure(config => $filename); .Ve .SH "DESCRIPTION" .IX Header "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'. .PP For \f(CW\*(C`Log::Report\*(C'\fR, those packags sets are differentiated via the text-domain value in the \f(CW\*(C`use\*(C'\fR statement: .PP .Vb 1 \& use Log::Report \*(Aqmy\-domain\*(Aq; .Ve .PP 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. .PP Extends \*(L"\s-1DESCRIPTION\*(R"\s0 in Log::Report::Minimal::Domain. .SH "METHODS" .IX Header "METHODS" Extends \*(L"\s-1METHODS\*(R"\s0 in Log::Report::Minimal::Domain. .SS "Constructors" .IX Subsection "Constructors" Extends \*(L"Constructors\*(R" in Log::Report::Minimal::Domain. .IP "Log::Report::Domain\->\fBnew\fR(%options)" 4 .IX Item "Log::Report::Domain->new(%options)" Create a new Domain object. .Sp .Vb 2 \& \-Option\-\-Defined in \-\-Default \& name Log::Report::Minimal::Domain .Ve .RS 4 .IP "name => \s-1STRING\s0" 2 .IX Item "name => STRING" .RE .RS 4 .RE .SS "Attributes" .IX Subsection "Attributes" Extends \*(L"Attributes\*(R" in Log::Report::Minimal::Domain. .ie n .IP "$obj\->\fBconfigure\fR(%options)" 4 .el .IP "\f(CW$obj\fR\->\fBconfigure\fR(%options)" 4 .IX Item "$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 \s-1DOMAIN.\s0 For one package, it will contain configuration information. These \f(CW%options\fR are used for all packages which use the same \s-1DOMAIN.\s0 See chapter \*(L"Configuring\*(R" below. .Sp .Vb 7 \& \-Option \-\-Defined in \-\-Default \& config undef \& context_rules undef \& formatter PRINTI \& native_language \*(Aqen_US\*(Aq \& translator created internally \& where Log::Report::Minimal::Domain .Ve .RS 4 .IP "config => \s-1FILENAME\s0" 2 .IX 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 \f(CW\*(C`context_rules\*(C'\fR, which need to be shared between the running application and \fIxgettext-perl\fR. See \fIreadConfig()\fR .IP "context_rules => HASH|OBJECT" 2 .IX Item "context_rules => HASH|OBJECT" When rules are provided, the translator will use the \f(CW\*(C`msgctxt\*(C'\fR fields as provided by PO-files (gettext). This parameter is used to initialize a Log::Report::Translator::Context helper object. .IP "formatter => CODE|HASH|'\s-1PRINTI\s0'" 2 .IX Item "formatter => CODE|HASH|'PRINTI'" Selects the formatter used for the errors messages. The default is \f(CW\*(C`PRINTI\*(C'\fR, which will use \fIString::Print::printi()\fR: interpolation with curly braces around the variable names. .IP "native_language => \s-1CODESET\s0" 2 .IX 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. .IP "translator => Log::Report::Translator|HASH" 2 .IX Item "translator => Log::Report::Translator|HASH" Set the object which will do the translations for this domain. .IP "where => \s-1ARRAY\s0" 2 .IX Item "where => ARRAY" .RE .RS 4 .RE .PD 0 .ie n .IP "$obj\->\fBcontextRules\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBcontextRules\fR()" 4 .IX Item "$obj->contextRules()" .ie n .IP "$obj\->\fBdefaultContext\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBdefaultContext\fR()" 4 .IX Item "$obj->defaultContext()" .PD Returns the current default translation context settings as \s-1HASH.\s0 You should not modify the content of that \s-1HASH:\s0 change it by called \fIsetContext()\fR or \&\fIupdateContext()\fR. .ie n .IP "$obj\->\fBisConfigured\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBisConfigured\fR()" 4 .IX Item "$obj->isConfigured()" Inherited, see \*(L"Attributes\*(R" in Log::Report::Minimal::Domain .ie n .IP "$obj\->\fBname\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBname\fR()" 4 .IX Item "$obj->name()" Inherited, see \*(L"Attributes\*(R" in Log::Report::Minimal::Domain .ie n .IP "$obj\->\fBnativeLanguage\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBnativeLanguage\fR()" 4 .IX Item "$obj->nativeLanguage()" .PD 0 .ie n .IP "$obj\->\fBreadConfig\fR($filename)" 4 .el .IP "\f(CW$obj\fR\->\fBreadConfig\fR($filename)" 4 .IX Item "$obj->readConfig($filename)" .IP "Log::Report::Domain\->\fBreadConfig\fR($filename)" 4 .IX Item "Log::Report::Domain->readConfig($filename)" .PD Helper method, which simply parses the content \f(CW$filename\fR into a \s-1HASH\s0 to be used as parameters to \fIconfigure()\fR. The filename must end on '.pl', to indicate that it uses perl syntax (can be processed with Perl's \f(CW\*(C`do\*(C'\fR command) or end on '.json'. See also chapter \*(L"Configuring\*(R" below. .Sp Currently, this file can be in Perl native format (when ending on \f(CW\*(C`.pl\*(C'\fR) or \s-1JSON\s0 (when it ends with \f(CW\*(C`.json\*(C'\fR). Various modules may explain parts of what can be found in these files, for instance Log::Report::Translator::Context. .ie n .IP "$obj\->\fBsetContext\fR(STRING|HASH|ARRAY|PAIRS)" 4 .el .IP "\f(CW$obj\fR\->\fBsetContext\fR(STRING|HASH|ARRAY|PAIRS)" 4 .IX Item "$obj->setContext(STRING|HASH|ARRAY|PAIRS)" Temporary set the default translation context for messages. This is used when the message is created without a \f(CW\*(C`_context\*(C'\fR parameter. The context can be retrieved with \fIdefaultContext()\fR. .Sp Contexts are totally ignored then there are no \f(CW\*(C`context_rules\*(C'\fR. When you do not wish to change settings, you may simply provide a \s-1HASH.\s0 .Sp example: .Sp .Vb 1 \& use Log::Report \*(Aqmy\-domain\*(Aq, context_rules => {}; .Ve .ie n .IP "$obj\->\fBtranslator\fR()" 4 .el .IP "\f(CW$obj\fR\->\fBtranslator\fR()" 4 .IX Item "$obj->translator()" .PD 0 .ie n .IP "$obj\->\fBupdateContext\fR(STRING|HASH|ARRAY|PAIRS)" 4 .el .IP "\f(CW$obj\fR\->\fBupdateContext\fR(STRING|HASH|ARRAY|PAIRS)" 4 .IX Item "$obj->updateContext(STRING|HASH|ARRAY|PAIRS)" .PD [1.10] Make changes and additions to the active context (see \fIsetContext()\fR). .SS "Action" .IX Subsection "Action" Extends \*(L"Action\*(R" in Log::Report::Minimal::Domain. .ie n .IP "$obj\->\fBinterpolate\fR( $msgid, [$args] )" 4 .el .IP "\f(CW$obj\fR\->\fBinterpolate\fR( \f(CW$msgid\fR, [$args] )" 4 .IX Item "$obj->interpolate( $msgid, [$args] )" Inherited, see \*(L"Action\*(R" in Log::Report::Minimal::Domain .ie n .IP "$obj\->\fBtranslate\fR($message, $language)" 4 .el .IP "\f(CW$obj\fR\->\fBtranslate\fR($message, \f(CW$language\fR)" 4 .IX Item "$obj->translate($message, $language)" Translate the \f(CW$message\fR into the \f(CW$language\fR. .SH "DETAILS" .IX Header "DETAILS" .SS "Configuring" .IX Subsection "Configuring" Configuration of a domain can happen in many ways: either explicitly or implicitly. The explicit form: .PP .Vb 2 \& package My::Package; \& use Log::Report \*(Aqmy\-domain\*(Aq; \& \& textdomain \*(Aqmy\-domain\*(Aq, %configuration; \& textdomain\->configure(%configuration); \& textdomain\->configure(\e%configuration); \& \& textdomain\->configure(conf => $filename); .Ve .PP The implicit form is (no variables possible, only constants!) .PP .Vb 3 \& package My::Package; \& use Log::Report \*(Aqmy\-domain\*(Aq, %configuration; \& use Log::Report \*(Aqmy\-domain\*(Aq, conf => \*(Aq/filename\*(Aq; .Ve .PP 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. .PP This also works for Log::Report::Optional, which is a dressed-down version of Log::Report. .PP \fIconfiguring your own formatter\fR .IX Subsection "configuring your own formatter" .PP [0.91] The \f(CW\*(C`PRINTI\*(C'\fR is a special constants for configure(formatter), and will use String::Print function \f(CW\*(C`printi()\*(C'\fR, with the standard tricks. .PP .Vb 6 \& textdomain \*(Aqsome\-domain\*(Aq \& formatter => \& { class => \*(AqString::Print\*(Aq # default \& , method => \*(Aqsprinti\*(Aq # default \& , %options # constructor options for the class \& ); .Ve .PP When you want your own formatter, or configuration of \f(CW\*(C`String::Print\*(C'\fR, you need to pass a \s-1CODE.\s0 Be aware that you may loose magic added by Log::Report and other layers, like Log::Report::Template: .PP .Vb 2 \& textdomain \*(Aqsome\-domain\*(Aq \& , formatter => \e&my_formatter; .Ve .PP \fIconfiguring global values\fR .IX Subsection "configuring global values" .PP 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: .PP .Vb 8 \& ### first enabled translation contexts \& use Log::Report \*(Aqmy\-domain\*(Aq, context_rules => {}; \& # or \& use Log::Report \*(Aqmy\-domain\*(Aq; \& textdomain\->configure(context_rules => {}); \& # or \& textdomain \*(Aqmy\-domain\*(Aq \& , content_rules => {}; \& \& ### every time you start working for a different virtual host \& (textdomain \*(Aqmy\-domain\*(Aq)\->setContext(host => $host); \& \& ### now you can use that in your code \& package My::Package; \& use Log::Report \*(Aqmy\-domain\*(Aq; \& error _\|_x"in {_context.host} not logged\-in {user}", user => $username; .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" This module is part of Log-Report distribution version 1.27, built on June 01, 2018. Website: \fIhttp://perl.overmeer.net/CPAN/\fR .SH "LICENSE" .IX Header "LICENSE" Copyrights 2007\-2018 by [Mark Overmeer ]. For other contributors see ChangeLog. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See \fIhttp://dev.perl.org/licenses/\fR