Returns true if the previous try block did produce a terminal\nerror. This \"try\" object is assigned to $@, and the usual\nperl syntax is if($@) {...error-handler...}.
Which STRING to use when an ARRAY is being filled-in as parameter.
\n" }, "id483" : { "call" : "$obj->index", "id" : "id483", "name" : "index", "intro" : "Returns a HASH of all defined PO objects, organized by msgid. Please try\nto avoid using this: use msgid() for lookup and add() for adding\ntranslations.
\n", "type" : "i_method" }, "id433" : { "intro" : "Remove all references.
\n", "options" : [ [ "id434", "id435" ] ], "type" : "i_method", "call" : "$obj->cleanup( %options )", "id" : "id433", "name" : "cleanup" }, "id911" : { "name" : "tags", "id" : "id911", "call" : "$obj->tags", "type" : "i_method", "intro" : "[1.44] Returns the LIST of tags which are defined for this message; message\ngroup indicators, as often found in exception-based programming.
\n" }, "id437-id289" : { "diagnostics" : [ "id438-id289" ], "call" : "$obj->write( [$domain], %options )", "type" : "i_method", "intro" : "Inherited, see Log::Report::Extract::write()
", "extends" : "id437", "id" : "id437-id289", "name" : "write" }, "id1099" : { "value" : "<basename $0>", "name" : "identity", "id" : "id1099", "type" : "default" }, "id909-id217" : { "intro" : "Inherited, see Log::Report::Message::context()
", "type" : "i_method", "call" : "$obj->context", "id" : "id909-id217", "name" : "context", "extends" : "id909" }, "id786-id1174" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "params" : "CLASS", "type" : "option", "extends" : "id786", "id" : "id786-id1174", "name" : "package" }, "id796-id818" : { "id" : "id796-id818", "name" : "max_line", "extends" : "id796", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "params" : "INTEGER", "type" : "option" }, "id416" : { "type" : "chapter", "path" : "METHODS", "nest" : [ "id417", "id425", "id431" ], "level" : 1, "id" : "id416", "name" : "METHODS" }, "id465" : { "value" : "undef",
"id" : "id465",
"name" : "filename",
"type" : "default"
},
"id438-id289" : {
"id" : "id438-id289",
"name" : "starting new textdomain $domain, template in $filename",
"extends" : "id438",
"subroutine" : "id437",
"type" : "info",
"intro" : "Inherited, see Log::Report::Extract::write()
" }, "id790-id1090" : { "name" : "linenr", "id" : "id790-id1090", "extends" : "id790", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "params" : "INTEGER", "type" : "option" }, "id791-id944" : { "extends" : "id791", "value" : "<required>", "id" : "id791-id944", "name" : "linenr", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "type" : "default" }, "id835" : { "type" : "default", "id" : "id835", "name" : "on_die", "value" : "'ERROR'" }, "id1293" : { "path" : "DETAILS", "nest" : [ "id1294" ], "type" : "chapter", "level" : 1, "id" : "id1293", "name" : "DETAILS" }, "id792" : { "params" : "STRING", "type" : "option", "id" : "id792", "name" : "call" }, "id304" : { "path" : "METHODS/Processors", "type" : "section", "subroutines" : [ "id439-id289", "id433-id289", "id437-id289", "id305", "id436-id289" ], "level" : 2, "id" : "id304", "name" : "Processors" }, "id425" : { "id" : "id425", "name" : "Attributes", "level" : 2, "subroutines" : [ "id428", "id430", "id426", "id429", "id427" ], "type" : "section", "path" : "METHODS/Attributes" }, "id890-id217" : { "id" : "id890-id217", "name" : "_class", "extends" : "id890", "value" : "undef",
"type" : "default",
"intro" : "Inherited, see Log::Report::Message::new(_class)
" }, "id885" : { "type" : "option", "params" : "$tags|\\@tags", "intro" : "Alternative name for _tag
\n", "name" : "_tags", "id" : "id885" }, "id1103" : { "value" : "'user'", "name" : "facility", "id" : "id1103", "type" : "default" }, "id644" : { "id" : "id644", "name" : "charset", "type" : "option", "params" : "STRING", "intro" : "The character-set which is used for the file. When not specified, it is\ntaken from the \"Content-Type\" field in the PO-file.
\n" }, "id771-id1174" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::name()
", "extends" : "id771", "id" : "id771-id1174", "name" : "name", "call" : "$obj->name" }, "id863" : { "type" : "overload", "intro" : "An (accidental) use of concatenation (a dot where a comma should be\nused) would immediately stringify the object. This is avoided by\noverloading that operation.
\n", "name" : "'.'", "id" : "id863", "call" : "overload '.'; concatenation" }, "id973" : { "type" : "error", "name" : "Log4perl level '$level' must be in 0-5", "id" : "id973", "subroutine" : "id967" }, "id1131" : { "path" : "METHODS", "nest" : [ "id1132", "id1134", "id1152" ], "type" : "chapter", "level" : 1, "name" : "METHODS", "id" : "id1131" }, "id1012" : { "id" : "id1012", "name" : "assert", "call" : "assert( $message )", "type" : "function", "intro" : "Short for report ASSERT => $message
Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
" }, "id1097" : { "type" : "default", "id" : "id1097", "name" : "format_reason", "value" : "'IGNORE'" }, "id650" : { "subroutine" : "id643", "id" : "id650", "name" : "cannot read superblock from $fn: $!", "type" : "fault" }, "id514" : { "name" : "DESCRIPTION", "id" : "id514", "type" : "chapter", "intro" : "This module is administering one translation object. Sets of PO\nrecords are kept in a POT file, implemented in Log::Report::Lexicon::POT.
\n", "path" : "DESCRIPTION", "level" : 1 }, "id211" : { "name" : "DESCRIPTION", "id" : "id211", "type" : "chapter", "path" : "DESCRIPTION", "intro" : "This module will allow libraries (helper modules) to have a dependency\nto a small module instead of the full Log-Report distribution. The full\npower of Log::Report is only released when the main program uses that\nmodule. In that case, the module using the 'Optional' will also use the\nfull Log::Report, otherwise the dressed-down Log::Report::Minimal\nversion.
For the full documentation:
\n\nThe latter provides the same functions from the former, but is the\nsimpelest possible way.
\n", "level" : 1 }, "id440-id289" : { "intro" : "Inherited, see Log::Report::Extract::store()
", "type" : "error", "subroutine" : "id439", "name" : "no context tags allowed in plural `$msgid'", "id" : "id440-id289", "extends" : "id440" }, "id797" : { "type" : "default", "name" : "max_line", "id" : "id797", "value" : "undef"
},
"id273" : {
"type" : "i_method",
"intro" : "Forwards the %options to Log::Report::Template::addTextdomain().
\n", "examples" : [ "id274" ], "call" : "$obj->addTextDomain( %options )", "id" : "id273", "name" : "addTextDomain" }, "id787-id958" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "value" : "<required>", "extends" : "id787", "id" : "id787-id958", "name" : "package" }, "id775" : { "name" : "needs", "id" : "id775", "call" : "$obj->needs( [$reason] )", "type" : "i_method", "intro" : "Returns the list with all REASONS which are needed to fulfill this\ndispatcher's needs. When disabled, the list is empty, but not forgotten.
\n\n[0.999] when only one $reason is specified, it is returned if in the\nlist.
\n" }, "id696" : { "intro" : "The tools which handle translations expect the msgctxt to be static.\nFor instance, contain a filename where the string is used to disambigue\naccidental collissions of the use of the same msgid for different\npurposes.
\n\nNow, we have designed far more flexible contexts. We need to generate all\npossible msgctxt values while extracting msgids to update the PO-files.\nTherefore, we need a map-file.
\n\nThe context maps are included in a configuration file which is passed to\nxgettext-perl and to the program which uses contexts.\nSee Log::Report::Domain::readConfig().
\n\nExample of such configuration file: (JSON syntax and Perl syntax)
\n\n === JSON === ==== Perl == =\n {{\n \"context_rules\" : { context_rules => {\n \"gender\" : [ gender => [\n \"male\", 'male',\n \"female\" 'female'\n ] ]\n } }\n } }\n\n\nor
\n\n { {\n \"context_rules\" : { context_rules => {\n \"gender\" : { gender => {\n \"alternatives\" : [ alternatives => [\n \"male\", 'male',\n \"female\", 'female',\n \"unknown\" 'unknown'\n ] ]\n ... more config for 'gender' ...\n } }\n } }\n } }\n\n\nAs \"alternatives\", we list the alternatives as known by the application\ninternals. Each msgid which contains a {<gender} mark will be\nreplicated three times, in each language table. Each copy will be marked\nwith a different value from \"alternatives\".
However, languages differ. For instance, in some language we may address\nthe unknown gender as being a male person. In other languages, the\ntranslation can express this \"unknown\" personality. To get this to work,\nyou can use the msgctxt construct.
The default msgctxt, as used in the previous example, is simply mapping\nthe alternatives directly on msgctxt values which are the same:
\n { { context_rules =>\n \"context_rules\" : { { gender =>\n \"gender\" : { { default => { qw/\n \"default\" : { female female\n \"female\" : \"female\", male male\n \"male\" : \"male\" unknown male / }\n \"unknown\" : \"male\", , 'nl,de' => { qw/\n }, unknown x / }\n \"nl,de\" : {\n \"unknown\" : \"x\"\n } }\n ... more configuration ...\n }\n ... more context rules ...\n } }\n } }\n\n\nBy default, there will only be two msgid copies in a language file,\nbecause at run-time the \"unknown\" is mapped on \"male\". An exception\nfor the Dutch (nl*) and German (de*) tables, which apparently support\nthe third gender.
\n\nIf you are not interested for a certain tag, then put it on 'IGNORE'\nas default or for your language.
\n\n \"default\" : \"IGNORE\", default => 'IGNORE'\n \"nl\": \"IGNORE\" nl => 'IGNORE'\n\n", "path" : "DETAILS/Using context_rules/Configuration", "type" : "subsection", "level" : 3, "id" : "id696", "name" : "Configuration" }, "id798" : { "id" : "id798", "name" : "max_params", "params" : "INTEGER", "type" : "option" }, "id1325" : { "level" : 1, "type" : "chapter", "intro" : "
Log::Report::Minimal::Domain is extended by\n Log::Report::Domain\n\n", "path" : "INHERITANCE", "id" : "id1325", "name" : "INHERITANCE" }, "id1116" : { "subroutines" : [ "id771-id1090", "id774-id1090", "id775-id1090", "id772-id1090", "id773-id1090", "id1117" ], "id" : "id1116", "name" : "Attributes", "level" : 2, "path" : "METHODS/Attributes", "type" : "section" }, "id1173-id618" : { "intro" : "
Inherited, see Log::Report::Translator::load()
", "type" : "i_method", "call" : "$obj->load( $domain, $locale )", "extends" : "id1173", "name" : "load", "id" : "id1173-id618" }, "id264" : { "distribution" : "Dancer2-Plugin-LogReport", "package" : "Dancer2::Template::TTLogReport", "inheritance" : { "extends" : [ "Moo::Object" ] }, "id" : "id264", "name" : "Dancer2::Template::TTLogReport", "title" : "Template toolkit engine with Log::Report translations for Dancer2", "is_pure_pod" : false, "chapters" : [ "id265", "id1326", "id266", "id267", "id268", "id276" ], "version" : "2.03" }, "id784" : { "name" : "collectLocation", "id" : "id784", "call" : "$any->collectLocation", "type" : "ci_method", "intro" : "Collect the information to be displayed as line where the error occurred.
\n" }, "id561" : { "type" : "warning", "id" : "id561", "name" : "do not understand line at $where:\\n $line", "subroutine" : "id557" }, "id734" : { "path" : "METHODS/Managing PO's/Translation", "type" : "subsection", "subroutines" : [ "id736", "id735" ], "level" : 3, "id" : "id734", "name" : "Translation" }, "id121" : { "path" : "FUNCTIONS", "nest" : [ "id123", "id133", "id145", "id155" ], "type" : "chapter", "subroutines" : [ "id122" ], "level" : 1, "id" : "id121", "name" : "FUNCTIONS" }, "id779" : { "call" : "$obj->translate( \\%options, $reason, $message )", "name" : "translate", "id" : "id779", "intro" : "See Processing the message, which describes the actions taken by\nthis method. A string is returned, which ends on a new-line, and\nmay be multi-line (in case a stack trace is produced).
\n", "type" : "i_method" }, "id656" : { "type" : "fault", "subroutine" : "id643", "id" : "id656", "name" : "cannot read msgids from $fn, need $size at $loc: $!" }, "id758" : { "type" : "default", "name" : "accept", "id" : "id758", "value" : "depend on mode"
},
"id1177" : {
"id" : "id1177",
"name" : "DESCRIPTION",
"type" : "chapter",
"path" : "DESCRIPTION",
"intro" : "This dispatchers produces output to and Log::Dispatch back-end.\n(which will NOT be automatically installed for you).
The REASON for a message often uses names which are quite similar to the\nlog-levels used by Log::Dispatch. However: they have a different\napproach. The REASON of Log::Report limits the responsibility of the\nprogrammer to indicate the cause of the message: whether it was able to\nhandle a certain situation. The Log::Dispatch levels are there for the\nuser's of the program. However: the programmer does not known anything\nabout the application (in the general case). This is cause of much of\nthe trickery in Perl programs.
\n\nThe default translation table is list below. You can change the mapping\nusing new(to_level). See example in SYNOPSIS.
\n", "level" : 1 }, "id1246" : { "id" : "id1246", "name" : "format", "call" : "$obj->format", "type" : "i_method" }, "id744-id637" : { "type" : "error", "intro" : "Inherited, see Log::Report::Lexicon::Table::setupPluralAlgorithm()
", "name" : "invalid plural-form algorithm '$alg'.", "id" : "id744-id637", "extends" : "id744", "subroutine" : "id743" }, "id1147-id375" : { "extends" : "id1147", "name" : "the native_language '$locale' is not a valid locale", "id" : "id1147-id375", "subroutine" : "id1138", "type" : "error", "intro" : "Inherited, see Log::Report::Domain::configure()
" }, "id912-id217" : { "intro" : "Inherited, see Log::Report::Message::classes()
", "type" : "i_method", "call" : "$obj->classes", "id" : "id912-id217", "name" : "classes", "extends" : "id912" }, "id1129" : { "id" : "id1129", "name" : "SYNOPSIS", "intro" : "# internal usage\n use Log::Report::Domain;\n my $domain = Log::Report::Domain->new(name => $name);\n\n # find a ::Domain object\n use Log::Report 'my-domain';\n my $domain = textdomain 'my-domain'; # find domain config\n my $domain = textdomain; # config of this package\n\n # explicit domain configuration\n package My::Package;\n use Log::Report 'my-domain'; # set textdomain for package\n\n textdomain $name, %configure; # set config, once per program\n (textdomain $name)->configure(%configure); # same\n textdomain->configure(%configure); # same if current package in $name\n\n # implicit domain configuration\n package My::Package;\n use Log::Report 'my-domain', %configure;\n\n # external file for configuration (perl or json format)\n use Log::Report 'my-domain', config => $filename;\n\n use Log::Report 'my-domain';\n textdomain->configure(config => $filename);\n\n", "path" : "SYNOPSIS", "type" : "chapter", "level" : 1 }, "id690" : { "id" : "id690", "name" : "Contexts in Log::Report", "type" : "section", "path" : "DETAILS/Contexts in Log::Report", "intro" : "
For Log::Report, the power of \"context\" is extended with selecting\nbetween alternatives for the use of a msgid on the same spot.
\n\nFor instance, the gender of the user of the website determines whether\n`he' or `she' needs to be used in the translation. In this example,\nthe gender is set as context keyword in the message:
\n\n my ($name, $sex) = ('Jack', 'male');\n print __x\"{name<gender} found his key\", name => $name,\n _context => \"gender=$sex\";\n\n\nThis would also be possible in traditional gettext, although probably\nrarely used. A complication is that the scripts to maintain the po\ntables are not too smart; do not understand complex code constructs.\nProbably this would beed needed:
\n\n if(sex==MALE)\n { printf pgettext('male', \"%s found his key\\n\", name);\n }\n else\n { printf pgettext('female', \"%s found her key\\n\", name);\n }\n\n",
"level" : 2
},
"id521" : {
"value" : "undef",
"id" : "id521",
"name" : "msgid_plural",
"type" : "default"
},
"id1057" : {
"subroutine" : "id1045",
"id" : "id1057",
"name" : "no domain for configuration options in $fn line $line",
"type" : "error"
},
"id794-id958" : {
"params" : "ARRAY",
"type" : "option",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "id" : "id794-id958", "name" : "params", "extends" : "id794" }, "id224" : { "distribution" : "Dancer2-Plugin-LogReport", "inheritance" : { "extends" : [ "Dancer::Logger::Abstract", "Exporter" ] }, "package" : "Dancer::Logger::LogReport", "name" : "Dancer::Logger::LogReport", "id" : "id224", "is_pure_pod" : false, "title" : "reroute Dancer logs into Log::Report", "chapters" : [ "id225", "id1337", "id226", "id227" ], "version" : "2.03" }, "id757" : { "id" : "id757", "name" : "accept", "intro" : "See Log::Report::Util::expand_reasons() for possible values. If\nthe initial mode for this dispatcher does not need verbose or debug\ninformation, then those levels will not be accepted.
\n\nWhen the mode equals \"NORMAL\" (the default) then accept's default\nis NOTICE- . In case of \"VERBOSE\" it will be INFO- , ASSERT\nresults in ASSERT- , and \"DEBUG\" in ALL.
my @colors = (N__\"red\", N__\"green\", N__\"blue\");\n my @colors = N__w\"red green blue\"; # same\n print __ $colors[1];\n\n", "type" : "example" }, "id161" : { "name" : "DESCRIPTION", "id" : "id161", "level" : 1, "path" : "DESCRIPTION", "intro" : "
Read Log::Report::Domain.
\n", "type" : "chapter" }, "id1187" : { "id" : "id1187", "name" : "callbacks", "type" : "option", "params" : "CODE|\\@CODE", "intro" : "See Log::Dispatch::Output.
\n" }, "id791-id1082" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "id" : "id791-id1082", "name" : "linenr", "extends" : "id791", "value" : "<required>" }, "id752" : { "level" : 1, "type" : "chapter", "path" : "SYNOPSIS", "intro" : "use Log::Report;\n\n # The following will be created for you automatically\n dispatcher 'PERL', 'default', accept => 'NOTICE-';\n dispatcher close => 'default'; # after deamonize\n\n dispatcher 'FILE', 'log',\n mode => 'DEBUG', to => '/var/log/mydir/myfile';\n\n # Full package name is used, same as 'FILE'\n dispatcher Log::Report::Dispatch::File => 'stderr',\n to => \\*STDERR, accept => 'NOTICE-';\n\n", "name" : "SYNOPSIS", "id" : "id752" }, "id839" : { "type" : "i_method", "intro" : "
Check whether the try stops message which were produced for $reason.
\n", "id" : "id839", "name" : "hides", "call" : "$obj->hides( $reason )" }, "id1253" : { "path" : "METHODS/Logging", "type" : "section", "subroutines" : [ "id781-id1228", "id785-id1228", "id778-id1228", "id784-id1228", "id1254", "id780-id1228", "id783-id1228", "id779-id1228" ], "id" : "id1253", "name" : "Logging", "level" : 2 }, "id1179" : { "subroutines" : [ "id1180" ], "level" : 2, "name" : "Constructors", "id" : "id1179", "path" : "METHODS/Constructors", "type" : "section" }, "id429" : { "type" : "i_method", "intro" : "Returns the list of Log::Report::Lexicon::POT objects which contain\nthe tables for $domain.
\n", "name" : "pots", "id" : "id429", "call" : "$obj->pots( $domain )" }, "id889" : { "intro" : "Deprecated alternative for _tag.
\n", "type" : "option", "params" : "$tags|\\@tags", "name" : "_class", "id" : "id889" }, "id964" : { "name" : "Limitiations", "id" : "id964", "type" : "subsection", "path" : "DESCRIPTION/Categories/Limitiations", "intro" : "The global $caller_depth concept of Log::Log4perl is broken.\nThat variable is used to find the filename and line number of the logged\nmessages. But these messages may have been caught, rerouted, eval'ed, and\notherwise followed a unpredictable multi-leveled path before it reached\nthe Log::Log4perl dispatcher. This means that layout patterns %F\nand %L are not useful in the generic case, maybe in your specific case.
undef"
},
"id790-id818" : {
"id" : "id790-id818",
"name" : "linenr",
"extends" : "id790",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "type" : "option", "params" : "INTEGER" }, "id780-id1174" : { "extends" : "id780", "name" : "collectStack", "id" : "id780-id1174", "call" : "$any->collectStack( [$maxdepth] )", "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::collectStack()
" }, "id924" : { "intro" : "Return the concatenation of the prepend, msgid, and append strings. Variable\nexpansions within the msgid is not performed.
\n", "type" : "i_method", "call" : "$obj->untranslated", "id" : "id924", "name" : "untranslated" }, "id75" : { "intro" : " use String::Print; # all\n use String::Print 'sprinti'; # only sprinti\n\n use String::Print 'printi', # only printi\n modifiers => [ EUR => sub {sprintf \"%5.2f e\", $_[0]} ],\n serializers => [ UNDEF => sub {'-'} ],\n defaults => [ DT => { standard => 'ISO' } ];\n\n printi \"price: {p EUR}\", p => 3.1415; # price: ␣␣3.14 e\n printi \"count: {c}\", c => undef; # count: -\n my $s = sprinti \"price: {p EUR}\", p => 7; # output in $s\n\n",
"type" : "example",
"id" : "id75"
},
"id1189" : {
"type" : "error",
"subroutine" : "id1180",
"name" : "Log::Dispatch level '$level' not understood",
"id" : "id1189"
},
"id1333" : {
"level" : 1,
"type" : "chapter",
"intro" : "Log::Report::Dispatcher is extended by\n Log::Report::Dispatcher::Callback\n Log::Report::Dispatcher::File\n Log::Report::Dispatcher::Log4perl\n Log::Report::Dispatcher::LogDispatch\n Log::Report::Dispatcher::Perl\n Log::Report::Dispatcher::Syslog\n Log::Report::Dispatcher::Try\n\n", "path" : "INHERITANCE", "name" : "INHERITANCE", "id" : "id1333" }, "id796-id1090" : { "extends" : "id796", "name" : "max_line", "id" : "id796-id1090", "intro" : "
Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "type" : "option", "params" : "INTEGER" }, "id1301" : { "type" : "subsection", "path" : "DETAILS/Processing the message/Filters", "level" : 3, "id" : "id1301", "name" : "Filters" }, "id1127" : { "inheritance" : { "extends" : [ "Log::Report::Minimal::Domain" ], "extended_by" : [ "Log::Report::Template::Textdomain" ] }, "package" : "Log::Report::Domain", "distribution" : "Log-Report", "is_pure_pod" : false, "title" : "administer one text-domain", "name" : "Log::Report::Domain", "id" : "id1127", "chapters" : [ "id1128", "id1321", "id1129", "id1130", "id1131", "id1159" ], "version" : "1.45" }, "id1059" : { "type" : "error", "name" : "translator must be a $pkg object for $domain", "id" : "id1059", "subroutine" : "id1045" }, "id896-id217" : { "intro" : "Inherited, see Log::Report::Message::new(_lang)
", "type" : "default", "extends" : "id896", "value" : "<from locale>", "id" : "id896-id217", "name" : "_lang" }, "id905-id217" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Message::msgid()
", "extends" : "id905", "id" : "id905-id217", "name" : "msgid", "call" : "$obj->msgid" }, "id1149-id375" : { "name" : "readConfig", "id" : "id1149-id375", "extends" : "id1149", "call" : "$any->readConfig( $filename )", "diagnostics" : [ "id1150-id375", "id1151-id375" ], "intro" : "Inherited, see Log::Report::Domain::readConfig()
", "type" : "ci_method" }, "id1163" : { "id" : "id1163", "name" : "Log::Report::Translator", "title" : "base implementation for translating messages", "is_pure_pod" : false, "distribution" : "Log-Report", "package" : "Log::Report::Translator", "inheritance" : { "extended_by" : [ "Log::Report::Translator::Gettext", "Log::Report::Translator::POT" ] }, "version" : "1.45", "chapters" : [ "id1164", "id1315", "id1165", "id1166", "id1167" ] }, "id469" : { "type" : "default", "name" : "charset", "id" : "id469", "value" : "<required>" }, "id925" : { "id" : "id925", "name" : "concat", "examples" : [ "id926" ], "call" : "$obj->concat( $text|$message, [$prepend] )", "intro" : "This method implements the overloading of concatenation, which is used\nto delay translations even longer. When $prepend is true, the $text\nor $message (another Log::Report::Message) will be prepended, otherwise\nit is appended in the final display.
Inherited, see Log::Report::Dispatcher::type()
", "name" : "type", "id" : "id772-id958", "extends" : "id772", "call" : "$obj->type" }, "id1062" : { "id" : "id1062", "name" : "needs", "examples" : [ "id1063" ], "call" : "$class->needs( $reason, [$reasons] )", "intro" : "Returns true when the reporter needs any of the $reasons, when any of\nthe active dispatchers is collecting messages in the specified level.\nThis is useful when the processing of data for the message is relatively\nexpensive, but for instance only required in debug mode.
Inherited, see Log::Report::Message::prepend()
", "extends" : "id904", "name" : "prepend", "id" : "id904-id217", "call" : "$obj->prepend" }, "id473" : { "type" : "error", "subroutine" : "id467", "name" : "unsupported charset $charset in $fn.", "id" : "id473" }, "id1272" : { "type" : "subsection", "path" : "METHODS/Managing PO's/Translation", "level" : 3, "name" : "Translation", "id" : "id1272", "subroutines" : [ "id589", "id588" ] }, "id897" : { "intro" : "[1.00] Set the @keywords which can be used to select alternatives\nbetween translations. Read the DETAILS section in\nLog::Report::Translator::Context
\n", "type" : "option", "params" : "$keyword|\\@keywords", "id" : "id897", "name" : "_context" }, "id1311" : { "id" : "id1311", "name" : "Automatic parameters", "level" : 2, "type" : "section", "nest" : [ "id1312", "id1313" ], "path" : "DETAILS/Automatic parameters" }, "id796-id944" : { "extends" : "id796", "id" : "id796-id944", "name" : "max_line", "type" : "option", "params" : "INTEGER", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
" }, "id427-id697" : { "name" : "charset", "id" : "id427-id697", "extends" : "id427", "call" : "$obj->charset", "type" : "i_method", "intro" : "Inherited, see Log::Report::Extract::charset()
" }, "id781-id1174" : { "name" : "addSkipStack", "id" : "id781-id1174", "extends" : "id781", "call" : "$any->addSkipStack( @CODE )", "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::addSkipStack()
" }, "id791-id818" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "type" : "default", "name" : "linenr", "id" : "id791-id818", "extends" : "id791", "value" : "<required>" }, "id933" : { "id" : "id933", "name" : "Messages with plural forms", "nest" : [ "id934" ], "level" : 2, "type" : "section", "intro" : "The Log::Report::__xn() message constructor is used when you need\na different translation based on the count of one of the inserted\nfields.
\n\n fault __x\"cannot read {file}\", file => $fn;\n # --> FAULT: cannot read /etc/shadow: Permission denied\\n\n\n print __xn\"directory {dir} contains one file\",\n \"directory {dir} contains {nr_files} files\",\n scalar(@files), # (1) (2) (3)\n nr_files => scalar @files, # (4)\n dir => $dir;\n\n\n(1) this required third parameter is used to switch between the different\nplural forms. English has only two forms, but some languages have many\nmore.
\n\n(2) the \"scalar\" keyword is not needed, because the third parameter is\nin SCALAR context. You may also pass \\@files there, because ARRAYs\nwill be converted into their length. A HASH will be converted into the\nnumber of keys in the HASH.
(3) you could also simply pass a reference to the ARRAY: it will take\nthe length as counter. With a HASH, it will count the number of keys.
\n\n(4) the scalar keyword is required here, because it is LIST context:\notherwise all filenames will be filled-in as parameters to __xn().\nSee below for the available _count value, to see how the nr_files\nparameter can disappear.
\n print __xn\"directory {dir} contains one file\",\n \"directory {dir} contains {_count} files\",\n \\@files, dir => $dir;\n\n\nSome languages need more than two translations based on the counter.\nThis is solved by the translation table definition. The two msgids\ngive here are simply the fallback, when there is not translation table\nactive.
\n", "path" : "DETAILS/Messages with plural forms" }, "id1243" : { "type" : "error", "id" : "id1243", "name" : "unknown format parameter `$what'", "subroutine" : "id1234" }, "id309" : { "name" : "pattern", "id" : "id309", "value" : "<from new(pattern)>", "type" : "default" }, "id983" : { "name" : "FUNCTIONS", "id" : "id983", "level" : 1, "nest" : [ "id984", "id1010", "id1022", "id1039", "id1044", "id1061" ], "path" : "FUNCTIONS", "type" : "chapter" }, "id649" : { "name" : "unsupported file type (magic number is $magic)", "id" : "id649", "subroutine" : "id643", "type" : "error" }, "id177-id1127" : { "intro" : "Inherited, see Log::Report::Minimal::Domain::configure(formatter)
", "type" : "default", "value" : "PRINTI",
"extends" : "id177",
"name" : "formatter",
"id" : "id177-id1127"
},
"id916" : {
"id" : "id916",
"name" : "valueOf",
"intro" : "Lookup the named $parameter for the message. All pre-defined names\nhave their own method which should be used with preference.
\n", "type" : "i_method", "examples" : [ "id917" ], "call" : "$obj->valueOf( $parameter )" }, "id965" : { "path" : "METHODS", "nest" : [ "id966", "id974", "id976" ], "type" : "chapter", "level" : 1, "name" : "METHODS", "id" : "id965" }, "id428-id697" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Extract::domains()
", "extends" : "id428", "name" : "domains", "id" : "id428-id697", "call" : "$obj->domains" }, "id1282" : { "name" : "Filters", "id" : "id1282", "level" : 3, "path" : "DETAILS/Processing the message/Filters", "type" : "subsection" }, "id875" : { "intro" : "The message label, which refers to some translation information.\nUsually a string which is close the English version of the message.\nThis will also be used if there is no translation possible/known.
\n\nLeading white-space \\s will be added to _prepend. Trailing\nwhite-space will be added before _append.
undef",
"id" : "id898",
"name" : "_context"
},
"id790-id1082" : {
"type" : "option",
"params" : "INTEGER",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "extends" : "id790", "name" : "linenr", "id" : "id790-id1082" }, "id1138-id375" : { "call" : "$obj->configure( %options )", "diagnostics" : [ "id1147-id375", "id1148-id375" ], "intro" : "Inherited, see Log::Report::Domain::configure()
", "type" : "i_method", "extends" : "id1138", "name" : "configure", "id" : "id1138-id375", "options" : [ [ "id1145-id375", "id1146-id375" ], [ "id1143-id375", "id1144-id375" ], [ "id176-id375", "id177-id375" ], [ "id1141-id375", "id1142-id375" ], [ "id1139-id375", "id1140-id375" ], [ "id174-id375", "id175-id375" ] ] }, "id160" : { "name" : "SYNOPSIS", "id" : "id160", "level" : 1, "type" : "chapter", "intro" : "use Log::Report::Minimal::Domain;\n my $domain = Log::Report::Minimal::Domain->new(name => $name);\n\n # normal usage\n use Log::Report::Optional; # or Log::Report itself\n my $domain = textdomain $name; # find config\n textdomain $name, %configure; # set config, only once.\n\n", "path" : "SYNOPSIS" }, "id745-id637" : { "intro" : "
Inherited, see Log::Report::Lexicon::Table::nrPlurals()
", "type" : "i_method", "call" : "$obj->nrPlurals", "extends" : "id745", "name" : "nrPlurals", "id" : "id745-id637" }, "id1157-id375" : { "call" : "$obj->defaultContext", "id" : "id1157-id375", "name" : "defaultContext", "extends" : "id1157", "intro" : "Inherited, see Log::Report::Domain::defaultContext()
", "type" : "i_method" }, "id172-id1127" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Minimal::Domain::format()
", "name" : "format", "id" : "id172-id1127", "extends" : "id172", "call" : "$obj->format" }, "id723" : { "type" : "c_method", "id" : "id723", "name" : "new", "call" : "$class->new( %options )" }, "id1166" : { "level" : 1, "type" : "chapter", "path" : "DESCRIPTION", "intro" : "A module (or distribution) has a certain way of translating messages,\nusually gettext. The translator is based on some textdomain\nfor the message, which can be specified as option per text element,\nbut usually is package scoped.
This base class does not translate at all: it will use the MSGID\n(and MSGID_PLURAL if available). It's a nice fallback if the\nlanguage packs are not installed.
\n", "name" : "DESCRIPTION", "id" : "id1166" }, "id89" : { "name" : "DETAILS", "id" : "id89", "nest" : [ "id90", "id91", "id92", "id95", "id96", "id110", "id113" ], "level" : 1, "path" : "DETAILS", "intro" : "Your manual-page reader may not support the unicode used\n in some of the examples below.\n\n", "type" : "chapter" }, "id520" : { "id" : "id520", "name" : "msgid_plural", "type" : "option", "params" : "$msgid" }, "id691" : { "level" : 2, "path" : "DETAILS/Using context_rules", "intro" : "
In Log::Report's extended concept of \"contexts\", you can select between\nmultiple translations for the same msgid, when they
\n\nIn the standard gettext set-up, some msgid may accidentally collide\nbetween two different uses. For instance, whether you translate the word\n\"Open\" in the menu for \"Files\" to mean \"open a file\", and the word \"Open\"\nin the status display meaning \"the file is open\". In some languages,\nthese translations may differ. Using a msgctxt keyword will cause the\nsame msgid to appear twice in the PO-file.
\n\nBut, there is a much broader need for context sensitive translations,\nwhich is not in the provided by standard gettext: environmental\ninformation or parameters may influence the translation more than simply\nsolvable by inserted parameters.
\n\nFor instance, the gender of the user of the website determines whether\n`he' or `she' needs to be used. In this example, the gender is set as\ncontext keyword in the message:
\n\n $name = 'Jack';\n print __x\"{name} found her key\", name => $name;\n\n\nYou may try to solve this via:
\n\n my ($name, $gender) = ('Jack', 'male');\n print __x\"{name} found {personal} key\", name => $name,\n personal => ($gender eq 'male' ? 'his' : 'her'); # No!\n\n\nThis does not translate! For one, you would need to translate his and\nher to the language as well. But in some languages, the differences\nbetween addressed genders have more impact on the whole sentence.
So, Log::Report translations add extra syntax:
\n\n my ($name, $gender) = ('Jack', 'male');\n print __x\"{name<gender} found her key\", name => $name,\n _context => \"gender=$gender\";\n\n\nThe gender marking tells the translation table builder (xgettext-perl)\nand the translation handler that there is a context active.
Now, the English PO-file has
\n\n # gender alternatives 'male' and 'female'\n\n msgctxt \"gender=male\"\n msgid \"{name} found his key\"\n msgstr \"{name} found his key\"\n\n msgctxt \"gender=female\"\n msgid \"{name} found his key\"\n msgstr \"{name} found her key\"\n\n\nTo make this work, both the application and the xgettext-perl script\nmust share information to understand which genders are available. See\nthe section on \"Configuration\" below.
Another example:
\n\n print __x\"greetings{<style}\";\n # style alternatives 'formal' and 'informal'\n\n msgctxt \"style=formal\"\n msgid \"greetings\"\n msgstr \"Dear Sir/Madam,\"\n\n msgctxt \"style=informal\"\n msgid \"greetings\"\n msgstr \"Hey buddy,\"\n\n\nAs can be seen, the '<style' marking may be added inside the '{}' of\na filled-in parameter, or may appear on its own. These markings are\nremoved from the msgid in the PO file, so that you may freely add them to\nthe strings used in your program without disturbing existing translations.
\n", "type" : "section", "name" : "Using context_rules", "id" : "id691", "nest" : [ "id692", "id693", "id694", "id695", "id696" ] }, "id225" : { "id" : "id225", "name" : "NAME", "level" : 1, "intro" : "Dancer::Logger::LogReport - reroute Dancer logs into Log::Report
\n", "path" : "NAME", "type" : "chapter" }, "id795-id958" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "extends" : "id795", "value" : "<required>", "name" : "params", "id" : "id795-id958" }, "id1047" : { "type" : "default", "name" : "syntax", "id" : "id1047", "value" : "'SHORT'" }, "id778-id958" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::log()
", "id" : "id778-id958", "name" : "log", "extends" : "id778", "call" : "$obj->log( \\%options, $reason, $message, $domain )" }, "id759-id958" : { "extends" : "id759", "id" : "id759-id958", "name" : "locale", "type" : "option", "params" : "LOCALE", "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
" }, "id519" : { "value" : "<required>", "name" : "msgid", "id" : "id519", "type" : "default" }, "id1336" : { "name" : "INHERITANCE", "id" : "id1336", "type" : "chapter", "intro" : "Log::Report::Template::Extract\n is a Log::Report::Extract\n\n", "path" : "INHERITANCE", "level" : 1 }, "id119" : { "level" : 1, "type" : "chapter", "path" : "SYNOPSIS", "intro" : "
# See Log::Report, most functions get \"hollow\" behavior\n use Log::Report::Optional mode => 'DEBUG';\n\n", "name" : "SYNOPSIS", "id" : "id119" }, "id756-id1082" : { "diagnostics" : [ "id767-id1082", "id768-id1082", "id769-id1082" ], "call" : "$class->new( $type, $name, %options )", "type" : "c_method", "intro" : "
Inherited, see Log::Report::Dispatcher::new()
", "extends" : "id756", "name" : "new", "id" : "id756-id1082", "options" : [ [ "id757-id1082", "id758-id1082" ], [ "id765-id1082", "id766-id1082" ], [ "id763-id1082", "id764-id1082" ], [ "id759-id1082", "id760-id1082" ], [ "id761-id1082", "id762-id1082" ] ] }, "id265" : { "name" : "NAME", "id" : "id265", "intro" : "Dancer2::Template::TTLogReport - Template toolkit engine with Log::Report translations for Dancer2
\n", "path" : "NAME", "type" : "chapter", "level" : 1 }, "id422-id697" : { "extends" : "id422", "value" : "'utf-8'", "name" : "charset", "id" : "id422-id697", "intro" : "Inherited, see Log::Report::Extract::new(charset)
", "type" : "default" }, "id785" : { "type" : "ci_method", "options" : [ [ "id800", "id801" ], [ "id792", "id793" ], [ "id788", "id789" ], [ "id790", "id791" ], [ "id796", "id797" ], [ "id798", "id799" ], [ "id786", "id787" ], [ "id794", "id795" ] ], "call" : "$any->stackTraceLine( %options )", "id" : "id785", "name" : "stackTraceLine" }, "id735" : { "id" : "id735", "name" : "msgid", "call" : "$obj->msgid( STRING, [$msgctxt] )", "type" : "i_method", "intro" : "Lookup the Log::Report::Lexicon::PO with the STRING.\nReturns undef when not defined.
try { report {to => 'default'}, ERROR => 'oops!' };\n $@->reportFatal(to => 'syslog');\n\n my ($syslog) = $exception->throw(to => 'syslog');\n my @disps = $@->wasFatal->throw(reason => 'WARNING');\n\n"
},
"id892" : {
"name" : "_to",
"id" : "id892",
"value" : "undef",
"type" : "default"
},
"id343" : {
"intro" : "my $domain = $templater->addTextdomain(\n name => 'my-project',\n function => 'loc', # default\n );\n\n", "type" : "example", "id" : "id343" }, "id233" : { "name" : "process", "id" : "id233", "call" : "$obj->process", "type" : "i_method", "intro" : "
process() is an eval, but one which expects and understands exceptions\ngenerated by Log::Report. Any messages will be logged as normal in\naccordance with the dispatchers, but any fatal exceptions will be caught\nand handled gracefully. This allows much simpler error handling, rather\nthan needing to test for lots of different scenarios.
In a module, it is enough to simply use the error keyword in the event\nof a fatal error.
The return value will be 1 for success or 0 if a fatal exception occurred.
\n\nSee the DETAILS for an example of how this is expected to be used.
\n\nThis module is configured only once in your application. The other modules\nwhich make your website do not need to require this plugin, instead they\ncan use Log::Report to get useful functions like error and fault.
This module implements the functions provided by Log::Report, but then\nas simple as possible: no support for translations, no dispatchers, no\nsmart exceptions. The package uses Log::Report in an ::Optional\nway, the main script determines whether it wants the ::Minimal or\nfull-blown feature set.
Lookup the best translation table, according to the rules described\nin chapter DETAILS, below.
\n\nReturned is a filename, or undef if nothing is defined for the\n$locale (there is no default on this level).
Log::Report::Minimal\n is an Exporter\n\n", "type" : "chapter", "id" : "id1320", "name" : "INHERITANCE" }, "id763" : { "name" : "format_reason", "id" : "id763", "type" : "option", "params" : "'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE", "intro" : "
How to show the reason text which is printed before the message. When\na CODE is specified, it will be called with a translated text and the\nreturned text is used.
\n" }, "id777-id958" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::close()
", "extends" : "id777", "name" : "close", "id" : "id777-id958", "call" : "$obj->close" }, "id1256" : { "level" : 2, "name" : "Available back-ends", "id" : "id1256", "path" : "DETAILS/Available back-ends", "type" : "section" }, "id283" : { "level" : 2, "intro" : "If using this module on its own (such as a drop-in replacement for\nDancer2::Logger::Syslog), then the logging format is configured as with any\nother Dancer logger. If using this module with Dancer2::Plugin::LogReport,\nthen log_format is ignored and messages are not formatted, in order to keep the\nmessage format consistent regardless of where the message was generated (be it\nanother module using Log::Report, the plugin, or Dancer itself). In this case,\nthe log format should be configured using the applicable dispatcher (such as\nLog::Report::Dispatcher::Syslog::new(format)).
\n\nIf also using with the Log::Report logging functions, then you probably want\nto set a very simple logger_format, because the dispatchers do already add\nsome of the fields that the default simple format adds. For instance, to\nget the filename/line-number in messages depends on the dispatcher 'mode' (f.i.\n'DEBUG').
You also want to set the Dancer2 log level to debug, because level filtering\nis controlled per dispatcher (as well).
See DETAILS for examples.
\n", "path" : "DESCRIPTION/Log Format", "type" : "section", "name" : "Log Format", "id" : "id283" }, "id796-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "type" : "option", "params" : "INTEGER", "extends" : "id796", "name" : "max_line", "id" : "id796-id1082" }, "id789" : { "type" : "default", "value" : "<required>", "id" : "id789", "name" : "filename" }, "id166" : { "type" : "default", "value" : "<required>", "id" : "id166", "name" : "name" }, "id269" : { "name" : "Constructors", "id" : "id269", "level" : 2, "intro" : "Standard Moo with Dancer2::Core::Role::Template extensions.
\n", "path" : "METHODS/Constructors", "type" : "section" }, "id1106" : { "params" : "'unix'|'inet'|'stream'|HASH", "type" : "option", "intro" : "If specified, the log socket type will be initialized to this before\nopenlog() is called. If not specified, the system default is used.
Returns a list with all defined Log::Report::Lexicon::PO objects. When\nthe string $active is given as parameter, only objects which have\nreferences are returned.
\n", "type" : "i_method", "call" : "$obj->translations( [$active] )", "diagnostics" : [ "id740" ], "name" : "translations", "id" : "id739" }, "id852" : { "type" : "default", "id" : "id852", "name" : "tag", "value" : "undef"
},
"id526" : {
"id" : "id526",
"name" : "comment",
"type" : "option",
"params" : "\\@text",
"intro" : "Translator added comments.\nSee addComment().
\n" }, "id108" : { "name" : "Private modifiers", "id" : "id108", "level" : 3, "type" : "subsection", "intro" : "You may pass your own modifiers. A modifier consists of a selector and\na CODE, which is called when the selector matches. The selector is either\na string or a regular expression.
\n\n # in Object Oriented syntax:\n my $f = String::Print->new(\n modifiers => [ qr/[€₤]/ => \\&money ],\n );\n\n # in function syntax:\n use String::Print 'printi', 'sprinti',\n modifiers => [ qr/[€₤]/ => \\&money ];\n\n # the implementation:\n sub money$$$$)\n { my ($formatter, $modif, $value, $args) = @_;\n\n $modif eq '€' ? sprintf(\"%.2f EUR\", $value+0.0001)\n : $modif eq '₤' ? sprintf(\"%.2f GBP\", $value/1.16+0.0001)\n : 'ERROR';\n }\n\n\nUsing printp() makes it a little shorter, but will become quite\ncomplex when there are more parameter in one string.
\n\n printi \"price: {p€}\", p => $pi; # price: 3.14 EUR\n printi \"price: {p₤}\", p => $pi; # price: 2.71 GBP\n\n printp \"price: %{€}s\", $pi; # price: 3.14 EUR\n printp \"price: %{₤}s\", $pi; # price: 2.71 GBP\n\n\nThis is very useful in the translation context, where the translator can\nspecify abstract formatting rules. As example, see the (GNU) gettext\nfiles, in the translation table for Dutch into English. The translator\ntells us which currency to use in the display.
\n\n msgid \"kostprijs: {p€}\"\n msgstr \"price: {p₤}\"\n\n\nAnother example. Now, we want to add timestamps. In this case, we\ndecide for modifier names in \\w, so we need a blank to separate\nthe parameter from the modifer.
Returns the encoding name (usable with module Encode) based on the current\ncodepage. For example, cp1252 for iso-8859-1 (latin-1) or cp932 for\nShift-JIS Japanese. Returns undef if the encoding cannot be identified.
Log::Report::Dispatcher::Syslog\n is a Log::Report::Dispatcher\n\n", "path" : "INHERITANCE", "type" : "chapter", "name" : "INHERITANCE", "id" : "id1324" }, "id210" : { "id" : "id210", "name" : "SYNOPSIS", "intro" : "
# Use Log::Report when already loaded, otherwise Log::Report::Minimal\n package My::Package;\n use Log::Report::Optional 'my-domain';\n\n", "path" : "SYNOPSIS", "type" : "chapter", "level" : 1 }, "id107" : { "id" : "id107", "name" : "Modifier: UNKNOWN or UNKNOWN($width)", "path" : "DETAILS/Interpolation: Modifiers/Modifier: UNKNOWN or UNKNOWN($width)", "intro" : "
[1.01] When you need to interpolate a value which is unknown and potentially\nunsafe, then use this. For instance, you produce an internal error message\nto report that a method is used incorrectly:
\n\n sub openFolder\n { my ($self, $folder) = @_;\n\n blessed $folder && $folder->isa('Mail::Box')\n or printi \"ERROR: expected a Mail::Box, got a {t UNKNOWN}.\",\n t => $folder;\n }\n\n\nNow, this $folder parameter is clearly wrong. But what is it? Did we\npass a wrong object type? Did we pass a string? An ARRAY maybe?
The UNKNOWN modifier distibuishes the following:
Care is taken that weird characters are escaped. The shortening uses the\ntrim setting: either 'EL' (default) or 'CHOP'.
Calls sprinti() to fill the %data into $format, and then sends it to\nthe $fh (by default the selected file handle)
\n\n open my $fh, '>:encoding(UTF-8)', $file;\n printi $fh, ...\n\n printi \\*STDERR, ...\n\n", "type" : "function" }, "id126" : { "type" : "default", "name" : "errno", "id" : "id126", "value" : "
$! or 1"
},
"id799-id958" : {
"value" : "8",
"extends" : "id799",
"id" : "id799-id958",
"name" : "max_params",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "type" : "default" }, "id229" : { "level" : 1, "intro" : "Dancer2::Plugin::LogReport - logging, exceptions and translations in Dancer2 via Log::Report
\n", "path" : "NAME", "type" : "chapter", "name" : "NAME", "id" : "id229" }, "id508" : { "id" : "id508", "name" : "ms_codepage_id", "call" : "ms_codepage_id", "type" : "function", "intro" : "Returns the numeric language ID for the current codepage language.\nFor example, the numeric value for 0x0409 for en-US, and 0x0411\nfor ja. Returns false if the codepage cannot be identified.
When code which runs in this block exits with a die(), it will get\ntranslated into a Log::Report::Exception using\nLog::Report::Die::die_decode(). How serious are we about these\nerrors?
\n", "type" : "option", "params" : "'ERROR'|'PANIC'", "name" : "on_die", "id" : "id834" }, "id318" : { "id" : "id318", "name" : "Predefined for Template-Toolkit", "level" : 3, "type" : "subsection", "path" : "DETAILS/Scan Patterns/Predefined for Template-Toolkit", "intro" : "There is not a single convention for translations in Template-Toolkit\n(see Template), so you need to specify which version TT you use and\nwhich function name you want to use. In extreme cases, you may even build\nseparate translation tables by simply providing using functions.
For instance
\n\n pattern => 'TT2-loc'\n\n\n
will scan for
\n\n [% loc(\"msgid\", key => value, ...) %]\n [% loc('msgid', key => value, ...) %]\n [% loc(\"msgid|plural\", count, key => value, ...) %]\n\n [% INCLUDE\n title = loc('something')\n %]\n\n [% | loc(n => name) %]hi {n}[% END %]\n [% 'hi {n}' | loc(n => name) %]\n\n\nFor TT1, the brackets can either be '[%...%]' or '%%...%%'. The function\nname is treated case-sensitive. Some people prefer 'l()' or 'L()'.
The code needed
\n\n # during initiation of the webserver, once in your script (before fork)\n my $lexicons = 'some-directory-for-translation-tables';\n my $pots = Log::Report::Translator::POT->new(lexicons => $lexicons);\n\n my $templater = Log::Report::Template->new(...);\n my $domain = $templater->addTextdomain(\n name => $domainname,\n function => 'loc',\n );\n $domain->configure(translator => $pots);\n\n # part of the processing per page\n $vars{translate_to} = 'nl_NL.utf8';\n $templater->process($template, \\%vars, \\$output);\n\n\nTo generate the pod tables, run in the shell something like
\n\n xgettext-perl -p $lexicons --template TT2-loc \\\n --domain $textdomain $templates_dir\n\n\n
If you want to implement your own extractor --to avoid xgettext-perl--\nyou need to run something like this:
\n my $extr = Log::Report::Template::Extract->new(\n lexicon => $output,\n charset => 'utf-8',\n domain => $domain,\n pattern => 'TT2-loc',\n );\n $extr->process($_) for @filenames;\n $extr->write;\n\n" }, "id50" : { "id" : "id50", "name" : "DESCRIPTION", "type" : "chapter", "path" : "DESCRIPTION", "intro" : "
This module inserts values into (format) strings. It provides printf()\nand sprintf() alternatives via both an object oriented and a functional\ninterface.
Read in the DETAILS chapter below, why this module provides a better\nalternative for printf(). Also, some extended examples can be\nfound down there. Take a look at them first, when you start using this\nmodule!
Update the domains mentioned in the $filename. All textdomains defined\nin the file will get updated automatically, but not written before\nall files where processed.
\n" }, "id424" : { "id" : "id424", "name" : "cannot create lexicon directory $dir: $!", "subroutine" : "id418", "type" : "fault" }, "id884" : { "type" : "default", "id" : "id884", "name" : "_tag", "value" : "[]" }, "id1113" : { "type" : "default", "id" : "id1113", "name" : "format", "value" : "<unchanged>" }, "id645" : { "type" : "default", "value" : "<from header>", "name" : "charset", "id" : "id645" }, "id891-id217" : { "intro" : "Inherited, see Log::Report::Message::new(_to)
", "type" : "option", "params" : "$dispatcher", "name" : "_to", "id" : "id891-id217", "extends" : "id891" }, "id969" : { "type" : "default", "name" : "to_level", "id" : "id969", "value" : "[]" }, "id858" : { "name" : "SYNOPSIS", "id" : "id858", "level" : 1, "path" : "SYNOPSIS", "intro" : " # Objects created by Log::Report's __ functions\n # Full feature description in the DETAILS section\n\n # no interpolation\n __\"Hello, World\";\n\n # with interpolation\n __x\"age {years}\", years => 12;\n\n # interpolation for one or many\n my $nr_files = @files;\n __nx\"one file\", \"{_count} files\", $nr_files;\n __nx\"one file\", \"{_count} files\", \\@files;\n\n # interpolation of arrays\n __x\"price-list: {prices%.2f}\", prices => \\@prices, _join => ', ';\n\n # white-spacing on msgid preserved\n print __\"\\tCongratulations,\\n\";\n print \"\\t\", __(\"Congratulations,\"), \"\\n\"; # same\n\n # Object serialization support\n my $clone = Log::Report::Message->thaw($msg->freeze);\n\n",
"type" : "chapter"
},
"id879" : {
"params" : "$text|$message",
"type" : "option",
"intro" : "Some $text or other $message object which need to be glued before this\nmessage object.
\n", "id" : "id879", "name" : "_prepend" }, "id102" : { "id" : "id102", "name" : "Modifiers: YEAR, DATE(), TIME, and DT()", "level" : 3, "path" : "DETAILS/Interpolation: Modifiers/Modifiers: YEAR, DATE(), TIME, and DT()", "intro" : "[0.91] A set of modifiers help displaying dates and times. They are a\nlittle flexible in values they accept, but do not expect miracles: when\nit get harder, you will need to process it yourself.
\n\nThe actual treatment of a time value depends on the value. Four\ndifferent situations:
\n\n\n my $now = DateTime->now;\n printi \"{t YEAR}\", t => $now; # works for DateTime, epoch and string\n printi \"{t.year YEAR}\", t => $now; # same effect, DateTime only\n printi \"{t.year}\", t => $now; # will also work, not as nice\n\n\n\n\nBy far not all possible date formats are supported, just a few common\nversions, like
\n\n 2017-06-27 10:04:15 +02:00\n 2017-06-27 17:34:28.571491+02 # psql timestamp with zone\n 20170627100415+2\n 2017-06-27T10:04:15Z # iso 8601\n 20170627 # only for YEAR and DATE\n 2017-6-1 # only for YEAR and DATE\n 12:34 # only for TIME\n\n\n
The meaning of 05-04-2017 is ambiguous, so not supported. Milliseconds\nget ignored.
When the provided value has a timezone indication, it will get\nconverted into the local timezone of the observer.
\n\nThe output of YEAR is in format 'YYYY', where TIME produces 'HH:mm:ss'.\nDT and DATE are configurable.
The DT modifier can produce different formats:
\n\n DT(ASC) : %a %b %e %T %Y asctime output (not on Windows)\n DT(FT) : %F %T YYYY-MM-DD HH:MM:SS (default)\n DT(ISO) : %FT%T%z iso8601\n DT(RFC822) : %a, %d %b %y %T %z email old\n DT(RFC2822) : %a, %d %b %Y %T %z email newer\n DT(RFC5322) : %a, %d %b %Y %T %z email newest [0.96]\n DT(%F-%T) [1.02] any own format\n\n\n
You may suggest additional formats, or add your own modifier. For your own\nformat: be warned that %F and %T are not supported on some Windows\nversions (but the difference is hidden by Perl >5.38).
[1.02] Also, the DATE modifier can produce different formats:
\n\n DATE(-) : %Y-%m-%d\n DATE(/) : %Y/%m/%d\n DATE(%d-%m-%Y) any own pattern\n DATE(%m-%d-%Y) better not use this broken order\n\n\n
Other fields than %Y, %m, and %d are not supported. Other characters\nare left untouched.
The defaults are:
\n\n DATE => { format => '-' },\n DT => { format => 'FT' },\n\n",
"type" : "subsection"
},
"id790-id944" : {
"id" : "id790-id944",
"name" : "linenr",
"extends" : "id790",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "params" : "INTEGER", "type" : "option" }, "id791-id1090" : { "id" : "id791-id1090", "name" : "linenr", "extends" : "id791", "value" : "<required>", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
" }, "id929" : { "type" : "c_method", "call" : "$class->thaw( \\%data, %options )", "id" : "id929", "name" : "thaw" }, "id502" : { "level" : 1, "type" : "chapter", "path" : "DESCRIPTION", "intro" : "Windows uses different locales to represent languages: codepages. Programs\nwhich are written with Log::Report however, will contain ISO encoded\nlanguage names; this module translates between them.
\n\nThe algorithms in this module are based on Win32::Locale and Win32::Codepage.
\n", "id" : "id502", "name" : "DESCRIPTION" }, "id317" : { "name" : "Scan Patterns", "id" : "id317", "nest" : [ "id318" ], "level" : 2, "type" : "section", "intro" : "Various template systems use different conventions for denoting strings\nto be translated.
\n", "path" : "DETAILS/Scan Patterns" }, "id857" : { "intro" : "Log::Report::Message - a piece of text to be translated
\n", "path" : "NAME", "type" : "chapter", "level" : 1, "name" : "NAME", "id" : "id857" }, "id910" : { "intro" : "The message context for the translation table lookup.
\n", "type" : "i_method", "call" : "$obj->msgctxt", "id" : "id910", "name" : "msgctxt" }, "id464" : { "params" : "STRING", "type" : "option", "intro" : "Specify an output filename. The name can also be specified when\nwrite() is called.
\n", "name" : "filename", "id" : "id464" }, "id743-id569" : { "diagnostics" : [ "id744-id569" ], "call" : "$obj->setupPluralAlgorithm", "type" : "i_method", "intro" : "Inherited, see Log::Report::Lexicon::Table::setupPluralAlgorithm()
", "id" : "id743-id569", "name" : "setupPluralAlgorithm", "extends" : "id743" }, "id622" : { "level" : 1, "id" : "id622", "name" : "METHODS", "type" : "chapter", "path" : "METHODS", "nest" : [ "id623", "id630", "id633" ] }, "id793-id944" : { "extends" : "id793", "value" : "<required>", "name" : "call", "id" : "id793-id944", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
" }, "id476" : { "type" : "option", "params" : "BOOLEAN", "intro" : "[1.02] Do not write records which do have a translation, but where the\nmsgid has disappeared from the sources. By default, these records are\ncommented out (marked with '#~') but left in the file.
\n", "id" : "id476", "name" : "only_active" }, "id1170" : { "name" : "Attributes", "id" : "id1170", "level" : 2, "type" : "section", "path" : "METHODS/Attributes" }, "id800-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "type" : "option", "params" : "INTEGER", "name" : "abstract", "id" : "id800-id1082", "extends" : "id800" }, "id861" : { "intro" : "When the object is used in string context, it will get translated.\nImplemented as toString().
\n", "type" : "overload", "call" : "overload '\"\"'; stringification", "id" : "id861", "name" : "'\"\"'" }, "id1094" : { "nest" : [ "id1095", "id1116", "id1118" ], "path" : "METHODS", "type" : "chapter", "id" : "id1094", "name" : "METHODS", "level" : 1 }, "id66" : { "intro" : "The PAIRS are a combination of an selector and a CODE which processes the\nvalue when the modifier matches. The selector is a string or (preferred)\na regular expression. Later modifiers with the same name overrule earlier\ndefinitions. You may also specify an ARRAY of modifiers per printi()\nor printp().
\n\nSee section Interpolation: Modifiers about the details.
\n", "type" : "i_method", "call" : "$obj->addModifiers( PAIRS )", "name" : "addModifiers", "id" : "id66" }, "id788-id1228" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
", "params" : "STRING", "type" : "option", "extends" : "id788", "name" : "filename", "id" : "id788-id1228" }, "id773-id1174" : { "call" : "$obj->mode", "extends" : "id773", "name" : "mode", "id" : "id773-id1174", "intro" : "Inherited, see Log::Report::Dispatcher::mode()
", "type" : "i_method" }, "id971" : { "name" : "config", "id" : "id971", "value" : "<undef>",
"type" : "default"
},
"id1032" : {
"type" : "function",
"intro" : "Same as __nx(), because we have no preferred order for 'x' and 'n'.
\n", "id" : "id1032", "name" : "__xn", "call" : "__xn( $single_msgid, $plural_msgid, $count, $paurs )" }, "id70" : { "id" : "id70", "name" : "defaults", "call" : "$obj->defaults( $modifier )", "examples" : [ "id71" ], "type" : "i_method", "intro" : "[1.00] Returns the current defaults for the $modifier.
\n" }, "id1111" : { "type" : "default", "value" : "'utf8'", "name" : "charset", "id" : "id1111" }, "id1180" : { "options" : [ [ "id757-id1174", "id758-id1174" ], [ "id1187", "id1188" ], [ "id765-id1174", "id766-id1174" ], [ "id763-id1174", "id764-id1174" ], [ "id759-id1174", "id760-id1174" ], [ "id1185", "id1186" ], [ "id1183", "id1184" ], [ "id761-id1174", "id762-id1174" ], [ "id1181", "id1182" ] ], "type" : "c_method", "intro" : "The Log::Dispatch infrastructure has quite a large number of output\nTYPEs, each extending the Log::Dispatch::Output base-class. You\ndo not create these objects yourself: Log::Report is doing it for you.
\n\nThe Log::Dispatch back-ends are very careful with validating their\nparameters, so you will need to restrict the options to what is supported\nfor the specific back-end. See their respective manual-pages. The errors\nproduced by the back-ends quite horrible and untranslated, sorry.
\n", "id" : "id1180", "name" : "new", "diagnostics" : [ "id1189" ], "call" : "$class->new( $type, $name, %options )" }, "id62" : { "id" : "id62", "name" : "defaults", "intro" : "[1.00] change the defaults for some modifiers. This is a %map of\nmodifier name to HASH with modifier specific settings.
\n", "params" : "\\%map", "type" : "option" }, "id740-id569" : { "id" : "id740-id569", "name" : "only acceptable parameter is 'ACTIVE'", "extends" : "id740", "subroutine" : "id739", "type" : "error", "intro" : "Inherited, see Log::Report::Lexicon::Table::translations()
" }, "id821" : { "type" : "chapter", "intro" : "The try works like Perl's build-in eval(), but implements\nreal exception handling which Perl core lacks.
The Log::Report::try() function creates this ::Try dispatcher\nobject with name 'try'. After the try() is over, you can find\nthe object in $@. The $@ as ::Try object behaves exactly\nas the $@ produced by eval, but has many added features.
The try() function catches fatal errors happening inside the BLOCK\n(CODE reference which is just following the function name) into the\n::Try object $@. The errors are not automatically progressed to\nactive dispatchers. However, non-fatal exceptions (like info or notice)\nare also collected (unless not accepted, see new(accept), but also\nimmediately passed to the active dispatchers (unless the reason is hidden,\nsee new(hide))
After the try() has run, you can introspect the collected exceptions.\nTypically, you use wasFatal() to get the exception which terminated\nthe run of the BLOCK.
[1.45] Add zero or more tags to this message.
\n", "type" : "i_method" }, "id431" : { "type" : "section", "path" : "METHODS/Processors", "name" : "Processors", "id" : "id431", "level" : 2, "subroutines" : [ "id439", "id433", "id437", "id432", "id436" ] }, "id1050" : { "name" : "import", "id" : "id1050", "intro" : "[0.998] When not specified, the syntax option determines the list\nof @functions which are being exported. With this option, the syntax\noption is ignored and only the specified @functions are imported.
\n", "type" : "option", "params" : "$function|\\@functions" }, "id394" : { "type" : "section", "path" : "METHODS/Attributes", "id" : "id394", "name" : "Attributes", "level" : 2, "subroutines" : [ "id170-id375", "id172-id375", "id1138-id375", "id171-id375", "id1136-id375", "id1137-id375", "id1135-id375", "id1149-id375", "id397", "id395", "id398", "id399", "id396" ] }, "id986" : { "name" : "to", "id" : "id986", "intro" : "Sent the $message only to the named dispatchers. Ignore unknown @names.\nStill, the dispatcher needs to be enabled and accept the $reason.
\n", "params" : "$name|\\@names", "type" : "option" }, "id1140-id375" : { "extends" : "id1140", "value" : "created internally",
"name" : "translator",
"id" : "id1140-id375",
"type" : "default",
"intro" : "Inherited, see Log::Report::Domain::configure(translator)
" }, "id662" : { "path" : "METHODS/Attributes", "type" : "section", "subroutines" : [ "id663", "id664", "id665" ], "id" : "id662", "name" : "Attributes", "level" : 2 }, "id936" : { "name" : "Automatic parameters", "id" : "id936", "nest" : [ "id938", "id939" ], "level" : 2, "examples" : [ "id937" ], "type" : "section", "intro" : "Besides the parameters which you specify yourself, Log::Report will add\na few which can also be interpolated. The all start with an underscore\n(_). These are collected when this Message object is instantiated,\nsee the %options of new(). These parameters have a purpose, but\nyou are also permitted tp interpolate them in your message. This may\nsimplify your coding.
The useful names are:
\n\nInherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "type" : "default" }, "id702" : { "id" : "id702", "name" : "What is extracted?", "level" : 3, "type" : "subsection", "path" : "DESCRIPTION/The extraction process/What is extracted?", "intro" : "This script will extract the msgids used in __(), __x(), __xn(),\nand __n() (implemented by Log::Report) For instance
\n __x\"msgid\", @more\n __x'msgid', @more <--- no! syntax error!\n __x(\"msgid\", @more)\n __x('msgid', @more)\n __x(msgid => @more)\n\n\nBesides, there are some helpers which are no-ops in the code, only to fill\nthe po-tables: N__(), N__n(), N__()
Returns the Log::Report::Template object which is performing the\ntemplate processing. This object gets instantiated based on values\nfound in the Dancer2 configuration file.
\n", "type" : "i_method", "call" : "$obj->tt", "name" : "tt", "id" : "id271" }, "id667" : { "call" : "$obj->msgid( STRING, [$msgctxt] )", "id" : "id667", "name" : "msgid", "intro" : "Lookup the translations with the STRING. Returns a SCALAR, when only\none translation is known, and an ARRAY when we have plural forms.\nReturns undef when the translation is not defined.
undef>",
"type" : "default"
},
"id726" : {
"level" : 1,
"intro" : "Log::Report::Lexicon::Table - generic interface to translation tables
\n", "path" : "NAME", "type" : "chapter", "name" : "NAME", "id" : "id726" }, "id539" : { "intro" : "Returns the message context string, if provided.
\n", "type" : "i_method", "call" : "$obj->msgctxt", "name" : "msgctxt", "id" : "id539" }, "id1136" : { "call" : "$obj->translator", "id" : "id1136", "name" : "translator", "type" : "i_method" }, "id762-id818" : { "extends" : "id762", "value" : "'NORMAL'", "id" : "id762-id818", "name" : "mode", "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
", "type" : "default" }, "id738-id569" : { "intro" : "Inherited, see Log::Report::Lexicon::Table::add()
", "type" : "i_method", "call" : "$obj->add( $po )", "name" : "add", "id" : "id738-id569", "extends" : "id738" }, "id589" : { "intro" : "Returns the translated string for $msgid. When not specified, $count is 1\n(the single form).
\n", "type" : "i_method", "call" : "$obj->msgstr( $msgid, [$count, [$msgctxt] )", "diagnostics" : [ "id590" ], "id" : "id589", "name" : "msgstr" }, "id715" : { "type" : "error", "subroutine" : "id708", "name" : "string is incorrect at line $line: $error", "id" : "id715" }, "id766" : { "name" : "charset", "id" : "id766", "value" : "undef",
"type" : "default"
},
"id668" : {
"call" : "$obj->msgstr( $msgid, [$count, $msgctxt] )",
"id" : "id668",
"name" : "msgstr",
"intro" : "Returns the translated string for $msgid. When not specified, $count is 1\n(the singular form).
\n", "type" : "i_method" }, "id189" : { "id" : "id189", "name" : "unknown reason $which in '$reasons'.", "subroutine" : "id187", "type" : "error" }, "id236" : { "intro" : " fatal_handler sub {\n my ($dsl, $msg, $reason, $default) = @_;\n\n (my $ctype = $dsl->request->header('content-type')) =~ s/;.*//;\n return if $ctype ne 'application/json';\n status $reason eq 'PANIC' ? 'Internal Server Error' : 'Bad Request';\n $dsl->send_as(JSON => {\n error => 1,\n description => $msg->toString,\n }, {\n content_type => 'application/json; charset=UTF-8',\n });\n };\n\n",
"type" : "example",
"id" : "id236",
"name" : "Return JSON responses for requests with content-type of application/json\n"
},
"id139" : {
"call" : "mistake( $message )",
"id" : "id139",
"name" : "mistake",
"type" : "function"
},
"id708" : {
"call" : "$obj->process( $filename, %options )",
"id" : "id708",
"name" : "process",
"diagnostics" : [
"id711",
"id712",
"id713",
"id714",
"id715",
"id716"
],
"intro" : "Update the domains mentioned in the $filename. All textdomains defined\nin the file will get updated automatically, but not written before\nall files where processed.
\n", "options" : [ [ "id709", "id710" ] ], "type" : "i_method" }, "id606" : { "nest" : [ "id607", "id609", "id610" ], "name" : "DETAILS", "id" : "id606", "type" : "chapter", "path" : "DETAILS", "intro" : "It's always complicated to find the lexicon files, because the perl\npackage can be installed on any weird operating system. Therefore,\nyou may need to specify the lexicon directory or alternative directories\nexplicitly. However, you may also choose to install the lexicon files\nin between the perl modules.
\n", "level" : 1 }, "id801-id818" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "type" : "default", "value" : "1", "extends" : "id801", "id" : "id801-id818", "name" : "abstract" }, "id174" : { "intro" : "Specifies the location of the configuration. It is not allowed to\nconfigure a domain on more than one location.
\n", "type" : "option", "params" : "ARRAY", "id" : "id174", "name" : "where" }, "id1120" : { "inheritance" : { "extends" : [ "Mojo::Log" ] }, "package" : "MojoX::Log::Report", "distribution" : "Log-Report", "is_pure_pod" : false, "title" : "divert log messages into Log::Report", "name" : "MojoX::Log::Report", "id" : "id1120", "chapters" : [ "id1121", "id1322", "id1122", "id1123", "id1124" ], "version" : "1.45" }, "id346" : { "type" : "i_method", "intro" : "Returns a LIST with all defined textdomains, unsorted.
\n", "name" : "domains", "id" : "id346", "call" : "$obj->domains" }, "id213" : { "id" : "id213", "name" : "usedBy", "call" : "$class->usedBy", "type" : "c_method", "intro" : "Returns the classes which loaded the optional module.
\n" }, "id627" : { "type" : "option", "params" : "STRING", "intro" : "Enforce character set for files. We default to reading the character-set\nas defined in the header of each PO file.
\n", "id" : "id627", "name" : "charset" }, "id242" : { "type" : "i_method", "call" : "$obj->notice", "id" : "id242", "name" : "notice" }, "id948" : { "intro" : " sub send_mail($$$)\n { my ($disp, $options, $reason, $message) = @_;\n my $msg = Mail::Send->new(Subject => $reason, To => 'admin@localhost');\n my $fh = $msg->open('sendmail');\n print $fh $disp->translate($reason, $message);\n close $fh;\n }\n\n dispatcher CALLBACK => 'mail', callback => \\&send_mail;\n\n",
"type" : "example",
"id" : "id948"
},
"id1306" : {
"type" : "chapter",
"path" : "DETAILS",
"nest" : [
"id1307",
"id1308",
"id1309",
"id1311"
],
"level" : 1,
"id" : "id1306",
"name" : "DETAILS"
},
"id719" : {
"level" : 1,
"name" : "SYNOPSIS",
"id" : "id719",
"path" : "SYNOPSIS",
"type" : "chapter"
},
"id185" : {
"type" : "chapter",
"nest" : [
"id186",
"id195",
"id200"
],
"path" : "FUNCTIONS",
"id" : "id185",
"name" : "FUNCTIONS",
"level" : 1
},
"id135" : {
"type" : "function",
"call" : "assert( $message )",
"name" : "assert",
"id" : "id135"
},
"id801-id1090" : {
"extends" : "id801",
"value" : "1",
"name" : "abstract",
"id" : "id801-id1090",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
" }, "id800-id944" : { "extends" : "id800", "id" : "id800-id944", "name" : "abstract", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "type" : "option", "params" : "INTEGER" }, "id382" : { "intro" : "The textdomain can only be used in the indicated directories: if found\nanywhere else, it's an error. When not specified, the function is\nallowed everywhere.
\n", "params" : "DIRECTORY|ARRAY", "type" : "option", "id" : "id382", "name" : "only_in_directory" }, "id523" : { "value" : "\"\" or []", "name" : "msgstr", "id" : "id523", "type" : "default" }, "id720" : { "type" : "chapter", "path" : "DESCRIPTION", "intro" : "This module is the main extry point for the distribution, but has\ncurrently no further use. This distribution contains all components\nof Log::Report which handle translations.
\n\nIf you do not need translations, you do not need to install this module.\nWhen you use Log::Report and need to add translations, it may be\nvery little work: when you nicely wrote texts in the advised message\nformat like
\n\n print __x\"Greetings to you, {name}\", name => $name;\n fault __x\"cannot open file {filename}\", filename => $fn;\n\n\nthen all is in perfect condition to introduce translations: it requires\nvery little to no additions to the existing code!
\n\nIn this distribution:
\n\nShort for report FAULT => $message
Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
" }, "id332" : { "id" : "id332", "name" : "modifiers", "value" : "[]", "type" : "default" }, "id163" : { "type" : "section", "path" : "METHODS/Constructors", "level" : 2, "name" : "Constructors", "id" : "id163", "subroutines" : [ "id164" ] }, "id760" : { "id" : "id760", "name" : "locale", "value" : "<system locale>", "type" : "default" }, "id280" : { "level" : 1, "intro" : "Dancer2::Logger::LogReport - reroute Dancer2 logs into Log::Report
\n", "path" : "NAME", "type" : "chapter", "id" : "id280", "name" : "NAME" }, "id563" : { "diagnostics" : [ "id566", "id567" ], "id" : "id563", "name" : "toString", "call" : "$obj->toString( %options )", "type" : "i_method", "options" : [ [ "id564", "id565" ] ], "intro" : "Format the object into a multi-lined string.
\n" }, "id762-id1090" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
", "name" : "mode", "id" : "id762-id1090", "extends" : "id762", "value" : "'NORMAL'" }, "id123" : { "subroutines" : [ "id124", "id132", "id131" ], "id" : "id123", "name" : "Report Production and Configuration", "level" : 2, "path" : "FUNCTIONS/Report Production and Configuration", "type" : "section" }, "id600" : { "type" : "section", "path" : "METHODS/Search", "level" : 2, "id" : "id600", "name" : "Search", "subroutines" : [ "id601", "id604", "id602", "id603" ] }, "id947" : { "examples" : [ "id948" ], "level" : 1, "path" : "DESCRIPTION", "intro" : "This basic file logger accepts a callback, which is called for each\nmessage which is to be logged. When you need complex things, you\nmay best make your own extension to Log::Report::Dispatcher, but\nfor simple things this will do.
\n", "type" : "chapter", "name" : "DESCRIPTION", "id" : "id947" }, "id1124" : { "level" : 1, "id" : "id1124", "name" : "METHODS", "path" : "METHODS", "nest" : [ "id1125" ], "type" : "chapter" }, "id862-id217" : { "id" : "id862-id217", "name" : "'&{}'", "extends" : "id862", "call" : "overload '&{}'; used as function", "type" : "overload", "intro" : "Inherited, see Log::Report::Message subroutine '&{}'
" }, "id230" : { "level" : 1, "type" : "chapter", "path" : "SYNOPSIS", "intro" : " # Load the plugin into Dancer2\n # see Log::Report::import() for %options\n use Dancer2::Plugin::LogReport %options;\n\n # Stop execution, redirect, and display an error to the user\n $name or error \"Please enter a name\";\n\n # Add debug information to logger\n trace \"We're here\";\n\n # Handling user errors cleanly\n if (process( sub {MyApp::Model->create_user} )) {\n # Success, redirect user elsewhere\n } else {\n # Failed, continue as if submit hadn't been made.\n # Error message will be in session for display later.\n }\n\n # Send errors to template for display\n hook before_template => sub {\n my $tokens = shift;\n $tokens->{messages} = session 'messages';\n session 'messages' => [];\n }\n\n",
"id" : "id230",
"name" : "SYNOPSIS"
},
"id535" : {
"type" : "default",
"value" : "[]",
"id" : "id535",
"name" : "format"
},
"id340" : {
"type" : "i_method",
"name" : "translateTo",
"id" : "id340",
"call" : "$obj->translateTo( [$language] )"
},
"id585" : {
"name" : "filename",
"id" : "id585",
"call" : "$obj->filename",
"type" : "i_method",
"intro" : "Returns the name of the source file for this data.
\n" }, "id1045" : { "examples" : [ "id1054" ], "call" : "$obj->import( [$level,][$domain,] %options )", "diagnostics" : [ "id1055", "id1056", "id1057", "id1058", "id1059" ], "intro" : "The import is automatically called when the package is compiled. For all\npackages but one in your distribution, it will only contain the name of\nthe $domain.
\n\nFor one package, the import list may additionally contain textdomain\nconfiguration %options. These %options are used for all packages which\nuse the same $domain. These are alternatives:
\n\n # Do not use variables in the %*config! They are not yet initialized\n # when Log::Report->import is run!!!\n use Log::Report 'my-domain', %config, %domain_config;\n\n use Log::Report 'my-domain', %config;\n textdomain 'my-domain', %domain_config; # vars allowed\n\n\n
The latter syntax has major advantages, when the configuration of the\ndomain is determined at run-time. It is probably also easier to understand.
\n\nSee Log::Report::Domain::configure(), for the list of %options\nfor the domain configuration. Here, we only list the options which are\nrelated to the normal import behavior.
\n\nThe export $level is a plus (+) followed by a number, for instance +1,\nto indicate to on which caller level we need to work. This is used\nin Log::Report::Optional. It defaults to '0': my direct caller.
The STRING is the content of $@ after an eval() caught a die().\ncroak(), or confess(). This routine tries to convert this into\nparameters for Log::Report::report(). This is done in a very\nsmart way, even trying to find the stringifications of $!.
Returned are four elements: the error string or object which triggered\nthe death originally (the original $@), and the opts, reason, and plain\ntext message. The opts is a HASH which, amongst other things, may contain\na stack trace and location extracted from the death text or object.
\n\nTranslated components will have exception classes perl, and die or\nconfess. On the moment, the croak cannot be distiguished from the\nconfess (when used in package main) or die (otherwise).
The returned reason depends on whether the translation of the current\n$! is found in the STRING, and the presence of a stack trace. The\nfollowing table is used:
\n errstr stack => reason\n no no ERROR (die) application internal problem\n yes no FAULT (die) external problem, think open()\n no yes PANIC (confess) implementation error\n yes yes ALERT (confess) external problem, caught\n\n", "type" : "function", "options" : [ [ "id815", "id816" ] ] }, "id470" : { "type" : "fault", "name" : "cannot read in $cs from file $fn: $!", "id" : "id470", "subroutine" : "id467" }, "id338" : { "path" : "METHODS/Attributes", "type" : "section", "subroutines" : [ "id340", "id339" ], "level" : 2, "name" : "Attributes", "id" : "id338" }, "id1090" : { "version" : "1.45", "chapters" : [ "id1091", "id1324", "id1092", "id1093", "id1094", "id1262" ], "title" : "send messages to syslog", "is_pure_pod" : false, "name" : "Log::Report::Dispatcher::Syslog", "id" : "id1090", "package" : "Log::Report::Dispatcher::Syslog", "inheritance" : { "extends" : [ "Log::Report::Dispatcher" ] }, "distribution" : "Log-Report" }, "id942" : { "intro" : "
use Log::Report::DBIC::Profiler;\n $schema->storage->debugobj(Log::Report::DBIC::Profiler->new);\n $schema->storage->debug(1);\n\n # And maybe (if no exceptions expected from DBIC)\n $schema->exception_action(sub { panic @_ });\n\n # Log to syslog\n use Log::Report;\n dispatcher SYSLOG => 'myapp',\n identity => 'myapp',\n facility => 'local0',\n flags => \"pid ndelay nowait\",\n mode => 'DEBUG';\n\n",
"path" : "SYNOPSIS",
"type" : "chapter",
"level" : 1,
"name" : "SYNOPSIS",
"id" : "id942"
},
"id1174" : {
"is_pure_pod" : false,
"title" : "send messages to Log::Dispatch back-end",
"name" : "Log::Report::Dispatcher::LogDispatch",
"id" : "id1174",
"inheritance" : {
"extends" : [
"Log::Report::Dispatcher"
]
},
"package" : "Log::Report::Dispatcher::LogDispatch",
"distribution" : "Log-Report",
"version" : "1.45",
"chapters" : [
"id1175",
"id1343",
"id1176",
"id1177",
"id1178",
"id1283"
]
},
"id248" : {
"name" : "failure",
"id" : "id248",
"call" : "$obj->failure",
"type" : "i_method"
},
"id867-id217" : {
"id" : "id867-id217",
"name" : "_expand",
"extends" : "id867",
"intro" : "Inherited, see Log::Report::Message::new(_expand)
", "params" : "BOOLEAN", "type" : "option" }, "id354" : { "id" : "id354", "name" : "filenames", "value" : "undef",
"type" : "default"
},
"id1155-id375" : {
"subroutine" : "id1153",
"name" : "you need to configure context_rules before setContext",
"id" : "id1155-id375",
"extends" : "id1155",
"intro" : "Inherited, see Log::Report::Domain::setContext()
", "type" : "error" }, "id794-id1228" : { "params" : "ARRAY", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "name" : "params", "id" : "id794-id1228", "extends" : "id794" }, "id337" : { "id" : "id337", "name" : "illegal value '$value' for 'processing_errors' option.", "subroutine" : "id326", "type" : "error" }, "id746-id569" : { "intro" : "Inherited, see Log::Report::Lexicon::Table::header()
", "type" : "i_method", "call" : "$obj->header( $field )", "extends" : "id746", "id" : "id746-id569", "name" : "header" }, "id387" : { "type" : "default", "value" : "undef",
"name" : "lexicon",
"id" : "id387"
},
"id1144-id375" : {
"value" : "undef",
"extends" : "id1144",
"id" : "id1144-id375",
"name" : "context_rules",
"intro" : "Inherited, see Log::Report::Domain::configure(context_rules)
", "type" : "default" }, "id980" : { "level" : 1, "intro" : "Log::Report - report a problem, with exceptions and translation support
\n", "path" : "NAME", "type" : "chapter", "id" : "id980", "name" : "NAME" }, "id94" : { "level" : 3, "type" : "subsection", "path" : "DETAILS/Interpolation: keys/Complex keys", "intro" : "[0.91] In the previous section, we kept our addressing it simple: let's\nchange that now. Two alternatives for the same:
\n\n my $user = { name => 'John' };\n printi \"Username: {name}\", name => $user->{name}; # simple key\n printi \"Username: {user.name}\", user => $user; # complex key\n\n\nThe way these complex keys work, is close to the flexibility of\ntemplate toolkit: the only thing you cannot do, is passing parameters\nto called CODE.
\n\nYou can pass a parameter name as HASH, which contains values. This may\neven be nested into multiple levels. You may also pass objects, class\n(package names), and code references.
\n\nIn above case of user.name, when user is a HASH it will take the\nvalue which belongs to the key name. When user is a CODE, it will\nrun code to get a value. When user is an object, the method name\nis called to get a value back. When user is a class name, the name\nrefers to an instance method on that class.
More examples which do work:
\n\n # when name is a column in the database query result\n printi \"Username: {user.name}\", user => $sth->fetchrow_hashref;\n\n # call a sub which does the database query, returning a HASH\n printi \"Username: {user.name}\", user => sub { $db->getUser('John') };\n\n # using an instance method (object)\n { package User;\n sub new { bless { myname => $_[1] }, $_[0] }\n sub name { $_[0]->{myname} }\n }\n my $user = User->new('John');\n printi \"Username: {user.name}\", user => $user;\n\n # using a class method\n sub User::count { 42 }\n printi \"Username: {user.count}\", user => 'User';\n\n # nesting, mixing\n printi \"Complain to {product.factory.address}\", product => $p;\n\n # mixed, here CODE, HASH, and Object\n printi \"Username: {document.author.name}\", document => sub {\n return +{ author => User->new('John') }\n };\n\n\nLimitation: you cannot pass arguments to CODE calls.
\n", "id" : "id94", "name" : "Complex keys" }, "id1054" : { "id" : "id1054", "name" : "of import\n", "intro" : "use Log::Report mode => 3; # '3' or 'DEBUG', no domain given\n\n use Log::Report 'my-domain'; # in each package producing messages\n\n use Log::Report 'my-domain', # in one package, top of distr\n mode => 'VERBOSE',\n syntax => 'REPORT', # report ERROR, not error()\n translator => Log::Report::Translator::POT->new(\n lexicon => '/home/mine/locale', # translation tables\n ),\n native_language => 'nl_NL'; # untranslated msgs are Dutch\n\n use Log::Report import => 'try'; # or ARRAY of functions\n\n", "type" : "example" }, "id1241" : { "value" : "<adds timestamp>", "name" : "format", "id" : "id1241", "type" : "default" }, "id247" : { "type" : "i_method", "call" : "$obj->alert", "name" : "alert", "id" : "id247" }, "id1184" : { "type" : "default", "name" : "min_level", "id" : "id1184", "value" : "
debug"
},
"id764-id1174" : {
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "id" : "id764-id1174", "name" : "format_reason", "extends" : "id764", "value" : "'LOWERCASE'" }, "id868-id217" : { "value" : "false",
"extends" : "id868",
"name" : "_expand",
"id" : "id868-id217",
"intro" : "Inherited, see Log::Report::Message::new(_expand)
", "type" : "default" }, "id930" : { "level" : 1, "intro" : "The message cast by the Log::Report exception framework can be\nplain strings. This is sufficient for some cases, for instance:\nwhich would you bother much about the content of trace messages?\nMessage which are destined for end-users or log-files however, need\nmore care; require a higher quality. In this case, you can better\nuse cast message objects which support interpolation.
Log::Report::Extract - Collect translatable strings
\n", "type" : "chapter", "level" : 1 }, "id793-id818" : { "extends" : "id793", "value" : "<required>", "name" : "call", "id" : "id793-id818", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "type" : "default" }, "id759-id1228" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "type" : "option", "params" : "LOCALE", "extends" : "id759", "id" : "id759-id1228", "name" : "locale" }, "id931" : { "name" : "Message-IDs", "id" : "id931", "level" : 2, "path" : "DETAILS/Message-IDs", "intro" : "An exception message as a string is pretty inflexible. It cannot\nbe translated anymore, and it cannot contain related information\nlike an error code. An exception message as an object (as this\nmodule implements) is able to contain additional information.
\n\nThe easiest way to create Log::Report::Message objects, is via the\n__x() (and friends) functions which are exported by Log::Report.\nThese are nearly equivalent:
\n my $msg = Log::Report::Message->new(_msgid => \"Hello, World!\");\n my $msg = __\"Hello, World!\";\n\n\n
The name msgid is used, because this object can do translations.\nIn the GNU gettext library for translations, the term msgid is\nused to describe the string which has to be looked-up in translation\ntables. When there are no tables, or the msgid is not found,\nthen the output string is equivalent to the msgid.
So, without any translation configuration, this happens:
\n\n my $msg = __\"Hello, World!\";\n print \"$msg\\n\"; # Hello, World!⏎\n\n\n
The __() function can be used with a static string, although you\ncould do this:
\n my $msg = __\"Hello $name!\"; #XXX Don't do this!\n print \"$msg\\n\"; # Hello Mark!⏎\n\n\n
With the __x() or __nx(), interpolation will take place on the\n(optionally) translated msgid string. This is how to write above:
\n my $msg = __x\"Hello {name}!\", name => $name;\n\n\nSo: the msgid is usually a format string. Only when you use\nformats correctly, you will be able to introduce translation later.
Inherited, see Log::Report::Dispatcher::log()
", "type" : "i_method" }, "id783-id1174" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::skipStack()
", "extends" : "id783", "name" : "skipStack", "id" : "id783-id1174", "call" : "$obj->skipStack" }, "id795-id1228" : { "extends" : "id795", "value" : "<required>", "name" : "params", "id" : "id795-id1228", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
" }, "id1175" : { "level" : 1, "path" : "NAME", "intro" : "Log::Report::Dispatcher::LogDispatch - send messages to Log::Dispatch back-end
\n", "type" : "chapter", "id" : "id1175", "name" : "NAME" }, "id807" : { "id" : "id807", "name" : "a filter on syslog\n", "intro" : " dispatcher filter => \\&myfilter, 'syslog';\n\n # ignore all translatable and non-translatable messages containing\n # the word \"skip\"\n sub myfilter($$$$)\n { my ($disp, $opts, $reason, $message) = @_;\n return () if $message->untranslated =~ m/\\bskip\\b/;\n ($reason, $message);\n }\n\n",
"type" : "example"
},
"id981" : {
"level" : 1,
"type" : "chapter",
"intro" : " # Invocation with 'mode' to get trace and verbose messages\n use Log::Report mode => 'DEBUG';\n\n # Usually invoked with a domain, which groups packages for translation\n use Log::Report 'my-domain', %options;\n\n # Interpolation syntax via String::Print\n # First step to translations, once you need it.\n print __x\"my name is {name}\", name => $n; # print, so no exception\n print __\"Hello World\\n\"; # no interpolation, optional translation\n print __x'Hello World'; # SYNTAX ERROR: quote is alternative for ::\n\n # Functions replacing die/warn/carp, casting exceptions but not message\n # objects and no translation support.\n error \"oops\"; # exception like die(), no translation\n -f $config or panic \"Help!\"; # alert/error/fault/info/...more\n\n # Combined exception, interpolation, and optional translation\n error __x\"Help!\"; # __x() creates ::Message object\n error __x('gettext msgid', param => $value, ...)\n if $condition;\n\n # Also non fatal \"exceptions\" find their way to dispatchers\n info __x\"started {pid}\", pid => $$; # translatable\n debug \"$i was here!\"; # you probably do not want to translate debug\n panic \"arrghhh\"; # like Carp::Confess\n\n # Many destinations for an exception message (may exist in parallel)\n dispatcher PERL => 'default', # see Log::Report::Dispatcher: use die/warn\n reasons => 'NOTICE-'; # this dispatcher is already present at start\n\n dispatcher SYSLOG => 'syslog' # also send to syslog,\n charset => 'iso-8859-1', # explicit character conversions\n locale => 'en_US'; # overrule user's locale\n\n dispatcher close => 'default' # stop default die/warn dispatcher\n\n # Fill-in values, like Locale::TextDomain and gettext\n # See Log::Report::Message section DETAILS\n fault __x\"cannot allocate {size} bytes\", size => $size;\n fault \"cannot allocate $size bytes\"; # no translation, ok\n fault __x\"cannot allocate $size bytes\"; # not translatable, wrong\n\n # Output (optionally with translation) depending on count\n # Leading and trailing whitespace stay magically outside translation\n # tables. @files in scalar context. Special parameter with _\n print __xn\"found one file\\n\", \"found {_count} files\", @files;\n\n # Borrow from an other text-domain (see Log::Report::Message)\n print __x(+\"errors in {line}\", _domain => 'global', line => $line);\n\n # catch errors (implements hidden eval/die)\n try { error };\n if($@) {...} # $@ isa Log::Report::Dispatcher::Try\n if(my $exception = $@->wasFatal) # ::Exception object\n\n # Language translations at the output component\n # Translation management via Log::Report::Lexicon\n use POSIX::1003::Locale qw/setlocale LC_ALL/;\n setlocale(LC_ALL, 'nl_NL');\n info __\"Hello World!\"; # in Dutch, if translation table found\n\n # Exception classes, see Log::Report::Exception\n try { error __x\"something\", _tags => 'parsing,schema' };\n if($@->wasFatal->taggedWith('parsing')) ...\n\n",
"path" : "SYNOPSIS",
"id" : "id981",
"name" : "SYNOPSIS"
},
"id436" : {
"id" : "id436",
"name" : "showStats",
"call" : "$obj->showStats( [$domains] )",
"type" : "i_method",
"intro" : "Show a status about the DOMAIN (by default all domains). At least mode\nverbose is required to see this.
\n\nThe statistics are sent to (Log::Report) dispatchers which accept\nnotice and info. This could be syslog. When you have no explicit\ndispatchers in your program, the level of detail get controlled by\nthe 'mode':
\n\n use Log::Report mode => 'DEBUG'; # or 'VERBOSE'\n\n" }, "id1044" : { "type" : "section", "path" : "FUNCTIONS/Configuration", "level" : 2, "id" : "id1044", "name" : "Configuration", "subroutines" : [ "id1045", "id1060" ] }, "id1251" : { "subroutine" : "id1249", "name" : "unable to rotate logfile $fn to $oldfn: $!", "id" : "id1251", "type" : "fault" }, "id826" : { "level" : 2, "id" : "id826", "name" : "Constructors", "subroutines" : [ "id827" ], "type" : "section", "path" : "METHODS/Constructors" }, "id552" : { "name" : "format", "id" : "id552", "type" : "i_method", "intro" : "
When one $language is specified, it looks whether a \"language-format\" or\n\"no-language-format\" is present in the line of FLAGS. This will return\n1 (true) in the first case, 0 (false) in the second case. It will\nreturn undef (also false) in case that both are not present.
You can also specify PAIRS: the key is a language name, and the\nvalue is either 0, 1, or undef.
Inherited, see Log::Report::Dispatcher::new(charset)
", "params" : "CHARSET", "type" : "option" }, "id486" : { "subroutines" : [ "id495", "id496", "id498", "id497" ], "id" : "id486", "name" : "Managing PO's", "level" : 2, "nest" : [ "id1276", "id1277" ], "path" : "METHODS/Managing PO's", "type" : "section" }, "id1055" : { "type" : "error", "subroutine" : "id1045", "id" : "id1055", "name" : "syntax flag must be either SHORT or REPORT, not `$flag' in $fn line $line" }, "id976" : { "id" : "id976", "name" : "Logging", "level" : 2, "subroutines" : [ "id781-id958", "id785-id958", "id778-id958", "id784-id958", "id777-id958", "id780-id958", "id783-id958", "id779-id958", "id977" ], "type" : "section", "path" : "METHODS/Logging" }, "id152" : { "call" : "N__( $msgid )", "id" : "id152", "name" : "N__", "type" : "function" }, "id1161" : { "level" : 3, "path" : "DETAILS/Configuring/configuring your own formatter", "intro" : "[0.91] The PRINTI is a special constants for configure(formatter), and\nwill use String::Print function printi(), with the standard tricks.
\n textdomain 'some-domain',\n formatter => {\n class => 'String::Print', # default\n method => 'sprinti', # default\n %options, # constructor options for String::Print\n );\n\n\nWhen you want your own formatter, or configuration of String::Print,\nyou need to pass a CODE. Be aware that you may loose magic added by\nLog::Report and other layers, like Log::Report::Template:
\n textdomain 'some-domain', formatter => \\&my_formatter;\n\n", "type" : "subsection", "id" : "id1161", "name" : "configuring your own formatter" }, "id808" : { "name" : "take all mistakes and warnings serious\n", "id" : "id808", "type" : "example", "intro" : "
dispatch filter => \\&take_warns_seriously;\n sub take_warns_seriously($$$$)\n { my ($disp, $opts, $reason, $message) = @_;\n $reason eq 'MISTAKE' ? (ERROR => $message)\n : $reason eq 'WARNING' ? (FAULT => $message)\n : ($reason => $message);\n }\n\n"
},
"id815" : {
"id" : "id815",
"name" : "on_die",
"params" : "REASON",
"type" : "option"
},
"id1185" : {
"type" : "option",
"params" : "$level",
"intro" : "Like min_level.
\n", "id" : "id1185", "name" : "max_level" }, "id866" : { "call" : "$class->new( %options )", "name" : "new", "id" : "id866", "intro" : "End-users: do not use this method directly, but use\nLog::Report::__(), Log::Report::__x() and friends. The %options\nis a mixed list of object initiation parameters (all with a leading\nunderscore) and variables to be filled in into the translated _msgid\nstring.
\n", "type" : "c_method", "options" : [ [ "id881", "id882" ], [ "id877", "id878" ], [ "id889", "id890" ], [ "id887", "id888" ], [ "id897", "id898" ], [ "id871", "id872" ], [ "id869", "id870" ], [ "id867", "id868" ], [ "id893", "id894" ], [ "id895", "id896" ], [ "id899", "id900" ], [ "id875", "id876" ], [ "id873", "id874" ], [ "id879", "id880" ], [ "id883", "id884" ], [ "id885", "id886" ], [ "id891", "id892" ] ] }, "id471" : { "type" : "fault", "subroutine" : "id467", "name" : "cannot read from file $fn (unknown charset): $!", "id" : "id471" }, "id399" : { "intro" : "The language we are going to translate to. Change this with translateTo()\nfor this domain, or better Log::Report::Template::translateTo().
\n", "type" : "i_method", "call" : "$obj->lang", "id" : "id399", "name" : "lang" }, "id1331" : { "name" : "INHERITANCE", "id" : "id1331", "intro" : "Log::Report::Message is extended by\n Dancer2::Plugin::LogReport::Message\n\n", "path" : "INHERITANCE", "type" : "chapter", "level" : 1 }, "id355" : { "name" : "filename_match", "id" : "id355", "type" : "option", "params" : "RegEx", "intro" : "
Process all files from the INCLUDE_PATH directories which match this\nregular expression.
\n" }, "id1303" : { "subroutines" : [ "id901-id217", "id866-id217" ], "level" : 2, "name" : "Constructors", "id" : "id1303", "path" : "METHODS/Constructors", "type" : "section" }, "id55" : { "type" : "default", "id" : "id55", "name" : "modifiers", "value" : "[ qr/^%\\S+/ => \\&format_printf]"
},
"id1145-id375" : {
"id" : "id1145-id375",
"name" : "config",
"extends" : "id1145",
"intro" : "Inherited, see Log::Report::Domain::configure(config)
", "type" : "option", "params" : "$file" }, "id558" : { "id" : "id558", "name" : "unknown comment type '$cmd' at $where.", "subroutine" : "id557", "type" : "warning" }, "id579" : { "id" : "id579", "name" : "cannot read in $charset from file $fn: $!", "subroutine" : "id575", "type" : "fault" }, "id341" : { "subroutines" : [ "id346", "id342", "id348", "id347" ], "name" : "Handling text domains", "id" : "id341", "level" : 2, "path" : "METHODS/Handling text domains", "type" : "section" }, "id534" : { "id" : "id534", "name" : "format", "params" : "ARRAY|HASH", "type" : "option", "intro" : "See format(). Either an ARRAY with PAIRS or a HASH with that same\ninformation.
\n" }, "id772-id1228" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::type()
", "name" : "type", "id" : "id772-id1228", "extends" : "id772", "call" : "$obj->type" }, "id231" : { "name" : "DESCRIPTION", "id" : "id231", "level" : 1, "type" : "chapter", "intro" : "[The Dancer2 plugin was contributed by Andrew Beverley]\nWhen you need to translate your templates as well (not only the messages\nin your code) then have a look at Dancer2::Template::TTLogReport.
\n\nThis module provides easy access to the extensive logging facilities\nprovided by Log::Report. Along with Dancer2::Logger::LogReport,\nthis brings together all the internal Dancer2 logging, handling for\nexpected and unexpected exceptions, translations and application logging.
\n\nLogging is extremely flexible using many of the available\ndispatchers. Multiple dispatchers can be\nused, each configured separately to display different messages in different\nformats. By default, messages are logged to a session variable for display on\na webpage, and to STDERR.
\n\nMessages within this plugin use the extended\nmanual Dancer2::Logger::LogReport::Message class rather than the standard\nLog::Report::Message class.
\n\nNote that it is currently recommended to use the plugin in all apps within\na Dancer2 program, not only some. Therefore, wherever you use Dancer2\nyou should also use Dancer2::Plugin::LogReport. This does not apply if\nusing the same app name (use Dancer2 appname, 'Already::Exists'). In\nall other modules, you can just use Log::Report.
Read the DETAILS in below in this manual-page.
\n", "path" : "DESCRIPTION" }, "id80" : { "value" : "', '", "id" : "id80", "name" : "_join", "type" : "default" }, "id601" : { "type" : "i_method", "intro" : "For internal use only.\nForce the creation of the index (if not already done). Returns a hash\nwith key-value pairs, where the key is the lower-cased version of the\nfilename, and the value the case-sensitive version of the filename.
\n", "name" : "index", "id" : "id601", "call" : "$obj->index" }, "id762-id944" : { "name" : "mode", "id" : "id762-id944", "value" : "'NORMAL'", "extends" : "id762", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
" }, "id157" : { "type" : "error", "subroutine" : "id156", "name" : "syntax flag must be either SHORT or REPORT, not `$flag'", "id" : "id157" }, "id281" : { "name" : "SYNOPSIS", "id" : "id281", "type" : "chapter", "path" : "SYNOPSIS", "intro" : "# This module is loaded when configured. It does not provide\n # end-user functions or methods.\n\n # See DETAILS\n\n", "level" : 1 }, "id761" : { "name" : "mode", "id" : "id761", "params" : "'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3", "type" : "option", "intro" : "
Possible values are NORMAL (or 0 or undef), which will not show\nINFO or debug messages, VERBOSE (1; shows INFO not debug),\nASSERT (2; only ignores TRACE messages), or DEBUG (3)\nwhich shows everything. See section Run modes.
You are advised to use the symbolic mode names when the mode is\nchanged within your program: the numerical values are available\nfor smooth Getopt::Long integration.
\n" }, "id584" : { "subroutines" : [ "id586", "id585" ], "name" : "Attributes", "id" : "id584", "level" : 2, "path" : "METHODS/Attributes", "type" : "section" }, "id557" : { "id" : "id557", "name" : "fromText", "diagnostics" : [ "id558", "id559", "id560", "id561", "id562" ], "call" : "$class->fromText( STRING, [$where] )", "type" : "c_method", "intro" : "Parse the STRING into a new PO object. The $where string should explain\nthe location of the STRING, to be used in error messages.
\n" }, "id184" : { "path" : "DESCRIPTION", "intro" : "This module collects a few functions and definitions which are shared\nbetween different components in the Log::Report infrastructure.\nThey should not be needed for end-user applications, although this\nman-page may contain some useful background information.
\n", "type" : "chapter", "level" : 1, "id" : "id184", "name" : "DESCRIPTION" }, "id1008" : { "type" : "function", "intro" : "Execute the CODE while blocking all dispatchers as long as it is running.\nThe exceptions which occur while running the CODE are caught until it\nhas finished. When there where no fatal errors, the result of the CODE\nexecution is returned.
\n\nAfter the CODE was tried, the $@ will contain a\nLog::Report::Dispatcher::Try object, which contains the collected\nmessages. Read that manual page to understand try.
Run-time errors from Perl and die's, croak's and confess's within the\nprogram (which shouldn't appear, but you never know) are collected into an\nLog::Report::Message object, using Log::Report::Die.
\n\nThe %options are passed to the constructor of the try-dispatcher, see\nLog::Report::Dispatcher::Try::new(). For instance, you may like to\nadd mode => 'DEBUG', or accept => 'ERROR-'.
Be warned that the parameter to try is a CODE reference. This means\nthat you shall not use a comma after the block when there are %options\nspecified. On the other hand, you shall use a semi-colon after the\nblock if there are no arguments.
Be warned that the {} are interpreted as subroutine, which\nmeans that --for instance-- it has its own @_ parameter list.\nThe manual-page of Try::Tiny lists a few more side-effects of this.
You can use contexts to set global interpolation parameters. For instance,\nrunning a pure perl webserver, you may serve multiple domains. Some of\nthe log messages may need to show that domain name. Of course, you can\ncollect (or pass on) the hostname when throwing the error... something\nlike this:
\n\n # can I access $vhost easily?\n error __x\"For {host}, login failed for {user}\",\n host => $vhost->name, user => $user;\n\n\nVia contexts:
\n\n # when you know the vhost: (max once per request)\n textdomain->setContext(host => $vhost->name); # or updateContext\n\n # until you reconfigure the context\n error __x\"For {_context.host}, login failed for {user}\", user => $user;\n\n\nThe context values are always available for interpolation.
\n", "type" : "subsection", "name" : "Global parameters", "id" : "id693" }, "id276" : { "name" : "DETAILS", "id" : "id276", "level" : 1, "type" : "chapter", "nest" : [ "id277", "id278" ], "path" : "DETAILS" }, "id179" : { "path" : "METHODS/Translating", "type" : "section", "subroutines" : [ "id180" ], "id" : "id179", "name" : "Translating", "level" : 2 }, "id158" : { "is_pure_pod" : false, "title" : "administer one text-domain", "id" : "id158", "name" : "Log::Report::Minimal::Domain", "inheritance" : { "extended_by" : [ "Log::Report::Domain" ] }, "package" : "Log::Report::Minimal::Domain", "distribution" : "Log-Report-Optional", "version" : "1.08", "chapters" : [ "id159", "id1325", "id160", "id161", "id162" ] }, "id800-id1090" : { "extends" : "id800", "name" : "abstract", "id" : "id800-id1090", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "params" : "INTEGER", "type" : "option" }, "id801-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "type" : "default", "extends" : "id801", "value" : "1", "id" : "id801-id944", "name" : "abstract" }, "id802" : { "type" : "chapter", "nest" : [ "id803", "id804" ], "path" : "DETAILS", "name" : "DETAILS", "id" : "id802", "level" : 1 }, "id1125" : { "path" : "METHODS/Constructors", "type" : "section", "subroutines" : [ "id1126" ], "level" : 2, "name" : "Constructors", "id" : "id1125" }, "id1316" : { "name" : "INHERITANCE", "id" : "id1316", "level" : 1, "intro" : "Log::Report::Optional\n is an Exporter\n\n", "path" : "INHERITANCE", "type" : "chapter" }, "id714" : { "subroutine" : "id708", "name" : "use double quotes not single, in $string on $file line $line.", "id" : "id714", "type" : "warning" }, "id447" : { "diagnostics" : [ "id466" ], "name" : "new", "id" : "id447", "call" : "$class->new( %options )", "type" : "c_method", "options" : [ [ "id448", "id449" ], [ "id462", "id463" ], [ "id464", "id465" ], [ "id460", "id461" ], [ "id454", "id455" ], [ "id456", "id457" ], [ "id458", "id459" ], [ "id450", "id451" ], [ "id452", "id453" ] ], "intro" : "
Create a new POT file. The initial header is generated for you, but\nit can be changed using the header() method.
\n" }, "id597" : { "name" : "new", "id" : "id597", "call" : "$class->new( $directory, %options )", "type" : "c_method", "intro" : "Create an index for a certain directory. If the directory does not\nexist or is empty, then the object will still be created.
\n\nAll files the $directory tree which are recognized as an translation table\nformat which is understood will be listed. Momentarily, those are:
\n\n[0.99] Files which are in directories which start with a dot (hidden\ndirectories) and files which start with a dot (hidden files) are skipped.
\n" }, "id372" : { "name" : "adding a new language", "id" : "id372", "level" : 3, "type" : "subsection", "intro" : "The first time you run extract(), you will see a file being created\nin $lexicon/$textdomain-$charset.po. That file will be left empty:\ncopy it to start a new translation.
There are many ways to structure PO-files. Which structure used, is\ndetected automatically by Log::Report::Lexicon. My personal preference\nis $lexicon/$textdomain/$language-$charset.po. On Unix-like systems,\nyou would do:
\n # Start a new language\n mkdir mylexicon/mydomain\n cp mylexicon/mydomain-utf8.po mylexicon/mydomain/nl_NL-utf8.po\n\n # fill the nl_NL-utf8.po file with the translation\n poedit mylexicon/mydomain/nl_NL-utf8.po\n\n # add the file to your version control system\n git add mylexicon/mydomain/nl_NL-utf8.po\n\n\n\n
Now, when your program sets the locale to 'nl-NL', it should start\ntranslating to Dutch. If it doesn't, it is not always easy to\nfigure-out what is wrong...
\n", "path" : "DETAILS/Extracting PO-files/adding a new language" }, "id653" : { "subroutine" : "id643", "id" : "id653", "name" : "cannot seek to $loc in $fn for translations: $!", "type" : "fault" }, "id800-id818" : { "params" : "INTEGER", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "extends" : "id800", "id" : "id800-id818", "name" : "abstract" }, "id175" : { "type" : "default", "value" : "<required>", "name" : "where", "id" : "id175" }, "id768-id1082" : { "type" : "error", "intro" : "Inherited, see Log::Report::Dispatcher::new()
", "id" : "id768-id1082", "name" : "illegal format_reason '$format' for dispatcher", "extends" : "id768", "subroutine" : "id756" }, "id198" : { "type" : "function", "call" : "must_show_location( $mode, $reason )", "name" : "must_show_location", "id" : "id198" }, "id1288" : { "level" : 1, "id" : "id1288", "name" : "DETAILS", "path" : "DETAILS", "nest" : [ "id1289", "id1290" ], "type" : "chapter" }, "id1068" : { "nest" : [ "id1069", "id1071", "id1075" ], "name" : "Error handling models", "id" : "id1068", "path" : "DETAILS/Error handling models", "intro" : "There are two approaches to handling errors and warnings. In the first\napproach, as produced by die, warn and the carp family of\ncommands, the program handles the problem immediately on the location\nwhere the problem appears. In the second approach, an exception\nis thrown on the spot where the problem is created, and then somewhere\nelse in the program the condition is handled.
The implementation of exceptions in Perl5 is done with a eval-die pair:\non the spot where the problem occurs, die is called. But, because of\nthe execution of that routine is placed within an eval, the program\nas a whole will not die, just the execution of a part of the program\nwill seize. However, what if the condition which caused the routine to die\nis solvable on a higher level? Or what if the user of the code doesn't\nbother that a part fails, because it has implemented alternatives for\nthat situation? Exception handling is quite clumsy in Perl5.
The Log::Report set of distributions let modules concentrate on the\nprogram flow, and let the main program decide on the report handling\nmodel. The infrastructure to translate messages into multiple languages,\nwhether to create exceptions or carp/die, to collect longer explanations\nwith the messages, to log to mail or syslog, and so on, is decided in\npluggable back-ends.
Read the POT table information from $filename, as compact as possible.\nComments, plural-form, and such are lost on purpose: they are not\nneeded for translations.
\n" }, "id448" : { "params" : "STRING", "type" : "option", "intro" : "The charset to be used for the createed file. It is unwise to use anything\nelse than 'UTF-8', but allowed. Before [1.09] this option was required.
\n", "id" : "id448", "name" : "charset" }, "id598" : { "name" : "Attributes", "id" : "id598", "level" : 2, "subroutines" : [ "id599" ], "type" : "section", "path" : "METHODS/Attributes" }, "id1278" : { "path" : "DETAILS", "nest" : [ "id1279", "id1280" ], "type" : "chapter", "level" : 1, "id" : "id1278", "name" : "DETAILS" }, "id270" : { "path" : "METHODS/Attributes", "type" : "section", "subroutines" : [ "id271" ], "level" : 2, "id" : "id270", "name" : "Attributes" }, "id1329" : { "name" : "INHERITANCE", "id" : "id1329", "level" : 1, "type" : "chapter", "path" : "INHERITANCE", "intro" : "Log::Report::Util\n is an Exporter\n\n" }, "id197" : { "name" : "mode_accepts", "id" : "id197", "call" : "mode_accepts( $mode )", "type" : "function", "intro" : "
Returns something acceptable by expand_reasons()
\n" }, "id767-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::new()
", "type" : "alert", "subroutine" : "id756", "extends" : "id767", "name" : "cannot use class $backend:\\n$@: $!", "id" : "id767-id1082" }, "id1095" : { "subroutines" : [ "id1096" ], "name" : "Constructors", "id" : "id1095", "level" : 2, "path" : "METHODS/Constructors", "type" : "section" }, "id192" : { "intro" : "Returns true if the STRING is one of the predefined REASONS.
Inherited, see Log::Report::Dispatcher::new(mode)
" }, "id819" : { "level" : 1, "path" : "NAME", "intro" : "Log::Report::Dispatcher::Try - capture all reports as exceptions
\n", "type" : "chapter", "id" : "id819", "name" : "NAME" }, "id1040" : { "id" : "id1040", "name" : "__p", "call" : "__p( $msgctxt, $msgid )", "type" : "function" }, "id1228" : { "distribution" : "Log-Report", "package" : "Log::Report::Dispatcher::File", "inheritance" : { "extends" : [ "Log::Report::Dispatcher" ] }, "name" : "Log::Report::Dispatcher::File", "id" : "id1228", "title" : "send messages to a file or file-handle", "is_pure_pod" : false, "chapters" : [ "id1229", "id1339", "id1230", "id1231", "id1232", "id1278" ], "version" : "1.45" }, "id395" : { "intro" : "The Log::Report::Template object which is using this textdomain.
\n", "type" : "i_method", "call" : "$obj->templater", "name" : "templater", "id" : "id395" }, "id359" : { "name" : "Template (Toolkit) base-class", "id" : "id359", "type" : "section", "path" : "METHODS/Template (Toolkit) base-class", "intro" : "The details of the following functions can be found in the Template\nmanual page. They are included here for reference only.
\n", "level" : 2, "subroutines" : [ "id361", "id360" ] }, "id430" : { "call" : "$obj->addPot( $domain, $pot, %options )", "name" : "addPot", "id" : "id430", "type" : "i_method" }, "id378" : { "level" : 1, "type" : "chapter", "path" : "DESCRIPTION", "intro" : "Manage one translation domain for Log::Report::Template.
\n", "id" : "id378", "name" : "DESCRIPTION" }, "id1150-id375" : { "type" : "fault", "intro" : "Inherited, see Log::Report::Domain::readConfig()
", "name" : "cannot open JSON file for context at $fn: $!", "id" : "id1150-id375", "extends" : "id1150", "subroutine" : "id1149" }, "id480" : { "type" : "fault", "subroutine" : "id475", "id" : "id480", "name" : "cannot write to file $fn with $layers: $!" }, "id820" : { "name" : "SYNOPSIS", "id" : "id820", "level" : 1, "intro" : " try { ... }; # mind the ';' !!\n if($@) { # signals something went wrong\n\n if(try {...}) { # block ended normally\n\n my $x = try { read_temperature() };\n my @x = try { read_lines_from_file() };\n\n try { ... } # no comma!!\n mode => 'DEBUG', accept => 'ERROR-';\n\n try sub { ... }, # with comma\n mode => 'DEBUG', accept => 'ALL';\n\n try \\&myhandler, accept => 'ERROR-';\n try { ... } hide => 'TRACE';\n\n print ref $@; # Log::Report::Dispatcher::Try\n\n $@->reportFatal; # re-dispatch result of try block\n $@->reportAll; # ... also warnings etc\n if($@) {...} # if errors\n if($@->failed) { # same # }\n if($@->success) { # no errors # }\n\n try { # something causes an error report, which is caught\n failure 'no network';\n };\n $@->reportFatal(to => 'syslog'); # overrule destination\n\n print $@->exceptions; # no re-cast, just print\n\n",
"path" : "SYNOPSIS",
"type" : "chapter"
},
"id741-id569" : {
"type" : "i_method",
"intro" : "Inherited, see Log::Report::Lexicon::Table::pluralIndex()
", "diagnostics" : [ "id742-id569" ], "call" : "$obj->pluralIndex( $count )", "name" : "pluralIndex", "id" : "id741-id569", "extends" : "id741" }, "id59" : { "value" : "undef",
"id" : "id59",
"name" : "encode_for",
"type" : "default"
},
"id1101" : {
"value" : "'pid,nowait'",
"name" : "flags",
"id" : "id1101",
"type" : "default"
},
"id1327" : {
"type" : "chapter",
"path" : "INHERITANCE",
"intro" : "Log::Report::Extract is extended by\n Log::Report::Extract::PerlPPI\n Log::Report::Template::Extract\n\n", "level" : 1, "name" : "INHERITANCE", "id" : "id1327" }, "id970" : { "name" : "config", "id" : "id970", "type" : "option", "params" : "FILENAME|SCALAR", "intro" : "
When a SCALAR reference is passed in, that must refer to a string which\ncontains the configuration text. Otherwise, specify an existing FILENAME.
\n\nBy default, it is expected that Log::Log4perl has been initialized\nexternally. That module uses global variables to communicate, which\nshould be present before any logging is attempted.
\n" }, "id799-id1228" : { "name" : "max_params", "id" : "id799-id1228", "extends" : "id799", "value" : "8", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "type" : "default" }, "id860" : { "subroutines" : [ "id863", "id861", "id862" ], "level" : 1, "name" : "OVERLOADED", "id" : "id860", "path" : "OVERLOADED", "type" : "chapter" }, "id1133" : { "intro" : "Create a new Domain object.
\n", "type" : "c_method", "options" : [ [ "id165-id1127", "id166-id1127" ] ], "call" : "$class->new( %options )", "name" : "new", "id" : "id1133" }, "id801-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "type" : "default", "id" : "id801-id1082", "name" : "abstract", "value" : "1", "extends" : "id801" }, "id1291" : { "type" : "subsection", "path" : "DETAILS/Processing the message/Addition information", "level" : 3, "name" : "Addition information", "id" : "id1291" }, "id893-id217" : { "intro" : "Inherited, see Log::Report::Message::new(_join)
", "params" : "$separator", "type" : "option", "name" : "_join", "id" : "id893-id217", "extends" : "id893" }, "id442" : { "path" : "NAME", "intro" : "Log::Report::Lexicon::POT - manage PO files
\n", "type" : "chapter", "level" : 1, "name" : "NAME", "id" : "id442" }, "id793-id1090" : { "extends" : "id793", "value" : "<required>", "name" : "call", "id" : "id793-id1090", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
" }, "id592" : { "path" : "NAME", "intro" : "Log::Report::Lexicon::Index - search through available translation files
\n", "type" : "chapter", "level" : 1, "name" : "NAME", "id" : "id592" }, "id377" : { "type" : "chapter", "intro" : "my $templater = Log::Report::Template->new(...);\n my $domain = $templater->addTextdomain(%options);\n\n", "path" : "SYNOPSIS", "level" : 1, "id" : "id377", "name" : "SYNOPSIS" }, "id663" : { "type" : "i_method", "intro" : "
Returns a HASH of all defined PO objects, organized by msgid. Please try\nto avoid using this: use msgid() for lookup.
\n", "id" : "id663", "name" : "index", "call" : "$obj->index" }, "id844" : { "name" : "log", "id" : "id844", "call" : "$obj->log( $opts, $reason, $message )", "type" : "i_method", "intro" : "Other dispatchers translate the message here, and make it leave the\nprogram. However, messages in a \"try\" block are only captured in\nan intermediate layer: they may never be presented to an end-users.\nAnd for sure, we do not know the language yet.
\n\nThe $message is either a STRING or a Log::Report::Message.
\n" }, "id781-id958" : { "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::addSkipStack()
", "id" : "id781-id958", "name" : "addSkipStack", "extends" : "id781", "call" : "$any->addSkipStack( @CODE )" }, "id703" : { "intro" : "Not extracted are the usage of anything above, where the first\nparameter is not a simple string. Not extracted are
\n\n __x($format, @more)\n __x$format, @more\n __x(+$format, _domain => 'other domain', @more)\n __x($first.$second, @more)\n\n\n
In these cases, you have to use N__() functions to declare the possible\nvalues of $format.
Inherited, see Log::Report::Dispatcher::collectLocation()
", "id" : "id784-id1082", "name" : "collectLocation", "extends" : "id784", "call" : "$any->collectLocation" }, "id500" : { "level" : 1, "type" : "chapter", "path" : "NAME", "intro" : "Log::Report::Win32Locale - unix/windows locales
\n", "name" : "NAME", "id" : "id500" }, "id205" : { "subroutine" : "id204", "name" : "unknown locale language in locale '$locale'.", "id" : "id205", "type" : "error" }, "id1247" : { "call" : "$obj->output( $msg )", "name" : "output", "id" : "id1247", "intro" : "Returns the file-handle to write the log lines to. [1.10] This may\ndepend on the $msg (especially message context)
\n", "type" : "i_method" }, "id635" : { "name" : "unknown translation table extension '$ext' in $file.", "id" : "id635", "subroutine" : "id634", "type" : "error" }, "id685" : { "name" : "needDecode", "id" : "id685", "diagnostics" : [ "id686" ], "call" : "$any->needDecode( $source, STRING|ARRAY|HASH|PAIRS )", "type" : "ci_method", "intro" : "Converts the context settings passed with the MSGID, into a HASH which will\nbe matched to the context providers.
\n" }, "id1176" : { "name" : "SYNOPSIS", "id" : "id1176", "path" : "SYNOPSIS", "intro" : "use Log::Dispatch::File;\n dispatcher Log::Dispatch::File => 'logger', accept => 'NOTICE-',\n filename => 'logfile', to_level => [ 'ALERT-' => 'err' ];\n\n # disable default dispatcher\n dispatcher close => 'logger';\n\n", "type" : "chapter", "level" : 1 }, "id218" : { "type" : "chapter", "path" : "NAME", "intro" : "
Dancer2::Plugin::LogReport::Message - extended Log::Report message class
\n", "level" : 1, "name" : "NAME", "id" : "id218" }, "id912" : { "name" : "classes", "id" : "id912", "call" : "$obj->classes", "type" : "i_method", "intro" : "Deprecated alternative for tags().
\n" }, "id779-id1082" : { "call" : "$obj->translate( \\%options, $reason, $message )", "extends" : "id779", "id" : "id779-id1082", "name" : "translate", "intro" : "Inherited, see Log::Report::Dispatcher::translate()
", "type" : "i_method" }, "id758-id1082" : { "name" : "accept", "id" : "id758-id1082", "value" : "depend on mode",
"extends" : "id758",
"intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "type" : "default" }, "id772-id1174" : { "intro" : "Inherited, see Log::Report::Dispatcher::type()
", "type" : "i_method", "call" : "$obj->type", "id" : "id772-id1174", "name" : "type", "extends" : "id772" }, "id1146-id375" : { "extends" : "id1146", "value" : "undef",
"name" : "config",
"id" : "id1146-id375",
"type" : "default",
"intro" : "Inherited, see Log::Report::Domain::configure(config)
" }, "id1022" : { "type" : "section", "path" : "FUNCTIONS/Messages (optionally translatable)", "intro" : "Even when you do not support translations (yet) you may want to use\nmessage objects to improve the logging feature. For instance,\nyou get very powerful interpolation from String::Print.
\n\nThe language translations are initiate by limited set of functions\nwhich contain two under-scores (__) in their name. Most\nof them return a Log::Report::Message object.
Be warned(1) that -in general- its considered very bad practice to\ncombine multiple translations into one message: translating may also\naffect the order of the translated components. Besides, when the person\nwhich translates only sees smaller parts of the text, his (or her) job\nbecomes more complex. So:
\n\n print __\"Hello\" . ', ' . __\"World!\"; # works, but to be avoided\n print __\"Hello, World!\"; # preferred, complete sentence\n\n\n
The the former case, tricks with overloading used by the\nLog::Report::Message objects will still make delayed translations\nwork.
\n\nIn normal situations, it is not a problem to translate interpolated\nvalues:
\n\n print __\"the color is {c}\", c => __\"red\";\n\n\nBe warned(2) that using __'Hello' will produce a syntax error like\n\"String found where operator expected at .... Can't find string terminator\n\"'\" anywhere before EOF\". The first quote is the cause of the complaint,\nbut the second generates the error. In the early days of Perl, the single\nquote was used to separate package name from function name, a role which\nwas later replaced by a double-colon. So __'Hello' gets interpreted\nas __::Hello '. Then, there is a trailing single quote which has\nno counterpart.
undef",
"name" : "max_level",
"id" : "id1186",
"type" : "default"
},
"id791" : {
"type" : "default",
"value" : "<required>",
"id" : "id791",
"name" : "linenr"
},
"id757-id1082" : {
"intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "type" : "option", "params" : "$reasons|\\@reasons", "name" : "accept", "id" : "id757-id1082", "extends" : "id757" }, "id792-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "params" : "STRING", "type" : "option", "extends" : "id792", "name" : "call", "id" : "id792-id944" }, "id100" : { "id" : "id100", "name" : "Modifier: BYTES", "level" : 3, "type" : "subsection", "intro" : "[0.91] Too often, you have to translate a (file) size into humanly readible\nformat. The BYTES modifier simplifies this a lot:
\n printp \"{size BYTES} {fn}\\n\", fn => $fn, size => -s $fn;\n\n\nThe output will always be 5 characters. Examples are \"999 B\", \"1.2kB\",\nand \" 27MB\".
\n", "path" : "DETAILS/Interpolation: Modifiers/Modifier: BYTES" }, "id217" : { "distribution" : "Dancer2-Plugin-LogReport", "inheritance" : { "extends" : [ "Log::Report::Message" ] }, "package" : "Dancer2::Plugin::LogReport::Message", "id" : "id217", "name" : "Dancer2::Plugin::LogReport::Message", "is_pure_pod" : false, "title" : "extended Log::Report message class", "chapters" : [ "id218", "id1347", "id219", "id220", "id1302", "id221", "id1306" ], "version" : "2.03" }, "id623" : { "subroutines" : [ "id624" ], "level" : 2, "id" : "id623", "name" : "Constructors", "path" : "METHODS/Constructors", "type" : "section" }, "id1348" : { "intro" : "Log::Report::Lexicon::Table is extended by\n Log::Report::Lexicon::MOTcompact\n Log::Report::Lexicon::POT\n Log::Report::Lexicon::POTcompact\n\n", "path" : "INHERITANCE", "type" : "chapter", "level" : 1, "id" : "id1348", "name" : "INHERITANCE" }, "id91" : { "type" : "section", "path" : "DETAILS/Four components", "intro" : "
To fill-in a FORMAT, four clearly separated components play a role:
\n\nundef\nand ARRAYs.\n\n\n%d. One conversion rule\nhas been added 'S', which provides unicode correct behavior.\n\n\nSimplified:
\n\n # sprinti() replaces \"{$key$modifiers$conversion}\" by\n $encode->($format->($serializer->($modifiers->($args{$key}))))\n\n # sprintp() replaces \"%pos{$modifiers}$conversion\" by\n $encode->($format->($serializer->($modifiers->($arg[$pos]))))\n\n\nExample:
\n\n printi \"price: {price € %-10s}\", price => $cost;\n printi \"price: {price € %-10s}\", { price => $cost };\n printp \"price: %-10{€}s\", $cost;\n\n $value = $cost (in €)\n $modifier = convert € to local currency £\n $serializer = show float as string\n $format = column width %-10s\n $encode = £ into £ # when encodingFor('HTML')\n\n",
"level" : 2,
"name" : "Four components",
"id" : "id91"
},
"id1056" : {
"type" : "error",
"name" : "message_class $class does not extend $base",
"id" : "id1056",
"subroutine" : "id1045"
},
"id905" : {
"type" : "i_method",
"intro" : "Returns the msgid which will later be translated.
\n", "id" : "id905", "name" : "msgid", "call" : "$obj->msgid" }, "id896" : { "type" : "default", "id" : "id896", "name" : "_lang", "value" : "<from locale>" }, "id1130" : { "id" : "id1130", "name" : "DESCRIPTION", "path" : "DESCRIPTION", "intro" : "Log::Report can handle multiple sets of packages used by your program at the same\ntime. In the common case, your program consists of more than one imported software\ndistribution, each containing a number of packages. So separate the Log::Report\nconfiguration for each distribution, you should explicitly assign each package\nto a set, to a namespace. This is (in translation lingo) a domain or text domain.\nThe default domain has name default.
For Log::Report, those package sets are selected with the text-domain\nvalue in the use statement:
\n use Log::Report 'my-domain';\n\n\n
There are many things you can configure per (text)domain. This is\nnot only related to translations, but also -for instance- for text\nformatting configuration (String::Print options). The administration\nfor the configuration is managed in this package.
\n\nThis class extends Log::Report::Minimal::Domain, which can be used when your\nprogram does not want any overhead from the powerful Log::Report features.\nIn that case, your program invokes Log::Report::Optional.
\n", "type" : "chapter", "level" : 1 }, "id1262" : { "type" : "chapter", "nest" : [ "id1263", "id1264" ], "path" : "DETAILS", "name" : "DETAILS", "id" : "id1262", "level" : 1 }, "id1304" : { "level" : 2, "name" : "Attributes", "id" : "id1304", "subroutines" : [ "id907-id217", "id913-id217", "id911-id217", "id914-id217", "id912-id217", "id915-id217", "id909-id217", "id905-id217", "id908-id217", "id916-id217", "id906-id217", "id904-id217", "id910-id217" ], "type" : "section", "path" : "METHODS/Attributes" }, "id426-id697" : { "call" : "$obj->index", "name" : "index", "id" : "id426-id697", "extends" : "id426", "intro" : "Inherited, see Log::Report::Extract::index()
", "type" : "i_method" }, "id1249" : { "type" : "i_method", "intro" : "[1.00] Move the current file to $filename, and start a new file.
\n", "diagnostics" : [ "id1250", "id1251", "id1252" ], "name" : "rotate", "id" : "id1249", "call" : "$obj->rotate( $filename|CODE )" }, "id797-id944" : { "name" : "max_line", "id" : "id797-id944", "extends" : "id797", "value" : "undef",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "type" : "default" }, "id924-id217" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Message::untranslated()
", "id" : "id924-id217", "name" : "untranslated", "extends" : "id924", "call" : "$obj->untranslated" }, "id918" : { "type" : "section", "path" : "METHODS/Processing", "id" : "id918", "name" : "Processing", "level" : 2, "subroutines" : [ "id927", "id922", "id920", "id924", "id919", "id925", "id929", "id921" ] }, "id212" : { "path" : "METHODS", "type" : "chapter", "subroutines" : [ "id213" ], "name" : "METHODS", "id" : "id212", "level" : 1 }, "id1072" : { "intro" : "The GetOptions() function will count the number of v options\non the command-line when a + is after the option name.
\n use Log::Report;\n use Getopt::Long qw(:config no_ignore_case bundling);\n\n my $mode; # defaults to NORMAL\n GetOptions 'v+' => \\$mode,\n 'verbose=i' => \\$mode,\n 'mode=s' => \\$mode\n or exit 1;\n\n dispatcher 'PERL', 'default', mode => $mode;\n\n\n
Now, -vv will set $mode to 2, as will --verbose 2 and\n--verbose=2 and --mode=ASSERT. Of course, you do not need to\nprovide all these options to the user: make a choice.
Inherited, see Log::Report::Dispatcher::close()
" }, "id369" : { "level" : 3, "type" : "subsection", "intro" : "Usually, when data is passed from the program's internal to the template,\nit should get encoded into HTML to escape some characters. Typical TT\ncode:
\n\n Title: [% title | html %]\n\n\n
When your insert is produced by the localizer, you can do this as well\n(set template_syntax to 'UNKNOWN' first)
\n [% loc(\"Title: {t}\", t => title) | html %]\n\n\nThe default TT syntax is 'HTML', which will circumvent the need to\nuse the html filter. In that default case, you only say:
\n\n [% loc(\"Title: {t}\", t => title) %]\n [% loc(\"Title: {title}\") %] # short form, see previous section\n\n\nWhen the title is already escaped for HTML, you can circumvent that\nby using tags which end on 'html':
\n\n [% loc(\"Title: {t_html}\", t_html => title) %]\n\n [% SET title_html = html(title) %]\n [% loc(\"Title: {title_html}\") %]\n\n",
"path" : "DETAILS/Supported syntax/Translation into HTML",
"name" : "Translation into HTML",
"id" : "id369"
},
"id739-id637" : {
"id" : "id739-id637",
"name" : "translations",
"extends" : "id739",
"intro" : "Inherited, see Log::Report::Lexicon::Table::translations()
", "type" : "i_method", "call" : "$obj->translations( [$active] )", "diagnostics" : [ "id740-id637" ] }, "id850" : { "id" : "id850", "name" : "wasFatal", "call" : "$obj->wasFatal( %options )", "options" : [ [ "id853", "id854" ], [ "id851", "id852" ] ], "type" : "i_method", "intro" : "Returns the Log::Report::Exception which caused the \"try\" block to\ndie, otherwise an empty LIST (undef).
Inherited, see Log::Report::Message::new(_class)
", "extends" : "id889", "name" : "_class", "id" : "id889-id217" }, "id1126" : { "intro" : "Inherited %options path and level are ignored.
Log::Report::Translator is extended by\n Log::Report::Translator::Gettext\n Log::Report::Translator::POT\n\n", "type" : "chapter" }, "id775-id944" : { "id" : "id775-id944", "name" : "needs", "extends" : "id775", "call" : "$obj->needs( [$reason] )", "type" : "i_method", "intro" : "
Inherited, see Log::Report::Dispatcher::needs()
" }, "id176-id1127" : { "intro" : "Inherited, see Log::Report::Minimal::Domain::configure(formatter)
", "type" : "option", "params" : "CODE|\\%config|'PRINTI'", "id" : "id176-id1127", "name" : "formatter", "extends" : "id176" }, "id1043" : { "call" : "__npx( $msgctxt, $msgid, $plural, count, PAIRS )", "id" : "id1043", "name" : "__npx", "type" : "function" }, "id917" : { "type" : "example", "intro" : "When the message was produced with
\n\n my @files = qw/one two three/;\n my $msg = __xn\n \"found one file: {file}\",\n \"found {nrfiles} files: {files}\",\n scalar @files,\n file => $files[0],\n files => \\@files,\n nrfiles => @files+0, # or scalar(@files)\n _tags => [ 'IO', 'files' ],\n _join => ', ';\n\n\nthen the values can be takes from the produced message as
\n\n my $files = $msg->valueOf('files'); # returns ARRAY reference\n print @$files; # 3\n my $count = $msg->count; # 3\n my @tags = $msg->tags; # 'IO', 'files'\n if($msg->taggedWith('files')) # true\n\n\nSimplified, the above example can also be written as:
\n\n local $\" = ', '; # Perl default\n my $msg = __xn\n \"found one file: {files}\",\n \"found {_count} files: {files}\",\n @files, # has scalar context\n files => \\@files,\n _tags => 'IO, files';\n\n",
"id" : "id917"
},
"id798-id944" : {
"id" : "id798-id944",
"name" : "max_params",
"extends" : "id798",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "params" : "INTEGER", "type" : "option" }, "id789-id1090" : { "extends" : "id789", "value" : "<required>", "name" : "filename", "id" : "id789-id1090", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
", "type" : "default" }, "id765-id1228" : { "id" : "id765-id1228", "name" : "charset", "extends" : "id765", "type" : "option", "params" : "CHARSET", "intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
" }, "id329" : { "type" : "option", "params" : "'UNKNOWN'|'HTML'", "intro" : "Linked to String::Print::new(encode_for): the output of the translation\nis HTML encoded unless the inserted value name ends on _html.\nRead Translation into HTML
Inherited, see Log::Report::Dispatcher::new(format_reason)
" }, "id778-id1174" : { "call" : "$obj->log( \\%options, $reason, $message, $domain )", "extends" : "id778", "name" : "log", "id" : "id778-id1174", "intro" : "Inherited, see Log::Report::Dispatcher::log()
", "type" : "i_method" }, "id783-id1228" : { "id" : "id783-id1228", "name" : "skipStack", "extends" : "id783", "call" : "$obj->skipStack", "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::skipStack()
" }, "id759-id1174" : { "type" : "option", "params" : "LOCALE", "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "extends" : "id759", "name" : "locale", "id" : "id759-id1174" }, "id1152" : { "path" : "METHODS/Translating", "type" : "section", "subroutines" : [ "id180-id1127", "id1153", "id1158", "id1156", "id1157" ], "id" : "id1152", "name" : "Translating", "level" : 2 }, "id795-id1174" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "name" : "params", "id" : "id795-id1174", "extends" : "id795", "value" : "<required>" }, "id874-id217" : { "type" : "default", "intro" : "Inherited, see Log::Report::Message::new(_plural)
", "value" : "undef",
"extends" : "id874",
"name" : "_plural",
"id" : "id874-id217"
},
"id785-id818" : {
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine()
", "type" : "ci_method", "options" : [ [ "id800-id818", "id801-id818" ], [ "id792-id818", "id793-id818" ], [ "id788-id818", "id789-id818" ], [ "id790-id818", "id791-id818" ], [ "id796-id818", "id797-id818" ], [ "id798-id818", "id799-id818" ], [ "id786-id818", "id787-id818" ], [ "id794-id818", "id795-id818" ] ], "call" : "$any->stackTraceLine( %options )", "extends" : "id785", "id" : "id785-id818", "name" : "stackTraceLine" }, "id1082" : { "version" : "1.45", "chapters" : [ "id1083", "id1319", "id1084", "id1085", "id1086", "id1255" ], "id" : "id1082", "name" : "Log::Report::Dispatcher::Perl", "title" : "send messages to die and warn", "is_pure_pod" : false, "distribution" : "Log-Report", "package" : "Log::Report::Dispatcher::Perl", "inheritance" : { "extends" : [ "Log::Report::Dispatcher" ] } }, "id774-id1090" : { "call" : "$obj->isDisabled", "name" : "isDisabled", "id" : "id774-id1090", "extends" : "id774", "intro" : "Inherited, see Log::Report::Dispatcher::isDisabled()
", "type" : "i_method" }, "id310" : { "subroutine" : "id305", "name" : "processing file $file in $charset.", "id" : "id310", "type" : "info" }, "id1153-id375" : { "intro" : "Inherited, see Log::Report::Domain::setContext()
", "type" : "i_method", "call" : "$obj->setContext( STRING|HASH|ARRAY|PAIRS )", "diagnostics" : [ "id1155-id375" ], "extends" : "id1153", "name" : "setContext", "id" : "id1153-id375" }, "id885-id217" : { "name" : "_tags", "id" : "id885-id217", "extends" : "id885", "intro" : "Inherited, see Log::Report::Message::new(_tags)
", "type" : "option", "params" : "$tags|\\@tags" }, "id758-id944" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "value" : "depend on mode",
"extends" : "id758",
"name" : "accept",
"id" : "id758-id944"
},
"id774-id818" : {
"call" : "$obj->isDisabled",
"extends" : "id774",
"id" : "id774-id818",
"name" : "isDisabled",
"intro" : "Inherited, see Log::Report::Dispatcher::isDisabled()
", "type" : "i_method" }, "id779-id944" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::translate()
", "name" : "translate", "id" : "id779-id944", "extends" : "id779", "call" : "$obj->translate( \\%options, $reason, $message )" }, "id1202" : { "type" : "section", "path" : "METHODS/Constructors", "name" : "Constructors", "id" : "id1202", "level" : 2, "subroutines" : [ "id1203" ] }, "id52" : { "path" : "METHODS/Constructors", "intro" : "When you use this package with functions, then you do not call the\nconstructor explicitly. In that case, these new() parameters are\nadded to the use String::Print line.
undef"
},
"id404" : {
"name" : "superfluous positional parameters for '$msgid'",
"id" : "id404",
"subroutine" : "id402",
"type" : "error"
},
"id785-id1090" : {
"type" : "ci_method",
"options" : [
[
"id800-id1090",
"id801-id1090"
],
[
"id792-id1090",
"id793-id1090"
],
[
"id788-id1090",
"id789-id1090"
],
[
"id790-id1090",
"id791-id1090"
],
[
"id796-id1090",
"id797-id1090"
],
[
"id798-id1090",
"id799-id1090"
],
[
"id786-id1090",
"id787-id1090"
],
[
"id794-id1090",
"id795-id1090"
]
],
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine()
", "extends" : "id785", "id" : "id785-id1090", "name" : "stackTraceLine", "call" : "$any->stackTraceLine( %options )" }, "id325" : { "type" : "section", "path" : "METHODS/Constructors", "name" : "Constructors", "id" : "id325", "level" : 2, "subroutines" : [ "id326" ] }, "id420-id697" : { "extends" : "id420", "value" : "<required>", "name" : "lexicon", "id" : "id420-id697", "intro" : "Inherited, see Log::Report::Extract::new(lexicon)
", "type" : "default" }, "id1300" : { "level" : 3, "id" : "id1300", "name" : "Addition information", "path" : "DETAILS/Processing the message/Addition information", "type" : "subsection" }, "id763-id1090" : { "extends" : "id763", "name" : "format_reason", "id" : "id763-id1090", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "type" : "option", "params" : "'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE" }, "id562" : { "name" : "no msgid in block $where.", "id" : "id562", "subroutine" : "id557", "type" : "warning" }, "id799-id1174" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "type" : "default", "value" : "8", "extends" : "id799", "id" : "id799-id1174", "name" : "max_params" }, "id789-id818" : { "name" : "filename", "id" : "id789-id818", "value" : "<required>", "extends" : "id789", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
" }, "id784-id944" : { "extends" : "id784", "id" : "id784-id944", "name" : "collectLocation", "call" : "$any->collectLocation", "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::collectLocation()
" }, "id1192" : { "name" : "Logging", "id" : "id1192", "level" : 2, "subroutines" : [ "id781-id1174", "id785-id1174", "id778-id1174", "id784-id1174", "id777-id1174", "id780-id1174", "id783-id1174", "id779-id1174", "id1193" ], "type" : "section", "path" : "METHODS/Logging" }, "id863-id217" : { "name" : "'.'", "id" : "id863-id217", "extends" : "id863", "call" : "overload '.'; concatenation", "type" : "overload", "intro" : "Inherited, see Log::Report::Message::'.'()
" }, "id419-id697" : { "id" : "id419-id697", "name" : "lexicon", "extends" : "id419", "params" : "$directory", "type" : "option", "intro" : "Inherited, see Log::Report::Extract::new(lexicon)
" }, "id166-id375" : { "type" : "default", "intro" : "Inherited, see Log::Report::Minimal::Domain::new(name)
", "value" : "<required>", "extends" : "id166", "id" : "id166-id375", "name" : "name" }, "id1134" : { "subroutines" : [ "id170-id1127", "id172-id1127", "id1138", "id171-id1127", "id1136", "id1137", "id1135", "id1149" ], "level" : 2, "id" : "id1134", "name" : "Attributes", "path" : "METHODS/Attributes", "type" : "section" }, "id122" : { "id" : "id122", "name" : "textdomain", "call" : "textdomain( <[$name],$config>|<$name, 'DELETE'|'EXISTS'>|$domain )", "type" : "function" }, "id170-id1127" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Minimal::Domain::name()
", "extends" : "id170", "name" : "name", "id" : "id170-id1127", "call" : "$obj->name" }, "id909" : { "call" : "$obj->context", "id" : "id909", "name" : "context", "intro" : "Returns an HASH if there is a context defined for this message.
\n", "type" : "i_method" }, "id522" : { "params" : "$translation|\\@translations", "type" : "option", "intro" : "The @translations for the msgid. When msgid_plural is defined, then an\nARRAY must be provided.
\n", "name" : "msgstr", "id" : "id522" }, "id856" : { "chapters" : [ "id857", "id1331", "id858", "id859", "id860", "id864", "id930" ], "version" : "1.45", "inheritance" : { "extended_by" : [ "Dancer2::Plugin::LogReport::Message" ] }, "package" : "Log::Report::Message", "distribution" : "Log-Report", "is_pure_pod" : false, "title" : "a piece of text to be translated", "id" : "id856", "name" : "Log::Report::Message" }, "id1119" : { "type" : "i_method", "intro" : "Returns a level which is understood by syslog(3), based on a translation\ntable. This can be changed with new(to_prio).
\n", "name" : "reasonToPrio", "id" : "id1119", "call" : "$obj->reasonToPrio( $reason )" }, "id911-id217" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Message::tags()
", "extends" : "id911", "name" : "tags", "id" : "id911-id217", "call" : "$obj->tags" }, "id383" : { "type" : "default", "value" : "undef",
"id" : "id383",
"name" : "only_in_directory"
},
"id333" : {
"name" : "translate_to",
"id" : "id333",
"intro" : "Globally set the output language of template processing. Usually, this\nis derived from the logged-in user setting or browser setting.\nSee translateTo().
\n", "params" : "LANGUAGE", "type" : "option" }, "id162" : { "id" : "id162", "name" : "METHODS", "level" : 1, "type" : "chapter", "nest" : [ "id163", "id169", "id179" ], "path" : "METHODS" }, "id757-id944" : { "params" : "$reasons|\\@reasons", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "name" : "accept", "id" : "id757-id944", "extends" : "id757" }, "id792-id1082" : { "extends" : "id792", "id" : "id792-id1082", "name" : "call", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "type" : "option", "params" : "STRING" }, "id745" : { "type" : "i_method", "intro" : "Returns the number of plurals, when not known then '2'.
\n", "id" : "id745", "name" : "nrPlurals", "call" : "$obj->nrPlurals" }, "id56" : { "params" : "HASH|ARRAY", "type" : "option", "intro" : "How to serialize data elements.
\n", "name" : "serializers", "id" : "id56" }, "id243" : { "type" : "i_method", "call" : "$obj->warning", "name" : "warning", "id" : "id243" }, "id316" : { "level" : 1, "name" : "DETAILS", "id" : "id316", "type" : "chapter", "path" : "DETAILS", "nest" : [ "id317", "id319" ] }, "id365" : { "id" : "id365", "name" : "Template::Toolkit in Dancer2", "intro" : "When you use Dancer2, you need to connect the text domain with
\n\n my $domain = (engine 'template')->addTextdomain(\n name => 'isaas',\n function => 'loc',\n );\n\n\n
And in file config.ini:
\n template: \"TTLogReport\"\n engines:\n template:\n TTLogReport:\n\n\n
This \"TTLogReport\" refers to module Dancer2::Template::TTLogReport, which is\npart of distribution Log-Report.
[1.02] The message-id has no references anymore and no translations.
\n", "name" : "useless", "id" : "id568", "call" : "$obj->useless" }, "id506" : { "call" : "iso_locale( [$codepage] )", "id" : "id506", "name" : "iso_locale", "intro" : "Returns the ISO string for the Microsoft codepage locale. Might return\nundef/false. By default, the actual codepage is used.
A good choice is to use Perl's distribution name for the domain name. For instance,\nthe domain name for this module would be set this way:
\n\n use Log::Report 'log-report-optional';\n use Log::Report 'log-report-opt';\n\n" }, "id797-id1082" : { "value" : "
undef",
"extends" : "id797",
"id" : "id797-id1082",
"name" : "max_line",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
" }, "id751" : { "name" : "NAME", "id" : "id751", "type" : "chapter", "path" : "NAME", "intro" : "Log::Report::Dispatcher - manage message dispatching, display or logging
\n", "level" : 1 }, "id527" : { "type" : "default", "value" : "[]", "name" : "comment", "id" : "id527" }, "id1096" : { "type" : "c_method", "options" : [ [ "id757-id1090", "id758-id1090" ], [ "id1110", "id1111" ], [ "id1102", "id1103" ], [ "id1100", "id1101" ], [ "id1112", "id1113" ], [ "id763-id1090", "id1097" ], [ "id1098", "id1099" ], [ "id1108", "id1109" ], [ "id759-id1090", "id760-id1090" ], [ "id1106", "id1107" ], [ "id761-id1090", "id762-id1090" ], [ "id1104", "id1105" ] ], "intro" : "With syslog, people tend not to include the REASON of the message\nin the logs, because that is already used to determine the destination\nof the message.
\n", "diagnostics" : [ "id1114", "id1115" ], "name" : "new", "id" : "id1096", "call" : "$class->new( $type, $name, %options )" }, "id943" : { "level" : 1, "type" : "chapter", "intro" : "This profile will log DBIx::Class queries via Log::Report to a\nselected back-end (via a dispatcher, see Log::Report::Dispatcher)
\n", "path" : "DESCRIPTION", "name" : "DESCRIPTION", "id" : "id943" }, "id127" : { "params" : "BOOLEAN", "type" : "option", "id" : "id127", "name" : "is_fatal" }, "id567" : { "name" : "no plurals expected for '$msgid'.", "id" : "id567", "subroutine" : "id563", "type" : "warning" }, "id674" : { "type" : "section", "path" : "METHODS/Constructors", "id" : "id674", "name" : "Constructors", "level" : 2, "subroutines" : [ "id675" ] }, "id106" : { "path" : "DETAILS/Interpolation: Modifiers/Modifier: CHOP or CHOP($width, [$units])", "intro" : "[1.00] When the string is larger than $width columns (defaults to\n20), then chop it short and add [+42]: the number of character\nchopped off. The $width is the size of the result string.\nThe comma is optional.
\n \"Intro: {text CHOP(10)}\"; # Intro: 12345[+42]\n \"Intro: {text CHOP(19 chars)}\"; # Intro: 1234578[+33 chars]\n \"Intro: {text CHOP(19, chars)}\"; # Intro: 1234578[+33 chars]\n\n\nThe same effect can be reached by setting the defaults
\n\n $sp->setDefaults(CHOP => +{width => 19, units => ' chars'});\n $sp->printi(\"Intro: {text CHOP}\", text => $t); # Intro: 1234578[+33 chars]\n\n\nOther defaults are head ([) and tail (]).
\n $sp->setDefaults(CHOP => +{head => '«', tail => '»'});\n $sp->printi(\"Intro: {text CHOP}\", text => $t); # Intro: 1234578«+12»\n\n",
"type" : "subsection",
"level" : 3,
"name" : "Modifier: CHOP or CHOP($width, [$units])",
"id" : "id106"
},
"id209" : {
"name" : "NAME",
"id" : "id209",
"level" : 1,
"path" : "NAME",
"intro" : "Log::Report::Optional - pick Log::Report or ::Minimal
\n", "type" : "chapter" }, "id639" : { "id" : "id639", "name" : "SYNOPSIS", "type" : "chapter", "intro" : " # using a MO table efficiently\n my $mot = Log::Report::Lexicon::MOTcompact->read('mo/nl.mo')\n or die;\n\n my $header = $mot->msgid('');\n print $mot->msgstr($msgid, 3);\n\n",
"path" : "SYNOPSIS",
"level" : 1
},
"id528" : {
"intro" : "The string is not yet translated, some smart guesses may have been made.\nSee fuzzy().
\n", "type" : "option", "params" : "BOOLEAN", "name" : "fuzzy", "id" : "id528" }, "id1117" : { "call" : "$obj->format( [CODE] )", "id" : "id1117", "name" : "format", "intro" : "Returns the CODE ref which formats the syslog line.
\n", "type" : "i_method" }, "id689" : { "level" : 1, "intro" : "The \"contexts\" concept in (GNU's version of) gettext, has a\nvery restricted purpose: to separate two (accidental) uses of the\nsame message-id, under different circumstances. The same msgid may\ntranslated diffently in one file or the other.
\n\nFor instance, two libraries used in the same application, or two\ncomponentent within a single library both want to used the same\ndefault text (which usually is very short)
\n\n char * t1 = pgettext('interface', 'None');\n char * t2 = pgettext('selections', 'None');\n\n\nSome translation setups use the library name consequently as msgctxt.\nBut, the name \"context\" is pretending much more power than the gettext\nlibraries are capable of: it usually only behaves like a namespace.
\n", "path" : "DETAILS", "type" : "chapter", "name" : "DETAILS", "id" : "id689", "nest" : [ "id690", "id691" ] }, "id798-id1082" : { "params" : "INTEGER", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "extends" : "id798", "id" : "id798-id1082", "name" : "max_params" }, "id168" : { "type" : "error", "subroutine" : "id164", "name" : "translation domain without name.", "id" : "id168" }, "id775-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::needs()
", "type" : "i_method", "call" : "$obj->needs( [$reason] )", "id" : "id775-id1082", "name" : "needs", "extends" : "id775" }, "id1321" : { "id" : "id1321", "name" : "INHERITANCE", "level" : 1, "intro" : "Log::Report::Domain\n is a Log::Report::Minimal::Domain\n\n Log::Report::Domain is extended by\n Log::Report::Template::Textdomain\n\n", "path" : "INHERITANCE", "type" : "chapter" }, "id849" : { "name" : "success", "id" : "id849", "call" : "$obj->success", "type" : "i_method", "intro" : "
Returns true if the block exited normally.
undef"
},
"id796" : {
"id" : "id796",
"name" : "max_line",
"params" : "INTEGER",
"type" : "option"
},
"id789-id1082" : {
"id" : "id789-id1082",
"name" : "filename",
"extends" : "id789",
"value" : "<required>",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
" }, "id698" : { "name" : "NAME", "id" : "id698", "level" : 1, "type" : "chapter", "path" : "NAME", "intro" : "Log::Report::Extract::PerlPPI - Collect translatable strings from Perl using PPI
\n" }, "id675" : { "options" : [ [ "id676", "id677" ] ], "type" : "c_method", "id" : "id675", "name" : "new", "call" : "$class->new( %options )" }, "id771-id958" : { "call" : "$obj->name", "id" : "id771-id958", "name" : "name", "extends" : "id771", "intro" : "Inherited, see Log::Report::Dispatcher::name()
", "type" : "i_method" }, "id1297" : { "level" : 1, "name" : "DETAILS", "id" : "id1297", "type" : "chapter", "path" : "DETAILS", "nest" : [ "id1298", "id1299" ] }, "id153" : { "type" : "function", "call" : "N__n( $single_msgid, $plural_msgid )", "id" : "id153", "name" : "N__n" }, "id774-id1082" : { "call" : "$obj->isDisabled", "name" : "isDisabled", "id" : "id774-id1082", "extends" : "id774", "intro" : "Inherited, see Log::Report::Dispatcher::isDisabled()
", "type" : "i_method" }, "id697" : { "name" : "Log::Report::Extract::PerlPPI", "id" : "id697", "is_pure_pod" : false, "title" : "Collect translatable strings from Perl using PPI", "distribution" : "Log-Report-Lexicon", "inheritance" : { "extends" : [ "Log::Report::Extract" ] }, "package" : "Log::Report::Extract::PerlPPI", "version" : "1.16", "chapters" : [ "id698", "id1342", "id699", "id700", "id704" ] }, "id750" : { "chapters" : [ "id751", "id1333", "id752", "id753", "id754", "id802" ], "version" : "1.45", "inheritance" : { "extended_by" : [ "Log::Report::Dispatcher::Callback", "Log::Report::Dispatcher::File", "Log::Report::Dispatcher::Log4perl", "Log::Report::Dispatcher::LogDispatch", "Log::Report::Dispatcher::Perl", "Log::Report::Dispatcher::Syslog", "Log::Report::Dispatcher::Try" ] }, "package" : "Log::Report::Dispatcher", "distribution" : "Log-Report", "is_pure_pod" : false, "title" : "manage message dispatching, display or logging", "id" : "id750", "name" : "Log::Report::Dispatcher" }, "id553" : { "type" : "example", "intro" : " # getters\n if($po->format('c')) ...\n unless($po->format('perl-brace')) ...\n if(defined $po->format('java')) ...\n\n # setters\n $po->format(java => 1); # results in 'java-format'\n $po->format(java => 0); # results in 'no-java-format'\n $po->format(java => undef); # results in ''\n\n",
"name" : "use of format()\n",
"id" : "id553"
},
"id412" : {
"package" : "Log::Report::Extract",
"inheritance" : {
"extended_by" : [
"Log::Report::Extract::PerlPPI",
"Log::Report::Template::Extract"
]
},
"distribution" : "Log-Report-Lexicon",
"title" : "Collect translatable strings",
"is_pure_pod" : false,
"id" : "id412",
"name" : "Log::Report::Extract",
"chapters" : [
"id413",
"id1327",
"id414",
"id415",
"id416"
],
"version" : "1.16"
},
"id792-id818" : {
"extends" : "id792",
"id" : "id792-id818",
"name" : "call",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "type" : "option", "params" : "STRING" }, "id786-id958" : { "extends" : "id786", "id" : "id786-id958", "name" : "package", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "params" : "CLASS", "type" : "option" }, "id803" : { "level" : 2, "path" : "DETAILS/Available back-ends", "intro" : "When a dispatcher is created (via new() or Log::Report::dispatcher()),\nyou must specify the TYPE of the dispatcher. This can either be a class\nname, which extends a Log::Report::Dispatcher, or a pre-defined\nabbreviation of a class name.
\n\nImplemented are:
\n\nprint(), warn() and die() to ventilate\nreports. This is the default dispatcher.\n\n\n\nLog::Dispatch::*Log::Log4perlInherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "extends" : "id797", "value" : "undef",
"id" : "id797-id818",
"name" : "max_line"
},
"id1299" : {
"level" : 2,
"id" : "id1299",
"name" : "Processing the message",
"type" : "section",
"path" : "DETAILS/Processing the message",
"nest" : [
"id1300",
"id1301"
]
},
"id417" : {
"type" : "section",
"path" : "METHODS/Constructors",
"id" : "id417",
"name" : "Constructors",
"level" : 2,
"subroutines" : [
"id418"
]
},
"id929-id217" : {
"type" : "c_method",
"intro" : "Inherited, see Log::Report::Message::thaw()
", "extends" : "id929", "id" : "id929-id217", "name" : "thaw", "call" : "$class->thaw( \\%data, %options )" }, "id787-id1174" : { "value" : "<required>", "extends" : "id787", "name" : "package", "id" : "id787-id1174", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
" }, "id744" : { "id" : "id744", "name" : "invalid plural-form algorithm '$alg'.", "subroutine" : "id743", "type" : "error" }, "id757-id1090" : { "extends" : "id757", "id" : "id757-id1090", "name" : "accept", "params" : "$reasons|\\@reasons", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
" }, "id910-id217" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Message::msgctxt()
", "extends" : "id910", "name" : "msgctxt", "id" : "id910-id217", "call" : "$obj->msgctxt" }, "id1109" : { "type" : "default", "name" : "include_domain", "id" : "id1109", "value" : "false"
},
"id692" : {
"id" : "id692",
"name" : "Specifying the context per Message",
"type" : "subsection",
"intro" : "You need to specify the context at each message which is influenced by\nthe context. This can be a comma separated list of words, an ARRAY, or\na HASH:
\n\n _context => 'gender=male'\n _context => 'gender=male,agegroup=adult,married=yes'\n _context => [ 'gender=male', 'agegroup=adult', 'married=yes']\n _context => [ qw/gender=male agegroup=adult married=yes/ ]\n\n my @context = (qw/gender=male agegroup=adult married=yes/);\n _context => \\@context;\n\n\n
Probably the
\n my %context = (gender => 'male', agegroup => 'adult', married => 'yes');\n my %context = qw/gender male agegroup adult married yes/;\n _context => \\%context;\n\n\n
Standard gettext only allows a single keyword (=string)\nLog::Report permits you to set-up a context for a whole\ntext-domain, which means that multiple context rules may be active at\nany moment.
Inherited, see Log::Report::Extract::showStats()
" }, "id364" : { "level" : 3, "path" : "DETAILS/Textdomains/Integration with Template::Toolkit", "intro" : "Instead of Template, from Template::Toolkit, you use its extension\nLog::Report::Template.
\n\n # during initiation of the webserver, once in your script (before fork)\n my $lexicons = 'some-directory-for-translation-tables';\n my $pots = Log::Report::Translator::POT->new(lexicons => $lexicons);\n\n my $templater = Log::Report::Template->new(...);\n my $domain = $templater->addTextdomain(\n name => $domainname,\n function => 'loc',\n );\n $domain->configure(translator => $pots);\n\n # part of the processing per page\n $vars{translate_to} = 'nl_NL.utf8';\n $templater->process($template, \\%vars, \\$output);\n\n\nWhen you use the same domain for both templates as source code, then be\naware that there is only one place where you can configure the domain.\nThis may be in the code. When you use a separate domain for the templates,\nthen you configure as shown above.
\n", "type" : "subsection", "name" : "Integration with Template::Toolkit", "id" : "id364" }, "id171-id1127" : { "extends" : "id171", "name" : "isConfigured", "id" : "id171-id1127", "call" : "$obj->isConfigured", "type" : "i_method", "intro" : "Inherited, see Log::Report::Minimal::Domain::isConfigured()
" }, "id884-id217" : { "type" : "default", "intro" : "Inherited, see Log::Report::Message::new(_tag)
", "value" : "[]", "extends" : "id884", "name" : "_tag", "id" : "id884-id217" }, "id775-id818" : { "intro" : "Inherited, see Log::Report::Dispatcher::needs()
", "type" : "i_method", "call" : "$obj->needs( [$reason] )", "extends" : "id775", "name" : "needs", "id" : "id775-id818" }, "id773-id1228" : { "extends" : "id773", "id" : "id773-id1228", "name" : "mode", "call" : "$obj->mode", "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::mode()
" }, "id788-id1174" : { "id" : "id788-id1174", "name" : "filename", "extends" : "id788", "params" : "STRING", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
" }, "id798-id818" : { "extends" : "id798", "id" : "id798-id818", "name" : "max_params", "type" : "option", "params" : "INTEGER", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
" }, "id418" : { "options" : [ [ "id421", "id422" ], [ "id419", "id420" ] ], "type" : "c_method", "call" : "$class->new( %options )", "name" : "new", "id" : "id418", "diagnostics" : [ "id423", "id424" ] }, "id1093" : { "name" : "DESCRIPTION", "id" : "id1093", "level" : 1, "type" : "chapter", "intro" : "This dispatchers produces output to syslog, based on the Sys::Syslog\nmodule (which will NOT be automatically installed for you, because some\nsystems have a problem with this dependency).
\n\nThe REASON for a message often uses names which are quite similar to\nthe log-levels used by syslog. However: they have a different purpose.\nThe REASON is used by the programmer to indicate the cause of the message:\nwhether it was able to handle a certain situation. The syslog levels\nare there for the user's of the program (with syslog usually the\nsystem administrators). It is not unusual to see a \"normal\" error\nor mistake as a very serious situation in a production environment. So,\nyou may wish to translate any message above reason MISTAKE into a LOG_CRIT.
\n\nThe default translation table is list below. You can change the mapping\nusing new(to_prio). See example in SYNOPSIS.
\n\n TRACE => LOG_DEBUG ERROR => LOG_ERR\n ASSERT => LOG_DEBUG FAULT => LOG_ERR\n INFO => LOG_INFO ALERT => LOG_ALERT\n NOTICE => LOG_NOTICE FAILURE => LOG_EMERG\n WARNING => LOG_WARNING PANIC => LOG_CRIT\n MISTAKE => LOG_WARNING\n\n", "path" : "DESCRIPTION" }, "id405" : { "subroutine" : "id402", "id" : "id405", "name" : "message does not contain counting alternatives in '$msgid'", "type" : "error" }, "id784-id1090" : { "intro" : "
Inherited, see Log::Report::Dispatcher::collectLocation()
", "type" : "ci_method", "call" : "$any->collectLocation", "id" : "id784-id1090", "name" : "collectLocation", "extends" : "id784" }, "id324" : { "level" : 1, "id" : "id324", "name" : "METHODS", "type" : "chapter", "path" : "METHODS", "nest" : [ "id325", "id338", "id341", "id357", "id358", "id359" ] }, "id1310" : { "path" : "DETAILS/Messages with plural forms/Interpolation with String::Print", "type" : "subsection", "id" : "id1310", "name" : "Interpolation with String::Print", "level" : 3 }, "id763-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "params" : "'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE", "type" : "option", "id" : "id763-id944", "name" : "format_reason", "extends" : "id763" }, "id421-id697" : { "extends" : "id421", "name" : "charset", "id" : "id421-id697", "params" : "$charset", "type" : "option", "intro" : "Inherited, see Log::Report::Extract::new(charset)
" }, "id879-id217" : { "type" : "option", "params" : "$text|$message", "intro" : "Inherited, see Log::Report::Message::new(_prepend)
", "extends" : "id879", "id" : "id879-id217", "name" : "_prepend" }, "id785-id944" : { "id" : "id785-id944", "name" : "stackTraceLine", "extends" : "id785", "call" : "$any->stackTraceLine( %options )", "options" : [ [ "id800-id944", "id801-id944" ], [ "id792-id944", "id793-id944" ], [ "id788-id944", "id789-id944" ], [ "id790-id944", "id791-id944" ], [ "id796-id944", "id797-id944" ], [ "id798-id944", "id799-id944" ], [ "id786-id944", "id787-id944" ], [ "id794-id944", "id795-id944" ] ], "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine()
" }, "id891" : { "intro" : "Specify the $dispatcher as destination explicitly. Short\nfor report {to => NAME}, ... See to()
$sp->setDefaults(EL => {width => 30}, CHOP => {width => 10});\n\n my %defs = (EL => {width => 30}, CHOP => {width => 10});\n $sp->setDefaults(\\%defs);\n\n",
"name" : "setting defaults\n",
"id" : "id69"
},
"id1212" : {
"type" : "i_method",
"id" : "id1212",
"name" : "reason",
"call" : "$obj->reason( [$reason] )"
},
"id779-id1090" : {
"call" : "$obj->translate( \\%options, $reason, $message )",
"id" : "id779-id1090",
"name" : "translate",
"extends" : "id779",
"intro" : "Inherited, see Log::Report::Dispatcher::translate()
", "type" : "i_method" }, "id758-id1090" : { "id" : "id758-id1090", "name" : "accept", "extends" : "id758", "value" : "depend on mode",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
" }, "id758-id818" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "type" : "default", "id" : "id758-id818", "name" : "accept", "extends" : "id758", "value" : "depend on mode"
},
"id779-id818" : {
"type" : "i_method",
"intro" : "Inherited, see Log::Report::Dispatcher::translate()
", "extends" : "id779", "name" : "translate", "id" : "id779-id818", "call" : "$obj->translate( \\%options, $reason, $message )" }, "id311" : { "subroutine" : "id305", "name" : "need pattern to scan for, either via new() or process().", "id" : "id311", "type" : "error" }, "id774-id944" : { "extends" : "id774", "name" : "isDisabled", "id" : "id774-id944", "call" : "$obj->isDisabled", "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::isDisabled()
" }, "id1053" : { "value" : "Log::Report::Message",
"name" : "message_class",
"id" : "id1053",
"type" : "default"
},
"id764-id1228" : {
"intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "type" : "default", "extends" : "id764", "value" : "'LOWERCASE'", "name" : "format_reason", "id" : "id764-id1228" }, "id1183" : { "params" : "$level", "type" : "option", "intro" : "Restrict the messages which are passed through based on the $level,\nso after the reason got translated into a Log::Dispatch compatible\nLEVEL. The default will use Log::Report restrictions only.
\n", "name" : "min_level", "id" : "id1183" }, "id1339" : { "id" : "id1339", "name" : "INHERITANCE", "level" : 1, "path" : "INHERITANCE", "intro" : "Log::Report::Dispatcher::File\n is a Log::Report::Dispatcher\n\n", "type" : "chapter" }, "id898-id217" : { "intro" : "
Inherited, see Log::Report::Message::new(_context)
", "type" : "default", "name" : "_context", "id" : "id898-id217", "value" : "undef",
"extends" : "id898"
},
"id1142" : {
"type" : "default",
"name" : "native_language",
"id" : "id1142",
"value" : "'en_US'"
},
"id875-id217" : {
"type" : "option",
"params" : "$msgid",
"intro" : "Inherited, see Log::Report::Message::new(_msgid)
", "extends" : "id875", "id" : "id875-id217", "name" : "_msgid" }, "id794-id1174" : { "type" : "option", "params" : "ARRAY", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "id" : "id794-id1174", "name" : "params", "extends" : "id794" }, "id784-id818" : { "call" : "$any->collectLocation", "extends" : "id784", "id" : "id784-id818", "name" : "collectLocation", "intro" : "Inherited, see Log::Report::Dispatcher::collectLocation()
", "type" : "ci_method" }, "id789-id944" : { "value" : "<required>", "extends" : "id789", "id" : "id789-id944", "name" : "filename", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
" }, "id798-id1090" : { "extends" : "id798", "id" : "id798-id1090", "name" : "max_params", "params" : "INTEGER", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
" }, "id430-id289" : { "call" : "$obj->addPot( $domain, $pot, %options )", "name" : "addPot", "id" : "id430-id289", "extends" : "id430", "intro" : "Inherited, see Log::Report::Extract::addPot()
", "type" : "i_method" }, "id775-id1090" : { "id" : "id775-id1090", "name" : "needs", "extends" : "id775", "call" : "$obj->needs( [$reason] )", "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::needs()
" }, "id1305" : { "name" : "Processing", "id" : "id1305", "level" : 2, "subroutines" : [ "id927-id217", "id922-id217", "id920-id217", "id924-id217", "id919-id217", "id925-id217", "id929-id217", "id921-id217" ], "type" : "section", "path" : "METHODS/Processing" }, "id65" : { "type" : "section", "path" : "METHODS/Attributes", "id" : "id65", "name" : "Attributes", "level" : 2, "subroutines" : [ "id68", "id70", "id67", "id66" ] }, "id851" : { "params" : "$tag|REGEX", "type" : "option", "intro" : "[1.44] Only return the exception if it was fatal, and in the same time in\nthe specified $tag (as string) or matches the REGEX.\nSee Log::Report::Message::taggedWith()
\n", "name" : "tag", "id" : "id851" }, "id1169" : { "id" : "id1169", "name" : "new", "call" : "$class->new( %options )", "type" : "c_method" }, "id1143-id375" : { "intro" : "Inherited, see Log::Report::Domain::configure(context_rules)
", "params" : "\\%rules|OBJECT", "type" : "option", "name" : "context_rules", "id" : "id1143-id375", "extends" : "id1143" }, "id916-id217" : { "id" : "id916-id217", "name" : "valueOf", "extends" : "id916", "call" : "$obj->valueOf( $parameter )", "type" : "i_method", "intro" : "Inherited, see Log::Report::Message::valueOf()
" }, "id1173" : { "name" : "load", "id" : "id1173", "call" : "$obj->load( $domain, $locale )", "type" : "i_method", "intro" : "Load the translation information in the text $domain for the indicated $locale.\nMultiple calls to load() should not cost significant performance: the\ndata must be cached.
\n" }, "id904" : { "call" : "$obj->prepend", "id" : "id904", "name" : "prepend", "intro" : "Returns the string which is prepended to this one. Usually undef.
Inherited, see Log::Report::Dispatcher::new(accept)
", "params" : "$reasons|\\@reasons", "type" : "option", "id" : "id757-id818", "name" : "accept", "extends" : "id757" }, "id1259" : { "name" : "Filters", "id" : "id1259", "level" : 3, "type" : "subsection", "path" : "DETAILS/Processing the message/Filters" }, "id925-id217" : { "extends" : "id925", "id" : "id925-id217", "name" : "concat", "call" : "$obj->concat( $text|$message, [$prepend] )", "type" : "i_method", "intro" : "Inherited, see Log::Report::Message::concat()
" }, "id373" : { "id" : "id373", "name" : "Keeping translations up to date", "level" : 3, "type" : "subsection", "path" : "DETAILS/Extracting PO-files/Keeping translations up to date", "intro" : "You have to call extract() when msgids have changed or added,\nto have the PO-tables updated. The language specific tables will\nget updated automatically... look for msgids which are 'fuzzy'\n(need update)
\n\nYou may also use the external program xgettext-perl, which is\nshipped with the Log::Report::Lexicon distribution.
undef",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "type" : "default" }, "id180-id1127" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Minimal::Domain::interpolate()
", "extends" : "id180", "id" : "id180-id1127", "name" : "interpolate", "call" : "$obj->interpolate( $msgid, [$args] )" }, "id1314" : { "id" : "id1314", "name" : "INHERITANCE", "level" : 1, "path" : "INHERITANCE", "intro" : "Log::Report\n is an Exporter\n\n", "type" : "chapter" }, "id897-id217" : { "id" : "id897-id217", "name" : "_context", "extends" : "id897", "intro" : "
Inherited, see Log::Report::Message::new(_context)
", "type" : "option", "params" : "$keyword|\\@keywords" }, "id652" : { "subroutine" : "id643", "name" : "cannot read originals from $fn, need $size at $loc: $!", "id" : "id652", "type" : "fault" }, "id892-id217" : { "extends" : "id892", "value" : "undef",
"id" : "id892-id217",
"name" : "_to",
"intro" : "Inherited, see Log::Report::Message::new(_to)
", "type" : "default" }, "id1167" : { "path" : "METHODS", "nest" : [ "id1168", "id1170", "id1171" ], "type" : "chapter", "level" : 1, "id" : "id1167", "name" : "METHODS" }, "id657" : { "subroutine" : "id643", "name" : "cannot seek to $loc in $fn for transl strings: $!", "id" : "id657", "type" : "fault" }, "id1156-id375" : { "call" : "$obj->updateContext( STRING|HASH|ARRAY|PAIRS )", "extends" : "id1156", "id" : "id1156-id375", "name" : "updateContext", "intro" : "Inherited, see Log::Report::Domain::updateContext()
", "type" : "i_method" }, "id593" : { "id" : "id593", "name" : "SYNOPSIS", "path" : "SYNOPSIS", "intro" : " my $index = Log::Report::Lexicon::Index->new($directory);\n my $fn = $index->find('my-domain', 'nl_NL.utf-8');\n\n",
"type" : "chapter",
"level" : 1
},
"id101" : {
"id" : "id101",
"name" : "Modifier: HTML",
"level" : 3,
"path" : "DETAILS/Interpolation: Modifiers/Modifier: HTML",
"intro" : "[0.95] interpolate the parameter with HTML entity encoding.
\n", "type" : "subsection" }, "id792-id1090" : { "type" : "option", "params" : "STRING", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "name" : "call", "id" : "id792-id1090", "extends" : "id792" }, "id790" : { "type" : "option", "params" : "INTEGER", "id" : "id790", "name" : "linenr" }, "id443" : { "type" : "chapter", "path" : "SYNOPSIS", "intro" : " # this is usually not for end-users, See ::Extract::PerlPPI\n # using a PO table\n\n my $pot = Log::Report::Lexicon::POT->read('po/nl.po', charset => 'utf-8')\n or die;\n\n my $po = $pot->msgid('msgid');\n my $po = $pot->msgid($msgid, $msgctxt);\n print $pot->nrPlurals;\n print $pot->msgstr('msgid', 3);\n print $pot->msgstr($msgid, 3, $msgctxt);\n $pot->write; # update the file\n\n # fill the table, by calling the next a lot\n my $po = Log::Report::Lexicon::PO->new(...);\n $pot->add($po);\n\n # creating a PO table\n $pot->write('po/nl.po')\n or die;\n\n",
"level" : 1,
"name" : "SYNOPSIS",
"id" : "id443"
},
"id1337" : {
"id" : "id1337",
"name" : "INHERITANCE",
"type" : "chapter",
"intro" : "Dancer::Logger::LogReport\n is a Dancer::Logger::Abstract\n\n Dancer::Logger::LogReport\n is an Exporter\n\n", "path" : "INHERITANCE", "level" : 1 }, "id1123" : { "intro" : "
[Included since Log::Report v1.00]\nMojo likes to log messages directly into a file, by default. Log::Report\nconstructs a Log::Report::Exception object first.
\n\nBe aware that this extension does catch the messages to be logged,\nbut that the dispatching of the error follows a different route now.\nFor instance, you cannot use $ENV{MOJO_LOG_LEVEL} to control the output\nlevel, but you need to use Log::Report::dispatcher() action mode.
Mojo defines five \"levels\" of messages, which map onto Log::Report's\nreasons this way:
\n\n debug TRACE\n info INFO\n warn WARNING\n error ERROR\n fatal ALERT\n\n", "path" : "DESCRIPTION", "type" : "chapter", "level" : 1, "name" : "DESCRIPTION", "id" : "id1123" }, "id1046" : { "name" : "syntax", "id" : "id1046", "params" : "'REPORT'|'SHORT'|'LONG'", "type" : "option", "intro" : "
The SHORT syntax will add the report abbreviations (like function\nerror()) to your name-space. Otherwise, each message must be produced\nwith report(). LONG is an alternative to REPORT: both do not\npollute your namespace with the useful abbrev functions.
Re-cast the messages in all collect exceptions into the defined\ndispatchers, which were disabled during the try block. The %options\nwill end-up as HASH of %options to Log::Report::report(); see\nLog::Report::Exception::throw() which does the job.
\n" }, "id785-id1082" : { "call" : "$any->stackTraceLine( %options )", "name" : "stackTraceLine", "id" : "id785-id1082", "extends" : "id785", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine()
", "options" : [ [ "id800-id1082", "id801-id1082" ], [ "id792-id1082", "id793-id1082" ], [ "id788-id1082", "id789-id1082" ], [ "id790-id1082", "id791-id1082" ], [ "id796-id1082", "id797-id1082" ], [ "id798-id1082", "id799-id1082" ], [ "id786-id1082", "id787-id1082" ], [ "id794-id1082", "id795-id1082" ] ], "type" : "ci_method" }, "id679" : { "name" : "rules", "id" : "id679", "call" : "$obj->rules", "type" : "i_method", "intro" : "Returns a HASH to the simplified context maps.
\n" }, "id756" : { "intro" : "Create a dispatcher. The $type of back-end to start is required, and listed\nin the DESCRIPTION part of this manual-page. For various external\nback-ends, special wrappers are created.
\n\nThe $name must be uniquely identifying this dispatcher. When a second\ndispatcher is created (via Log::Report::dispatcher()) with the name\nof an existing dispatcher, the existing one will get replaced.
\n\nAll %options which are not consumed by this base constructor are passed\nto the wrapped back-end. Some of them will check whether all %options\nare understood, other ignore unknown %options.
\n", "type" : "c_method", "options" : [ [ "id757", "id758" ], [ "id765", "id766" ], [ "id763", "id764" ], [ "id759", "id760" ], [ "id761", "id762" ] ], "call" : "$class->new( $type, $name, %options )", "diagnostics" : [ "id767", "id768", "id769" ], "name" : "new", "id" : "id756" }, "id658" : { "subroutine" : "id643", "name" : "cannot read translations from $fn, need $size at $loc: $!", "id" : "id658", "type" : "fault" }, "id204" : { "diagnostics" : [ "id205" ], "id" : "id204", "name" : "parse_locale", "call" : "parse_locale( STRING )", "type" : "function", "intro" : "Decompose a locale string.
\n\nFor simplicity of the caller's code, the capatization of the returned\nfields is standardized to the preferred, although the match is case-\ninsensitive as required by the RFC. The territory in returned in capitals\n(ISO3166), the language is lower-case (ISO639), the script as upper-case\nfirst, the character-set as lower-case, and the modifier and variant unchanged.
\n\nIn LIST context, four elements are returned: language, territory,\ncharacter-set (codeset), and modifier. Those four are important for the\nusual unix translationg infrastructure. Only the \"country\" is obligatory,\nthe others can be undef. It may also return C and POSIX.
In SCALAR context, a HASH is returned which can contain more information:\nlanguage, script, territory, variant, codeset, and modifiers. The\nvariant (RFC3066 is probably never used)
\n" }, "id1257" : { "level" : 2, "name" : "Processing the message", "id" : "id1257", "type" : "section", "path" : "DETAILS/Processing the message", "nest" : [ "id1258", "id1259" ] }, "id763-id1082" : { "name" : "format_reason", "id" : "id763-id1082", "extends" : "id763", "params" : "'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
" }, "id193" : { "name" : "is_fatal", "id" : "id193", "call" : "is_fatal( $reason )", "type" : "function", "intro" : "Returns true if the $reason is severe enough to cause an exception\n(or program termination).
# Only usable on Windows\n print codepage_to_iso(0x0413); # nl-NL\n print iso_to_codepage('nl_NL'); # 1043\n printf \"%x\", iso_to_codepage('nl_NL'); # 413\n\n my $iso = iso_locale(ms_codepage_id());\n my $iso = iso_locale; # same\n\n print charset_encoding; # cp1252\n print ms_codepage_id; # 1043\n print ms_install_codepage_id; # 1043\n print ms_locale; # Dutch (Netherlands)\n\n",
"path" : "SYNOPSIS"
},
"id634" : {
"diagnostics" : [
"id635",
"id636"
],
"id" : "id634",
"name" : "translate",
"call" : "$obj->translate( $msg, $lang, $context )",
"type" : "i_method"
},
"id780-id958" : {
"type" : "ci_method",
"intro" : "Inherited, see Log::Report::Dispatcher::collectStack()
", "id" : "id780-id958", "name" : "collectStack", "extends" : "id780", "call" : "$any->collectStack( [$maxdepth] )" }, "id1238" : { "name" : "replace", "id" : "id1238", "value" : "false",
"type" : "default"
},
"id684" : {
"id" : "id684",
"name" : "unknown alternative `$alt' for tag `$tag' in context of `$msgid'",
"subroutine" : "id681",
"type" : "warning"
},
"id862" : {
"type" : "overload",
"intro" : "When the object is called as function, a new object is created with\nthe data from the original one but updated with the new parameters.\nImplemented in clone().
MojoX::Log::Report - divert log messages into Log::Report
\n", "level" : 1, "name" : "NAME", "id" : "id1121" }, "id278" : { "level" : 2, "type" : "section", "path" : "DETAILS/Advanced Customization", "intro" : "Module manual Dancer2::Template::TemplateToolkit describes how to extend the Template\nby wrapping the _build_engine method. The instantiation trick is insufficient\nfor a bit more complex modules, like our Log::Report translation feature. You may\nbe able to extend this module with your own templater, however.
\n # in config.yml\n engines:\n template:\n TTLogReport:\n start_tag: '<%'\n end_tag: '%>'\n templater: Log::Report::Template # default\n\n", "id" : "id278", "name" : "Advanced Customization" }, "id156" : { "type" : "i_method", "intro" : "\n", "diagnostics" : [ "id157" ], "name" : "import", "id" : "id156", "call" : "$obj->import( [$domain], %options )" }, "id972" : { "value" : "'ALL'", "name" : "accept", "id" : "id972", "type" : "default" }, "id259" : { "type" : "subsection", "path" : "DETAILS/In use/Exceptions", "intro" : "
Log::Report is a combination of a logger and an exception system. Messages\nto be logged are thrown to all listening dispatchers to be handled.
\n\nThis module will also catch any unexpected exceptions:
\n\n # This will be caught, the error will be logged (full stacktrace to STDOUT,\n # short message to the session messages), and the user will be forwarded\n # (default to /). This would also be sent to syslog with the appropriate\n # dispatcher.\n get 'route' => sub {\n my $foo = 1;\n my $bar = $foo->{x}; # whoops\n }\n\n\nFor a production application (show_errors: 1), the message saved in the\nsession will be the generic text \"An unexpected error has occurred\". This\ncan be customised in the configuration file, and will be translated.
String::Print - printf alternative
\n", "path" : "NAME", "type" : "chapter", "name" : "NAME", "id" : "id48" }, "id440" : { "type" : "error", "subroutine" : "id439", "id" : "id440", "name" : "no context tags allowed in plural `$msgid'" }, "id590" : { "id" : "id590", "name" : "string '$text' not between quotes at $location", "subroutine" : "id589", "type" : "warning" }, "id621" : { "type" : "chapter", "path" : "DESCRIPTION", "intro" : "Translate a message by directly accessing POT files. The files will load\nlazily (unless forced). This module accesses the PO's in a compact way,\nusing Log::Report::Lexicon::POTcompact, which is much more efficient\nthan Log::Report::Lexicon::PO.
\n", "level" : 1, "name" : "DESCRIPTION", "id" : "id621" }, "id82" : { "type" : "default", "value" : "undef",
"name" : "_prepend",
"id" : "id82"
},
"id731-id569" : {
"call" : "$class->new( %options )",
"extends" : "id731",
"id" : "id731-id569",
"name" : "new",
"intro" : "Inherited, see Log::Report::Lexicon::Table::new()
", "type" : "c_method" }, "id86" : { "name" : "printp", "id" : "id86", "call" : "printp( [$fh], $format, @positionals, %options )", "type" : "function", "intro" : "Calls sprintp() to fill the @positionals in $format, and\nthen sends it to the $fh (by default the selected file handle).
\n" }, "id661" : { "subroutine" : "id643", "id" : "id661", "name" : "unsupported charset $charset in $fn.", "type" : "error" }, "id783-id958" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::skipStack()
", "id" : "id783-id958", "name" : "skipStack", "extends" : "id783", "call" : "$obj->skipStack" }, "id1208" : { "params" : "Log::Report::Message", "type" : "option", "id" : "id1208", "name" : "message" }, "id277" : { "id" : "id277", "name" : "Dancer2 Configuration", "type" : "section", "path" : "DETAILS/Dancer2 Configuration", "intro" : "Most configuration variables are available when creating a new instance\nof a manual Template::Toolkit object can be declared in your config.yml file.\nFor example:
\n\n template: TTLogReport\n\n engines:\n template:\n TTLogReport:\n start_tag: '<%'\n end_tag: '%>'\n\n\n
(Note: start_tag and end_tag are regexes. If you want to use PHP-style\ntags, you will need to list them as <\\? >> and C<< \\?>.)\nSee manual Template::Manual::Config for the configuration variables.
In addition to the standard configuration variables, the option show_private_variables\nis also available. Template::Toolkit, by default, does not render private variables\n(the ones starting with an underscore). If in your project it gets easier to disable\nthis feature than changing variable names, add this option to your configuration.
\n show_private_variables: true\n\n\n
Warning: Given the way Template::Toolkit implements this option, different Dancer2\napplications running within the same interpreter will share this option!
\n", "level" : 2 }, "id701" : { "id" : "id701", "name" : "The extraction process", "nest" : [ "id702", "id703" ], "level" : 2, "intro" : "All pm-files need to be processed in one go: no incremental processing!
\n\nThe Perl source is parsed using PPI, which does understand Perl syntax\nquite well, but does not support all features.
\n\nAutomatically, the textdomain of the translations is discovered, as\nfirst parameter of use Log::Report. You may switch textdomain inside\none pm-file.
When all files have been processed, during the write(), all existing\npo-files for all discovered textdomains will get updated. Not only the\n$lexicon/$domain.po template, but also all $lexicon/$domain/$lang.po\nwill be replaced. When a msgid has disappeared, existing translations\nwill get disabled, not removed. New msgids will be added and flagged\n\"fuzzy\".
As shown in the examples above, you can specify a format. This can,\nfor instance, help you with rounding or columns:
\n\n printp \"π = {pi%.3f}\", pi => 3.1415;\n printp \"weight is {kilogram%d}\", kilogram => 127*OUNCE_PER_KILO;\n printp \"{filename%-20.20s}\\n\", filename => $fn;\n\n",
"level" : 3
},
"id760-id1082" : {
"name" : "locale",
"id" : "id760-id1082",
"value" : "<system locale>",
"extends" : "id760",
"intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "type" : "default" }, "id190" : { "type" : "error", "id" : "id190", "name" : "reason '$begin' more serious than '$end' in '$reasons'.", "subroutine" : "id187" }, "id482" : { "intro" : "The character-set to be used for reading and writing. You do not need\nto be aware of Perl's internal encoding for the characters.
\n", "type" : "i_method", "call" : "$obj->charset", "id" : "id482", "name" : "charset" }, "id1198" : { "subroutines" : [ "id1199", "id1200" ], "level" : 1, "name" : "OVERLOADED", "id" : "id1198", "path" : "OVERLOADED", "type" : "chapter" }, "id556" : { "subroutines" : [ "id568", "id557", "id563" ], "level" : 2, "id" : "id556", "name" : "Parsing", "path" : "METHODS/Parsing", "type" : "section" }, "id822" : { "subroutines" : [ "id824", "id823" ], "level" : 1, "id" : "id822", "name" : "OVERLOADED", "path" : "OVERLOADED", "type" : "chapter" }, "id432" : { "intro" : "Update the domains mentioned in the $filename. All text-domains defined\nin the file will get updated automatically, but should not written before\nall files are processed.
\n\nReturned is the number of messages found in this particular file.
\n", "type" : "i_method", "call" : "$obj->process( $filename, %options )", "name" : "process", "id" : "id432" }, "id765-id958" : { "extends" : "id765", "id" : "id765-id958", "name" : "charset", "intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
", "params" : "CHARSET", "type" : "option" }, "id1335" : { "level" : 1, "path" : "INHERITANCE", "intro" : "Log::Report::Lexicon::MOTcompact\n is a Log::Report::Lexicon::Table\n\n", "type" : "chapter", "id" : "id1335", "name" : "INHERITANCE" }, "id433-id289" : { "options" : [ [ "id434-id289", "id435-id289" ] ], "type" : "i_method", "intro" : "
Inherited, see Log::Report::Extract::cleanup()
", "name" : "cleanup", "id" : "id433-id289", "extends" : "id433", "call" : "$obj->cleanup( %options )" }, "id437" : { "intro" : "Update the information of the files related to $domain, by default all\nprocessed DOMAINS.
\n\nAll information known about the written $domain is removed from the cache.\nThe %options are passed to the write() of the specific lexicon\nmanager.
Lookup the Log::Report::Lexicon::PO with the STRING. If you\nwant to add a new translation, use add(). Returns undef\nwhen not defined.
Inherited, see Log::Report::Domain::configure(native_language)
", "type" : "option", "params" : "CODESET" }, "id761-id818" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
", "type" : "option", "params" : "'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3", "extends" : "id761", "name" : "mode", "id" : "id761-id818" }, "id1165" : { "level" : 1, "path" : "SYNOPSIS", "intro" : "# internal infrastructure\n my $msg = Log::Report::Message->new(_msgid => \"Hello World\\n\");\n print Log::Report::Translator->new(...)->translate($msg);\n\n # normal use\n textdomain 'my-domain',\n translator => Log::Report::Translator->new; # default\n print __\"Hello World\\n\";\n\n", "type" : "chapter", "id" : "id1165", "name" : "SYNOPSIS" }, "id781-id1228" : { "intro" : "
Inherited, see Log::Report::Dispatcher::addSkipStack()
", "type" : "ci_method", "call" : "$any->addSkipStack( @CODE )", "name" : "addSkipStack", "id" : "id781-id1228", "extends" : "id781" }, "id868" : { "id" : "id868", "name" : "_expand", "value" : "false",
"type" : "default"
},
"id1309" : {
"path" : "DETAILS/Messages with plural forms",
"nest" : [
"id1310"
],
"type" : "section",
"level" : 2,
"name" : "Messages with plural forms",
"id" : "id1309"
},
"id744-id441" : {
"intro" : "Inherited, see Log::Report::Lexicon::Table::setupPluralAlgorithm()
", "type" : "error", "subroutine" : "id743", "name" : "invalid plural-form algorithm '$alg'.", "id" : "id744-id441", "extends" : "id744" }, "id1051" : { "id" : "id1051", "name" : "import", "value" : "undef",
"type" : "default"
},
"id1244" : {
"path" : "METHODS/Attributes",
"type" : "section",
"subroutines" : [
"id771-id1228",
"id774-id1228",
"id775-id1228",
"id772-id1228",
"id773-id1228",
"id1246",
"id1245",
"id1247"
],
"level" : 2,
"name" : "Attributes",
"id" : "id1244"
},
"id1181" : {
"id" : "id1181",
"name" : "to_level",
"intro" : "See reasonToLevel().
\n", "type" : "option", "params" : "\\@PAIRS" }, "id995" : { "value" : "undef",
"id" : "id995",
"name" : "locale",
"type" : "default"
},
"id806" : {
"examples" : [
"id807",
"id808"
],
"level" : 3,
"intro" : "With a filter, you can block or modify specific messages before\ntranslation. There may be a wish to change the REASON of a report\nor its content. It is not possible to avoid the exit which is\nrelated to the original message, because a module's flow depends\non it to happen.
\n\nWhen there are filters defined, they will be called in order of\ndefinition. For each of the dispatchers which are called for a\ncertain REASON (which accept that REASON), it is checked whether\nits name is listed for the filter (when no names where specified,\nthen the filter is applied to all dispatchers).
When selected, the filter's CODE reference is called with four arguments:\nthe dispatcher object (a Log::Report::Dispatcher), the HASH-of-OPTIONS\npassed as optional first argument to Log::Report::report(), the\nREASON, and the MESSAGE. Returned is the new REASON and MESSAGE.\nWhen the returned REASON is undef, then the message will be ignored\nfor that dispatcher.
Be warned about processing the MESSAGE: it is a Log::Report::Message\nobject which may have a prepend string and append string or\nobject. When the call to Log::Report::report() contained multiple\ncomma-separated components, these will already have been joined together\nusing concatenation (see Log::Report::Message::concat().
use Log::Log4perl qw/:levels/;\n\n # by default, ALERTs are output as $FATAL\n dispatcher Log::Log4perl => 'logger',\n to_level => [ ALERT => $ERROR, ],\n ...;\n\n", "id" : "id978" }, "id272" : { "path" : "METHODS/Action", "type" : "section", "subroutines" : [ "id275", "id273" ], "level" : 2, "id" : "id272", "name" : "Action" }, "id959" : { "type" : "chapter", "intro" : "
Log::Report::Dispatcher::Log4perl - send messages to Log::Log4perl back-end
\n", "path" : "NAME", "level" : 1, "id" : "id959", "name" : "NAME" }, "id488" : { "id" : "id488", "name" : "msgstr", "call" : "$obj->msgstr( $msgid, [$count, [$msgctxt]] )", "type" : "i_method", "intro" : "Returns the translated string for $msgid. When $count is not specified or\nundef, the translation string related to \"1\" is returned.
ARRAY of Log::Report::Exception objects.
\n", "id" : "id828", "name" : "exceptions" }, "id1110" : { "params" : "$charset", "type" : "option", "intro" : "Translate the text-strings into the specified $charset, otherwise the\nsysadmin may get unreadable text.
\n", "id" : "id1110", "name" : "charset" }, "id370" : { "type" : "section", "intro" : "You may define a textdomain without doing any translations (yet) However,\nwhen you start translating, you will need to maintain translation tables\nwhich are in PO-format. PO-files can be maintained with a wide variety\nof tools, for instance poedit, Pootle, virtaal, GTranslator, Lokalize,\nor Webtranslateit.
\n", "path" : "DETAILS/Extracting PO-files", "level" : 2, "nest" : [ "id371", "id372", "id373", "id374" ], "name" : "Extracting PO-files", "id" : "id370" }, "id438" : { "name" : "starting new textdomain $domain, template in $filename", "id" : "id438", "subroutine" : "id437", "type" : "info" }, "id165-id1127" : { "extends" : "id165", "id" : "id165-id1127", "name" : "name", "type" : "option", "params" : "STRING", "intro" : "Inherited, see Log::Report::Minimal::Domain::new(name)
" }, "id1171" : { "path" : "METHODS/Translating", "type" : "section", "subroutines" : [ "id1173", "id1172" ], "id" : "id1171", "name" : "Translating", "level" : 2 }, "id977" : { "call" : "$obj->reasonToLevel( $reason )", "examples" : [ "id978" ], "intro" : "Returns a level which is understood by Log::Dispatch, based on\na translation table. This can be changed with new(to_level).
\n", "type" : "i_method", "id" : "id977", "name" : "reasonToLevel" }, "id454" : { "id" : "id454", "name" : "nr_plurals", "params" : "INTEGER", "type" : "option", "intro" : "The number of translations each of the translation with plural form\nneed to have.
\n" }, "id766-id944" : { "id" : "id766-id944", "name" : "charset", "extends" : "id766", "value" : "undef",
"intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
", "type" : "default" }, "id867" : { "name" : "_expand", "id" : "id867", "params" : "BOOLEAN", "type" : "option", "intro" : "Indicates whether variables are to be filled-in; whether __x or __ was\nused to define the message.
Inherited, see Log::Report::Extract::pots()
", "id" : "id429-id289", "name" : "pots", "extends" : "id429", "call" : "$obj->pots( $domain )" }, "id381" : { "options" : [ [ "id390", "id391" ], [ "id386", "id387" ], [ "id165-id375", "id166-id375" ], [ "id382", "id383" ], [ "id388", "id389" ], [ "id384", "id385" ] ], "type" : "c_method", "call" : "$class->new( %options )", "id" : "id381", "name" : "new" }, "id913-id217" : { "call" : "$obj->addTags( @tags )", "id" : "id913-id217", "name" : "addTags", "extends" : "id913", "intro" : "Inherited, see Log::Report::Message::addTags()
", "type" : "i_method" }, "id1139" : { "name" : "translator", "id" : "id1139", "intro" : "Set the object which will do the translations for this domain.
\n", "params" : "Log::Report::Translator|\\%config", "type" : "option" }, "id175-id375" : { "intro" : "Inherited, see Log::Report::Minimal::Domain::configure(where)
", "type" : "default", "name" : "where", "id" : "id175-id375", "value" : "<required>", "extends" : "id175" }, "id331" : { "type" : "option", "params" : "\\@modifiers", "intro" : "Add @modifiers to the default set. Modifiers are part of the\nformatting process, when values get inserted in the translated string.\nRead Formatter value modifiers.
\n", "id" : "id331", "name" : "modifiers" }, "id1028" : { "intro" : "It depends on the value of $count (and the selected language) which\ntext will be displayed. When translations can not be performed, then\n$msgid will be used when $count is 1, and PLURAL_MSGSID in other cases.\nHowever, some languages have more complex schemes than English.
\n\nThe PAIRS are options for Log::Report::Message::new() and variables\nto be filled in.
\n", "type" : "function", "examples" : [ "id1029" ], "call" : "__n( $msgid, $plural_msgid, $count, PAIRS )", "id" : "id1028", "name" : "__n" }, "id1240" : { "id" : "id1240", "name" : "format", "type" : "option", "params" : "CODE|'LONG'", "intro" : "[1.00] process each printed line. By default, this adds a timestamp,\nbut you may want to add hostname, process number, or more.
\n\n format => sub { '['.localtime().'] '.$_[0] }\n format => sub { shift } # no timestamp\n format => 'LONG'\n\n\nThe first parameter to format is the string to print; it is already\ntranslated and trailed by a newline. The second parameter is the\ntext-domain (if known).
\n\n[1.10] As third parameter, you get the message raw object as well (maybe\nyou want to use the message context?)
\n\n[1.19] After the three positional parameters, there may be a list\nof pairs providing additional facts about the exception. It may\ncontain location information.
The \"LONG\" format is equivalent to:
\n\n my $t = strftime \"%FT%T\", gmtime;\n \"[$t $$] $_[1] $_[0]\"\n\n\n
Use of context:
\n\n format => sub { my ($msgstr, $domain, $msg, %more) = @_;\n my $host = $msg->context->{host};\n \"$host $msgstr\";\n }\n\n"
},
"id494" : {
"subroutine" : "id493",
"name" : "no header defined in POT for file $fn.",
"id" : "id494",
"type" : "error"
},
"id434-id697" : {
"intro" : "Inherited, see Log::Report::Extract::cleanup(keep)
", "type" : "option", "params" : "HASH|ARRAY", "id" : "id434-id697", "name" : "keep", "extends" : "id434" }, "id1105" : { "type" : "default", "value" : "[]", "id" : "id1105", "name" : "to_prio" }, "id241" : { "call" : "$obj->info", "id" : "id241", "name" : "info", "type" : "i_method" }, "id544" : { "call" : "$obj->automatic( [@lines|\\@lines|$text] )", "name" : "automatic", "id" : "id544", "intro" : "Returns a STRING which contains the cleaned paragraph of automatically\nadded comments. If an argument is specified, it will replace the current\ncomment.
\n", "type" : "i_method" }, "id1342" : { "name" : "INHERITANCE", "id" : "id1342", "type" : "chapter", "path" : "INHERITANCE", "intro" : "Log::Report::Extract::PerlPPI\n is a Log::Report::Extract\n\n", "level" : 1 }, "id800" : { "intro" : "
The higher the abstraction value, the less details are given\nabout the caller. The minimum abstraction is specified, and\nthen increased internally to make the line fit within the max_line\nmargin.
\n", "type" : "option", "params" : "INTEGER", "name" : "abstract", "id" : "id800" }, "id376" : { "level" : 1, "intro" : "Log::Report::Template::Textdomain - template translation with one domain
\n", "path" : "NAME", "type" : "chapter", "name" : "NAME", "id" : "id376" }, "id144" : { "id" : "id144", "name" : "panic", "call" : "panic( $message )", "type" : "function" }, "id761-id1090" : { "id" : "id761-id1090", "name" : "mode", "extends" : "id761", "params" : "'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
" }, "id760-id944" : { "id" : "id760-id944", "name" : "locale", "value" : "<system locale>", "extends" : "id760", "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "type" : "default" }, "id1091" : { "name" : "NAME", "id" : "id1091", "path" : "NAME", "intro" : "Log::Report::Dispatcher::Syslog - send messages to syslog
\n", "type" : "chapter", "level" : 1 }, "id861-id217" : { "extends" : "id861", "name" : "'\"\"'", "id" : "id861-id217", "call" : "overload '\"\"'; stringification", "type" : "overload", "intro" : "Inherited, see Log::Report::Message::'\"\"'()
" }, "id999" : { "id" : "id999", "name" : "token '$token' not recognized as reason.", "subroutine" : "id985", "type" : "error" }, "id955" : { "path" : "METHODS/Attributes", "type" : "section", "subroutines" : [ "id771-id944", "id774-id944", "id775-id944", "id772-id944", "id773-id944", "id956" ], "name" : "Attributes", "id" : "id955", "level" : 2 }, "id1114" : { "subroutine" : "id1096", "id" : "id1114", "name" : "max one active syslog dispatcher, attempt for $new have $old", "type" : "error" }, "id941" : { "name" : "NAME", "id" : "id941", "level" : 1, "type" : "chapter", "intro" : "Log::Report::DBIC::Profiler - query profiler for DBIx::Class
\n", "path" : "NAME" }, "id150" : { "id" : "id150", "name" : "__nx", "call" : "__nx( $msgid, $plural_msgid, $count, PAIRS )", "type" : "function" }, "id596" : { "type" : "section", "path" : "METHODS/Constructors", "level" : 2, "id" : "id596", "name" : "Constructors", "subroutines" : [ "id597" ] }, "id1158" : { "intro" : "Translate the $message into the $language.
\n", "type" : "i_method", "call" : "$obj->translate( $message, $language )", "name" : "translate", "id" : "id1158" }, "id1323" : { "id" : "id1323", "name" : "INHERITANCE", "type" : "chapter", "intro" : "Log::Report::Translator::Gettext\n is a Log::Report::Translator\n\n", "path" : "INHERITANCE", "level" : 1 }, "id446" : { "subroutines" : [ "id447", "id467", "id475" ], "level" : 2, "name" : "Constructors", "id" : "id446", "path" : "METHODS/Constructors", "type" : "section" }, "id1137" : { "type" : "i_method", "call" : "$obj->contextRules", "name" : "contextRules", "id" : "id1137" }, "id1088" : { "level" : 2, "id" : "id1088", "name" : "Attributes", "subroutines" : [ "id771-id1082", "id774-id1082", "id775-id1082", "id772-id1082", "id773-id1082" ], "type" : "section", "path" : "METHODS/Attributes" }, "id1268" : { "type" : "section", "path" : "DETAILS/Available back-ends", "name" : "Available back-ends", "id" : "id1268", "level" : 2 }, "id766-id1082" : { "type" : "default", "intro" : "
Inherited, see Log::Report::Dispatcher::new(charset)
", "extends" : "id766", "value" : "undef",
"name" : "charset",
"id" : "id766-id1082"
},
"id196" : {
"call" : "mode_number( $name|$mode )",
"id" : "id196",
"name" : "mode_number",
"intro" : "Returns the $mode as number.
\n", "type" : "function" }, "id299" : { "id" : "id299", "name" : "pattern", "value" : "<undef>",
"type" : "default"
},
"id255" : {
"level" : 3,
"intro" : "Set up Dancer2::Logger::LogReport by adding it to your Dancer2\napplication configuration (see manual Dancer2::Config). By default,\nall messages will go to STDERR.
\n\nTo get all message out \"the Perl way\" (using print, warn and die) just use
\n\n logger: \"LogReport\"\n\n\n
At start, these are handled by a Log::Report::Dispatcher::Perl object,\nnamed 'default'. If you open a new dispatcher with the name 'default',\nthe output via the perl mechanisms will be stopped.
\n\nTo also send messages to your syslog:
\n\n logger: \"LogReport\"\n\n engines:\n logger:\n LogReport:\n log_format: %a%i%m # See Dancer2::Logger::LogReport\n app_name: MyApp\n dispatchers:\n default: # Name\n type: SYSLOG # Log::Reporter::dispatcher() options\n identity: myapp\n facility: local0\n flags: \"pid ndelay nowait\"\n mode: DEBUG\n\n\n
To send messages to a file:
\n\n logger: \"LogReport\"\n\n engines:\n logger:\n LogReport:\n log_format: %a%i%m # See Dancer2::Logger::LogReport\n app_name: MyApp\n dispatchers:\n logfile: # \"default\" dispatcher stays open as well\n type: FILE\n to: /var/log/myapp.log\n charset: utf-8\n mode: DEBUG\n\n\n
See Log::Report::Dispatcher for full details of options.
\n\nFinally: a Dancer2 script may run many applications. Each application\ncan have its own logger configuration. However, Log::Report dispatchers\nare global, so will be shared between Dancer2 applications. Any attempt\nto create a new Log::Report dispatcher by the same name (as will happen\nwhen a new Dancer2 application is started with the same configuration)\nwill be ignored.
\n", "path" : "DETAILS/Setup and Configuration/Dancer2::Logger::LogReport", "type" : "subsection", "id" : "id255", "name" : "Dancer2::Logger::LogReport" }, "id550" : { "call" : "$obj->isActive", "id" : "id550", "name" : "isActive", "intro" : "Returns whether the translation has any references, or is the header.
\n", "type" : "i_method" }, "id1078" : { "id" : "id1078", "name" : "Compared to other solutions in Perl", "nest" : [ "id1079", "id1080", "id1081" ], "level" : 2, "type" : "section", "path" : "DETAILS/Compared to other solutions in Perl", "intro" : "Some notes on differences between the Log::Report approach and other\nPerl concepts.
\n" }, "id753" : { "id" : "id753", "name" : "DESCRIPTION", "level" : 1, "path" : "DESCRIPTION", "intro" : "In Log::Report, dispatchers are used to handle (exception) messages\nwhich are created somewhere else. Those message were produced (thrown)\nby Log::Report::error() and friends.
\n\nThis base-class handles the creation of dispatchers, plus the common\nfiltering rules. See the DETAILS section, below.
\n", "type" : "chapter" }, "id614" : { "id" : "id614", "name" : "DESCRIPTION", "level" : 1, "path" : "DESCRIPTION", "intro" : "UNTESTED!!! PLEASE CONTRIBUTE!!!\nTranslate a message using the GNU gettext infrastructure.
\n\nGuido Flohr reports:\nbe aware that Locale::gettext is only a binding for the C library\nlibintl and depends on its features. That means that your module will\neffectively only run on GNU systems and maybe on Solaris (depending\non the exact version), because only these systems provide the plural\nhandling functions ngettext(), dngettext() and dcngettext(). Sooner or\nlater you will probably also need bind_textdomain_codeset() which is\nalso only available on certain systems.
\n", "type" : "chapter" }, "id727" : { "name" : "SYNOPSIS", "id" : "id727", "type" : "chapter", "intro" : " # use one of the extensions, for instance:\n my $pot = Log::Report::Lexicon::POT->read('po/nl.po', charset => 'utf-8')\n or panic;\n\n",
"path" : "SYNOPSIS",
"level" : 1
},
"id47" : {
"chapters" : [
"id48",
"id49",
"id50",
"id51",
"id74",
"id89"
],
"version" : "1.02",
"distribution" : "String-Print",
"package" : "String::Print",
"inheritance" : {},
"id" : "id47",
"name" : "String::Print",
"title" : "printf alternative",
"is_pure_pod" : false
},
"id348" : {
"id" : "id348",
"name" : "extract",
"call" : "$obj->extract( %options )",
"type" : "i_method",
"options" : [
[
"id349",
"id350"
],
[
"id355",
"id356"
],
[
"id353",
"id354"
],
[
"id351",
"id352"
]
],
"intro" : "Extract message ids from the templates, and register them to the lexicon.\nRead section Extracting PO-files how to use this method.
\n\nShow statistics will be show when the Log::Report more is VERBOSE or\nDEBUG.
\n" }, "id551" : { "type" : "i_method", "intro" : "Returns whether the translation needs human inspection.
\n", "name" : "fuzzy", "id" : "id551", "call" : "$obj->fuzzy( [BOOLEAN] )" }, "id254" : { "type" : "section", "path" : "DETAILS/Setup and Configuration", "intro" : "To make full use of Log::Report, you'll need to use both\nDancer2::Logger::LogReport and Dancer2::Plugin::LogReport.
\n", "level" : 2, "nest" : [ "id255", "id256" ], "id" : "id254", "name" : "Setup and Configuration" }, "id608" : { "type" : "example", "intro" : "My module is named Some::Module and installed in\nsome of perl's directories, say ~perl5.8.8. The module is defining\ntextdomain my-domain. The translation is made into nl-NL.utf-8\n(locale for Dutch spoken in The Netherlands, utf-8 encoded text file).
The default location for the translation table is under
\n ~perl5.8.8/Some/Module/messages/\n\n\n
for instance
\n ~perl5.8.8/Some/Module/messages/nl-NL.utf-8/LC_MESSAGES/my-domain.po\n\n\n
There are alternatives, as described in Log::Report::Lexicon::Index,\nfor instance
\n ~perl5.8.8/Some/Module/messages/my-domain/nl-NL.utf-8.po\n ~perl5.8.8/Some/Module/messages/my-domain/nl.po\n\n", "id" : "id608", "name" : "lexicon in module tree\n" }, "id706" : { "id" : "id706", "name" : "Attributes", "level" : 2, "subroutines" : [ "id428-id697", "id430-id697", "id426-id697", "id429-id697", "id427-id697" ], "type" : "section", "path" : "METHODS/Attributes" }, "id238" : { "id" : "id238", "name" : "Handlers", "path" : "METHODS/Handlers", "intro" : "
All the standard Log::Report functions are available to use. Please see the\nThe Reason for the report for details\nof when each one should be used.
\n\nLog::Report class functionality\nto class messages (which can then be tested later):
\n\n notice __x\"Tag me up\", _tag => 'label';\n ...\n if ($msg->taggedWith('label')) ...\n\n\nDancer2::Plugin::LogReport has a special message class, no_session,\nwhich prevents the message from being saved to the messages session\nvariable. This is useful, for example, if you are writing messages within\nthe session hooks, in which case recursive loops can be experienced.
Simple perl scripts will use print() with variables in the string.\nHowever, when the content of the variable gets more unpredictable or\nneeds some pre-processing, then it gets tricky. When you do want to\nintroduce translations (in the far future of your successful project)\nit gets impossible. Let me give you some examples:
\n print \"product: $name\\n\"; # simple perl\n\n # Will not work because \"$name\" is interpolated too early\n print translate(\"product: $name\"), \"\\n\";\n\n # This is the gettext solution, with formats\n printf translate(\"product: %s\\n\"), $name;\n\n # With named in stead of positional parameters\n print translate(\"product: {p}\\n\", p => $name);\n\n # With Log::Report, the translate() is hidden in __x()\n print __x\"product: {p}\\n\", p => $name;\n\n\nBesides making translation possible, interpolation via format strings\nis much cleaner than in the simpelest perl way. For instance, these\ncases:
\n\n # Safety measures while interpolation\n my $name = undef;\n print \"product: $name\\n\"; # uninitialized warning\n print __x\"product: {p}\\n\", p => $name; # --> product: undef\n\n # Interpolation of more complex data\n my @names = qw/a b c/;\n print \"products: \", join(', ', @names), \"\\n\";\n print __x\"products: {p}\\n\", p => \\@names;\n\n # Padded values hard to do without format strings\n print \"padded counter: \", ' ' x (6-length $c), \"$c\\n\";\n printf \"padded counter: %6d\\n\", $counter;\n print __x\"padded counter: {c%6d}\\n\", c => $counter;\n\n\nSo: using formats has many advantages. Advice: use simple perl only in\ntrace and assert messages, maybe also with panics. For serious output\nof your program, use formatted output.
Get messages to users and logs. Log::Report combines three tasks\nwhich are closely related in one:
gettext and Locale::TextDomain)You do not need to use this module for all three reasons: pick what\nyou need now, maybe extend the usage later. Read more about how and\nwhy in the DETAILS section, below. Especially, you should B
Also, you can study this module swiftly via the article published in\nthe German Perl $foo-magazine. English version:\nhttps://perl.overmeer.net/log-report/papers/201306-PerlMagazine-article-en.html
Returns the textdomain with the specified $name.
\n", "name" : "domain", "id" : "id347", "call" : "$obj->domain( $name )" }, "id472" : { "subroutine" : "id467", "id" : "id472", "name" : "cannot detect charset in $fn.", "type" : "error" }, "id728" : { "name" : "DESCRIPTION", "id" : "id728", "intro" : "This base class defines the generic interface for translation tables.
\n\nCurrently, there are three extensions:
\n\nInherited, see Log::Report::Dispatcher::mode()
" }, "id767" : { "subroutine" : "id756", "name" : "cannot use class $backend:\\n$@: $!", "id" : "id767", "type" : "alert" }, "id93" : { "id" : "id93", "name" : "Simple keys", "type" : "subsection", "path" : "DETAILS/Interpolation: keys/Simple keys", "intro" : "A simple key directly refers to a named parameter of the function or method:
\n\n printi \"Username: {name}\", name => 'John';\n\n\nYou may also pass them as HASH or CODE:
\n\n printi \"Username: {name}\", { name => 'John' };\n printi \"Username: {name}\", name => sub { 'John' };\n printi \"Username: {name}\", { name => sub { 'John' } };\n printi \"Username: {name}\", name => sub { sub {'John'} };\n\n\nThe smartness of pre-processing CODE is part of serialization.
\n", "level" : 3 }, "id151" : { "type" : "function", "call" : "__xn( $single_msgid, $plural_msgid, $count, PAIRS )", "name" : "__xn", "id" : "id151" }, "id940" : { "id" : "id940", "name" : "Log::Report::DBIC::Profiler", "is_pure_pod" : false, "title" : "query profiler for DBIx::Class", "distribution" : "Log-Report", "inheritance" : { "extends" : [ "DBIx::Class::Storage::Statistics" ] }, "package" : "Log::Report::DBIC::Profiler", "version" : "1.45", "chapters" : [ "id941", "id1330", "id942", "id943" ] }, "id98" : { "type" : "subsubsection", "intro" : "The POSIX printf() does not handle unicode strings. Perl does\nunderstand that the 's' modifier may need to insert utf8 so does not\ncount bytes but characters. printi() does not use characters but\n\"grapheme clusters\" via Unicode::GCString. Now, also composed\ncharacters do work correctly.
Additionally, you can use the new 'S' conversion to count in columns.\nIn fixed-width fonts, graphemes can have width 0, 1 or 2. For instance,\nChinese characters have width 2. When printing in fixed-width, this\n'S' is probably the better choice over 's'. When the field does not\nspecify its width, then there is no performance penalty for using 'S'.
\n\n # name right aligned, commas on same position, always\n printp \"name: {name%20S},\\n\", name => $some_chinese;\n\n",
"path" : "DETAILS/Interpolation: Modifiers/Modifier: POSIX format starts with '%'/POSIX modifier extension '%S'",
"level" : 4,
"name" : "POSIX modifier extension '%S'",
"id" : "id98"
},
"id607" : {
"path" : "DETAILS/merge lexicon files with perl modules",
"intro" : "By default, the filename which contains the package which contains the\ntextdomain's translator configuration is taken (that can be only one)\nand changed into a directory name. The path is then extended with messages\nto form the root of the lexicon: the top of the index. After this,\nthe locale indication, the lc-category (usually LC_MESSAGES), and\nthe textdomain followed by .po are added. This is exactly as\ngettext(1) does, but then using the PO text file instead of the MO\nbinary file.
See reasonToPrio().
\n", "id" : "id1104", "name" : "to_prio" }, "id602" : { "intro" : "Add a certain file to the index. This method returns the $absolute\npath to that file, which must be used to access it. When not explicitly\nspecified, the $absolute path will be calculated.
\n", "type" : "i_method", "call" : "$obj->addFile( $basename, [$absolute] )", "id" : "id602", "name" : "addFile" }, "id938" : { "level" : 3, "type" : "subsection", "intro" : "In above examples, the msgid and plural form have a trailing new-line.\nIn general, it is much easier to write
\n\n print __x\"Hello, World!\\n\";\n\n\n
than
\n\n print __x(\"Hello, World!\") . \"\\n\";\n\n\n
For the translation tables, however, that trailing new-line is \"ignorable\ninformation\"; it is an layout issue, not a translation issue.
\n\nTherefore, the first form will automatically be translated into the\nsecond. All leading and trailing white-space (blanks, new-lines, tabs,\n...) are removed from the msgid before the look-up, and then added to\nthe translated string.
\n\nLeading and trailing white-space on the plural form will also be\nremoved. However, after translation the spacing of the msgid will\nbe used.
\n", "path" : "DETAILS/Automatic parameters/Handling white-spaces", "name" : "Handling white-spaces", "id" : "id938" }, "id771-id1228" : { "call" : "$obj->name", "name" : "name", "id" : "id771-id1228", "extends" : "id771", "intro" : "Inherited, see Log::Report::Dispatcher::name()
", "type" : "i_method" }, "id232" : { "level" : 1, "name" : "METHODS", "id" : "id232", "subroutines" : [ "id234", "id233" ], "type" : "chapter", "path" : "METHODS", "nest" : [ "id238" ] }, "id988" : { "params" : "INTEGER", "type" : "option", "intro" : "When the $reason includes the error text (See Run modes), you can\noverrule the error code kept in $!. In other cases, the return code\ndefaults to 1 (historical UNIX behavior). When the message $reason\n(combined with the run-mode) is severe enough to stop the program,\nthis value as return code of the program. The use of this option itself\nwill not trigger an die().
[The Dancer2 plugin was contributed by Andrew Beverley]
\n\nThis logger allows the use of the many logging backends available\nin Log::Report. It will process all of the Dancer2 log messages,\nand also allow any other module to use the same logging facilities. The\nsame log messages can be sent to multiple destinations at the same time\nvia flexible dispatchers.
\n\nIf using this logger, you may also want to use\nDancer2::Plugin::LogReport
\n\nMany log back-ends, like syslog, have more levels of system messages.\nModules who explicitly load this module can use the missing assert,\nnotice, panic, and alert log levels. The trace name is\nprovided as well: when you are debugging, you add a 'trace' to your\nprogram... it's just a better name than 'debug'. You will need to load\nLog::Report in order to use the additional levels; if doing so directly within\na Dancer2 application (not a sub-module), then you will either need to load\nLog::Report with syntax, 'LONG' or use Dancer2::Plugin::LogReport to\nprevent namespace clashes.
Inherited, see Log::Report::Dispatcher::new(mode)
", "params" : "'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3", "type" : "option", "extends" : "id761", "name" : "mode", "id" : "id761-id944" }, "id1330" : { "id" : "id1330", "name" : "INHERITANCE", "level" : 1, "intro" : "Log::Report::DBIC::Profiler\n is a DBIx::Class::Storage::Statistics\n\n", "path" : "INHERITANCE", "type" : "chapter" }, "id145" : { "path" : "FUNCTIONS/Language Translations", "intro" : "
No translations, no Log::Report::Message objects returned.
\n", "type" : "section", "subroutines" : [ "id153", "id152", "id150", "id147", "id146", "id154", "id151", "id149" ], "level" : 2, "id" : "id145", "name" : "Language Translations" }, "id760-id1090" : { "id" : "id760-id1090", "name" : "locale", "value" : "<system locale>", "extends" : "id760", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
" }, "id423-id697" : { "intro" : "Inherited, see Log::Report::Extract::new()
", "type" : "error", "subroutine" : "id418", "id" : "id423-id697", "name" : "extractions require an explicit lexicon directory.", "extends" : "id423" }, "id1294" : { "type" : "section", "path" : "DETAILS/Configuring", "nest" : [ "id1295", "id1296" ], "level" : 2, "name" : "Configuring", "id" : "id1294" }, "id342" : { "type" : "i_method", "intro" : "Create a new Log::Report::Template::Textdomain object.\nSee its new() method for the options.
Additional facts about the options: you may specify only_in_directory\nas a path. Those directories must be in the INCLUDE_PATH as well.\nThe (domain) name must be unique, and the function not yet in use.
When the code also uses this textdomain, then that configuration will\nget extended with this configuration.
\n", "diagnostics" : [ "id344", "id345" ], "examples" : [ "id343" ], "call" : "$obj->addTextdomain( %options )", "name" : "addTextdomain", "id" : "id342" }, "id893" : { "id" : "id893", "name" : "_join", "intro" : "Which $separator string to be used then an ARRAY is being filled-in.
\n", "params" : "$separator", "type" : "option" }, "id1160" : { "nest" : [ "id1161", "id1162" ], "name" : "Configuring", "id" : "id1160", "type" : "section", "intro" : "Configuration of a domain can happen in many ways: either explicitly or\nimplicitly. The explicit form:
\n\n package My::Package;\n use Log::Report 'my-domain';\n\n textdomain 'my-domain', %configuration;\n textdomain->configure(%configuration);\n textdomain->configure(\\%configuration);\n\n textdomain->configure(conf => $filename);\n\n\n
The implicit form is (no variables possible, only constants!)
\n\n package My::Package;\n use Log::Report 'my-domain', %configuration;\n use Log::Report 'my-domain', conf => '/filename';\n\n\n
You can only configure your domain in one place in your program. The\ntextdomain setup is then used for all packages in the same domain.
\n\nThis also works for Log::Report::Optional, which is a dressed-down\nversion of Log::Report.
\n", "path" : "DETAILS/Configuring", "level" : 2 }, "id72" : { "examples" : [ "id73" ], "level" : 2, "path" : "METHODS/Printing", "intro" : "The following are provided both as method and as function. The function\nversion is explained further down on this page, because it reads a bit\neasier, but the object version is most flexible.
\n\n my $sp = String::Print->new;\n $sp->printi([$fh], $format, %data|\\%data); # see printi()\n $sp->printp([$fh], $format, @params, %options); # see printp()\n my $s = $sp->sprinti($format, %data|\\%data); # see sprinti()\n my $s = $sp->sprintp($format, @params, %options); # see sprintp()\n\n", "type" : "section", "id" : "id72", "name" : "Printing" }, "id954" : { "subroutine" : "id951", "id" : "id954", "name" : "dispatcher $name needs a 'callback'", "type" : "error" }, "id1232" : { "type" : "chapter", "nest" : [ "id1233", "id1244", "id1248", "id1253" ], "path" : "METHODS", "name" : "METHODS", "id" : "id1232", "level" : 1 }, "id477" : { "name" : "only_active", "id" : "id477", "value" : "
false",
"type" : "default"
},
"id801" : {
"name" : "abstract",
"id" : "id801",
"value" : "1",
"type" : "default"
},
"id60" : {
"id" : "id60",
"name" : "missing_key",
"intro" : "[0.91] During interpolation, it may be discovered that a key is missing\nfrom the parameter list. In that case, a warning is produced and undef\ninserted. May can overrule that behavior.
undef",
"type" : "default"
},
"id174-id375" : {
"intro" : "Inherited, see Log::Report::Minimal::Domain::configure(where)
", "type" : "option", "params" : "ARRAY", "extends" : "id174", "id" : "id174-id375", "name" : "where" }, "id76" : { "name" : "sprinti", "id" : "id76", "call" : "sprinti( $format, %data|\\%data|OBJECT, %options )", "type" : "function", "options" : [ [ "id83", "id84" ], [ "id77", "id78" ], [ "id79", "id80" ], [ "id81", "id82" ] ], "intro" : "The $format refers to some string, maybe the result of a translation.
\n\nThe %data (which may be passed as LIST, HASH, or blessed HASH) contains\na mixture of special and normal variables to be filled in. The names\nof the special variables (the %options) start with an underscore (_).
Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "type" : "option", "params" : "CLASS" }, "id1326" : { "id" : "id1326", "name" : "INHERITANCE", "level" : 1, "type" : "chapter", "intro" : "Dancer2::Template::TTLogReport\n is a Moo::Object\n\n", "path" : "INHERITANCE" }, "id1115" : { "subroutine" : "id1096", "name" : "syslog level '$level' not understood", "id" : "id1115", "type" : "error" }, "id937" : { "name" : "using the _count\n", "id" : "id937", "type" : "example", "intro" : "
With Locale::TextDomain, you have to do
\n\n use Locale::TextDomain;\n print __nx(\n \"One file has been deleted.\\n\",\n \"{num} files have been deleted.\\n\",\n $num_files,\n num => $num_files,\n );\n\n\nWith Log::Report, you can do
\n use Log::Report;\n print __nx(\n \"One file has been deleted.\\n\",\n \"{_count} files have been deleted.\\n\",\n $num_files,\n );\n\n\nOf course, you need to be aware that the name used to reference the\ncounter is fixed to _count. The first example works as well, but\nis more verbose.
Inherited, see Log::Report::Extract::cleanup(keep)
", "value" : "[]", "extends" : "id435", "name" : "keep", "id" : "id435-id697" }, "id495" : { "type" : "i_method", "intro" : "Replace the \"PO-Revision-Date\" with the specified $date, or the current\nmoment.
\n", "name" : "updated", "id" : "id495", "call" : "$obj->updated( [$date] )" }, "id330" : { "type" : "default", "value" : "'HTML'", "name" : "template_syntax", "id" : "id330" }, "id459" : { "value" : "<constructed from nr_plurals and plural_alg>", "id" : "id459", "name" : "plural_forms", "type" : "default" }, "id478" : { "name" : "no filename or file-handle specified for PO", "id" : "id478", "subroutine" : "id475", "type" : "error", "intro" : "When a PO file is written, then a filename or file-handle must be\nspecified explicitly, or set beforehand using the filename()\nmethod, or known because the write follows a read() of the file.
\n" }, "id766-id818" : { "extends" : "id766", "value" : "undef",
"name" : "charset",
"id" : "id766-id818",
"intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
", "type" : "default" }, "id545" : { "call" : "$obj->addAutomatic( @lines|\\@lines|$text )", "id" : "id545", "name" : "addAutomatic", "intro" : "Add multiple lines to the translator's comment block. Returns an\nempty string if there are no comments.
\n", "type" : "i_method" }, "id380" : { "type" : "section", "path" : "METHODS/Constructors", "name" : "Constructors", "id" : "id380", "level" : 2, "subroutines" : [ "id381", "id392" ] }, "id722" : { "type" : "section", "path" : "METHODS/Constructors", "name" : "Constructors", "id" : "id722", "level" : 2, "subroutines" : [ "id723" ] }, "id866-id217" : { "intro" : "Inherited, see Log::Report::Message::new()
", "type" : "c_method", "options" : [ [ "id881-id217", "id882-id217" ], [ "id877-id217", "id878-id217" ], [ "id889-id217", "id890-id217" ], [ "id887-id217", "id888-id217" ], [ "id897-id217", "id898-id217" ], [ "id871-id217", "id872-id217" ], [ "id869-id217", "id870-id217" ], [ "id867-id217", "id868-id217" ], [ "id893-id217", "id894-id217" ], [ "id895-id217", "id896-id217" ], [ "id899-id217", "id900-id217" ], [ "id875-id217", "id876-id217" ], [ "id873-id217", "id874-id217" ], [ "id879-id217", "id880-id217" ], [ "id883-id217", "id884-id217" ], [ "id885-id217", "id886-id217" ], [ "id891-id217", "id892-id217" ] ], "call" : "$class->new( %options )", "extends" : "id866", "id" : "id866-id217", "name" : "new" }, "id1245" : { "type" : "i_method", "intro" : "Returns the name of the opened file, or undef in case this dispatcher\nwas started from a file-handle or file-object.
Log::Report::Translator - base implementation for translating messages
\n", "type" : "chapter", "level" : 1 }, "id1290" : { "id" : "id1290", "name" : "Processing the message", "level" : 2, "type" : "section", "nest" : [ "id1291", "id1292" ], "path" : "DETAILS/Processing the message" }, "id371" : { "id" : "id371", "name" : "Setting-up translations", "path" : "DETAILS/Extracting PO-files/Setting-up translations", "intro" : "Start with desiging a domain structure. Probably, you want to create\na separate domain for the templates (external texts in many languages)\nand your Perl program (internal texts with few languages).
\n\nPick a lexicon directory, which is also inside your version control setup,\nfor instance your GIT repository. Some po-editors can work together\nwith various version control systems.
\n\nNow, start using this module. There are two ways: either by creating it\nas object, or by extension.
\n\n ### As object\n # Somewhere in your code\n use Log::Report::Template;\n my $templater = Log::Report::Template->new(%config);\n $templater->addTextdomain(...);\n\n $templater->process('template_file.tt', \\%vars); # runtime\n $templater->extract(...); # rarely, \"off-line\"\n\n\nSome way or another, you want to be able to share the creation of the\ntemplater and configuration of the textdomain between the run-time use\nand the irregular (off-line) extraction of msgids.
\n\nThe alternative is via extension:
\n\n ### By extension\n # Somewhere in your code:\n use My::Template;\n my $templater = My::Template->new;\n $templater->process('template_file.tt', \\%vars);\n\n # File lib/My/Template.pm\n package My::Template;\n use parent 'Log::Report::Template';\n\n sub init($) {\n my ($self, $args) = @_;\n # add %config into %$args\n $self->SUPER::init($args);\n $self->addTextdomain(...);\n $self;\n }\n\n 1;\n\n\nThe second solution requires a little bit of experience with OO, but is\neasier to maintain and to share.
\n", "type" : "subsection", "level" : 3 }, "id499" : { "chapters" : [ "id500", "id1341", "id501", "id502", "id503" ], "version" : "1.16", "distribution" : "Log-Report-Lexicon", "package" : "Log::Report::Win32Locale", "inheritance" : { "extends" : [ "Exporter" ] }, "name" : "Log::Report::Win32Locale", "id" : "id499", "title" : "unix/windows locales", "is_pure_pod" : false }, "id439-id697" : { "id" : "id439-id697", "name" : "store", "extends" : "id439", "call" : "$obj->store( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )", "diagnostics" : [ "id440-id697" ], "intro" : "Inherited, see Log::Report::Extract::store()
", "type" : "i_method" }, "id549" : { "call" : "$obj->keepReferencesTo( $table )", "name" : "keepReferencesTo", "id" : "id549", "intro" : "Remove all references which are not found as key in the hash $table.\nReturns the number of references left.
\n", "type" : "i_method" }, "id1334" : { "path" : "INHERITANCE", "intro" : "Log::Report::Translator::POT\n is a Log::Report::Translator\n\n", "type" : "chapter", "level" : 1, "name" : "INHERITANCE", "id" : "id1334" }, "id455" : { "value" : "2", "name" : "nr_plurals", "id" : "id455", "type" : "default" }, "id1100" : { "id" : "id1100", "name" : "flags", "intro" : "
Any combination of $flags as defined by Sys::Syslog, as comma-separated\nstring. Examples for flags are: pid, ndelay, and nowait.
Log::Report::Dispatcher::Perl\n is a Log::Report::Dispatcher\n\n", "path" : "INHERITANCE", "level" : 1, "id" : "id1319", "name" : "INHERITANCE" }, "id780-id1228" : { "call" : "$any->collectStack( [$maxdepth] )", "id" : "id780-id1228", "name" : "collectStack", "extends" : "id780", "intro" : "
Inherited, see Log::Report::Dispatcher::collectStack()
", "type" : "ci_method" }, "id1151-id375" : { "type" : "error", "intro" : "Inherited, see Log::Report::Domain::readConfig()
", "extends" : "id1151", "name" : "unsupported context file type for $fn", "id" : "id1151-id375", "subroutine" : "id1149" }, "id149" : { "name" : "__n", "id" : "id149", "call" : "__n( $msgid, $plural_msgid, $count, PAIRS )", "type" : "function" }, "id246" : { "call" : "$obj->fault", "name" : "fault", "id" : "id246", "type" : "i_method" }, "id760-id818" : { "extends" : "id760", "value" : "<system locale>", "name" : "locale", "id" : "id760-id818", "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "type" : "default" }, "id336" : { "id" : "id336", "name" : "textdomain_class", "value" : "Log::Report::Template::Textdomain",
"type" : "default"
},
"id745-id441" : {
"call" : "$obj->nrPlurals",
"id" : "id745-id441",
"name" : "nrPlurals",
"extends" : "id745",
"intro" : "Inherited, see Log::Report::Lexicon::Table::nrPlurals()
", "type" : "i_method" }, "id1041" : { "type" : "function", "id" : "id1041", "name" : "__px", "call" : "__px( $msgctxt, $msgid, PAIRS )" }, "id1254" : { "type" : "i_method", "intro" : "Only when initiated with a FILENAME, the file will be closed. In any\nother case, nothing will be done.
\n", "id" : "id1254", "name" : "close", "call" : "$obj->close" }, "id994" : { "id" : "id994", "name" : "locale", "type" : "option", "params" : "$locale", "intro" : "Use this specific $locale, in stead of the user's preference.
\n" }, "id853" : { "params" : "$class|REGEX", "type" : "option", "intro" : "Deprecated alternative for tag.
Inherited, see Log::Report::Lexicon::Table::pluralIndex()
" }, "id503" : { "type" : "chapter", "path" : "FUNCTIONS", "level" : 1, "id" : "id503", "name" : "FUNCTIONS", "subroutines" : [ "id506", "id510", "id508", "id509", "id505", "id507", "id504" ] }, "id191" : { "name" : "unknown reason $which in '$reasons'.", "id" : "id191", "subroutine" : "id187", "type" : "error" }, "id761-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
", "params" : "'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3", "type" : "option", "extends" : "id761", "name" : "mode", "id" : "id761-id1082" }, "id700" : { "id" : "id700", "name" : "DESCRIPTION", "nest" : [ "id701" ], "level" : 1, "type" : "chapter", "intro" : "This module helps maintaining the POT files, updating the list of\nmessage-ids which are kept in them. After initiation, the process()\nmethod needs to be called with all files which changed since last processing\nand the existing PO files will get updated accordingly.
\n\nIf no translations exist yet, one $lexicon/$domain.po file will be\ncreated. If you want to start a translation, copy $lexicon/$domain.po\nto $lexicon/$domain/$lang.po and edit that file. You may use\npoedit to edit po-files. There are many smart translation management\napplications which can hand po-files, for instance Pootle and Weblate.
Do not forget to add the new po-file to your distribution (MANIFEST)
\n", "path" : "DESCRIPTION" }, "id1218" : { "name" : "Processing", "id" : "id1218", "level" : 2, "subroutines" : [ "id1219", "id1221", "id1223", "id1225", "id1226", "id1220" ], "type" : "section", "path" : "METHODS/Processing" }, "id660" : { "type" : "error", "name" : "cannot detect charset in $fn.", "id" : "id660", "subroutine" : "id643" }, "id764-id958" : { "id" : "id764-id958", "name" : "format_reason", "extends" : "id764", "value" : "'LOWERCASE'", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
" }, "id294" : { "subroutines" : [ "id295" ], "level" : 2, "id" : "id294", "name" : "Constructors", "path" : "METHODS/Constructors", "type" : "section" }, "id620" : { "intro" : "# internal use\n my $msg = Log::Report::Message->new(\n _msgid => \"Hello World\\n\",\n _domain => 'my-domain',\n );\n\n print Log::Report::Translator::POT\n ->new(lexicons => $dir)\n ->translate($msg, 'nl-BE');\n\n # normal use (end-users view in the program's ::main)\n textdomain 'my-domain',\n translator => Log::Report::Translator::POT->new(lexicon => $dir);\n print __\"Hello World\\n\";\n\n", "path" : "SYNOPSIS", "type" : "chapter", "level" : 1, "id" : "id620", "name" : "SYNOPSIS" }, "id103" : { "id" : "id103", "name" : "Modifier: //word, //\"string\", //'string'", "level" : 3, "intro" : "
[0.91] By default, an undefined value is shown as text 'undef'. Empty\nstrings are shown as nothing. This may not be nice. You may want to\nbe more specific when a value is missing.
\n \"visitors: {count //0}\"\n \"published: {date DT//'not yet'}\"\n \"copyright: {year//2017 YEAR}\n\n\nModifiers will usually return undef when they are called with an\nundefined or empty value. By the right order of '//', you may product\ndifferent kinds of output:
\n \"price: {price//5 EUR}\"\n \"price: {price EUR//unknown}\"\n\n",
"path" : "DETAILS/Interpolation: Modifiers/Modifier: //word, //\"string\", //'string'",
"type" : "subsection"
},
"id591" : {
"chapters" : [
"id592",
"id593",
"id594",
"id595",
"id606"
],
"version" : "1.16",
"distribution" : "Log-Report-Lexicon",
"package" : "Log::Report::Lexicon::Index",
"inheritance" : {},
"id" : "id591",
"name" : "Log::Report::Lexicon::Index",
"title" : "search through available translation files",
"is_pure_pod" : false
},
"id441" : {
"id" : "id441",
"name" : "Log::Report::Lexicon::POT",
"title" : "manage PO files",
"is_pure_pod" : false,
"distribution" : "Log-Report-Lexicon",
"package" : "Log::Report::Lexicon::POT",
"inheritance" : {
"extends" : [
"Log::Report::Lexicon::Table"
]
},
"version" : "1.16",
"chapters" : [
"id442",
"id1338",
"id443",
"id444",
"id445"
]
},
"id1317" : {
"name" : "INHERITANCE",
"id" : "id1317",
"level" : 1,
"intro" : "Log::Report::Template\n is a Template\n\n", "path" : "INHERITANCE", "type" : "chapter" }, "id946" : { "name" : "SYNOPSIS", "id" : "id946", "level" : 1, "type" : "chapter", "intro" : "
sub cb($$$)\n { my ($disp, $options, $reason, $message) = @_;\n ...\n }\n\n dispatcher Log::Report::Dispatcher::Callback => 'cb',\n callback => \\&cb;\n\n dispatcher CALLBACK => 'cb', # same\n callback => \\&cb;\n\n",
"path" : "SYNOPSIS"
},
"id619" : {
"level" : 1,
"type" : "chapter",
"path" : "NAME",
"intro" : "Log::Report::Translator::POT - translation based on POT files
\n", "name" : "NAME", "id" : "id619" }, "id743-id637" : { "name" : "setupPluralAlgorithm", "id" : "id743-id637", "extends" : "id743", "intro" : "Inherited, see Log::Report::Lexicon::Table::setupPluralAlgorithm()
", "type" : "i_method", "call" : "$obj->setupPluralAlgorithm", "diagnostics" : [ "id744-id637" ] }, "id492" : { "name" : "the only acceptable parameter is 'ACTIVE', not '$p'.", "id" : "id492", "subroutine" : "id491", "type" : "error" }, "id542" : { "type" : "i_method", "intro" : "Returns a STRING which contains the cleaned paragraph of translator's\ncomment. If an argument is specified, it will replace the current\ncomment.
\n", "id" : "id542", "name" : "comment", "call" : "$obj->comment( [@lines|\\@lines|$text] )" }, "id1158-id375" : { "intro" : "Inherited, see Log::Report::Domain::translate()
", "type" : "i_method", "call" : "$obj->translate( $message, $language )", "id" : "id1158-id375", "name" : "translate", "extends" : "id1158" }, "id1137-id375" : { "intro" : "Inherited, see Log::Report::Domain::contextRules()
", "type" : "i_method", "call" : "$obj->contextRules", "id" : "id1137-id375", "name" : "contextRules", "extends" : "id1137" }, "id1322" : { "name" : "INHERITANCE", "id" : "id1322", "intro" : "MojoX::Log::Report\n is a Mojo::Log\n\n", "path" : "INHERITANCE", "type" : "chapter", "level" : 1 }, "id725" : { "chapters" : [ "id726", "id1348", "id727", "id728", "id729" ], "version" : "1.16", "distribution" : "Log-Report-Lexicon", "inheritance" : { "extended_by" : [ "Log::Report::Lexicon::MOTcompact", "Log::Report::Lexicon::POT", "Log::Report::Lexicon::POTcompact" ] }, "package" : "Log::Report::Lexicon::Table", "name" : "Log::Report::Lexicon::Table", "id" : "id725", "is_pure_pod" : false, "title" : "generic interface to translation tables" }, "id130" : { "name" : "odd length parameter list with '$msg'", "id" : "id130", "subroutine" : "id124", "type" : "error" }, "id793-id958" : { "name" : "call", "id" : "id793-id958", "extends" : "id793", "value" : "<required>", "intro" : "
Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "type" : "default" }, "id617" : { "id" : "id617", "name" : "translate", "call" : "$obj->translate( $msg, $lang, $ctxt )", "type" : "i_method" }, "id223" : { "intro" : "Get a suitable bootstrap context color for the message. This can be\nused as per the SYNOPSIS.
\n\nCSS class success is used for Dancer2::Plugin::LogReport::success()\nmessages, info colors are used for messages notice and below,\nwarning is used for warning and mistake, danger is used for\nall other messages.
Deprecated name for taggedWith().
\n", "type" : "i_method" }, "id180" : { "name" : "interpolate", "id" : "id180", "call" : "$obj->interpolate( $msgid, [$args] )", "type" : "i_method", "intro" : "Interpolate the keys used in $msgid from the values in $args.\nThis is handled by the formatter, by default a String::Print\ninstance.
\n" }, "id1048" : { "type" : "option", "params" : "LEVEL", "intro" : "This sets the default mode for all created dispatchers. You can\nalso selectively change the output mode, like
\n dispatcher PERL => 'default', mode => 3\n\n", "id" : "id1048", "name" : "mode" }, "id263" : { "level" : 3, "type" : "subsection", "path" : "DETAILS/In use/Email alerts of exceptions", "intro" : "
If you have an unexpected exception in your production application,\nthen you probably want to be notified about it. One way to do so is\nconfigure rsyslog to send emails of messages at the panic level. Use\nthe following configuration to do so:
\n\n # Normal logging from LOCAL0\n local0.* -/var/log/myapp.log\n\n # Load the mail module\n $ModLoad ommail\n # Configure sender, receiver and mail server\n $ActionMailSMTPServer localhost\n $ActionMailFrom root\n $ActionMailTo root\n # Set up an email template\n $template mailSubject,\"Critical error on %hostname%\"\n $template mailBody,\"RSYSLOG Alert\\r\\nmsg='%msg%'\\r\\nseverity='%syslogseverity-text%'\"\n $ActionMailSubject mailSubject\n # Send an email no more frequently than every minute\n $ActionExecOnlyOnceEveryInterval 60\n # Configure the level of message to notify via email\n if $syslogfacility-text == 'local0' and $syslogseverity < 3 then :ommail:;mailBody\n $ActionExecOnlyOnceEveryInterval 0\n\n\n
With the above configuration, you will only be emailed of severe errors, but can\nview the full log information in /var/log/myapp.log
\n\n=encoding UTF-8
\n", "id" : "id263", "name" : "Email alerts of exceptions" }, "id49" : { "id" : "id49", "name" : "SYNOPSIS", "level" : 1, "intro" : " ### Functional interface\n\n use String::Print; # simpelest way\n use String::Print qw/printi printp/, %config;\n\n printi 'age {years}', years => 12; # to STDOUT\n my $s = sprinti 'age {years}', years => 12; # in variable\n\n # interpolation of arrays and hashes (serializers)\n printi 'price-list: {prices}', prices => \\@p, _join => \"+\";\n printi 'dump: {c}', c => \\%data;\n\n # same with positional parameters\n printp 'age %d\", 12;\n printp 'price-list: %.2f', \\@prices;\n printp 'dump: %s', \\%settings;\n my $s = sprintp 'age %d\", 12;\n\n # modifiers\n printi 'price: {price%.2f}', price => 3.14 * EURO;\n\n # [0.91] more complex interpolation names\n printi 'filename: {c.filename}', c => \\%data;\n printi 'username: {user.name}', user => $user_object;\n printi 'price: {product.price €}', product => $db->product(3);\n\n ### Object Oriented interface\n\n use String::Print 'oo', %config; # import no functions\n my $f = String::Print->new(%config);\n $f->printi('age {years}', years => 12);\n $f->printp('age %d', 12);\n my $s = $f->sprinti('age {y}', y => 12);\n my $s = $f->sprintp('age %d', 12);\n\n ### via Log::Report's __* functions (optional translation)\n\n use Log::Report; # or Log::Report::Optional\n print __x\"age {years}\", years => 12;\n\n ### via Log::Report::Template (Template Toolkit extension)\n\n [% SET name = 'John Doe' %]\n [% loc(\"Dear {name},\") %] # includes translation\n\n",
"path" : "SYNOPSIS",
"type" : "chapter"
},
"id783" : {
"id" : "id783",
"name" : "skipStack",
"call" : "$obj->skipStack",
"type" : "i_method",
"intro" : "[1.13] Returns the number of nestings in the stack which should be skipped\nto get outside the Log::Report (and related) modules. The end-user\ndoes not want to see those internals in stack-traces.
\n" }, "id54" : { "id" : "id54", "name" : "modifiers", "intro" : "Add one or more modifier handlers to power of the formatter. They will\nget preference over the predefined modifiers, but lower than the modifiers\npassed to print[ip] itself.
Automatically added comments.\nSee addAutomatic().
\n", "type" : "option", "params" : "\\@text", "name" : "automatic", "id" : "id530" }, "id345" : { "type" : "error", "id" : "id345", "name" : "translation function '$func' already in use by textdomain '$name'", "subroutine" : "id342" }, "id733" : { "id" : "id733", "name" : "Managing PO's", "level" : 2, "nest" : [ "id734", "id737" ], "path" : "METHODS/Managing PO's", "type" : "section" }, "id440-id697" : { "id" : "id440-id697", "name" : "no context tags allowed in plural `$msgid'", "extends" : "id440", "subroutine" : "id439", "type" : "error", "intro" : "Inherited, see Log::Report::Extract::store()
" }, "id605" : { "type" : "example", "intro" : " my @l = $index->list('my-domain');\n my @l = $index->list('my-domain', 'po');\n my @l = $index->list('my-domain', qr/^readme/i);\n\n",
"id" : "id605"
},
"id235" : {
"intro" : " fatal_handler sub {\n my ($dsl, $msg, $reason) = @_;\n return if $dsl->app->request->uri !~ m!^/api/!;\n status $reason eq 'PANIC' ? 'Internal Server Error' : 'Bad Request';\n $dsl->send_as(JSON => {\n error => 1,\n error_description => $msg->toString,\n }, {\n content_type => 'application/json; charset=UTF-8',\n });\n };\n\n",
"type" : "example",
"name" : "Error handler based on URL (e.g. API)\n",
"id" : "id235"
},
"id765" : {
"id" : "id765",
"name" : "charset",
"intro" : "Convert the messages in the specified character-set (codeset). By\ndefault, no conversion will take place, because the right choice cannot\nbe determined automatically.
\n", "type" : "option", "params" : "CHARSET" }, "id1236" : { "type" : "default", "value" : "<required>", "id" : "id1236", "name" : "to" }, "id285" : { "type" : "i_method", "call" : "$obj->log( $level, $params )", "id" : "id285", "name" : "log" }, "id716" : { "type" : "error", "subroutine" : "id708", "id" : "id716", "name" : "count missing in $function in line $line." }, "id618" : { "id" : "id618", "name" : "Log::Report::Translator::POT", "is_pure_pod" : false, "title" : "translation based on POT files", "distribution" : "Log-Report-Lexicon", "inheritance" : { "extends" : [ "Log::Report::Translator" ] }, "package" : "Log::Report::Translator::POT", "version" : "1.16", "chapters" : [ "id619", "id1334", "id620", "id621", "id622" ] }, "id142" : { "call" : "alert( $message )", "name" : "alert", "id" : "id142", "type" : "function" }, "id1343" : { "type" : "chapter", "path" : "INHERITANCE", "intro" : "Log::Report::Dispatcher::LogDispatch\n is a Log::Report::Dispatcher\n\n", "level" : 1, "name" : "INHERITANCE", "id" : "id1343" }, "id923" : { "intro" : "
print $msg->toHTML('NL');\n\n",
"type" : "example",
"id" : "id923"
},
"id1015" : {
"name" : "warning",
"id" : "id1015",
"call" : "warning( $message )",
"type" : "function",
"intro" : "Short for report WARNING => $message
# use internally only\n\n", "path" : "SYNOPSIS", "type" : "chapter", "name" : "SYNOPSIS", "id" : "id811" }, "id1280" : { "id" : "id1280", "name" : "Processing the message", "level" : 2, "type" : "section", "nest" : [ "id1281", "id1282" ], "path" : "DETAILS/Processing the message" }, "id61" : { "value" : "<warning>", "id" : "id61", "name" : "missing_key", "type" : "default" }, "id1139-id375" : { "params" : "Log::Report::Translator|\\%config", "type" : "option", "intro" : "
Inherited, see Log::Report::Domain::configure(translator)
", "extends" : "id1139", "name" : "translator", "id" : "id1139-id375" }, "id438-id697" : { "subroutine" : "id437", "extends" : "id438", "id" : "id438-id697", "name" : "starting new textdomain $domain, template in $filename", "intro" : "Inherited, see Log::Report::Extract::write()
", "type" : "info" }, "id498" : { "call" : "$obj->stats", "id" : "id498", "name" : "stats", "intro" : "Returns a HASH with some statistics about this POT table.
\n", "type" : "i_method" }, "id351" : { "name" : "write_tables", "id" : "id351", "params" : "BOOLEAN", "type" : "option", "intro" : "When false, the po-files will not get updated.
When you pass an open $fh, you are yourself responsible that\nthe correct character-encoding (binmode) is set. When the write\nfollowed a read() or the filename was explicitly set with filename(),\nthen you may omit the first parameter.
\n", "type" : "i_method", "options" : [ [ "id476", "id477" ] ], "call" : "$obj->write( [$filename|$fh], %options )", "diagnostics" : [ "id478", "id479", "id480" ], "id" : "id475", "name" : "write" }, "id548" : { "id" : "id548", "name" : "removeReferencesTo", "call" : "$obj->removeReferencesTo( $filename )", "type" : "i_method", "intro" : "Remove all the references to the indicate $filename from the list. Returns\nthe number of refs left.
\n" }, "id791-id1228" : { "name" : "linenr", "id" : "id791-id1228", "value" : "<required>", "extends" : "id791", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
" }, "id1270" : { "path" : "DETAILS/Processing the message/Addition information", "type" : "subsection", "id" : "id1270", "name" : "Addition information", "level" : 3 }, "id935" : { "intro" : " # This tries to display the $param as useful and safe as possible,\n # where you have totally no idea what its contents is.\n error __x\"illegal parameter {p UNKNOWN}.\", p => $param;\n # ---> \"illegal parameter 'accidentally passed text'.\"\n # ---> \"illegal parameter Unexpected::Object::Type.\"\n\n # fault() adds \": $!\", with $! translated when configured.\n open my($fh), \"<:encoding(utf-8)\", $filename\n \t or fault __x\"cannot read {file}\", file => $filename;\n\n # Auto-abbreviation\n trace __x\"first lines: '{text EL}'\\n\", text => $t;\n # ---> \"first lines: 'This text is long, we sho⋯'.\\n\"\n\n trace __x\"first lines: {text CHOP}\\n\", text => $t;\n # ---> \"This text is long, we [+3712 chars]\\n\"\n\n info __x\"file {file} size {size BYTES}\\n\", file => $fn, size => -s $fn;\n # --> \"/etc/passwd size 23kB\\n\"\n\n # HASH or object values\n print __x\"Name: {user.first} {user.surname}\\n\", user => $login;\n\n\nThere are more nice standard interpolation modifiers, and you can add\nyour own. Besides, you can add serializers which determine how\nobjects are inlined.
\n", "type" : "example", "id" : "id935", "name" : "using format features\n" }, "id985" : { "call" : "report( [\\%options], $reason, $message|<$text,%params>, )", "examples" : [ "id998" ], "diagnostics" : [ "id999", "id1000", "id1001", "id1002" ], "intro" : "The report function is sending (for some $reason) a $message to be\ndisplayed or logged (by a `dispatcher'). This function is the core\nfor error(), info() etc functions, which are nicer names for this\nexception throwing: better use those short names.
The optional %options are listed below. Quite differently from other\nfunctions and methods, they have to be passed in a HASH as first parameter.
\n\nThe $reason is a string like 'ERROR' (for function error()).\nThe $message is a Log::Report::Message object (which is created with\nthe special translation syntax like __x()).
The message may also be a plain piece of $text, or a\nLog::Report::Exception object. The %params can be used to influence\nthe dispatchers, like real message objects can.
\n\nThis function returns the LIST of dispatchers which accepted the $message.\nWhen empty, no back-end has accepted it so the $message was \"lost\".\nEven when no back-end needs the message, the program will still exit\nwhen there is a $reason to die().
dispatcher Log::Dispatcher::File => mylog =>,\n accept => 'MISTAKE-', # for wrapper\n locale => 'pt_BR', # other language\n filename => 'logfile'; # for back-end\n\n dispatcher close => 'mylog'; # cleanup\n my $obj = dispatcher find => 'mylog';\n my @obj = dispatcher 'list';\n dispatcher disable => 'syslog';\n dispatcher enable => 'mylog', 'syslog'; # more at a time\n dispatcher mode => 'DEBUG', 'mylog';\n dispatcher mode => 'DEBUG', 'ALL';\n my $catcher = dispatcher 'active-try';\n dispatcher 'do-not-reopen';\n\n my @need_info = dispatcher needs => 'INFO';\n if(dispatcher needs => 'INFO') ... # anyone needs INFO\n\n # Getopt::Long integration: see Log::Report::Dispatcher::mode()\n dispatcher PERL => 'default', mode => 'DEBUG', accept => 'ALL'\n if $debug;\n\n", "type" : "example" }, "id612" : { "name" : "NAME", "id" : "id612", "level" : 1, "path" : "NAME", "intro" : "
Log::Report::Translator::Gettext - the GNU gettext infrastructure
\n", "type" : "chapter" }, "id1211" : { "call" : "$obj->report_opts", "name" : "report_opts", "id" : "id1211", "type" : "i_method" }, "id1060" : { "type" : "function", "intro" : "[1.00] Without CONFIGuration, this returns the Log::Report::Domain object\nwhich administers the $domain, by default the domain effective in the scope\nof the package.
\n\nA very special case is \"DELETE\", which will remove the domain\nconfiguration. [1.20] \"EXISTS\" will check for existence: when it exists,\nit will be returned, but a domain will not be automagically created.
\n\n[1.20] You may also pass a pre-configured domain.
\n", "id" : "id1060", "name" : "textdomain", "call" : "textdomain( <[$name],$config>|<$name, 'DELETE'|'EXISTS'>|$domain )" }, "id963" : { "type" : "section", "path" : "DESCRIPTION/Categories", "intro" : "Log::Report uses text-domains for translation tables. These are\nalso used as categories for the Log4perl infrastructure. So, typically\nevery module start with:
\n use Log::Report 'my-text-domain', %more_options;\n\n\n
Now, if there is a logger inside the log4perl configuration which is\nnamed 'my-text-domain', that will be used. Otherwise, the name of the\ndispatcher is used to select the logger.
\n", "level" : 2, "nest" : [ "id964" ], "id" : "id963", "name" : "Categories" }, "id437-id697" : { "intro" : "Inherited, see Log::Report::Extract::write()
", "type" : "i_method", "call" : "$obj->write( [$domain], %options )", "diagnostics" : [ "id438-id697" ], "id" : "id437-id697", "name" : "write", "extends" : "id437" }, "id497" : { "id" : "id497", "name" : "keepReferencesTo", "call" : "$obj->keepReferencesTo( $table )", "type" : "i_method", "intro" : "Remove all references which are not found as key in the hash $table.\nReturns the number of references left.
\n" }, "id547" : { "call" : "$obj->addReferences( $locations|@locations|\\@locations )", "id" : "id547", "name" : "addReferences", "intro" : "A single scalar contains a blank separated list of @locations. The LIST\nand ARRAY contain separate @locations. A LOCATION is of the form\nfilename:linenumber. Returns the internal HASH with references.
Inherited, see Log::Report::Dispatcher::new(mode)
", "type" : "option", "params" : "'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3" }, "id873" : { "name" : "_plural", "id" : "id873", "params" : "$msgid", "type" : "option", "intro" : "Can be used together with _count. This plural form of the _msgid\ntext is used to simplify the work of translators, and as fallback when\nno translation is possible: therefore, this can best resemble an\nEnglish message.
\n\nWhite-space at the beginning and end of the string are stripped off.\nThe white-space provided by the _msgid will be used.
\n" }, "id939" : { "name" : "Avoiding repetative translations", "id" : "id939", "level" : 3, "type" : "subsection", "path" : "DETAILS/Automatic parameters/Avoiding repetative translations", "intro" : "This way of translating is somewhat expensive, because an object to\nhandle the Log::Report::__x() is created each time.
\n for my $i (1..100_000)\n { print __x \"Hello World {i}\\n\", i => $i;\n }\n\n\nThe suggestion that Locale::TextDomain makes to improve performance,\nis to get the translation outside the loop, which only works without\ninterpolation:
\n\n use Locale::TextDomain;\n my $i = 42;\n my $s = __x(\"Hello World {i}\\n\", i => $i);\n foreach $i (1..100_000)\n { print $s;\n }\n\n\nOops, not what you mean because the first value of $i is captured\nin the initial message object. With Log::Report, you can do it (except\nwhen you use contexts)
\n use Log::Report;\n my $i;\n my $s = __x(\"Hello World {i}\\n\", i => \\$i);\n foreach $i (1..100_000)\n { print $s;\n }\n\n\nMind you not to write: for my $i in above case!!!!
You can also write an incomplete translation:
\n\n use Log::Report;\n my $s = __x \"Hello World {i}\\n\";\n foreach my $i (1..100_000)\n { print $s->(i => $i);\n }\n\n\nIn either case, the translation will be looked-up only once.
\n" }, "id989" : { "name" : "errno", "id" : "id989", "value" : "$! or 1",
"type" : "default"
},
"id303" : {
"type" : "i_method",
"call" : "$obj->pattern",
"name" : "pattern",
"id" : "id303"
},
"id864" : {
"name" : "METHODS",
"id" : "id864",
"level" : 1,
"nest" : [
"id865",
"id903",
"id918"
],
"path" : "METHODS",
"type" : "chapter"
},
"id1284" : {
"id" : "id1284",
"name" : "Available back-ends",
"level" : 2,
"path" : "DETAILS/Available back-ends",
"type" : "section"
},
"id643" : {
"diagnostics" : [
"id646",
"id647",
"id648",
"id649",
"id650",
"id651",
"id652",
"id653",
"id654",
"id655",
"id656",
"id657",
"id658",
"id659",
"id660",
"id661"
],
"name" : "read",
"id" : "id643",
"call" : "$class->read( $filename, %options )",
"type" : "c_method",
"options" : [
[
"id644",
"id645"
]
],
"intro" : "Read the MOT table information from $filename.
\n" }, "id1141" : { "name" : "native_language", "id" : "id1141", "type" : "option", "params" : "CODESET", "intro" : "This is the language which you have used to write the translatable and\nthe non-translatable messages in. In case no translation is needed,\nyou still wish the system error messages to be in the same language\nas the report. Of course, each textdomain can define its own.
\n" }, "id800-id958" : { "params" : "INTEGER", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "extends" : "id800", "id" : "id800-id958", "name" : "abstract" }, "id457" : { "type" : "default", "name" : "plural_alg", "id" : "id457", "value" : "n!=1"
},
"id974" : {
"type" : "section",
"path" : "METHODS/Attributes",
"level" : 2,
"id" : "id974",
"name" : "Attributes",
"subroutines" : [
"id771-id958",
"id774-id958",
"id775-id958",
"id772-id958",
"id773-id958",
"id975"
]
},
"id484" : {
"call" : "$obj->filename",
"id" : "id484",
"name" : "filename",
"intro" : "Returns the filename, as derived from read() or specified during\ninitiation with new(filename).
\n", "type" : "i_method" }, "id824" : { "type" : "overload", "intro" : "When $@ is used the traditional way, it is checked to have\na string content. In this case, stringify into the fatal error\nor nothing.
Keep the information about these filename, either specified as ARRAY of\nnames, or a HASH where the keys are the named.
\n", "type" : "option", "params" : "HASH|ARRAY", "name" : "keep", "id" : "id434" }, "id1000" : { "type" : "error", "subroutine" : "id985", "name" : "odd length parameter list with '$msg'.", "id" : "id1000" }, "id391" : { "type" : "default", "value" : "undef",
"id" : "id391",
"name" : "lang"
},
"id479" : {
"subroutine" : "id475",
"name" : "no filename or file-handle specified for PO.",
"id" : "id479",
"type" : "error"
},
"id458" : {
"id" : "id458",
"name" : "plural_forms",
"type" : "option",
"params" : "RULE",
"intro" : "[0.992] When this option is used, it overrules nr_plurals and\nplural_alg. The RULE should be a full \"Plural-Forms\" field.
\n" }, "id745-id569" : { "intro" : "Inherited, see Log::Report::Lexicon::Table::nrPlurals()
", "type" : "i_method", "call" : "$obj->nrPlurals", "extends" : "id745", "id" : "id745-id569", "name" : "nrPlurals" }, "id1274" : { "id" : "id1274", "name" : "Translation", "level" : 3, "subroutines" : [ "id668", "id667" ], "type" : "subsection", "path" : "METHODS/Managing PO's/Translation" }, "id1224" : { "id" : "id1224", "name" : "printing exceptions\n", "type" : "example", "intro" : "print $_->toString for $@->exceptions;\n print $_ for $@->exceptions; # via overloading\n\n" }, "id113" : { "id" : "id113", "name" : "String::Print compared to other modules on CPAN", "level" : 2, "intro" : "
There are a quite a number of modules on CPAN which extend the functionality\nof printf(). To name a few:\nString::Format,\nString::Errf,\nString::Formatter,\nText::Sprintf::Named,\nAcme::StringFormat,\nText::sprintf,\nLog::Sprintf, and\nString::Sprintf.\nThey are all slightly different.
When the String::Print module was created, none of the modules\nmentioned above handled unicode correctly. Global configuration\nof serializers and modifiers is also usually not possible, sometimes\nprovided per explicit function call. Only String::Print cleanly\nseparates the roles of serializers, modifiers, and conversions.
String::Print is nicely integrated with Log::Report.
Inherited, see Log::Report::Lexicon::Table::pluralIndex()
", "type" : "error", "subroutine" : "id741", "id" : "id742-id441", "name" : "there is no Plural-Forms field in the header, but needed.", "extends" : "id742" }, "id349" : { "type" : "option", "params" : "CHARSET", "name" : "charset", "id" : "id349" }, "id274" : { "type" : "example", "intro" : "my $lexicon = $directory; # f.i. $directory/<domain>/nl_NL.utf-8.po\n my $tables = Log::Report::Translator::POT->new(lexicon => $lexicon);\n (engine 'template')->addTextdomain(name => 'mydomain')->configure(translator => $tables);\n\n", "id" : "id274" }, "id571" : { "level" : 1, "intro" : "
# using a PO table efficiently\n my $pot = Log::Report::Lexicon::POTcompact->read('po/nl.po')\n or die;\n\n my $header = $pot->msgid('');\n print $pot->msgstr('msgid', 3);\n\n",
"path" : "SYNOPSIS",
"type" : "chapter",
"id" : "id571",
"name" : "SYNOPSIS"
},
"id609" : {
"type" : "section",
"intro" : "The exact gettext defined format of the locale is
\n language[_territory[.codeset]][@modifier]\n\nThe modifier will be used in above directory search, but only if provided\nexplicitly.\n\n
The manual info gettext determines the rules. During the search,\ncomponents of the locale get stripped, in the following order:
The normalized codeset (character-set name) is derived by
\nTo speed-up the search for the right table, the full directory tree\nwill be indexed only once when needed the first time. The content of\nall defined lexicon directories will get merged into one tree.
\n", "path" : "DETAILS/Locale search", "level" : 2, "name" : "Locale search", "id" : "id609" }, "id136" : { "id" : "id136", "name" : "info", "call" : "info( $message )", "type" : "function" }, "id239" : { "type" : "i_method", "name" : "trace", "id" : "id239", "call" : "$obj->trace" }, "id186" : { "path" : "FUNCTIONS/Reasons", "type" : "section", "subroutines" : [ "id194", "id193", "id187", "id192" ], "name" : "Reasons", "id" : "id186", "level" : 2 }, "id289" : { "distribution" : "Log-Report-Template", "inheritance" : { "extends" : [ "Log::Report::Extract" ] }, "package" : "Log::Report::Template::Extract", "name" : "Log::Report::Template::Extract", "id" : "id289", "is_pure_pod" : false, "title" : "collect translatable strings from template files", "chapters" : [ "id290", "id1336", "id291", "id292", "id293", "id316" ], "version" : "1.05" }, "id769" : { "type" : "error", "name" : "Perl does not support charset $cs", "id" : "id769", "subroutine" : "id756" }, "id586" : { "type" : "i_method", "intro" : "[1.09] Returns the character-set of the strings found in the file. They will\nget translated into utf8 before being used in Perl.
\n", "name" : "originalCharset", "id" : "id586", "call" : "$obj->originalCharset" }, "id452" : { "id" : "id452", "name" : "version", "type" : "option", "params" : "STRING" }, "id536" : { "id" : "id536", "name" : "no msgid defined for PO.", "subroutine" : "id517", "type" : "error" }, "id729" : { "path" : "METHODS", "nest" : [ "id730", "id732", "id733" ], "type" : "chapter", "level" : 1, "id" : "id729", "name" : "METHODS" }, "id171" : { "type" : "i_method", "call" : "$obj->isConfigured", "id" : "id171", "name" : "isConfigured" }, "id710" : { "type" : "default", "value" : "'iso-8859-1'", "id" : "id710", "name" : "charset" }, "id513" : { "path" : "SYNOPSIS", "type" : "chapter", "name" : "SYNOPSIS", "id" : "id513", "level" : 1 }, "id297" : { "type" : "default", "id" : "id297", "name" : "domain", "value" : "<required>" }, "id711" : { "subroutine" : "id708", "id" : "id711", "name" : "cannot read perl from file $filename: $!", "type" : "fault" }, "id99" : { "intro" : "The full pattern is pretty complex: %[+ -0]?[0-9]*[_,.]?d, POSIX\nformat style with a few extra features. The middle (optional) digits tell\nthe minimal size of the integer to be displayed. The optional character\nbefore it says: + will add a '+' sign when positive, 'blank' adds one\nblank before the digits when positive, a 0 pads left with zeros instead\nof blanks. Finally, a C<-> means left-align padding blanks on the right.
[0.96] The last pattern is only useful when you print (big) decimals:\nadd an underscore, comma, or dot on the thousands.
\n\n printi \"{count%_d}\\n\", count => 1e9; # 1_000_000_000\n printi \"{count%,d}\\n\", count => 1e9; # 1,000,000,000\n printi \"{count%.d}\\n\", count => 1e9; # 1.000.000.000\n\n printi \"'{v%10.d}'\", v => 10000; # ' 10.000';\n printi \"'{v%10_d}'\", v => -10000; # ' -10_000';\n printi \"'{v%-10.d}'\", v => 10000; # '10.000 ';\n printi \"'{v%-10.d}'\", v => -10000; # '-10.000 ';\n printi \"'{v%+10,d}'\", v => 10000; # ' +10,000';\n printi \"'{v% ,d}'\", v => 10000; # ' 10,000';\n printi \"'{v% ,d}'\", v => -10000; # '-10,000';\n\n\n[1.00] You can set the default FORMAT separator:
\n use String::Print\n defaults => [ FORMAT => { thousands => ',' } ];\n\n # or\n my $sp = String::Print->new(\n defaults => { FORMAT => { thousands => ',' }},\n );\n\n # or\n $sp->setDefaults(FORMAT => { thousands => ',' });\n\n",
"path" : "DETAILS/Interpolation: Modifiers/Modifier: POSIX format starts with '%'/POSIX modifier extensions '%d'",
"type" : "subsubsection",
"level" : 4,
"name" : "POSIX modifier extensions '%d'",
"id" : "id99"
},
"id170" : {
"type" : "i_method",
"name" : "name",
"id" : "id170",
"call" : "$obj->name"
},
"id1225" : {
"type" : "i_method",
"intro" : "[1.11] Calls toString() and then escapes HTML volatile characters.
\n", "id" : "id1225", "name" : "toHTML", "call" : "$obj->toHTML( [$locale] )" }, "id422-id289" : { "value" : "'utf-8'", "extends" : "id422", "id" : "id422-id289", "name" : "charset", "type" : "default", "intro" : "Inherited, see Log::Report::Extract::new(charset)
" }, "id1098" : { "id" : "id1098", "name" : "identity", "params" : "$program", "type" : "option" }, "id1021" : { "call" : "panic( $message )", "id" : "id1021", "name" : "panic", "intro" : "Short for report PANIC => $message
When defined, this location is used in the display. Otherwise, it\nis determined automatically if needed. An empty string will disable\nany attempt to display this line.
\n", "id" : "id992", "name" : "location" }, "id298" : { "intro" : "See the DETAILS section below for a detailed explenation.
\n", "type" : "option", "params" : "PREDEFINED|CODE", "id" : "id298", "name" : "pattern" }, "id275" : { "type" : "i_method", "intro" : "Renders the template. The first arg is a filename for the template file\nor a reference to a string that contains the template. The second arg\nis a hashref for the tokens that you wish to pass to\nmanual Template::Toolkit for rendering.
\n\nWhen a translation language is set, then this renderer adds the following\nvariables: language (like \"nl\"), language_territory (like \"nl_BE\"),\nand locale (like \"nl_BE.utf8\").
Log::Report::Lexicon::POTcompact - use translations from a POT file
\n", "level" : 1, "name" : "NAME", "id" : "id570" }, "id773" : { "type" : "i_method", "intro" : "Returns the mode in use for the dispatcher as number. See new(mode)\nand Run modes.
\n", "id" : "id773", "name" : "mode", "call" : "$obj->mode" }, "id485" : { "type" : "i_method", "intro" : "Returns the language code, which is derived from the filename.
\n", "name" : "language", "id" : "id485", "call" : "$obj->language" }, "id1285" : { "nest" : [ "id1286", "id1287" ], "path" : "DETAILS/Processing the message", "type" : "section", "name" : "Processing the message", "id" : "id1285", "level" : 2 }, "id825" : { "type" : "chapter", "path" : "METHODS", "nest" : [ "id826", "id836", "id843", "id847" ], "level" : 1, "name" : "METHODS", "id" : "id825" }, "id428-id289" : { "call" : "$obj->domains", "extends" : "id428", "name" : "domains", "id" : "id428-id289", "intro" : "Inherited, see Log::Report::Extract::domains()
", "type" : "i_method" }, "id766-id1174" : { "id" : "id766-id1174", "name" : "charset", "value" : "undef",
"extends" : "id766",
"intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
", "type" : "default" }, "id390" : { "params" : "LANGUAGES", "type" : "option", "intro" : "[1.01] Initial language to translate to. Usually, this language which change\nfor each user connection via translateTo().
\n", "name" : "lang", "id" : "id390" }, "id1261" : { "type" : "section", "path" : "METHODS/Attributes", "level" : 2, "id" : "id1261", "name" : "Attributes" }, "id1010" : { "subroutines" : [ "id1013", "id1017", "id1019", "id1012", "id1015", "id1016", "id1020", "id1011", "id1014", "id1021", "id1018" ], "level" : 2, "intro" : "The following functions are all wrappers for calls to report(),\nand available when \"syntax is SHORT\" (by default, see import()).\nYou cannot specify additional options to influence the behavior of\nreport(), which are usually not needed anyway.
Inherited, see Log::Report::Dispatcher::new(mode)
", "type" : "default" }, "id997" : { "id" : "id997", "name" : "is_fatal", "value" : "<depends on reason>", "type" : "default" }, "id796-id1228" : { "type" : "option", "params" : "INTEGER", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "id" : "id796-id1228", "name" : "max_line", "extends" : "id796" }, "id463" : { "type" : "default", "id" : "id463", "name" : "date", "value" : "now" }, "id744-id569" : { "intro" : "Inherited, see Log::Report::Lexicon::Table::setupPluralAlgorithm()
", "type" : "error", "subroutine" : "id743", "extends" : "id744", "id" : "id744-id569", "name" : "invalid plural-form algorithm '$alg'." }, "id1071" : { "path" : "DETAILS/Error handling models/Run modes", "intro" : "The run-mode change which messages are passed to a dispatcher, the verbosity.\nIt takes a different angle than the dispatch filters: the mode changes\nbehavioral aspects of the messages, which are described in detail in\nProcessing the message. However, it should\nbehave as you expect: the DEBUG mode shows more than the VERBOSE mode,\nand both show more than the NORMAL mode.
\n", "type" : "subsection", "examples" : [ "id1072", "id1073", "id1074" ], "level" : 3, "name" : "Run modes", "id" : "id1071" }, "id801-id958" : { "name" : "abstract", "id" : "id801-id958", "value" : "1", "extends" : "id801", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "type" : "default" }, "id833" : { "name" : "hide", "id" : "id833", "value" : "'NONE'", "type" : "default" }, "id1275" : { "subroutines" : [ "id741-id637", "id745-id637", "id743-id637", "id746-id637", "id738-id637", "id739-id637" ], "level" : 3, "id" : "id1275", "name" : "Administration", "path" : "METHODS/Managing PO's/Administration", "type" : "subsection" }, "id883" : { "params" : "$tags|\\@tags", "type" : "option", "intro" : "When messages are used for exception based programming, you add a\n_tag parameter to the argument list. Later, with for instance\nLog::Report::Dispatcher::Try::wasFatal(tag), you can check the\ncategory (group, class) of the exception.
\n\nThe $tags is interpreted as comma- and/or blank separated list of class\ntokens (barewords), the ARRAY lists all tags separately. See tags().
\n", "id" : "id883", "name" : "_tag" }, "id356" : { "type" : "default", "value" : "qr/\\.tt2?$/", "name" : "filename_match", "id" : "id356" }, "id427-id289" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Extract::charset()
", "name" : "charset", "id" : "id427-id289", "extends" : "id427", "call" : "$obj->charset" }, "id423" : { "subroutine" : "id418", "id" : "id423", "name" : "extractions require an explicit lexicon directory.", "type" : "error" }, "id865" : { "type" : "section", "path" : "METHODS/Constructors", "name" : "Constructors", "id" : "id865", "level" : 2, "subroutines" : [ "id901", "id866" ] }, "id1081" : { "level" : 3, "type" : "subsection", "path" : "DETAILS/Compared to other solutions in Perl/Locale::gettext and Locate::TextDomain", "intro" : "Both on GNU gettext based implementations can be used as translation\nframeworks. Locale::TextDomain syntax is supported, with quite some\nextensions. Read the excellent documentation of Locale::TextDomain.\nOnly the tried access via $__ and %__ are not supported.
The main difference with these modules is the moment when the translation\ntakes place. In Locale::TextDomain, an __x() will result in an\nimmediate translation request via gettext(). Log::Report's version\nof __x() will only capture what needs to be translated in an object.\nWhen the object is used in a print statement, only then the translation\nwill take place. This is needed to offer ways to send different\ntranslations of the message to different destinations.
To be able to postpone translation, objects are returned which stringify\ninto the translated text.
\n", "name" : "Locale::gettext and Locate::TextDomain", "id" : "id1081" }, "id816" : { "type" : "default", "id" : "id816", "name" : "on_die", "value" : "'ERROR'" }, "id1151" : { "subroutine" : "id1149", "id" : "id1151", "name" : "unsupported context file type for $fn", "type" : "error" }, "id292" : { "level" : 1, "path" : "DESCRIPTION", "intro" : "This module helps maintaining the POT files which list translatable\nstrings from template files (or other flat text files) by updating the\nlist of message-ids which are kept in them.
\n\nAfter initiation, the process() method needs to be called for each file\nin the domain and the existing PO files will get updated accordingly.
\n\nIf no translations exist yet, one $textdomain.po file will be\ncreated as point to start. Copy that file into $textdomain/$lang.po
# long syntax example\n report TRACE => \"start processing now\";\n report INFO => '500: ' . __'Internal Server Error';\n\n # explicit dispatcher, no translation\n report {to => 'syslog'}, NOTICE => \"started process $$\";\n notice \"started process $$\", _to => 'syslog'; # same\n\n # short syntax examples\n trace \"start processing now\";\n warning __x'Disk {percent%.2f}% full', percent => $p\n if $p > 97;\n\n # error message, overruled to be printed in Brazilian\n report {locale => 'pt_BR'},\n WARNING => \"do this at home!\";\n\n",
"type" : "example",
"name" : "for use of report()\n",
"id" : "id998"
},
"id1065" : {
"type" : "section",
"path" : "DETAILS/Introduction",
"intro" : "Getting messages to users and logs. The distincting concept of this module,\nis that three tasks which are strongly related are merged into one simple\nsyntax. The three tasks:
\n\nText messages in Perl are produced by commands like print, die,\nwarn, carp, or croak. But where is that output directed to?\nTranslations is hard. There is no clean exception mechanism.
Besides, the print/warn/die together produce only three different\noutput \"levels\" with a message. Think of the variation syslog offers:\nmore than 7 levels. Many people manually implement their own tricks to\nget additional levels, like verbose and debug flags. Log::Report offers\nthat variety.
The (optional) translations use the beautiful syntax defined by\nLocale::TextDomain, with some own extensions (of course). A very\nimportant difference is that translations are delayed till the delivery\nstep: until a dispatcher actually writes your message into a file, sends\nit to syslog, or shows it on the screen. This means that the pop-up in\nthe graphical interface of the user may show the text in the language\nof the user --say Chinese in utf8--, but at the same time syslog may\nwrite the latin1 English version of the same message.
\n", "level" : 2, "nest" : [ "id1066", "id1067" ], "id" : "id1065", "name" : "Introduction" }, "id975" : { "type" : "i_method", "intro" : "Returns the Log::Log4perl::Logger object which is used for logging.\nWhen there is no specific logger for this $domain (logger with the exact\nname of the $domain) the default logger is being used, with the name of\nthis dispatcher.
\n", "name" : "logger", "id" : "id975", "call" : "$obj->logger( [$domain] )" }, "id760-id1174" : { "value" : "<system locale>", "extends" : "id760", "id" : "id760-id1174", "name" : "locale", "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "type" : "default" }, "id1233" : { "level" : 2, "name" : "Constructors", "id" : "id1233", "subroutines" : [ "id1234" ], "type" : "section", "path" : "METHODS/Constructors" }, "id177-id375" : { "intro" : "Inherited, see Log::Report::Minimal::Domain::configure(formatter)
", "type" : "default", "name" : "formatter", "id" : "id177-id375", "value" : "PRINTI",
"extends" : "id177"
},
"id934" : {
"id" : "id934",
"name" : "Interpolation with String::Print",
"level" : 3,
"examples" : [
"id935"
],
"type" : "subsection",
"path" : "DETAILS/Messages with plural forms/Interpolation with String::Print",
"intro" : "There is no way of checking beforehand whether you have provided all\nrequired values, to be interpolated in the translated string.
\n\nThis Log::Report::Message uses String::Print to handle formatted strings.\nOn object of that module is hidden in the logic of __x() and friends.
String::Print is a very capable format string processor, and you should\nreally read its manual page to see how it can help you. It would be\npossible to support an other formatter (pretty simple even), but this is\nnot (yet) supported.
\n" }, "id984" : { "subroutines" : [ "id985", "id1008", "id1003" ], "id" : "id984", "name" : "Report production and configuration", "level" : 2, "path" : "FUNCTIONS/Report production and configuration", "type" : "section" }, "id396" : { "type" : "i_method", "intro" : "Returns the name of the function which is used for translations.
\n", "name" : "function", "id" : "id396", "call" : "$obj->function" }, "id1201" : { "level" : 1, "id" : "id1201", "name" : "METHODS", "path" : "METHODS", "nest" : [ "id1202", "id1210", "id1218" ], "type" : "chapter" }, "id869" : { "id" : "id869", "name" : "_domain", "params" : "$name|$object", "type" : "option", "intro" : "The text-domain (translation table) to which this _msgid belongs.
\n\nWith this parameter, your can \"borrow\" translations from other textdomains.\nBe very careful with this (although there are good use-cases) The xgettext\nmsgid extractor may add the used msgid to this namespace as well. To\navoid that, add a harmless '+':
\n\n print __x(+\"errors\", _domain => 'global');\n\n\n
The extractor will not take the msgid when it is an expression. The '+'\nhas no effect on the string at runtime.
\n" }, "id1014" : { "intro" : "Short for report NOTICE => $message
Returns the Log::Dispatch::Output object which is used for logging.
\n", "type" : "i_method" }, "id958" : { "inheritance" : { "extends" : [ "Log::Report::Dispatcher" ] }, "package" : "Log::Report::Dispatcher::Log4perl", "distribution" : "Log-Report", "is_pure_pod" : false, "title" : "send messages to Log::Log4perl back-end", "id" : "id958", "name" : "Log::Report::Dispatcher::Log4perl", "chapters" : [ "id959", "id1344", "id960", "id961", "id965", "id1288" ], "version" : "1.45" }, "id252" : { "level" : 1, "intro" : "This chapter will guide you through the myriad of ways that you can use\nLog::Report in your Dancer2 application.
\n\nWe will set up our application to do the following:
\n\nInherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "type" : "option", "params" : "INTEGER", "extends" : "id790", "id" : "id790-id1228", "name" : "linenr" }, "id489" : { "type" : "i_method", "intro" : "Add the information from a $po into this POT. If the msgid of the $po\nis already known, that is an error.
\n", "diagnostics" : [ "id490" ], "id" : "id489", "name" : "add", "call" : "$obj->add( $po )" }, "id1128" : { "level" : 1, "type" : "chapter", "path" : "NAME", "intro" : "Log::Report::Domain - administer one text-domain
\n", "id" : "id1128", "name" : "NAME" }, "id829" : { "type" : "default", "name" : "exceptions", "id" : "id829", "value" : "[]" }, "id1039" : { "id" : "id1039", "name" : "Messages with Context", "level" : 2, "subroutines" : [ "id1040", "id1041", "id1042", "id1043" ], "type" : "section", "path" : "FUNCTIONS/Messages with Context", "intro" : "In Log::Report, the message context (mgsctxt in the PO-files --in the\ntranslation tables) can be used in a very powerful way. Read all about\nit in Log::Report::Translator::Context
The msgctxt versions of the tranditional gettext infrastructure are far\nless useful for Log::Report, because we can easily work with different\ntext domains within the same program. That should avoid most of the\naccidental translation conflicts between components of the code.
\n\nJust for compatibility with Locale::TextDomain and completeness, the\n'p' versions of above methods are supported. See examples for these\nfunctions in Locale::TextDomain.
\n\nWarnings: Functions N__p() and N__np() seem not to be usable in\nreality, hence not implemented. The script xgettext-perl and\nLog::Report::Extract::PerlPPI (both in the Log::Report::Lexicon\ndistribution) do not yet support these functions.
Register the existence of a ($msg, $msg_plural) in all POTs of\nthe $domain.
\n", "diagnostics" : [ "id440" ], "id" : "id439", "name" : "store", "call" : "$obj->store( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )" }, "id810" : { "name" : "NAME", "id" : "id810", "type" : "chapter", "path" : "NAME", "intro" : "Log::Report::Die - compatibility routines with Perl's die/croak/confess
\n", "level" : 1 }, "id474" : { "subroutine" : "id467", "id" : "id474", "name" : "failed reading from file $fn: $!", "type" : "fault" }, "id957" : { "path" : "METHODS/Logging", "type" : "section", "subroutines" : [ "id781-id944", "id785-id944", "id778-id944", "id784-id944", "id777-id944", "id780-id944", "id783-id944", "id779-id944" ], "id" : "id957", "name" : "Logging", "level" : 2 }, "id1005" : { "id" : "id1005", "name" : "only one dispatcher name accepted in SCALAR context.", "subroutine" : "id1003", "type" : "error", "intro" : "In SCALAR context, only one dispatcher name accepted The dispatcher()\nmethod returns the Log::Report::Dispatcher objects which it has accessed.\nWhen multiple names where given, it wishes to return a LIST of objects,\nnot the count of them.
\n" }, "id344" : { "name" : "directory $dir not in INCLUDE_PATH, used by $option", "id" : "id344", "subroutine" : "id342", "type" : "error" }, "id258" : { "intro" : "In its simplest form, you can now use all the\nLog::Report logging functions\nto send messages to your dispatchers (as configured in the Logger\nconfiguration):
\n\n trace \"I'm here\";\n\n warning \"Something dodgy happened\";\n\n panic \"I'm bailing out\";\n\n # Additional, special Dancer2 keyword\n success \"Settings saved successfully\";\n\n", "path" : "DETAILS/In use/Logging debug information", "type" : "subsection", "level" : 3, "name" : "Logging debug information", "id" : "id258" }, "id176" : { "type" : "option", "params" : "CODE|\\%config|'PRINTI'", "intro" : "
Selects the formatter used for the errors messages. The default is the\nstring PRINTI, which will use String::Print::printi(): interpolation\nwith curly braces around the variable names.
Your callback is called with five parameters: this dispatcher object,\nthe options, a reason and a message. The options are the first\nparameter of Log::Report::report() (read over there). The reason\nis a capitized string like ERROR. Then, the message (is a\nLog::Report::Message). Finally the text-domain of the message.
Returned is a list of filenames which is used to update the list of\nMSGIDs when source files have changed. All translation files which\nbelong to a certain $domain are listed.
\n\nThe $extension filter can be used to reduce the filenames further, for\ninstance to select only po, mo or gmo files, and ignore readme's.\nUse an string, without dot and interpreted case-insensitive, or a\nregular expression.
fatal_handler() allows alternative handlers to be defined in place of (or in\naddition to) the default redirect handler that is called on a fatal error.
Calls should be made with 1 parameter: the subroutine to call in the case of a\nfatal error. The subroutine is passed 3 parameters: the DSL, the message in\nquestion, and the reason. The subroutine should return true or false depending\non whether it handled the error. If it returns false, the next fatal handler is\ncalled, and if there are no others then the default redirect fatal handler is\ncalled.
Inherited, see Log::Report::Domain::configure()
", "type" : "warning", "subroutine" : "id1138", "id" : "id1148-id375", "name" : "Missing key '$key' in format '$format', file $use", "extends" : "id1148" }, "id131" : { "call" : "dispatcher( <$type, $name, %options>|<$command, @names> )", "id" : "id131", "name" : "dispatcher", "intro" : "Not supported.
\n", "type" : "function" }, "id95" : { "level" : 2, "type" : "section", "path" : "DETAILS/Interpolation: Serialization", "intro" : "The 'interpolation' functions have named VARIABLES to be filled-in, but\nalso additional OPTIONS. To distinguish between the OPTIONS and VARIABLES\n(both a list of key-value pairs), the keys of the OPTIONS start with\nan underscore _. As result of this, please avoid the use of keys\nwhich start with an underscore in variable names. On the other hand,\nyou are allowed to interpolate OPTION values in your strings.
There is no way of checking beforehand whether you have provided all\nvalues to be interpolated in the translated string. When you refer to\nvalue which is missing, it will be interpreted as undef.
,␣ between the elements.\nAlternatively (maybe nicer), you can pass an interpolation parameter\nvia the _join OPTION.\n\n printi \"matching files: {files}\", files => \\@files, _join => ', '\n\n\n\n\n\n $key => $value, $key2 => $value2, ...\n\n\n
There is no quoting on the keys or values (yet). Usually, this will\nproduce an ugly result anyway.
\n\n\n\nserialization parameter, you can overrule the interpolation\nof above defaults, but also add rules for your own objects. By default,\nobjects get stringified.\n\n serialization => [ $myclass => \\&name_in_reverse ]\n\n sub name_in_reverse($$$)\n { my ($formatter, $object, $args) = @_;\n # the $args are all parameters to be filled-in\n scalar reverse $object->name;\n }\n\n\nWhen the charset is not specified, it will be taken from the content-type\nfield in the po-file header.
\n", "name" : "charset", "id" : "id576" }, "id1037" : { "name" : "N__w", "id" : "id1037", "intro" : "This extension to the Locale::TextDomain syntax, is a combined\nqw (list of quoted words) and N__() into a list of translatable\nwords.
Log::Report::Dispatcher::Try\n is a Log::Report::Dispatcher\n\n", "path" : "INHERITANCE", "type" : "chapter", "level" : 1, "name" : "INHERITANCE", "id" : "id1346" }, "id172-id375" : { "type" : "i_method", "intro" : "
Inherited, see Log::Report::Minimal::Domain::format()
", "name" : "format", "id" : "id172-id375", "extends" : "id172", "call" : "$obj->format" }, "id1058" : { "subroutine" : "id1045", "name" : "textdomain `$domain' for translator not defined", "id" : "id1058", "type" : "error" }, "id564" : { "name" : "nr_plurals", "id" : "id564", "params" : "INTEGER", "type" : "option", "intro" : "If the number of plurals is specified, then the plural translation\nlist can be checked for the correct length. Otherwise, no smart\nbehavior is attempted.
\n" }, "id781" : { "call" : "$any->addSkipStack( @CODE )", "examples" : [ "id782" ], "intro" : "[1.13] Add one or more CODE blocks of caller lines which should not be\ncollected for stack-traces or location display. A CODE gets\ncalled with an ARRAY of caller information, and returns true\nwhen that line should get skipped.
Warning: this logic is applied globally: on all dispatchers.
\n", "type" : "ci_method", "name" : "addSkipStack", "id" : "id781" }, "id261" : { "name" : "Handling user errors", "id" : "id261", "path" : "DETAILS/In use/Handling user errors", "intro" : "Sometimes we write a function in a model, and it would be nice to have a\nnice easy way to return from the function with an error message. One\nway of doing this is with a separate error message variable, but that\ncan be messy code. An alternative is to use exceptions, but these\ncan be a pain to deal with in terms of catching them.\nHere's how to do it with Log::Report.
\n\nIn this example, we do use exceptions, but in a neat, easier to use manner.
\n\nFirst, your module/model:
\n\n package MyApp::CD;\n\n sub update {\n my ($self, %values) = @_;\n $values{title} or error \"Please enter a title\";\n $values{description} or warning \"No description entered\";\n }\n\n\nThen, in your controller:
\n\n package MyApp;\n use Dancer2;\n\n post '/cd' => sub {\n my %values = (\n title => param('title');\n description => param('description');\n );\n if (process sub { MyApp::CD->update(%values) } ) {\n success \"CD updated successfully\";\n redirect '/cd';\n }\n\n template 'cd' => { values => \\%values };\n }\n\n\nNow, when update() is called, any exceptions are caught. However, there is\nno need to worry about any error messages. Both the error and warning\nmessages in the above code will have been stored in the messages session\nvariable, where they can be displayed using the code in the previous section.\nThe error will have caused the code to stop running, and process()\nwill have returned false. warning will have simply logged the warning\nand not caused the function to stop running.
Be warned that %options is a HASH here.
\n", "options" : [ [ "id125", "id126" ], [ "id127", "id128" ] ], "type" : "function" }, "id731" : { "call" : "$class->new( %options )", "name" : "new", "id" : "id731", "type" : "c_method" }, "id772-id818" : { "intro" : "Inherited, see Log::Report::Dispatcher::type()
", "type" : "i_method", "call" : "$obj->type", "extends" : "id772", "id" : "id772-id818", "name" : "type" }, "id1216" : { "id" : "id1216", "type" : "example", "intro" : " $e->message->concat('!!')); # will not work!\n $e->message($e->message->concat('!!'));\n\n $e->message(__x\"some message {xyz}\", xyz => $xyz);\n\n"
},
"id402" : {
"call" : "$obj->translationFunction",
"id" : "id402",
"name" : "translationFunction",
"diagnostics" : [
"id403",
"id404",
"id405",
"id406",
"id407",
"id408"
],
"intro" : "This method returns a CODE which is able to handle a call for\ntranslation by Template Toolkit.
\n", "type" : "i_method" }, "id741-id637" : { "diagnostics" : [ "id742-id637" ], "call" : "$obj->pluralIndex( $count )", "type" : "i_method", "intro" : "Inherited, see Log::Report::Lexicon::Table::pluralIndex()
", "name" : "pluralIndex", "id" : "id741-id637", "extends" : "id741" }, "id695" : { "name" : "The msgctxt", "id" : "id695", "type" : "subsection", "intro" : "The gnutext implementation of the context is very simple. This is to\nbe expected from a library written in C. The msgctxt alternatives\nare matched against the context keywords of the message. In all or\nnone of the alternatives match, then just a random translation is\nchosen.
\n\nIn the simplest form, the msgctxt field contains a single keyword\n(not containing a comma).
\n\n msgctxt \"gender=male\"\n\n\n
But you can do more. Be warned that most (all?) existing tools\nwhich smartly edit PO-files do not understand these constructs: they\nsee the msgctxt as dump string without meaning.
\n\n msgctxt \"agegroup=baby,agegroup=grandparent\" # baby OR grandparent\n msgctxt \"gender=male agegroup=adult\" # both male AND adult\n\n\n
So, a comma separated list of alternatives. If any matches, then the\nrule is selected.
\n", "path" : "DETAILS/Using context_rules/The msgctxt", "level" : 3 }, "id1007" : { "id" : "id1007", "name" : "the 'filter' sub-command needs a CODE reference.", "subroutine" : "id1003", "type" : "error" }, "id659" : { "type" : "error", "name" : "the header is not the first entry, needed for charset in $fn.", "id" : "id659", "subroutine" : "id643" }, "id776" : { "subroutines" : [ "id781", "id785", "id778", "id784", "id777", "id780", "id783", "id779" ], "level" : 2, "name" : "Logging", "id" : "id776", "path" : "METHODS/Logging", "type" : "section" }, "id678" : { "level" : 2, "id" : "id678", "name" : "Attributes", "subroutines" : [ "id679" ], "type" : "section", "path" : "METHODS/Attributes" }, "id221" : { "type" : "chapter", "nest" : [ "id1303", "id1304", "id1305" ], "path" : "METHODS", "id" : "id221", "name" : "METHODS", "level" : 1, "subroutines" : [ "id222", "id223" ] }, "id791-id958" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "value" : "<required>", "extends" : "id791", "id" : "id791-id958", "name" : "linenr" }, "id524" : { "name" : "msgctxt", "id" : "id524", "intro" : "Context string: specifies where the msgid belongs.
\n", "type" : "option", "params" : "$context" }, "id794-id1082" : { "name" : "params", "id" : "id794-id1082", "extends" : "id794", "params" : "ARRAY", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
" }, "id164" : { "diagnostics" : [ "id168" ], "name" : "new", "id" : "id164", "examples" : [ "id167" ], "call" : "$class->new( %options )", "type" : "c_method", "options" : [ [ "id165", "id166" ] ] }, "id466" : { "subroutine" : "id447", "name" : "textdomain parameter is required.", "id" : "id466", "type" : "error" }, "id793-id1228" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "name" : "call", "id" : "id793-id1228", "extends" : "id793", "value" : "<required>" }, "id759-id818" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "params" : "LOCALE", "type" : "option", "id" : "id759-id818", "name" : "locale", "extends" : "id759" }, "id415" : { "id" : "id415", "name" : "DESCRIPTION", "type" : "chapter", "path" : "DESCRIPTION", "intro" : "This module helps maintaining the POT files, updating the list of\nmessage-ids which are kept in them. After initiation, the process()\nmethod needs to be called with all files which changed since last\nprocessing and the existing PO files will get updated accordingly. If no\ntranslations exist yet, one textdomain/xx.po file will be created.
Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "type" : "default" }, "id785-id1174" : { "call" : "$any->stackTraceLine( %options )", "name" : "stackTraceLine", "id" : "id785-id1174", "extends" : "id785", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine()
", "options" : [ [ "id800-id1174", "id801-id1174" ], [ "id792-id1174", "id793-id1174" ], [ "id788-id1174", "id789-id1174" ], [ "id790-id1174", "id791-id1174" ], [ "id796-id1174", "id797-id1174" ], [ "id798-id1174", "id799-id1174" ], [ "id786-id1174", "id787-id1174" ], [ "id794-id1174", "id795-id1174" ] ], "type" : "ci_method" }, "id408" : { "name" : "Missing key '$key' in format '$format', in $use //template", "id" : "id408", "subroutine" : "id402", "type" : "warning" }, "id1193" : { "intro" : "Returns a level which is understood by Log::Dispatch, based on\na translation table. This can be changed with new(to_level).
\n", "type" : "i_method", "call" : "$obj->reasonToLevel( $reason )", "id" : "id1193", "name" : "reasonToLevel" }, "id899-id217" : { "extends" : "id899", "name" : "_msgctxt", "id" : "id899-id217", "type" : "option", "params" : "$context", "intro" : "Inherited, see Log::Report::Message::new(_msgctxt)
" }, "id961" : { "nest" : [ "id962", "id963" ], "id" : "id961", "name" : "DESCRIPTION", "type" : "chapter", "path" : "DESCRIPTION", "intro" : "This dispatchers produces output tot syslog, based on the Sys::Log4perl\nmodule (which will not be automatically installed for you).
This basic file logger accepts an file-handle or filename as destination.
\n\n[1.00] writing to the file protected by a lock, so multiple processes\ncan write to the same file.
\n", "path" : "DESCRIPTION", "type" : "chapter" }, "id788-id944" : { "id" : "id788-id944", "name" : "filename", "extends" : "id788", "type" : "option", "params" : "STRING", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
" }, "id799-id1090" : { "extends" : "id799", "value" : "8", "name" : "max_params", "id" : "id799-id1090", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
" }, "id871" : { "intro" : "When defined, the _plural need to be defined as well. When an\nARRAY is provided, the length of the ARRAY is taken. When a HASH\nis given, the number of keys in the HASH is used.
\n", "type" : "option", "params" : "INTEGER|ARRAY|HASH", "name" : "_count", "id" : "id871" }, "id763-id1174" : { "id" : "id763-id1174", "name" : "format_reason", "extends" : "id763", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "params" : "'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE", "type" : "option" }, "id67" : { "call" : "$obj->encodeFor( \\%settings|undef|($predefined, %overrule) )", "id" : "id67", "name" : "encodeFor", "intro" : "[0.91] Enable/define the output encoding. The %settings contain the encoding\nCODE and the tag name patterns to exclude from encoding. Output for HTML\nis $predefined, but you may %overrule its settings.
Read section Output encoding about the details.
\n", "type" : "i_method" }, "id1203" : { "options" : [ [ "id1208", "id1209" ], [ "id1206", "id1207" ], [ "id1204", "id1205" ] ], "type" : "c_method", "intro" : "Create a new exception object, which is basically a message which\nwas produced for a reason.
\n", "name" : "new", "id" : "id1203", "call" : "$class->new( %options )" }, "id407" : { "subroutine" : "id402", "name" : "superfluous positional parameters for '$msgid'", "id" : "id407", "type" : "error" }, "id1035" : { "intro" : "Label to indicate that the two MSGIDs are related, the first as\nsingle, the seconds as its plural. Only used to find the text\nfragments to be translated. The function itself does nothing.
\n", "type" : "function", "examples" : [ "id1036" ], "call" : "N__n( $single_msgid, $plural_msgid )", "name" : "N__n", "id" : "id1035" }, "id921" : { "type" : "i_method", "intro" : "Translate a message. If not specified, the default locale is used.
\n", "id" : "id921", "name" : "toString", "call" : "$obj->toString( [$locale] )" }, "id777-id818" : { "extends" : "id777", "name" : "close", "id" : "id777-id818", "call" : "$obj->close", "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::close()
" }, "id813" : { "subroutines" : [ "id817", "id814" ], "name" : "FUNCTIONS", "id" : "id813", "level" : 1, "path" : "FUNCTIONS", "type" : "chapter" }, "id886" : { "type" : "default", "id" : "id886", "name" : "_tags", "value" : "[]" }, "id353" : { "params" : "$file|\\@files", "type" : "option", "intro" : "By default, all filenames from the INCLUDE_PATH directories which match\nthe filename_match are processed, but you may explicitly create a\nsubset by hand.
\n", "name" : "filenames", "id" : "id353" }, "id426" : { "type" : "i_method", "intro" : "Returns the Log::Report::Lexicon::Index object, which is listing\nthe files in the lexicon directory tree.
\n", "name" : "index", "id" : "id426", "call" : "$obj->index" }, "id1009" : { "id" : "id1009", "type" : "example", "intro" : " my $x = try { 3/$x }; # mind the ';' !!\n if($@) { # signals something went wrong\n\n if(try {...}) { # block ended normally, returns bool\n\n try { ... } # no comma!!\n mode => 'DEBUG', accept => 'ERROR-';\n\n try sub { ... }, # with comma, also \\&function\n mode => 'DEBUG', accept => 'ALL';\n\n my $response = try { $ua->request($request) };\n if(my $e = $@->wasFatal) ...\n\n"
},
"id900-id217" : {
"intro" : "Inherited, see Log::Report::Message::new(_msgctxt)
", "type" : "default", "extends" : "id900", "value" : "undef",
"name" : "_msgctxt",
"id" : "id900-id217"
},
"id672" : {
"intro" : "[Added in Log::Report v1.00]\nThe \"contexts\" concept in (GNU's version of) gettext, has a\nvery restricted purpose: to separate two (accidental) uses of the\nsame message-id, under different circumstances. The same msgid may\ntranslated diffently in one file or the other.
\n\nFor instance, two libraries used in the same application, or two\ncomponentent within a single library both want to used the same\ndefault text (which usually is very short)
\n\n char * t1 = pgettext('interface', 'None');\n char * t2 = pgettext('selections', 'None');\n\n\nSome translation setups use the library name consequently as msgctxt.\nBut, the name \"context\" is pretending much more power than the gettext\nlibraries are capable of: it usually only behaves like a namespace.
\n\nFor Log::Report, the power of \"context\" is extended with selecting\nbetween alternatives for the use of a msgid on the same spot.
\n\nFor instance, the gender of the user of the website determines whether\n`he' or `she' needs to be used in the translation. In this example,\nthe gender is set as context keyword in the message:
\n\n my ($name, $sex) = ('Jack', 'male');\n print __x\"{name<gender} found his key\", name => $name,\n _context => \"gender=$sex\";\n\n",
"path" : "DESCRIPTION",
"type" : "chapter",
"level" : 1,
"name" : "DESCRIPTION",
"id" : "id672"
},
"id836" : {
"path" : "METHODS/Attributes",
"type" : "section",
"subroutines" : [
"id771-id818",
"id774-id818",
"id775-id818",
"id772-id818",
"id773-id818",
"id837",
"id838",
"id840",
"id839",
"id842"
],
"level" : 2,
"name" : "Attributes",
"id" : "id836"
},
"id787-id944" : {
"id" : "id787-id944",
"name" : "package",
"extends" : "id787",
"value" : "<required>",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
" }, "id1227" : { "intro" : "print $exception; # via overloading\n $exception->print; # OO style\n\n", "type" : "example", "id" : "id1227" }, "id460" : { "id" : "id460", "name" : "index", "intro" : "
A set of translations (Log::Report::Lexicon::PO objects),\nwith msgid as key.
\n", "type" : "option", "params" : "HASH" }, "id1169-id611" : { "intro" : "Inherited, see Log::Report::Translator::new()
", "type" : "c_method", "call" : "$class->new( %options )", "extends" : "id1169", "id" : "id1169-id611", "name" : "new" }, "id1289" : { "level" : 2, "id" : "id1289", "name" : "Available back-ends", "path" : "DETAILS/Available back-ends", "type" : "section" }, "id914" : { "name" : "to", "id" : "id914", "call" : "$obj->to( [$name] )", "type" : "i_method", "intro" : "Returns the $name of a dispatcher if explicitly specified with\nthe '_to' key. Can also be used to set it. Usually, this will\nreturn undef, because usually all dispatchers get all messages.
my $mode = dispatcher(find => 'myname')->mode;\n\n", "type" : "example" }, "id393" : { "type" : "error", "id" : "id393", "name" : "extension to domain '$name' already exists", "subroutine" : "id392" }, "id777-id1090" : { "type" : "i_method", "intro" : "
Inherited, see Log::Report::Dispatcher::close()
", "id" : "id777-id1090", "name" : "close", "extends" : "id777", "call" : "$obj->close" }, "id842" : { "intro" : "Returns the value of new(on_die).
\n", "type" : "i_method", "call" : "$obj->die2reason", "name" : "die2reason", "id" : "id842" }, "id1263" : { "level" : 2, "name" : "Available back-ends", "id" : "id1263", "type" : "section", "path" : "DETAILS/Available back-ends" }, "id877-id217" : { "id" : "id877-id217", "name" : "_category", "extends" : "id877", "intro" : "Inherited, see Log::Report::Message::new(_category)
", "type" : "option", "params" : "INTEGER" }, "id1083" : { "id" : "id1083", "name" : "NAME", "intro" : "Log::Report::Dispatcher::Perl - send messages to die and warn
\n", "path" : "NAME", "type" : "chapter", "level" : 1 }, "id419" : { "name" : "lexicon", "id" : "id419", "params" : "$directory", "type" : "option", "intro" : "The place where the lexicon is kept. When no lexicon is defined yet,\nthis will be the $directory where an domain/xx.po file will be created.
Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "type" : "default", "name" : "max_params", "id" : "id799-id818", "extends" : "id799", "value" : "8" }, "id794-id944" : { "name" : "params", "id" : "id794-id944", "extends" : "id794", "params" : "ARRAY", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
" }, "id1279" : { "type" : "section", "path" : "DETAILS/Available back-ends", "level" : 2, "id" : "id1279", "name" : "Available back-ends" }, "id789-id1174" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
", "type" : "default", "name" : "filename", "id" : "id789-id1174", "value" : "<required>", "extends" : "id789" }, "id927-id217" : { "intro" : "Inherited, see Log::Report::Message::freeze()
", "type" : "i_method", "call" : "$obj->freeze( %options )", "extends" : "id927", "id" : "id927-id217", "name" : "freeze" }, "id1153" : { "name" : "setContext", "id" : "id1153", "examples" : [ "id1154" ], "call" : "$obj->setContext( STRING|HASH|ARRAY|PAIRS )", "diagnostics" : [ "id1155" ], "intro" : "Temporary set the default translation context for messages. This is used\nwhen the message is created without a _context parameter. The context\ncan be retrieved with defaultContext().
Contexts are totally ignored then there are no context_rules. When\nyou do not wish to change settings, you may simply provide an empty HASH.
Log::Report::Dispatcher::Callback\n is a Log::Report::Dispatcher\n\n", "type" : "chapter", "level" : 1 }, "id301" : { "type" : "section", "path" : "METHODS/Attributes", "name" : "Attributes", "id" : "id301", "level" : 2, "subroutines" : [ "id428-id289", "id430-id289", "id426-id289", "id429-id289", "id427-id289", "id302", "id303" ] }, "id1173-id611" : { "call" : "$obj->load( $domain, $locale )", "extends" : "id1173", "id" : "id1173-id611", "name" : "load", "intro" : "
Inherited, see Log::Report::Translator::load()
", "type" : "i_method" }, "id906-id217" : { "intro" : "Inherited, see Log::Report::Message::append()
", "type" : "i_method", "call" : "$obj->append", "extends" : "id906", "name" : "append", "id" : "id906-id217" }, "id895-id217" : { "extends" : "id895", "id" : "id895-id217", "name" : "_lang", "params" : "ISO", "type" : "option", "intro" : "Inherited, see Log::Report::Message::new(_lang)
" }, "id420" : { "id" : "id420", "name" : "lexicon", "value" : "<required>", "type" : "default" }, "id774-id1174" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::isDisabled()
", "extends" : "id774", "id" : "id774-id1174", "name" : "isDisabled", "call" : "$obj->isDisabled" }, "id1069" : { "type" : "subsection", "intro" : "Traditionally, perl has a very simple view on error reports: you\neither have a warning or an error. However, it would be much clearer\nfor user's and module-using applications, when a distinction is made\nbetween various causes. For instance, a configuration error is quite\ndifferent from a disk-full situation. In Log::Report, the produced\nreports in the code tell what is wrong. The main application defines\nloggers, which interpret the cause into (syslog) levels.
Defined by Log::Report are
panic.\n\n\n\nverbose flag is given on the command-line.\n\n\n\nDesktop directory in your\nhome directory. Notices should be sparse.\n\n\n\nIt is much nicer to tell someone that he/she made a mistake, than\nto call that an error.
\n\n\n\n$!. The program will be stopped, usually before taken off.\n\n\n\n$! ($ERRNO) variable is set here.\n\n\n\n$! is set. Usually, a system administrator\nneeds to be informed about the problem.\n\n\n\n$! is set, and usually the system administrator wants to be\ninformed. The program will die.\n\nThe difference with fault is subtile and not always clear. A fault\nreports an error returned by an operating system call, where the failure\nwould report an operational problem, like a failing mount.
For instance, in an OO perl module, the base class requires all\nsub-classes to implement a certain method. The base class will produce\na stub method with triggers a panic when called. The non-dieing version\nof this test assert.
Debugging or being verbose are run-time behaviors, and have nothing\ndirectly to do with the type of message which is produced. These two\nare modes which can be set on the dispatchers: one dispatcher may\nbe more verbose that some other.
On purpose, we do not use the terms die or fatal, because the\ndispatcher can be configured what to do in cause of which condition.\nFor instance, it may decide to stop execution on warnings as well.
The terms carp and croak are avoided, because the program cause\nversus user cause distinction (warn vs carp) is reflected in the use\nof different reasons. There is no need for confess and croak\neither, because the dispatcher can be configured to produce stack-trace\ninformation (for a limited sub-set of dispatchers)
undef",
"id" : "id880",
"name" : "_prepend"
},
"id878-id217" : {
"type" : "default",
"intro" : "Inherited, see Log::Report::Message::new(_category)
", "value" : "undef",
"extends" : "id878",
"name" : "_category",
"id" : "id878-id217"
},
"id84" : {
"type" : "default",
"id" : "id84",
"name" : "_append",
"value" : "undef"
},
"id1042" : {
"call" : "__np( $msgctxt, $msgid, $plural, count )",
"name" : "__np",
"id" : "id1042",
"type" : "function"
},
"id795-id1090" : {
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "type" : "default", "name" : "params", "id" : "id795-id1090", "value" : "<required>", "extends" : "id795" }, "id830" : { "intro" : "The exit string or object ($@) of the eval'ed block, in its unprocessed state.
Inherited, see Log::Report::Dispatcher::new(locale)
", "type" : "option", "params" : "LOCALE" }, "id778-id1090" : { "call" : "$obj->log( \\%options, $reason, $message, $domain )", "name" : "log", "id" : "id778-id1090", "extends" : "id778", "intro" : "Inherited, see Log::Report::Dispatcher::log()
", "type" : "i_method" }, "id848" : { "intro" : "Returns true if the block was left with an fatal message.
Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
" }, "id699" : { "name" : "SYNOPSIS", "id" : "id699", "intro" : " my $ppi = Log::Report::Extract::PerlPPI->new(\n lexicon => '/usr/share/locale',\n );\n $ppi->process('lib/My/Pkg.pm'); # call for each .pm file\n $ppi->showStats; # optional\n $ppi->write;\n\n # See script xgettext-perl\n bin/xgettext-perl -p $lexdir @source_dirs\n\n",
"path" : "SYNOPSIS",
"type" : "chapter",
"level" : 1
},
"id655" : {
"type" : "fault",
"name" : "cannot seek to $loc in $fn for msgid strings: $!",
"id" : "id655",
"subroutine" : "id643"
},
"id800-id1228" : {
"type" : "option",
"params" : "INTEGER",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "name" : "abstract", "id" : "id800-id1228", "extends" : "id800" }, "id1287" : { "level" : 3, "name" : "Filters", "id" : "id1287", "type" : "subsection", "path" : "DETAILS/Processing the message/Filters" }, "id173" : { "call" : "$obj->configure( %options )", "diagnostics" : [ "id178" ], "id" : "id173", "name" : "configure", "intro" : "Collect the settings for this domain.
\n", "type" : "i_method", "options" : [ [ "id176", "id177" ], [ "id174", "id175" ] ] }, "id511" : { "title" : "one translation definition", "is_pure_pod" : false, "id" : "id511", "name" : "Log::Report::Lexicon::PO", "package" : "Log::Report::Lexicon::PO", "inheritance" : {}, "distribution" : "Log-Report-Lexicon", "version" : "1.16", "chapters" : [ "id512", "id513", "id514", "id515" ] }, "id1229" : { "name" : "NAME", "id" : "id1229", "type" : "chapter", "intro" : "Log::Report::Dispatcher::File - send messages to a file or file-handle
\n", "path" : "NAME", "level" : 1 }, "id922-id217" : { "id" : "id922-id217", "name" : "toHTML", "extends" : "id922", "call" : "$obj->toHTML( [$locale] )", "type" : "i_method", "intro" : "Inherited, see Log::Report::Message::toHTML()
" }, "id787-id1082" : { "value" : "<required>", "extends" : "id787", "id" : "id787-id1082", "name" : "package", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "type" : "default" }, "id872-id217" : { "extends" : "id872", "value" : "undef",
"name" : "_count",
"id" : "id872-id217",
"intro" : "Inherited, see Log::Report::Message::new(_count)
", "type" : "default" }, "id111" : { "name" : "Example with Log::Report::Template", "id" : "id111", "level" : 3, "type" : "subsection", "path" : "DETAILS/Output encoding/Example with Log::Report::Template", "intro" : "In pure Template Toolkit, you would write
\n\n # in your TT-template\n <div>Username: [% username | html %]</div>\n # in your code\n username => $user->name,\n\n\n
With plain String::Print with output encoding enabled, you can do:
\n\n # in your TT-template\n <div>[% show_username %]</div>\n # in your code with encodeFor('HTML')\n show_username => printi(\"Username: {user}\", user => $user->name),\n # or\n show_username => printp(\"Username: %s\", $user->name),\n\n\nThat does not look very efficient, however it changes for the good when\nthis is combined with Log::Report::Lexicon (translations) You can\neither do:
\n\n # in your TT-template\n <div>[% show_username %]</div>\n # in your code with encodeFor('HTML')\n show_username => __x(\"Username: {user}\", user => $user->name),\n\n\nShorter:
\n\n # in your TT-template with encodeFor('HTML')\n <div>[% loc(\"Username: {user}\", user => username) %]</div>\n # in your code\n username => $user->name,\n\n\nEven shorter:
\n\n # in your TT-template with encodeFor('HTML')\n <div>[% loc(\"Username: {user.name}\", user => userobj) %]</div>\n # in your code\n userobj => $user,\n\n\nShortest:
\n\n # in your TT-template with encodeFor('HTML')\n <div>[% loc(\"Username: {user.name}\") %]</div>\n # in your code\n user => $user,\n\n\nShorter that the original, and translations for free!\nMore examples in Log::Report::Template.
\n" }, "id770" : { "id" : "id770", "name" : "Attributes", "level" : 2, "subroutines" : [ "id771", "id774", "id775", "id772", "id773" ], "type" : "section", "path" : "METHODS/Attributes" }, "id573" : { "level" : 1, "name" : "METHODS", "id" : "id573", "path" : "METHODS", "nest" : [ "id574", "id584", "id587" ], "type" : "chapter" }, "id847" : { "subroutines" : [ "id848", "id850", "id855", "id849" ], "level" : 2, "name" : "Status", "id" : "id847", "path" : "METHODS/Status", "type" : "section" }, "id772-id1090" : { "call" : "$obj->type", "name" : "type", "id" : "id772-id1090", "extends" : "id772", "intro" : "Inherited, see Log::Report::Dispatcher::type()
", "type" : "i_method" }, "id1067" : { "level" : 3, "path" : "DETAILS/Introduction/Background ideas", "intro" : "The following ideas are the base of this implementation:
\n\ngettext(). However, in the Log::Report infrastructure,\ntranslations are postponed until the text is dispatched to a screen\nor log-file; the same report can be sent to syslog in (for instance)\nEnglish and to the user interface in Dutch.\n\n\n\nundef",
"name" : "config",
"id" : "id1146"
},
"id1023" : {
"id" : "id1023",
"name" : "__",
"examples" : [
"id1024"
],
"call" : "__( $msgid )",
"type" : "function",
"intro" : "This function (name is two under-score characters) will cause the $msgid\nto be replaced by the translations when doing the actual output. Returned\nis a Log::Report::Message object, which will be used in translation\nlater. Translating is invoked when the object gets stringified. When\nyou have no translation tables, the $msgid will be shown untranslated.
\n\nIf you need options for Log::Report::Message::new() then use __x();\nthe prototype of this function does not permit parameters: it is a\nprefix operator!
\n" }, "id1277" : { "path" : "METHODS/Managing PO's/Administration", "type" : "subsection", "subroutines" : [ "id741-id441", "id745-id441", "id743-id441", "id493", "id489", "id491" ], "level" : 3, "name" : "Administration", "id" : "id1277" }, "id569" : { "id" : "id569", "name" : "Log::Report::Lexicon::POTcompact", "is_pure_pod" : false, "title" : "use translations from a POT file", "distribution" : "Log-Report-Lexicon", "inheritance" : { "extends" : [ "Log::Report::Lexicon::Table" ] }, "package" : "Log::Report::Lexicon::POTcompact", "version" : "1.16", "chapters" : [ "id570", "id1332", "id571", "id572", "id573" ] }, "id792-id1174" : { "type" : "option", "params" : "STRING", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "name" : "call", "id" : "id792-id1174", "extends" : "id792" }, "id1122" : { "name" : "SYNOPSIS", "id" : "id1122", "level" : 1, "intro" : "use MojoX::Log::Report;\n my $log = MojoX::Log::Report->new(%options);\n $app->log($log); # install logger in the Mojo::App\n\n", "path" : "SYNOPSIS", "type" : "chapter" }, "id226" : { "name" : "SYNOPSIS", "id" : "id226", "level" : 1, "path" : "SYNOPSIS", "intro" : "
# When your main program is not a Dancer object\n use My::Dancer::App;\n use Log::Report;\n ... start dispatcher ...\n error \"something is wrong\"; # Log::Report::error()\n\n # When your main program is a Dancer object\n use Dancer;\n use Dancer::Logger::LogReport;\n use Log::Report import => 'dispatcher';\n ... start dispatcher ...\n error \"something is wrong\"; # Dancer::error()\n\n # In any case, your main program needs to start log dispatcers\n # Both Dancer and other Log::Report based modules will send\n # their messages here:\n dispatcher FILE => 'default', ...;\n\n # In your config\n logger: log_report\n logger_format: %i%m # keep it simple\n log: debug # filtered by dispatchers\n\n", "type" : "chapter" }, "id129" : { "name" : "token '$token' not recognized as reason", "id" : "id129", "subroutine" : "id124", "type" : "error" }, "id796-id958" : { "extends" : "id796", "name" : "max_line", "id" : "id796-id958", "intro" : "
Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "params" : "INTEGER", "type" : "option" }, "id687" : { "name" : "expand", "id" : "id687", "diagnostics" : [ "id688" ], "call" : "$obj->expand( $msgid, $language, %options )", "type" : "i_method", "intro" : "Expand the context settings into all possible combinations which need\ntranslations in the PO file. This may depend on the $language.\nThe $msgid is used in error messages.
\n" }, "id1156" : { "intro" : "[1.10] Make changes and additions to the active context (see setContext()).
\n", "type" : "i_method", "call" : "$obj->updateContext( STRING|HASH|ARRAY|PAIRS )", "id" : "id1156", "name" : "updateContext" }, "id90" : { "id" : "id90", "name" : "Why useprinti() to replace printf()?",
"intro" : "The printf() function is provided by Perl's CORE; you do not need\nto install any module to use it. Why would you use consider using\nthis module?
printf() uses positional parameters, where printi() uses names\nto refer to the values to be filled-in. Especially in a set-up with\ntranslations, where the format strings get extracted into PO-files,\nit is much clearer to use names. This is also a disadvantage of\nprintp()\n\n\n\nprinti() supports serialization for specific data-types: how to\ninterpolate undef, HASHes, etc.\n\n\n\nprintf() is broken: it takes your string\nas bytes, not Perl strings (which may be utf8). In unicode, one\n\"character\" may use many bytes. Also, some characters are displayed\ndouble wide, for instance in Chinese. The printi() implementation\nwill use Unicode::GCString for correct behavior.\n\n\n\nInherited, see Log::Report::Dispatcher::type()
" }, "id771" : { "call" : "$obj->name", "id" : "id771", "name" : "name", "intro" : "Returns the unique name of this dispatcher.
\n", "type" : "i_method" }, "id746-id637" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Lexicon::Table::header()
", "name" : "header", "id" : "id746-id637", "extends" : "id746", "call" : "$obj->header( $field )" }, "id110" : { "id" : "id110", "name" : "Output encoding", "nest" : [ "id111", "id112" ], "level" : 2, "path" : "DETAILS/Output encoding", "intro" : "[0.91] This module is also used by Log::Report::Template, which is used\nto insert (translated) strings with parameters into HTML templates.\nYou can imagine that some of the parameter may need to be encoded to\nHTML in the template, and other not.
\n", "type" : "section" }, "id207" : { "name" : "conflict: package {pkg} in translation domain {domain1} in {file1} line {line1}, but in {domain2} in {file2} line {line2}.", "id" : "id207", "subroutine" : "id206", "type" : "warning" }, "id762-id1228" : { "value" : "'NORMAL'", "extends" : "id762", "id" : "id762-id1228", "name" : "mode", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
" }, "id1086" : { "name" : "METHODS", "id" : "id1086", "level" : 1, "type" : "chapter", "nest" : [ "id1087", "id1088", "id1089" ], "path" : "METHODS" }, "id637" : { "version" : "1.16", "chapters" : [ "id638", "id1335", "id639", "id640", "id641" ], "name" : "Log::Report::Lexicon::MOTcompact", "id" : "id637", "is_pure_pod" : false, "title" : "use translations from an MO file", "distribution" : "Log-Report-Lexicon", "inheritance" : { "extends" : [ "Log::Report::Lexicon::Table" ] }, "package" : "Log::Report::Lexicon::MOTcompact" }, "id510" : { "id" : "id510", "name" : "ms_locale", "call" : "ms_locale", "type" : "function", "intro" : "Returns the locale setting from the control panel.
\n" }, "id1266" : { "name" : "Filters", "id" : "id1266", "level" : 3, "path" : "DETAILS/Processing the message/Filters", "type" : "subsection" }, "id713" : { "type" : "info", "id" : "id713", "name" : "processing file $fn in $charset.", "subroutine" : "id708" }, "id654" : { "type" : "fault", "name" : "cannot read translations from $fn, need $size at $loc: $!", "id" : "id654", "subroutine" : "id643" }, "id902" : { "type" : "example", "intro" : " my $s = __x \"found {nr} files\", nr => 5;\n my $t = $s->clone(nr => 3);\n my $t = $s->(nr => 3); # equivalent\n print $s; # found 5 files\n print $t; # found 3 files\n\n",
"name" : "use of clone()\n",
"id" : "id902"
},
"id801-id1228" : {
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "id" : "id801-id1228", "name" : "abstract", "extends" : "id801", "value" : "1" }, "id208" : { "id" : "id208", "name" : "Log::Report::Optional", "title" : "pick Log::Report or ::Minimal", "is_pure_pod" : false, "distribution" : "Log-Report-Optional", "package" : "Log::Report::Optional", "inheritance" : { "extends" : [ "Exporter" ] }, "version" : "1.08", "chapters" : [ "id209", "id1316", "id210", "id211", "id212" ] }, "id529" : { "type" : "default", "value" : "false",
"id" : "id529",
"name" : "fuzzy"
},
"id736" : {
"call" : "$obj->msgstr( $msgid, [$count, $msgctxt] )",
"id" : "id736",
"name" : "msgstr",
"intro" : "Returns the translated string for $msgid. When not specified, $count is 1.
\n", "type" : "i_method" }, "id638" : { "name" : "NAME", "id" : "id638", "level" : 1, "intro" : "Log::Report::Lexicon::MOTcompact - use translations from an MO file
\n", "path" : "NAME", "type" : "chapter" }, "id1076" : { "intro" : "Interpolation via formats is optional.
\n\nIn shown examples, you see __x() everywhere. Using that function\nis required when you wish to use translations (later in your project),\nbut also has many other benefits. The functions __x and friends\ncreate a Log::Report::Message object.
Continue reading:
\nTo use this engine, you may configure manual Dancer2 via config.yaml:
\n template: \"TTLogReport\"\n\n\n
Or you may also change the rendering engine on a per-route basis by\nsetting it manually with set:
\n set template => 'TTLogReport';\n\n\n
Application:
\n\n # In your daemon startup\n my $pot = Log::Report::Translator::POT->new(lexicon => $poddir);\n my $domain = (engine 'template')->addTextdomain(name => $mydomain);\n $domain->configure(translator => $pot);\n\n # Use it:\n get '/' => sub {\n template index => {\n title => 'my webpage',\n\n # The actual language is stored in the user session.\n translate_to => 'nl_NL.utf-8',\n };\n };\n\n",
"level" : 1,
"name" : "SYNOPSIS",
"id" : "id266"
},
"id688" : {
"subroutine" : "id687",
"name" : "unknown context tag '$tag' used in '$msgid'",
"id" : "id688",
"type" : "error"
},
"id786" : {
"id" : "id786",
"name" : "package",
"params" : "CLASS",
"type" : "option"
},
"id799-id1082" : {
"id" : "id799-id1082",
"name" : "max_params",
"extends" : "id799",
"value" : "8",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
" }, "id1142-id375" : { "intro" : "Inherited, see Log::Report::Domain::configure(native_language)
", "type" : "default", "extends" : "id1142", "value" : "'en_US'", "name" : "native_language", "id" : "id1142-id375" }, "id778-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::log()
", "type" : "i_method", "call" : "$obj->log( \\%options, $reason, $message, $domain )", "extends" : "id778", "id" : "id778-id944", "name" : "log" }, "id759-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "params" : "LOCALE", "type" : "option", "extends" : "id759", "name" : "locale", "id" : "id759-id944" }, "id831" : { "type" : "default", "id" : "id831", "name" : "died", "value" : "undef"
},
"id795-id944" : {
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "type" : "default", "name" : "params", "id" : "id795-id944", "extends" : "id795", "value" : "<required>" }, "id63" : { "value" : "see modifier docs",
"name" : "defaults",
"id" : "id63",
"type" : "default"
},
"id907" : {
"call" : "$obj->domain",
"name" : "domain",
"id" : "id907",
"intro" : "Returns the domain of the first translatable string in the structure.
\n", "type" : "i_method" }, "id1143" : { "id" : "id1143", "name" : "context_rules", "type" : "option", "params" : "\\%rules|OBJECT", "intro" : "When %rules are provided, the translator will use the msgctxt fields\nas provided by PO-files (gettext). This parameter is used to initialize\na Log::Report::Translator::Context helper object.
[1.00] Set the defaults for modifiers, either with a HASH where the key modifier name\nmaps to a HASH of settings, or a list of PAIRS.
\n\nWhen using the methods in OO style , you can change the defaults at any time. For\nfunctional style, the object is hidden.
\n" }, "id881" : { "name" : "_append", "id" : "id881", "intro" : "Some $text or other $message object which need to be pasted after this\nmessage object.
\n", "type" : "option", "params" : "$text|$message" }, "id640" : { "id" : "id640", "name" : "DESCRIPTION", "path" : "DESCRIPTION", "intro" : "This module is translating, based on MO files (binary versions of\nthe PO files, the \"Machine Object\" format)
\n\nActually, this module is not \"compact\" anymore: not trading off\nspeed for memory. That may change again in the future.
\n\nTo get a MO file, you first need a PO file. Then run msgfmt, which\nis part of the gnu gettext package.
\n\n msgfmt -cv -o $domain.mo $domain.po\n\n # -c = --check-format & --check-header & --check-domain\n # -v = --verbose\n # -o = --output-file\n\n", "type" : "chapter", "level" : 1 }, "id421" : { "intro" : "
The character-set used in the PO files.
\n", "params" : "$charset", "type" : "option", "name" : "charset", "id" : "id421" }, "id1026" : { "name" : "how to use__x()\n",
"id" : "id1026",
"type" : "example",
"intro" : "This is by far the most used message constructor.
\n\n print __x\"Name {person.name}\", person => $person_obj;\n error __x\"Too many options: max 5, got {count}\", count => $c;\n fault __x\"Cannot open file {f}\", f => $input_filename;\n\n"
},
"id300" : {
"subroutine" : "id295",
"id" : "id300",
"name" : "template extract requires explicit domain.",
"type" : "error"
},
"id894-id217" : {
"intro" : "Inherited, see Log::Report::Message::new(_join)
", "type" : "default", "id" : "id894-id217", "name" : "_join", "extends" : "id894", "value" : "$\" $LIST_SEPARATOR"
},
"id775-id1174" : {
"intro" : "Inherited, see Log::Report::Dispatcher::needs()
", "type" : "i_method", "call" : "$obj->needs( [$reason] )", "extends" : "id775", "name" : "needs", "id" : "id775-id1174" }, "id1182" : { "name" : "to_level", "id" : "id1182", "value" : "[]", "type" : "default" }, "id788-id818" : { "params" : "STRING", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
", "extends" : "id788", "id" : "id788-id818", "name" : "filename" }, "id798-id1174" : { "name" : "max_params", "id" : "id798-id1174", "extends" : "id798", "params" : "INTEGER", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
" }, "id418-id697" : { "options" : [ [ "id421-id697", "id422-id697" ], [ "id419-id697", "id420-id697" ] ], "extends" : "id418", "id" : "id418-id697", "name" : "new", "intro" : "Inherited, see Log::Report::Extract::new()
", "type" : "c_method", "call" : "$class->new( %options )", "diagnostics" : [ "id423-id697", "id424-id697" ] }, "id1052" : { "name" : "message_class", "id" : "id1052", "params" : "CLASS", "type" : "option", "intro" : "[1.08] Use a more powerful message object class, for instance because\nyour messages need extra attributes. The provided CLASS must extend\nLog::Report::Message
\n" }, "id794-id1090" : { "name" : "params", "id" : "id794-id1090", "extends" : "id794", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
", "params" : "ARRAY", "type" : "option" }, "id926" : { "intro" : " print __\"Hello\" . ' ' . __\"World!\\n\";\n print __(\"Hello\")->concat(' ')->concat(__\"World!\")->concat(\"\\n\");\n\n",
"type" : "example",
"id" : "id926",
"name" : "of concatenation\n"
},
"id202" : {
"intro" : "Replace all backslash-something escapes by their escape character.\nFor instance, backslash-t is replaced by a tab character.
\n", "type" : "function", "call" : "unescape_chars( STRING )", "name" : "unescape_chars", "id" : "id202" }, "id908" : { "intro" : "Returns the count, which is used to select the translation\nalternatives.
\n", "type" : "i_method", "call" : "$obj->count", "id" : "id908", "name" : "count" }, "id876" : { "value" : "undef",
"id" : "id876",
"name" : "_msgid",
"type" : "default"
},
"id632" : {
"call" : "$obj->charset",
"name" : "charset",
"id" : "id632",
"intro" : "Returns the default charset, which can be overrule by the locale.
\n", "type" : "i_method" }, "id1030" : { "id" : "id1030", "name" : "__nx", "examples" : [ "id1031" ], "call" : "__nx( $msgid, $plural_msgid, $count, PAIRS )", "type" : "function", "intro" : "It depends on the value of $count (and the selected language) which\ntext will be displayed. See details in __n(). After translation,\nthe VARIABLES will be filled-in.
\n\nThe PAIRS are options for Log::Report::Message::new() and variables\nto be filled in.
\n" }, "id682" : { "name" : "no context definition for `$tag' in `$msgid'", "id" : "id682", "subroutine" : "id681", "type" : "error" }, "id777-id944" : { "call" : "$obj->close", "extends" : "id777", "id" : "id777-id944", "name" : "close", "intro" : "Inherited, see Log::Report::Dispatcher::close()
", "type" : "i_method" }, "id966" : { "subroutines" : [ "id967" ], "id" : "id966", "name" : "Constructors", "level" : 2, "path" : "METHODS/Constructors", "type" : "section" }, "id915" : { "name" : "errno", "id" : "id915", "call" : "$obj->errno( [$errno] )", "type" : "i_method", "intro" : "[1.38] Returns the value of the _errno key, to indicate the error\nnumber (to be returned from your script). Usually, this method will\nreturn undef. For FAILURE, FAULT, and ALERT, the errno is by default\ntaken from $! and $?.
undef",
"extends" : "id797",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
" }, "id787-id818" : { "name" : "package", "id" : "id787-id818", "value" : "<required>", "extends" : "id787", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "type" : "default" }, "id1172" : { "name" : "translate", "id" : "id1172", "call" : "$obj->translate( $message, [$language, $ctxt] )", "type" : "i_method", "intro" : "Returns the translation of the $message, a Log::Report::Message object,\nbased on the current locale.
\n\nTranslators are permitted to peek into the internal HASH of the\nmessage object, for performance reasons.
\n" }, "id787-id1090" : { "value" : "<required>", "extends" : "id787", "id" : "id787-id1090", "name" : "package", "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
" }, "id327" : { "name" : "processing_errors", "id" : "id327", "type" : "option", "params" : "'NATIVE'|'EXCEPTION'", "intro" : "The Template Toolkit infrastructure handles errors carefully: undef is\nreturned and you need to call error() to collect it.
Inherited, see Log::Report::Message::clone()
", "type" : "i_method", "call" : "$obj->clone( %options, $variables )", "name" : "clone", "id" : "id901-id217", "extends" : "id901" }, "id1019" : { "intro" : "Short for report ALERT => $message
Inherited, see Log::Report::Message::new(_classes)
" }, "id919" : { "type" : "i_method", "intro" : "[1.44] Returns true if the message carries the specified $tag (string) or\nmatches the Regexp. The trueth value is the (first matching) tag.
Inherited, see Log::Report::Dispatcher::type()
", "type" : "i_method" }, "id646" : { "type" : "error", "name" : "unsupported explicit charset $charset for $fn.", "id" : "id646", "subroutine" : "id643" }, "id1341" : { "level" : 1, "path" : "INHERITANCE", "intro" : "Log::Report::Win32Locale\n is an Exporter\n\n", "type" : "chapter", "id" : "id1341", "name" : "INHERITANCE" }, "id306" : { "type" : "option", "params" : "STRING", "intro" : "
The character encoding used in this template file.
\n", "id" : "id306", "name" : "charset" }, "id920" : { "name" : "inClass", "id" : "id920", "call" : "$obj->inClass( $tag|Regexp )", "type" : "i_method", "intro" : "Deprecated alternative for taggedWith().
\n" }, "id757-id1174" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "params" : "$reasons|\\@reasons", "type" : "option", "extends" : "id757", "id" : "id757-id1174", "name" : "accept" }, "id368" : { "level" : 3, "intro" : "With TT, we can add a simplificition which we cannot offer for Perl\ntranslations: TT variables are dynamic and stored in the stash which\nwe can access. Therefore, we can lookup \"accidentally\" missed parameters.
\n\n [% SET name = 'John Doe' %]\n [% loc(\"Hi {name}\", name => name) %] # looks silly\n [% loc(\"Hi {name}\") %] # uses TT stash directly\n\n\nSometimes, computation of objects is expensive: you never know. So, you\nmay try to avoid repeated computation. In the follow example, \"soldOn\"\nis collected/computed twice:
\n\n [% IF product.soldOn %]\n <tdE<gt>[% loc(\"Sold on {product.soldOn DATE}\")</tdE<gt>\n [% END %]\n\n\nThe performance is predictable optimal with:
\n\n [% sold_on = product.soldOn; IF sold_on %]\n <tdE<gt>[% loc(\"Sold on {sold_on DATE}\")</tdE<gt>\n [% END %]\n\n",
"path" : "DETAILS/Supported syntax/Translation syntax, more magic",
"type" : "subsection",
"name" : "Translation syntax, more magic",
"id" : "id368"
},
"id1135-id375" : {
"type" : "i_method",
"intro" : "Inherited, see Log::Report::Domain::nativeLanguage()
", "extends" : "id1135", "id" : "id1135-id375", "name" : "nativeLanguage", "call" : "$obj->nativeLanguage" }, "id1213" : { "type" : "i_method", "intro" : "Returns whether this exception has a severity which makes it fatal\nwhen thrown. [1.34] This can have been overruled with the is_fatal\nattribute. See Log::Report::Util::is_fatal().
Inherited, see Log::Report::Message::new(_classes)
", "type" : "default", "name" : "_classes", "id" : "id888-id217", "value" : "undef",
"extends" : "id888"
},
"id738-id637" : {
"intro" : "Inherited, see Log::Report::Lexicon::Table::add()
", "type" : "i_method", "call" : "$obj->add( $po )", "name" : "add", "id" : "id738-id637", "extends" : "id738" }, "id870" : { "type" : "default", "value" : "<from \"use Log::Report\">", "name" : "_domain", "id" : "id870" }, "id414" : { "id" : "id414", "name" : "SYNOPSIS", "path" : "SYNOPSIS", "intro" : "# See the extensions\n\n", "type" : "chapter", "level" : 1 }, "id794-id818" : { "name" : "params", "id" : "id794-id818", "extends" : "id794", "params" : "ARRAY", "type" : "option", "intro" : "
Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
" }, "id799-id944" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "extends" : "id799", "value" : "8", "name" : "max_params", "id" : "id799-id944" }, "id784-id1174" : { "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::collectLocation()
", "extends" : "id784", "id" : "id784-id1174", "name" : "collectLocation", "call" : "$any->collectLocation" }, "id328" : { "type" : "default", "value" : "'NATIVE'", "id" : "id328", "name" : "processing_errors" }, "id788-id1090" : { "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
", "params" : "STRING", "type" : "option", "id" : "id788-id1090", "name" : "filename", "extends" : "id788" }, "id960" : { "intro" : " # start using log4perl via a config file\n # The name of the dispatcher is the name of the default category.\n dispatcher LOG4PERL => 'logger',\n accept => 'NOTICE-',\n config => \"$ENV{HOME}/.log.conf\";\n\n # disable default dispatcher\n dispatcher close => 'logger';\n\n # configuration inline, not in file: adapted from the Log4perl manpage\n my $name = 'logger';\n my $outfile = '/tmp/a.log';\n my $config = <<__CONFIG;\n log4perl.category.$name = INFO, Logfile\n log4perl.logger.Logfile = Log::Log4perl::Appender::File\n log4perl.logger.Logfile.filename = $outfn\n log4perl.logger.Logfile.layout = Log::Log4perl::Layout::PatternLayout\n log4perl.logger.Logfile.layout.ConversionPattern = %d %F{1} %L> %m\n __CONFIG\n\n dispatcher LOG4PERL => $name, config => \\$config;\n\n",
"path" : "SYNOPSIS",
"type" : "chapter",
"level" : 1,
"name" : "SYNOPSIS",
"id" : "id960"
},
"id1034" : {
"type" : "example",
"intro" : "# add three msgids to the translation table\n my @colors = (N__\"red\", N__\"green\", N__\"blue\");\n my @colors = N__w \"red green blue\"; # same\n print __ $colors[1]; # translate green\n\n # using __(), would work as well\n my @colors = (__\"red\", __\"green\", __\"blue\");\n print $colors[1];\n # however: this will always create all Log::Report::Message objects,\n # where maybe only one is used.\n\n", "name" : "how to use
N__()\n",
"id" : "id1034"
},
"id758-id1174" : {
"name" : "accept",
"id" : "id758-id1174",
"value" : "depend on mode",
"extends" : "id758",
"intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "type" : "default" }, "id779-id1174" : { "intro" : "Inherited, see Log::Report::Dispatcher::translate()
", "type" : "i_method", "call" : "$obj->translate( \\%options, $reason, $message )", "name" : "translate", "id" : "id779-id1174", "extends" : "id779" }, "id367" : { "type" : "subsection", "path" : "DETAILS/Supported syntax/Translation syntax", "intro" : "Let say that your translation function is called 'loc', which is the\ndefault name. Then, you can use that name as simple function.
\n\nIn these examples, PAIRS is a list of values to be inserted in the\nmsgid string. When the msgid is specified with a plural alternative,\nthen a COUNTER value is required to indicate which alternative is\nrequired.
\n [% loc(\"msgid\", PAIRS) %]\n [% loc('msgid', PAIRS) %]\n [% loc(\"msgid|plural\", COUNTER, PAIRS) %]\n [% loc(\"msgid|plural\", _count => COUNTER, PAIRS) %]\n\n [% INCLUDE\n title = loc('something')\n %]\n\n\nBut also as filter. Although filters and functions work differently\ninternally in Template Toolkit, it is convenient to permit both syntaxes.
\n\n [% | loc(PAIRS) %]msgid[% END %]\n [% 'msgid' | loc(PAIRS) %]\n [% \"msgid\" | loc(PAIRS) %]\n\n [% \"msgid|plural\" | loc(COUNTER, PAIRS) %]\n [% \"msgid|plural\" | loc(_count => COUNTER, PAIRS) %]\n [% FILTER loc %]msgid[% END %]\n [% FILTER loc(COUNTER, PAIRS) %]msgid|plural[% END %]\n\n\n
As examples
\n\n [% loc(\"hi {n}\", n => name) %]\n [% | loc(n => name) %]hi {n}[% END %]\n [% \"hi {n}\" | loc(n => name) %]\n [% loc(\"one person|{_count} people\", size) %]\n [% | loc(size) %]one person|{_count} people[% END %]\n [% 'one person|{_count} people' | loc(size) %]\n\n\nThese syntaxes work exacly like translations with Log::Report for your\nPerl programs. Compare this with:
\n\n __x\"hi {n}\", n => name; # equivalent to\n __x(\"hi {n}\", n => name); # replace __x() by loc()\n\n",
"level" : 3,
"name" : "Translation syntax",
"id" : "id367"
},
"id1092" : {
"level" : 1,
"path" : "SYNOPSIS",
"intro" : "# add syslog dispatcher\n dispatcher SYSLOG => 'syslog', accept => 'NOTICE-',\n format_reason => 'IGNORE',\n to_prio => [ 'ALERT-' => 'err' ];\n\n # disable default dispatcher, when daemon\n dispatcher close => 'default';\n\n", "type" : "chapter", "name" : "SYNOPSIS", "id" : "id1092" }, "id183" : { "type" : "chapter", "path" : "SYNOPSIS", "intro" : "
my ($language, $territory, $charset, $modifier)\n = parse_locale 'nl_BE.utf-8@home';\n\n my @take = expand_reasons 'INFO-ERROR,PANIC';\n\n", "level" : 1, "name" : "SYNOPSIS", "id" : "id183" }, "id694" : { "name" : "Specifying the context per Domain", "id" : "id694", "type" : "subsection", "path" : "DETAILS/Using context_rules/Specifying the context per Domain", "intro" : "
Above examples are to be specified per message. You may also\nset a default. The top of your modules set the text-domain (name\nof the translation table) for all strings found in those files.\nIn this case, for instance \"webpages\"
\n\n # Log::Report::textdomain()\n (textdomain 'webpages')->setContext(%context);\n\n\n
This context is used as defaults, the _context attribute used by\nstrings are overruling these.
Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "type" : "option", "params" : "INTEGER" }, "id220" : { "type" : "chapter", "intro" : "[This Dancer2 plugin was contributed by Andrew Beverley]
\n\nThis class is an extension of Log::Report::Message, with functions\nspecifically designed for Dancer applications. Minimal functions are\nprovided (currently only aimed at Bootstrap), but ideas for new ones are\nwelcome.
\n", "path" : "DESCRIPTION", "level" : 1, "id" : "id220", "name" : "DESCRIPTION" }, "id133" : { "subroutines" : [ "id143", "id134", "id137", "id144", "id141", "id140", "id136", "id142", "id135", "id138", "id139" ], "level" : 2, "id" : "id133", "name" : "Abbreviations for report()", "path" : "FUNCTIONS/Abbreviations for report()", "type" : "section" }, "id362" : { "path" : "DETAILS", "nest" : [ "id363", "id366", "id370" ], "type" : "chapter", "level" : 1, "id" : "id362", "name" : "DETAILS" }, "id1017" : { "name" : "error", "id" : "id1017", "call" : "error( $message )", "type" : "function", "intro" : "Short for report ERROR => $message
undef",
"id" : "id525",
"name" : "msgctxt",
"type" : "default"
},
"id795-id1082" : {
"extends" : "id795",
"value" : "<required>",
"id" : "id795-id1082",
"name" : "params",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(params)
" }, "id165" : { "intro" : "The name of the textdomain is used in its invocation, but also as (part of) the\ntranslation file names, hence please keep it simple and short.
\n", "params" : "STRING", "type" : "option", "id" : "id165", "name" : "name" }, "id759-id1082" : { "extends" : "id759", "name" : "locale", "id" : "id759-id1082", "params" : "LOCALE", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
" }, "id742" : { "subroutine" : "id741", "id" : "id742", "name" : "there is no Plural-Forms field in the header, but needed.", "type" : "error" }, "id740-id637" : { "intro" : "Inherited, see Log::Report::Lexicon::Table::translations()
", "type" : "error", "subroutine" : "id739", "id" : "id740-id637", "name" : "only acceptable parameter is 'ACTIVE'", "extends" : "id740" }, "id778-id1082" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::log()
", "id" : "id778-id1082", "name" : "log", "extends" : "id778", "call" : "$obj->log( \\%options, $reason, $message, $domain )" }, "id219" : { "level" : 1, "path" : "SYNOPSIS", "intro" : "In your template:\n\n [% FOR message IN messages %]\n <div class=\"alert alert-[% message.bootstrap_color %]\">\n [% message.toString | html_entity %]\n </div>\n [% END %]\n\n", "type" : "chapter", "id" : "id219", "name" : "SYNOPSIS" }, "id565" : { "type" : "default", "value" : "
undef",
"id" : "id565",
"name" : "nr_plurals"
},
"id516" : {
"type" : "section",
"path" : "METHODS/Constructors",
"name" : "Constructors",
"id" : "id516",
"level" : 2,
"subroutines" : [
"id517"
]
},
"id1206" : {
"type" : "option",
"params" : "$reason",
"name" : "reason",
"id" : "id1206"
},
"id125" : {
"id" : "id125",
"name" : "errno",
"type" : "option",
"params" : "INTEGER"
},
"id730" : {
"type" : "section",
"path" : "METHODS/Constructors",
"id" : "id730",
"name" : "Constructors",
"level" : 2,
"subroutines" : [
"id731"
]
},
"id882-id217" : {
"name" : "_append",
"id" : "id882-id217",
"extends" : "id882",
"value" : "undef",
"type" : "default",
"intro" : "Inherited, see Log::Report::Message::new(_append)
" }, "id1196" : { "level" : 1, "path" : "SYNOPSIS", "intro" : " # created within a try block\n try { error \"help!\" };\n my $exception = $@->wasFatal;\n $exception->throw if $exception;\n\n $@->reportFatal; # combination of above two lines\n\n my $message = $exception->message; # the Log::Report::Message\n\n if($message->taggedWith('die')) ...\n if($exception->taggedWith('die')) ... # same\n if($@->wasFatal(tag => 'die')) ... # same\n\n",
"type" : "chapter",
"name" : "SYNOPSIS",
"id" : "id1196"
},
"id533" : {
"value" : "[]",
"name" : "references",
"id" : "id533",
"type" : "default"
},
"id777-id1082" : {
"type" : "i_method",
"intro" : "Inherited, see Log::Report::Dispatcher::close()
", "id" : "id777-id1082", "name" : "close", "extends" : "id777", "call" : "$obj->close" }, "id322" : { "path" : "SYNOPSIS", "intro" : " use Log::Report::Template;\n my $templater = Log::Report::Template->new(%config);\n $templater->addTextdomain(name => \"Tic\", lexicons => ...);\n $templater->process('template_file.tt', \\%vars, \\$output);\n\n",
"type" : "chapter",
"level" : 1,
"name" : "SYNOPSIS",
"id" : "id322"
},
"id583" : {
"name" : "unsupported charset $charset in $fn.",
"id" : "id583",
"subroutine" : "id575",
"type" : "error"
},
"id260" : {
"level" : 3,
"type" : "subsection",
"intro" : "To make it easier to send messages to your users, messages at the following\nlevels are also stored in the user's session: notice, warning, mistake,\nerror, fault, alert, failure and panic.
You can pass these to your template and display them at each page render:
\n\n hook before_template => sub {\n my $tokens = shift;\n $tokens->{messages} = session 'messages';\n session 'messages' => []; # Clear the message queue\n }\n\n\nThen in your template (for example the main layout):
\n\n [% FOR message IN messages %]\n <div class=\"alert alert-[% message.bootstrap_color %]\">\n [% message.toString | html_entity %]\n </div>\n [% END %]\n\n\n
The bootstrap_color of the message is compatible with Bootstrap contextual\ncolors: success, info, warning or danger.
When you use Dancer2::Template::TTLogReport as well, which enables the\ntranslations of your whole templates, then add locale:
\n [% message.toString(locale) | html_entity %]\n\n\n
Now, anywhere in your application that you have used Log::Report, you can
\n\n warning \"Hey user, you should now about this\";\n\n\n
and the message will be sent to the next page the user sees.
\n", "path" : "DETAILS/In use/Sending messages to the user", "name" : "Sending messages to the user", "id" : "id260" }, "id74" : { "name" : "FUNCTIONS", "id" : "id74", "path" : "FUNCTIONS", "intro" : "The functional interface creates a hidden String::Print object, which is\nreused in the whole active package. Seperate packages will use different\nhidden objects.
You may import any of these functions explicitly, or all together by\nnot specifying the names.
\n", "type" : "chapter", "examples" : [ "id75" ], "subroutines" : [ "id87", "id85", "id86", "id76" ], "level" : 1 }, "id780" : { "call" : "$any->collectStack( [$maxdepth] )", "name" : "collectStack", "id" : "id780", "intro" : "Returns an ARRAY of ARRAYs with text, filename, line-number.
\n", "type" : "ci_method" }, "id1085" : { "intro" : "Ventilate the problem reports via the standard Perl error mechanisms:\ndie(), warn(), and print(). There can be only one such dispatcher\n(per thread), because once die() is called, we are not able to return.\nTherefore, this dispatcher will always be called last.
In the early releases of Log::Report, it tried to simulate the behavior\nof warn and die using STDERR and exit; however: that is not possible.
\n", "path" : "DESCRIPTION", "type" : "chapter", "level" : 1, "name" : "DESCRIPTION", "id" : "id1085" }, "id384" : { "id" : "id384", "name" : "translation_function", "params" : "STRING", "type" : "option", "intro" : "The name of the function as used in the template to call for translation.\nSee function(). It must be unique over all text-domains used.
\n" }, "id805" : { "id" : "id805", "name" : "Addition information", "type" : "subsection", "path" : "DETAILS/Processing the message/Addition information", "intro" : "The modules which use Log::Report will only specify the base of\nthe message string. The base dispatcher and the back-ends will extend\nthis message with additional information:
$!When the message is a translatable object (Log::Report::Message, for\ninstance created with Log::Report::__()), then the added components\nwill get translated as well. Otherwise, all will be in English.
\n\nExactly what will be added depends on the actual mode of the dispatcher\n(change it with mode(), initiate it with new(mode)).
\n\n mode mode mode mode\n REASON SOURCE TE! NORM VERB ASSE DEBUG\n trace program ... S\n assert program ... SL SL\n info program T.. S S S\n notice program T.. S S S S\n mistake user T.. S S S SL\n warning program T.. S S SL SL\n error user TE. S S SL SC\n fault system TE! S S SL SC\n alert system T.! SL SL SC SC\n failure system TE! SL SL SC SC\n panic program .E. SC SC SC SC\n\n T - usually translated\n E - exception (execution interrupted)\n ! - will include $! text at display\n L - include filename and linenumber\n S - show/print when accepted\n C - stack trace (like Carp::confess())\n\n", "level" : 3 }, "id996" : { "params" : "BOOLEAN", "type" : "option", "intro" : "
Some logged exceptions are fatal, other aren't. The default usually\nis correct. However, you may want an error to be caught (usually with\ntry()), redispatch it to syslog, but without it killing the main\nprogram.
\n", "id" : "id996", "name" : "is_fatal" }, "id1061" : { "id" : "id1061", "name" : "Reasons", "level" : 2, "subroutines" : [ "id1062" ], "type" : "section", "path" : "FUNCTIONS/Reasons" }, "id1210" : { "type" : "section", "path" : "METHODS/Attributes", "level" : 2, "name" : "Attributes", "id" : "id1210", "subroutines" : [ "id1213", "id1215", "id1212", "id1211" ] }, "id818" : { "version" : "1.45", "chapters" : [ "id819", "id1346", "id820", "id821", "id822", "id825", "id1297" ], "title" : "capture all reports as exceptions", "is_pure_pod" : false, "name" : "Log::Report::Dispatcher::Try", "id" : "id818", "package" : "Log::Report::Dispatcher::Try", "inheritance" : { "extends" : [ "Log::Report::Dispatcher" ] }, "distribution" : "Log-Report" }, "id334" : { "value" : "undef",
"name" : "translate_to",
"id" : "id334",
"type" : "default"
},
"id1155" : {
"type" : "error",
"subroutine" : "id1153",
"name" : "you need to configure context_rules before setContext",
"id" : "id1155"
},
"id797-id1228" : {
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "extends" : "id797", "value" : "undef",
"name" : "max_line",
"id" : "id797-id1228"
},
"id541" : {
"type" : "i_method",
"intro" : "Returns a $translation, optionally after setting it.\nWhen no plural is defined, the $index is ignored.
\n", "name" : "msgstr", "id" : "id541", "call" : "$obj->msgstr( [$index, [$translation]] )" }, "id170-id375" : { "intro" : "Inherited, see Log::Report::Minimal::Domain::name()
", "type" : "i_method", "call" : "$obj->name", "name" : "name", "id" : "id170-id375", "extends" : "id170" }, "id244" : { "id" : "id244", "name" : "mistake", "call" : "$obj->mistake", "type" : "i_method" }, "id491" : { "call" : "$obj->translations( [$active] )", "name" : "translations", "id" : "id491", "diagnostics" : [ "id492" ], "intro" : "Returns a list with all defined Log::Report::Lexicon::PO objects. When\nthe string $active is given as parameter, only objects which have\nreferences are returned.
\n", "type" : "i_method" }, "id379" : { "id" : "id379", "name" : "METHODS", "level" : 1, "nest" : [ "id380", "id394", "id400" ], "path" : "METHODS", "type" : "chapter" }, "id358" : { "id" : "id358", "name" : "Formatter value modifiers", "level" : 2, "type" : "section", "path" : "METHODS/Formatter value modifiers", "intro" : "Modifiers simplify the display of values. Read the section about\nmodifiers in String::Print. Here, only some examples are shown.
\n\nYou can achieve the same transformation with TT vmethods, or with the\nperl code which drives your website. The advantange is that you can\ntranslate them. And they are quite readible.
\n\n%-10s, %2.4f, etcExactly like format of the perl's internal printf() (which is\nactually being called to do the formatting)
Examples:
\n\n # pi in two decimals\n [% loc(\"π = {pi %.2f}\", pi => 3.14157) %]\n\n # show int, no fraction. filesize is a template variable\n [% loc(\"file size {size %d}\", size => filesize + 0.5) %]\n\nConvert a file size into a nice human readible format.
\n\nExamples:
\n\n # filesize and fn are passed as variables to the templater\n [% loc(\"downloaded {size BYTES} {fn}\\n\", size => fs, fn => fn) %]\n # may produce: \" 0 B\", \"25 MB\", \"1.5 GB\", etc\n\nAccept various time syntaxes as value, and translate them into\nstandard formats: year only, date in YYYY-MM-DD, time as HH::MM::SS,\nand various DateTime formats:
Examples:
\n\n # shows 'Copyright 2017'\n [% loc(\"Copyright {today YEAR}\", today => '2017-06-26') %]\n\n # shows 'Created: 2017-06-26'\n [% loc(\"Created: {now DATE}\", now => '2017-06-26 00:24:15') %]\n\n # shows 'Night: 00:24:15'\n [% loc(\"Night: {now TIME}\", now => '2017-06-26 00:24:15') %]\n\n # shows 'Mon Jun 26 00:28:50 CEST 2017'\n [% loc(\"Stamp: {now DT(ASC)}\", now => 1498429696) %]\n\nWhen a parameter has no value or is an empty string, the word or\nstring will take its place.
\n\n [% loc(\"visitors: {count //0}\", count => 3) %]\n [% loc(\"published: {date DT//'not yet'}\", date => '') %]\n [% loc(\"copyright: {year//2017 YEAR}\", year => '2018') %]\n [% loc(\"price: {price//5 EUR}\", price => product.price %]\n [% loc(\"price: {price EUR//unknown}\", price => 3 %]\n\n\nInherited, see Log::Report::Dispatcher::needs()
", "id" : "id775-id1228", "name" : "needs", "extends" : "id775", "call" : "$obj->needs( [$reason] )" }, "id817" : { "call" : "exception_decode( $exception, %options )", "id" : "id817", "name" : "exception_decode", "intro" : "[1.23] This function attempts to translate object of other exception frameworks\ninto information to create a Log::Report::Exception. It returns the\nsame list of parameters as die_decode() does.
\n\nCurrently supported:
\nInherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "type" : "option", "params" : "INTEGER" }, "id950" : { "id" : "id950", "name" : "Constructors", "level" : 2, "subroutines" : [ "id951" ], "type" : "section", "path" : "METHODS/Constructors" }, "id773-id818" : { "intro" : "Inherited, see Log::Report::Dispatcher::mode()
", "type" : "i_method", "call" : "$obj->mode", "id" : "id773-id818", "name" : "mode", "extends" : "id773" }, "id765-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
", "type" : "option", "params" : "CHARSET", "extends" : "id765", "id" : "id765-id944", "name" : "charset" }, "id141" : { "type" : "function", "id" : "id141", "name" : "fault", "call" : "fault( $message )" }, "id1075" : { "id" : "id1075", "name" : "Exceptions", "level" : 3, "path" : "DETAILS/Error handling models/Exceptions", "intro" : "The simple view on live says: you 're dead when you die. However,\nmore complex situations try to revive the dead. Typically, the \"die\"\nis considered a terminating exception, but not terminating the whole\nprogram, but only some logical block. Of course, a wrapper round\nthat block must decide what to do with these emerging problems.
\n\nJava-like languages do not \"die\" but throw exceptions which contain the\ninformation about what went wrong. Perl modules like Exception::Class\nsimulate this. It's a hassle to create exception class objects for each\nemerging problem, and the same amount of work to walk through all the\noptions.
Log::Report follows a simpler scheme. Fatal messages will \"die\", which is\ncaught with \"eval\", just the Perl way (used invisible to you). However,\nthe wrapper gets its hands on the message as the user has specified it:\nuntranslated, with all unprocessed parameters still at hand.
\n\n try { fault __x \"cannot open file {file}\", file => $fn };\n if($@) # is Log::Report::Dispatcher::Try\n { my $cause = $@->wasFatal; # is Log::Report::Exception\n $cause->throw if $cause->message->msgid =~ m/ open /;\n # all other problems ignored\n }\n\n\nSee Log::Report::Dispatcher::Try and Log::Report::Exception.
\n", "type" : "subsection" }, "id166-id1127" : { "name" : "name", "id" : "id166-id1127", "extends" : "id166", "value" : "<required>", "intro" : "Inherited, see Log::Report::Minimal::Domain::new(name)
", "type" : "default" }, "id403" : { "type" : "error", "subroutine" : "id402", "id" : "id403", "name" : "no counting positional for '$msgid'" }, "id783-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::skipStack()
", "type" : "i_method", "call" : "$obj->skipStack", "extends" : "id783", "id" : "id783-id944", "name" : "skipStack" }, "id1281" : { "level" : 3, "name" : "Addition information", "id" : "id1281", "type" : "subsection", "path" : "DETAILS/Processing the message/Addition information" }, "id1144" : { "id" : "id1144", "name" : "context_rules", "value" : "undef",
"type" : "default"
},
"id426-id289" : {
"id" : "id426-id289",
"name" : "index",
"extends" : "id426",
"call" : "$obj->index",
"type" : "i_method",
"intro" : "Inherited, see Log::Report::Extract::index()
" }, "id357" : { "level" : 2, "type" : "section", "path" : "METHODS/Template filters", "intro" : "Some common activities in templates are harder when translation is\nneeded. A few TT filters are provided to easy the process.
\n\nA typical example of an HTML component which needs translation is
\n\n <trE<gt><tdE<gt>Price:</tdE<gt><tdE<gt>20 £</tdE<gt></trE<gt>\n\n\n
Both the price text as value need to be translated. In plain perl\n(with Log::Report) you would write
\n\n __x\"Price: {price £}\", price => $product->price # or\n __x\"Price: {p.price £}\", p => $product;\n\n\nIn HTML, there seems to be the need for two separate translations,\nmay in the program code. This module (actually String::Print)\ncan be trained to convert money during translation, because '£'\nis a modifier. The translation for Dutch (via a PO table) could be
\n\n \"Prijs: {p.price €}\"\n\n\nSO: we want to get both table fields in one translation. Try this:
\n\n <trE<gt>[% loc(\"Price:\\t{p.price £}\" | cols %]</trE<gt>\n\n\nIn the translation table, you have to place the tabs (backslash-t) as\nwell.
\n\nThere are two main forms of cols. The first form is the containerizer:\npass 'cols' a list of container names. The fields in the input string\n(as separated by tabs) are wrapped in the named container. The last\ncontainer name will be reused for all remaining columns. By default,\neverything is wrapped in 'td' containers.
\n \"a\\tb\\tc\" | cols <tdE<gt>aE<lt>/tdE<gt><tdE<gt>bE<lt>/tdE<gt><tdE<gt>cE<lt>/tdE<gt>\n \"a\\tb\\tc\" | cols('td') same\n \"a\\tb\\tc\" | cols('th', 'td') <thE<gt>aE<lt>/thE<gt><tdE<gt>bE<lt>/tdE<gt><tdE<gt>cE<lt>/tdE<gt>\n \"a\" | cols('div') <divE<gt>aE<lt>/divE<gt>\n loc(\"a\") | cols('div') <divE<gt>xxxxE<lt>/divE<gt>\n\n\nThe second form has one pattern, which contains (at least one) $1\nreplacement positions. Missing columns for positional parameters\nwill be left blank.
\n \"a\\tb\\tc\" | cols('#$3#$1#') #c#a#\n \"a\" | cols('#$3#$1#') ##a#\n loc(\"a\") | cols('#$3#$1#') #mies#aap#\n\nSome translations will produce more than one line of text. Add\n'<brE<gt>' after each of them.
\n\n [% loc('intro-text') | br %]\n [% | br %][% intro_text %][% END %]\n [% FILTER br %][% intro_text %][% END %]\n\n\nInherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
", "id" : "id801-id1174", "name" : "abstract", "extends" : "id801", "value" : "1" }, "id352" : { "id" : "id352", "name" : "write_tables", "value" : "<true>",
"type" : "default"
},
"id673" : {
"nest" : [
"id674",
"id678",
"id680"
],
"path" : "METHODS",
"type" : "chapter",
"id" : "id673",
"name" : "METHODS",
"level" : 1
},
"id1108" : {
"name" : "include_domain",
"id" : "id1108",
"intro" : "[1.00] Include the text-domain of the message in each logged message.
\n", "params" : "BOOLEAN", "type" : "option" }, "id155" : { "name" : "Configuration", "id" : "id155", "level" : 2, "subroutines" : [ "id156" ], "type" : "section", "path" : "FUNCTIONS/Configuration" }, "id1025" : { "id" : "id1025", "name" : "__x", "diagnostics" : [ "id1027" ], "call" : "__x( $msgid, PAIRS )", "examples" : [ "id1026" ], "type" : "function", "intro" : "Translate the $msgid and then interpolate the VARIABLES in that string.\nOf course, translation and interpolation is delayed as long as possible.\nBoth OPTIONS and VARIABLES are key-value pairs.
\n\nThe PAIRS are options for Log::Report::Message::new() and variables\nto be filled in.
\n" }, "id296" : { "name" : "domain", "id" : "id296", "intro" : "There is no syntax for specifying domains in templates (yet), so you\nmust be explicit about the collection we are making now.
\n", "type" : "option", "params" : "DOMAIN" }, "id199" : { "name" : "must_show_stack", "id" : "id199", "call" : "must_show_stack( $mode, $reason )", "type" : "function" }, "id769-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::new()
", "type" : "error", "subroutine" : "id756", "extends" : "id769", "id" : "id769-id1082", "name" : "Perl does not support charset $cs" }, "id812" : { "type" : "chapter", "path" : "DESCRIPTION", "intro" : "This module is used internally, to translate output of 'die' and Carp\nfunctions into Log::Report::Message objects. Also, it tries to\nconvert other kinds of exception frameworks into our message object.
\n", "level" : 1, "id" : "id812", "name" : "DESCRIPTION" }, "id1298" : { "level" : 2, "name" : "Available back-ends", "id" : "id1298", "path" : "DETAILS/Available back-ends", "type" : "section" }, "id766-id958" : { "name" : "charset", "id" : "id766-id958", "value" : "undef",
"extends" : "id766",
"intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
", "type" : "default" }, "id1221" : { "examples" : [ "id1222" ], "call" : "$obj->throw( %options )", "type" : "i_method", "intro" : "Insert the message contained in the exception into the currently defined\ndispatchers. The throw as method name is commonly known exception\nrelated terminology for report.
The %options overrule the captured options to Log::Report::report().\nThis can be used to overrule a destination. Also, the reason can\nbe changed.
\n\nReturned is the LIST of dispatchers which have accepted the forwarded\nexception.
\n", "name" : "throw", "id" : "id1221" }, "id762-id1174" : { "type" : "default", "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
", "extends" : "id762", "value" : "'NORMAL'", "name" : "mode", "id" : "id762-id1174" }, "id449" : { "id" : "id449", "name" : "charset", "value" : "'UTF-8'", "type" : "default" }, "id555" : { "type" : "warning", "subroutine" : "id554", "id" : "id555", "name" : "unknown flag $flag ignored" }, "id599" : { "call" : "$obj->directory", "name" : "directory", "id" : "id599", "intro" : "Returns the directory name.
\n", "type" : "i_method" }, "id250" : { "call" : "$obj->success", "name" : "success", "id" : "id250", "intro" : "This is a special additional type, equivalent to notice. The difference is\nthat messages using this keyword will have the class success added, which\ncan be used to color the messages differently to the end user. For example,\nmanual Dancer2::Plugin::LogReport::Message#bootstrap_color uses this to display the\nmessage in green.
Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
" }, "id81" : { "name" : "_prepend", "id" : "id81", "type" : "option", "params" : "STRING|OBJECT", "intro" : "Text as STRING prepended before $format, without interpolation. This\nmay also be an OBJECT which gets stringified, but variables not filled-in.
\n" }, "id611" : { "version" : "1.16", "chapters" : [ "id612", "id1323", "id613", "id614", "id615" ], "is_pure_pod" : false, "title" : "the GNU gettext infrastructure", "id" : "id611", "name" : "Log::Report::Translator::Gettext", "inheritance" : { "extends" : [ "Log::Report::Translator" ] }, "package" : "Log::Report::Translator::Gettext", "distribution" : "Log-Report-Lexicon" }, "id1136-id375" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Domain::translator()
", "extends" : "id1136", "id" : "id1136-id375", "name" : "translator", "call" : "$obj->translator" }, "id578" : { "type" : "fault", "subroutine" : "id575", "name" : "failed reading from file {fn}: $!", "id" : "id578" }, "id559" : { "type" : "warning", "subroutine" : "id557", "id" : "id559", "name" : "do not understand command '$cmd' at $where." }, "id445" : { "id" : "id445", "name" : "METHODS", "level" : 1, "nest" : [ "id446", "id481", "id486" ], "path" : "METHODS", "type" : "chapter" }, "id1168" : { "path" : "METHODS/Constructors", "type" : "section", "subroutines" : [ "id1169" ], "id" : "id1168", "name" : "Constructors", "level" : 2 }, "id595" : { "level" : 1, "id" : "id595", "name" : "METHODS", "path" : "METHODS", "nest" : [ "id596", "id598", "id600" ], "type" : "chapter" }, "id290" : { "level" : 1, "type" : "chapter", "intro" : "Log::Report::Template::Extract - collect translatable strings from template files
\n", "path" : "NAME", "id" : "id290", "name" : "NAME" }, "id624" : { "name" : "new", "id" : "id624", "call" : "$class->new( %options )", "examples" : [ "id629" ], "type" : "c_method", "options" : [ [ "id627", "id628" ], [ "id625", "id626" ] ] }, "id177" : { "type" : "default", "value" : "PRINTI",
"name" : "formatter",
"id" : "id177"
},
"id1338" : {
"name" : "INHERITANCE",
"id" : "id1338",
"type" : "chapter",
"path" : "INHERITANCE",
"intro" : "Log::Report::Lexicon::POT\n is a Log::Report::Lexicon::Table\n\n", "level" : 1 }, "id843" : { "type" : "section", "path" : "METHODS/Logging", "level" : 2, "name" : "Logging", "id" : "id843", "subroutines" : [ "id781-id818", "id785-id818", "id844", "id784-id818", "id777-id818", "id780-id818", "id783-id818", "id779-id818", "id846", "id845" ] }, "id577" : { "type" : "default", "value" : "
undef",
"name" : "charset",
"id" : "id577"
},
"id392" : {
"intro" : "Upgrade a base class Log::Report::Domain-object into an Template\ndomain.
\n\nThis is a bit akward process, needed when one of the code packages\nuses the same domain as the templating system uses. The generic domain\nconfiguration stays intact.
\n", "type" : "c_method", "call" : "$class->upgrade( $domain, %options )", "diagnostics" : [ "id393" ], "name" : "upgrade", "id" : "id392" }, "id664" : { "id" : "id664", "name" : "filename", "call" : "$obj->filename", "type" : "i_method", "intro" : "Returns the name of the source file for this data.
\n" }, "id760-id958" : { "extends" : "id760", "value" : "<system locale>", "name" : "locale", "id" : "id760-id958", "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "type" : "default" }, "id704" : { "level" : 1, "id" : "id704", "name" : "METHODS", "type" : "chapter", "path" : "METHODS", "nest" : [ "id705", "id706", "id707" ] }, "id783-id1082" : { "call" : "$obj->skipStack", "extends" : "id783", "name" : "skipStack", "id" : "id783-id1082", "intro" : "Inherited, see Log::Report::Dispatcher::skipStack()
", "type" : "i_method" }, "id159" : { "name" : "NAME", "id" : "id159", "type" : "chapter", "path" : "NAME", "intro" : "Log::Report::Minimal::Domain - administer one text-domain
\n", "level" : 1 }, "id256" : { "type" : "subsection", "path" : "DETAILS/Setup and Configuration/Dancer2::Plugin::LogReport", "intro" : "To use the plugin, you simply use it in your application:
\n\n package MyApp;\n use Log::Report (); # use early and minimal once\n use Dancer2;\n use Dancer2::Plugin::LogReport %config;\n\n\n
Dancer2::Plugin::LogReport takes the same %config options as\nLog::Report itself (see Log::Report::import()).
If you want to send messages from your modules/models, there is\nno need to use this specific plugin. Instead, you should simply\nuse Log::Report to negate the need of loading all the Dancer2\nspecific code.
Only used in combination with a to filename: throw away the old file\nif it exists. Probably you wish to append to existing information.
\n\nUse the locale setting by default, which is LC_CTYPE or LC_ALL or LANG\n(in that order). If these contain a character-set which Perl understands,\nthen that is used, otherwise silently ignored.
\n" }, "id765-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
", "type" : "option", "params" : "CHARSET", "extends" : "id765", "id" : "id765-id1082", "name" : "charset" }, "id195" : { "name" : "Modes", "id" : "id195", "path" : "FUNCTIONS/Modes", "intro" : "Run-modes are explained in Log::Report::Dispatcher.
\n", "type" : "section", "subroutines" : [ "id197", "id198", "id199", "id196" ], "level" : 2 }, "id1258" : { "type" : "subsection", "path" : "DETAILS/Processing the message/Addition information", "level" : 3, "id" : "id1258", "name" : "Addition information" }, "id1033" : { "examples" : [ "id1034" ], "call" : "N__( $msgid )", "type" : "function", "intro" : "Label to indicate that the string is a text which will be translated\nlater. The function itself does nothing. See also N__w().
\n\nThis no-op function is used as label to the xgettext program to build the\ntranslation tables.
\n", "name" : "N__", "id" : "id1033" }, "id779-id1228" : { "call" : "$obj->translate( \\%options, $reason, $message )", "name" : "translate", "id" : "id779-id1228", "extends" : "id779", "intro" : "Inherited, see Log::Report::Dispatcher::translate()
", "type" : "i_method" }, "id990" : { "name" : "stack", "id" : "id990", "intro" : "When defined, that data is used to display the call stack. Otherwise,\nit is collected via caller() if needed.
depend on mode",
"extends" : "id758",
"name" : "accept",
"id" : "id758-id1228",
"intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "type" : "default" }, "id764-id818" : { "name" : "format_reason", "id" : "id764-id818", "value" : "'LOWERCASE'", "extends" : "id764", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "type" : "default" }, "id1001" : { "id" : "id1001", "name" : "a message object is reported with more parameters.", "subroutine" : "id985", "type" : "error" }, "id1214" : { "id" : "id1214", "type" : "example", "intro" : " if($ex->isFatal) { $ex->throw(reason => 'ALERT') }\n else { $ex->throw }\n\n"
},
"id741-id441" : {
"type" : "i_method",
"intro" : "Inherited, see Log::Report::Lexicon::Table::pluralIndex()
", "diagnostics" : [ "id742-id441" ], "call" : "$obj->pluralIndex( $count )", "id" : "id741-id441", "name" : "pluralIndex", "extends" : "id741" }, "id873-id217" : { "params" : "$msgid", "type" : "option", "intro" : "Inherited, see Log::Report::Message::new(_plural)
", "extends" : "id873", "id" : "id873-id217", "name" : "_plural" }, "id176-id375" : { "intro" : "Inherited, see Log::Report::Minimal::Domain::configure(formatter)
", "params" : "CODE|\\%config|'PRINTI'", "type" : "option", "extends" : "id176", "name" : "formatter", "id" : "id176-id375" }, "id784-id1228" : { "intro" : "Inherited, see Log::Report::Dispatcher::collectLocation()
", "type" : "ci_method", "call" : "$any->collectLocation", "extends" : "id784", "id" : "id784-id1228", "name" : "collectLocation" }, "id773-id1090" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::mode()
", "extends" : "id773", "id" : "id773-id1090", "name" : "mode", "call" : "$obj->mode" }, "id397" : { "type" : "i_method", "intro" : "Directory where the translation tables are kept.
\n", "id" : "id397", "name" : "lexicon", "call" : "$obj->lexicon" }, "id572" : { "id" : "id572", "name" : "DESCRIPTION", "level" : 1, "type" : "chapter", "path" : "DESCRIPTION", "intro" : "This module is translating, based on PO files. PO files are used to store\ntranslations in humanly readable format for most of existing translation\nframeworks, like GNU gettext and Perl's Maketext.
\n\nInternally, this module tries to be as efficient as possible: high\nspeed and low memory foot-print. You will not be able to sub-class\nthis class cleanly.
\n\nIf you like to change the content of PO files, then use\nLog::Report::Lexicon::POT.
\n" }, "id956" : { "call" : "$obj->callback", "id" : "id956", "name" : "callback", "intro" : "Returns the code reference which will handle each logged message.
\n", "type" : "i_method" }, "id172" : { "type" : "i_method", "intro" : "Returns the CODE which implements the formatting. It needs to be called with a\nmsgid and a HASH with arguments, usually via interpolate().
\n", "id" : "id172", "name" : "format", "call" : "$obj->format" }, "id1140" : { "value" : "created internally",
"name" : "translator",
"id" : "id1140",
"type" : "default"
},
"id809" : {
"name" : "Log::Report::Die",
"id" : "id809",
"title" : "compatibility routines with Perl's die/croak/confess",
"is_pure_pod" : false,
"distribution" : "Log-Report",
"package" : "Log::Report::Die",
"inheritance" : {
"extends" : [
"Exporter"
]
},
"version" : "1.45",
"chapters" : [
"id810",
"id1340",
"id811",
"id812",
"id813"
]
},
"id1239" : {
"type" : "default",
"value" : "LC_CTYPE",
"name" : "charset",
"id" : "id1239"
},
"id757-id1228" : {
"intro" : "Inherited, see Log::Report::Dispatcher::new(accept)
", "type" : "option", "params" : "$reasons|\\@reasons", "id" : "id757-id1228", "name" : "accept", "extends" : "id757" }, "id419-id289" : { "intro" : "Inherited, see Log::Report::Extract::new(lexicon)
", "type" : "option", "params" : "$directory", "id" : "id419-id289", "name" : "lexicon", "extends" : "id419" }, "id1195" : { "level" : 1, "intro" : "Log::Report::Exception - a single generated event
\n", "path" : "NAME", "type" : "chapter", "name" : "NAME", "id" : "id1195" }, "id398" : { "type" : "i_method", "intro" : "Return true when the function name which relates to this domain is\nallowed to be used for the indicated file. The msgid extractor will warn\nwhen there is no match.
Inherited, see Log::Report::Extract::new(lexicon)
", "type" : "default", "id" : "id420-id289", "name" : "lexicon", "extends" : "id420", "value" : "<required>" }, "id389" : { "type" : "default", "value" : "<required>", "name" : "templater", "id" : "id389" }, "id421-id289" : { "extends" : "id421", "name" : "charset", "id" : "id421-id289", "intro" : "Inherited, see Log::Report::Extract::new(charset)
", "params" : "$charset", "type" : "option" }, "id1150" : { "type" : "fault", "subroutine" : "id1149", "id" : "id1150", "name" : "cannot open JSON file for context at $fn: $!" }, "id1215" : { "intro" : "Change the $message of the exception, must be a Log::Report::Message\nobject.
\n\nWhen you use a Log::Report::Message object, you will get a new one\nreturned. Therefore, if you want to modify the message in an exception,\nyou have to re-assign the result of the modification.
Inherited, see Log::Report::Minimal::Domain::interpolate()
", "type" : "i_method", "call" : "$obj->interpolate( $msgid, [$args] )", "id" : "id180-id375", "name" : "interpolate", "extends" : "id180" }, "id1080" : { "name" : "Log::Dispatch and Log::Log4perl", "id" : "id1080", "level" : 3, "type" : "subsection", "intro" : "The two major logging frameworks for Perl are Log::Dispatch and\nLog::Log4perl; both provide a pluggable logging interface.
\n\nBoth frameworks do not have (gettext or maketext) language translation\nsupport, which has various consequences. When you wish for to report\nin some other language, it must be translated before the logging\nfunction is called. This may mean that an error message is produced\nin Chinese, and therefore also ends-up in the syslog file in Chinese.\nWhen this is not your language, you have a problem.
\n\nLog::Report translates only in the back-end, which means that the user may\nget the message in Chinese, but you get your report in your beloved Dutch.\nWhen no dispatcher needs to report the message, then no time is lost in\ntranslating.
\n\nWith both logging frameworks, you use terminology comparable to\nsyslog: the module programmer determines the seriousness of the\nerror message, not the application which integrates multiple modules.\nThis is the way perl programs usually work, but often the cause for\ninconsequent user interaction.
\n", "path" : "DETAILS/Compared to other solutions in Perl/Log::Dispatch and Log::Log4perl" }, "id339" : { "intro" : "Get the String::Print object which formats the messages.
The package name, used in the directory structure to store the\nPO files.
\n", "id" : "id450", "name" : "textdomain" }, "id146" : { "type" : "function", "call" : "__( $msgid )", "id" : "id146", "name" : "__" }, "id249" : { "type" : "i_method", "call" : "$obj->panic", "id" : "id249", "name" : "panic" }, "id712" : { "type" : "info", "name" : "no Perl in file $filename.", "id" : "id712", "subroutine" : "id708" }, "id374" : { "level" : 3, "intro" : "PO-files are quite large. You can reduce the translation table size by\ncreating a binary \"MO\"-file for each of them. Log::Report::Lexicon\nwill prefer mo files, if it encounters them, but generation is not (yet)\norganized via Log::Report components. Search for \"msgfmt\" as separate\ntool or CPAN module.
\n", "path" : "DETAILS/Extracting PO-files/More performance via MO-files", "type" : "subsection", "id" : "id374", "name" : "More performance via MO-files" }, "id1070" : { "level" : 4, "path" : "DETAILS/Error handling models/The Reason for the report/Report level comparison", "intro" : "Various frameworks used with perl programs define different labels\nto indicate the reason for the message to be produced.
\n\n Perl5 Log::Dispatch Syslog Log4Perl Log::Report\n print 0,debug debug debug trace\n print 0,debug debug debug assert\n print 1,info info info info\n warn\\n 2,notice notice info notice\n warn 3,warning warn warn mistake\n carp 3,warning warn warn warning\n die\\n 4,error err error error\n die 5,critical crit fatal fault\n croak 6,alert alert fatal alert\n croak 7,emergency emerg fatal failure\n confess 7,emergency emerg fatal panic\n\n", "type" : "subsubsection", "id" : "id1070", "name" : "Report level comparison" }, "id773-id944" : { "call" : "$obj->mode", "id" : "id773-id944", "name" : "mode", "extends" : "id773", "intro" : "
Inherited, see Log::Report::Dispatcher::mode()
", "type" : "i_method" }, "id765-id818" : { "extends" : "id765", "name" : "charset", "id" : "id765-id818", "intro" : "Inherited, see Log::Report::Dispatcher::new(charset)
", "params" : "CHARSET", "type" : "option" }, "id1349" : { "id" : "id1349", "name" : "INHERITANCE", "level" : 1, "type" : "chapter", "path" : "INHERITANCE", "intro" : "Dancer2::Logger::LogReport\n is a Moo::Object\n\n" }, "id546" : { "intro" : "
Returns an unsorted LIST of @locations. When data are specified,\nthen those will be used to replace all currently defined references.
\n", "type" : "i_method", "call" : "$obj->references( [$locations|@locations|\\@locations] )", "id" : "id546", "name" : "references" }, "id496" : { "type" : "i_method", "intro" : "Remove all the references to the indicate $filename from all defined\ntranslations. Returns the number of refs left.
\n", "id" : "id496", "name" : "removeReferencesTo", "call" : "$obj->removeReferencesTo( $filename )" }, "id436-id697" : { "intro" : "Inherited, see Log::Report::Extract::showStats()
", "type" : "i_method", "call" : "$obj->showStats( [$domains] )", "extends" : "id436", "name" : "showStats", "id" : "id436-id697" }, "id763-id1228" : { "type" : "option", "params" : "'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "id" : "id763-id1228", "name" : "format_reason", "extends" : "id763" }, "id1204" : { "name" : "report_opts", "id" : "id1204", "params" : "\\%opts", "type" : "option" }, "id1132" : { "path" : "METHODS/Constructors", "type" : "section", "subroutines" : [ "id1133" ], "level" : 2, "id" : "id1132", "name" : "Constructors" }, "id1011" : { "intro" : "Short for report TRACE => $message
Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "type" : "default" }, "id783-id818" : { "extends" : "id783", "name" : "skipStack", "id" : "id783-id818", "call" : "$obj->skipStack", "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::skipStack()
" }, "id71" : { "type" : "example", "intro" : " my $def = $sp->defaults('EL');\n say \"Default max width is \", $def->{width};\n\n",
"id" : "id71",
"name" : "getting defaults for a modifier\n"
},
"id1260" : {
"path" : "METHODS/Constructors",
"type" : "section",
"subroutines" : [
"id1169-id611"
],
"name" : "Constructors",
"id" : "id1260",
"level" : 2
},
"id785-id1228" : {
"name" : "stackTraceLine",
"id" : "id785-id1228",
"extends" : "id785",
"call" : "$any->stackTraceLine( %options )",
"options" : [
[
"id800-id1228",
"id801-id1228"
],
[
"id792-id1228",
"id793-id1228"
],
[
"id788-id1228",
"id789-id1228"
],
[
"id790-id1228",
"id791-id1228"
],
[
"id796-id1228",
"id797-id1228"
],
[
"id798-id1228",
"id799-id1228"
],
[
"id786-id1228",
"id787-id1228"
],
[
"id794-id1228",
"id795-id1228"
]
],
"type" : "ci_method",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine()
" }, "id1194" : { "name" : "Log::Report::Exception", "id" : "id1194", "is_pure_pod" : false, "title" : "a single generated event", "distribution" : "Log-Report", "inheritance" : {}, "package" : "Log::Report::Exception", "version" : "1.45", "chapters" : [ "id1195", "id1196", "id1197", "id1198", "id1201" ] }, "id991" : { "type" : "default", "name" : "stack", "id" : "id991", "value" : "undef"
},
"id869-id217" : {
"intro" : "Inherited, see Log::Report::Message::new(_domain)
", "params" : "$name|$object", "type" : "option", "extends" : "id869", "name" : "_domain", "id" : "id869-id217" }, "id718" : { "level" : 1, "path" : "NAME", "intro" : "Log::Report::Lexicon - translation component of Log::Report
\n", "type" : "chapter", "id" : "id718", "name" : "NAME" }, "id616" : { "type" : "section", "path" : "METHODS/Translating", "id" : "id616", "name" : "Translating", "level" : 2, "subroutines" : [ "id1173-id611", "id617" ] }, "id949" : { "level" : 1, "name" : "METHODS", "id" : "id949", "path" : "METHODS", "nest" : [ "id950", "id955", "id957" ], "type" : "chapter" }, "id665" : { "id" : "id665", "name" : "originalCharset", "call" : "$obj->originalCharset", "type" : "i_method", "intro" : "Returns the character-set as found in the PO-file. The strings are\nconverted into utf8 before you use them in the program.
\n" }, "id705" : { "type" : "section", "path" : "METHODS/Constructors", "level" : 2, "name" : "Constructors", "id" : "id705", "subroutines" : [ "id418-id697" ] }, "id633" : { "type" : "section", "path" : "METHODS/Translating", "level" : 2, "name" : "Translating", "id" : "id633", "subroutines" : [ "id1173-id618", "id634" ] }, "id203" : { "type" : "function", "intro" : "[1.02] Escape HTML volatile characters.
\n", "name" : "to_html", "id" : "id203", "call" : "to_html( $string )" }, "id764-id1082" : { "extends" : "id764", "value" : "'LOWERCASE'", "name" : "format_reason", "id" : "id764-id1082", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "type" : "default" }, "id194" : { "type" : "function", "id" : "id194", "name" : "use_errno", "call" : "use_errno( $reason )" }, "id761-id958" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
", "type" : "option", "params" : "'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3", "id" : "id761-id958", "name" : "mode", "extends" : "id761" }, "id683" : { "subroutine" : "id681", "name" : "no value for tag `$tag' in the context", "id" : "id683", "type" : "warning" }, "id1020" : { "type" : "function", "intro" : "Short for report FAILURE => $message
This module is reading, extending, and writing POT files. POT files\nare used to store translations in humanly readable format for most of\nexisting translation frameworks, like GNU gettext and Perl's Maketext.\nIf you only wish to access the translation, then you may use the much\nmore efficient Log::Report::Lexicon::POTcompact.
\n\nThe code is loosely based on Locale::PO, by Alan Schwartz. The coding\nstyle is a bit off the rest of Log::Report, and there was a need to\nsincere simplification. Each PO record will be represented by a\nLog::Report::Lexicon::PO.
This module handles the lookup of translation files for a whole\ndirectory tree. It is lazy loading, which means that it will only\nbuild the search tree when addressed, not when the object is\ncreated.
\n", "type" : "chapter", "level" : 1 }, "id291" : { "level" : 1, "type" : "chapter", "intro" : " # Added Log-Report-Template v0.90\n # First use of this module: extract msgids from various kinds\n # of text-files, usually web templates.\n # See script \"xgettext-perl\" for standard wrapper script\n\n my $extr = Log::Report::Template::Extract->new(\n lexicon => '/usr/share/locale',\n domain => 'my-web-site',\n pattern => 'TT2-loc',\n );\n $extr->process('website/page.html'); # many times\n $extr->showStats;\n $extr->write;\n\n # Second use: connect to Template::Toolkit\n # See DETAILS chapter below\n\n [% loc(\"Greetings {name},\", name => client.name) %]\n [% | loc(name => client.name) %]Greetings {name}[% END %]\n [% 'Greetings {name}' | loc(name => client.name) %]\n\n",
"path" : "SYNOPSIS",
"name" : "SYNOPSIS",
"id" : "id291"
},
"id625" : {
"id" : "id625",
"name" : "lexicons",
"intro" : "The $directory where the translations can be found. See\nLog::Report::Lexicon::Index for the expected structure of such\ndirectory.
\n\nThe default is based on the location of the module which instantiates\nthis translator. The filename of the module is stripped from its .pm\nextension, and used as directory name. Within that directory, there\nmust be a directory named messages, which will be the root directory\nof a Log::Report::Lexicon::Index.
Dancer2::Plugin::LogReport::Message\n is a Log::Report::Message\n\n", "path" : "INHERITANCE", "level" : 1, "id" : "id1347", "name" : "INHERITANCE" }, "id1036" : { "intro" : "
my @save = N__n \"save file\", \"save files\";\n my @save = (N__n \"save file\", \"save files\");\n my @save = N__n(\"save file\", \"save files\");\n\n # be warned about SCALARs in prototype!\n print __n @save, $nr_files; # wrong!\n print __n $save[0], $save[1], @files, %vars;\n\n", "type" : "example", "id" : "id1036", "name" : "how to use N__n()\n" }, "id137" : { "id" : "id137", "name" : "notice", "call" : "notice( $message )", "type" : "function" }, "id610" : { "level" : 2, "type" : "section", "intro" : "
My module is named Some::Module and installed in some of perl's\ndirectories, say ~perl5. The module is defining textdomain\nmy-domain. The translation is made into nl-NL.utf-8 (locale for\nDutch spoken in The Netherlands, utf-8 encoded text file).
The translation table is taken from the first existing of these files:
\n nl-NL.utf-8/LC_MESSAGES/my-domain.po\n nl-NL.utf-8/LC_MESSAGES/my-domain.po\n nl-NL.utf8/LC_MESSAGES/my-domain.po\n nl-NL/LC_MESSAGES/my-domain.po\n nl/LC_MESSAGES/my-domain.po\n\n\n
Then, attempts are made which are not compatible with gettext. The\nadvantage is that the directory structure is much simpler. The idea\nis that each domain has its own locale installation directory, instead\nof everything merged in one place, what gettext presumes.
\n\nIn order of attempts:
\n nl-NL.utf-8/my-domain.po\n nl-NL.utf8/my-domain.po\n nl-NL/my-domain.po\n nl/my-domain.po\n my-domain/nl-NL.utf8.po\n my-domain/nl-NL.po\n my-domain/nl.po\n\n\n
Filenames may get mutulated by the platform (which we will try to hide\nfrom you [please help improve this]), and are treated case-INsensitive!
\n", "path" : "DETAILS/Example", "id" : "id610", "name" : "Example" }, "id1024" : { "name" : "how to use__()\n",
"id" : "id1024",
"type" : "example",
"intro" : " print __\"Hello World\"; # translated into user's language\n print __'Hello World'; # syntax error!\n print __('Hello World'); # ok, translated\n print __\"Hello\", \" World\"; # World not translated\n\n my $s = __\"Hello World\"; # creates object, not yet translated\n print ref $s; # Log::Report::Message\n print $s; # ok, translated\n print $s->toString('fr'); # ok, forced into French\n\n"
},
"id554" : {
"call" : "$obj->addFlags( STRING )",
"diagnostics" : [
"id555"
],
"name" : "addFlags",
"id" : "id554",
"intro" : "Parse a \"flags\" line.
\n", "type" : "i_method" }, "id187" : { "id" : "id187", "name" : "expand_reasons", "type" : "function", "intro" : "Returns a sub-set of all existing message reason labels, based on the\ncontent reason patterns. Either use a comma separated list of patterns\nin string $reasons, or an ARRAY of patterns.
\n\nThe following rules apply for the patterns:
\n\n REASONS = BLOCK [ ',' BLOCKS ] | ARRAY-of-REASON\n BLOCK = '-' TO | FROM '-' TO | ONE | SOURCE\n FROM,TO,ONE = 'TRACE' | 'ASSERT' | ,,, | 'PANIC'\n SOURCE = 'USER' | 'PROGRAM' | 'SYSTEM' | 'FATAL' | 'ALL' | 'NONE'\n\n\n
The SOURCE specification group all reasons which are usually related to\nthe problem: report about problems caused by the user, reported by\nthe program, or with system interaction.
\n", "diagnostics" : [ "id189", "id190", "id191" ], "examples" : [ "id188" ], "call" : "expand_reasons( $reasons|\\@reasons )" }, "id538" : { "type" : "i_method", "intro" : "Returns the actual msgid, which cannot be undef.
# file xxx/perl5.8.8/My/Module.pm\n use Log::Report 'my-domain',\n translator => Log::Report::Translator::POT->new;\n\n # lexicon now in xxx/perl5.8.8/My/Module/messages/\n\n", "name" : "default lexicon directory\n", "id" : "id629" }, "id588" : { "intro" : "
Lookup the translations with the $msgid. Returns a SCALAR, when only\none translation is known, and an ARRAY where there are multiple.\nReturns undef when nothing about the translation is known.
Inherited, see Log::Report::Lexicon::Table::translations()
", "type" : "i_method", "call" : "$obj->translations( [$active] )", "diagnostics" : [ "id740-id569" ], "extends" : "id739", "id" : "id739-id569", "name" : "translations" }, "id945" : { "level" : 1, "intro" : "Log::Report::Dispatcher::Callback - call a code-ref for each log-line
\n", "path" : "NAME", "type" : "chapter", "id" : "id945", "name" : "NAME" }, "id188" : { "intro" : "WARNING-FAULT # == WARNING,MISTAKE,ERROR,FAULT\n WARNING,INFO # == WARNING,INFO\n -INFO # == TRACE-INFO\n ALERT- # == ALERT,FAILURE,PANIC\n USER # == MISTAKE,ERROR\n ALL # == TRACE-PANIC\n FATAL # == ERROR,FAULT,FAILURE,PANIC [1.07]\n NONE # ==\n\n", "type" : "example", "name" : "of expanded REASONS\n", "id" : "id188" }, "id669" : { "version" : "1.16", "chapters" : [ "id670", "id671", "id672", "id673", "id689" ], "name" : "Log::Report::Translator::Context", "id" : "id669", "is_pure_pod" : false, "title" : "handle translation contexts", "distribution" : "Log-Report-Lexicon", "inheritance" : {}, "package" : "Log::Report::Translator::Context" }, "id138" : { "call" : "warning( $message )", "name" : "warning", "id" : "id138", "type" : "function" }, "id709" : { "name" : "charset", "id" : "id709", "params" : "$charset", "type" : "option", "intro" : "
PPI v1.284 still does not support unicode by itself, so you need to help\nit by specifying the character-set which is used in the file.
\n" }, "id154" : { "type" : "function", "id" : "id154", "name" : "N__w", "call" : "N__w( STRING )" }, "id587" : { "level" : 2, "id" : "id587", "name" : "Managing PO's", "path" : "METHODS/Managing PO's", "nest" : [ "id1272", "id1273" ], "type" : "section" }, "id1118" : { "level" : 2, "name" : "Logging", "id" : "id1118", "subroutines" : [ "id781-id1090", "id785-id1090", "id778-id1090", "id784-id1090", "id777-id1090", "id780-id1090", "id783-id1090", "id779-id1090", "id1119" ], "type" : "section", "path" : "METHODS/Logging" }, "id773-id1082" : { "intro" : "Inherited, see Log::Report::Dispatcher::mode()
", "type" : "i_method", "call" : "$obj->mode", "extends" : "id773", "name" : "mode", "id" : "id773-id1082" }, "id537" : { "path" : "METHODS/Attributes", "type" : "section", "subroutines" : [ "id542", "id550", "id549", "id543", "id547", "id541", "id545", "id551", "id546", "id540", "id539", "id548", "id544", "id552", "id538", "id554" ], "level" : 2, "id" : "id537", "name" : "Attributes" }, "id800-id1174" : { "id" : "id800-id1174", "name" : "abstract", "extends" : "id800", "type" : "option", "params" : "INTEGER", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(abstract)
" }, "id774-id1228" : { "call" : "$obj->isDisabled", "extends" : "id774", "name" : "isDisabled", "id" : "id774-id1228", "intro" : "Inherited, see Log::Report::Dispatcher::isDisabled()
", "type" : "i_method" }, "id532" : { "params" : "$locations|\\@locations", "type" : "option", "intro" : "As SCALAR, this contains a blank separated list of @locations.\nThe @locations are of the form filename:linenumber, for\ninstance lib/Foo.pm:42\nSee addReferences()
Inherited, see Log::Report::Message::new(_tag)
", "params" : "$tags|\\@tags", "type" : "option", "extends" : "id883", "name" : "_tag", "id" : "id883-id217" }, "id764-id944" : { "value" : "'LOWERCASE'", "extends" : "id764", "name" : "format_reason", "id" : "id764-id944", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "type" : "default" }, "id456" : { "type" : "option", "params" : "EXPRESSION", "intro" : "The algorithm to be used to calculate which translated msgstr to use.
\n", "name" : "plural_alg", "id" : "id456" }, "id582" : { "type" : "error", "id" : "id582", "name" : "cannot detect charset in $fn.", "subroutine" : "id575" }, "id783-id1090" : { "intro" : "Inherited, see Log::Report::Dispatcher::skipStack()
", "type" : "i_method", "call" : "$obj->skipStack", "extends" : "id783", "id" : "id783-id1090", "name" : "skipStack" }, "id323" : { "level" : 1, "path" : "DESCRIPTION", "intro" : "This module extends Template, which is the core of Template Toolkit.\nThe main addition is support for translations via the translation\nframework offered by Log::Report.
\n\nYou add translations to a template system, by adding calls to some\ntranslation function (by default called loc()) to your template text.\nThat function will perform dark magic to collect the translation from\ntranslation tables, and fill in values. For instance:
\n [% price = 3.14 %]\n <divE<gt>Price: [% price %]</divE<gt> # no translation\n <divE<gt>[% loc(\"Price: {price}\") %]</divE<gt> # translation optional\n\n\nIt's quite a lot of work to make your templates translatable.\nPlease read the DETAILS section before you start using this module.
\n", "type" : "chapter", "name" : "DESCRIPTION", "id" : "id323" }, "id789-id1228" : { "id" : "id789-id1228", "name" : "filename", "extends" : "id789", "value" : "<required>", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
", "type" : "default" }, "id1084" : { "level" : 1, "type" : "chapter", "intro" : "dispatcher Log::Report::Dispatcher::Perl => 'default',\n accept => 'NOTICE-';\n\n # close the default dispatcher\n dispatcher close => 'default';\n\n", "path" : "SYNOPSIS", "id" : "id1084", "name" : "SYNOPSIS" }, "id140" : { "type" : "function", "call" : "error( $message )", "name" : "error", "id" : "id140" }, "id1154" : { "type" : "example", "intro" : "
use Log::Report 'my-domain', context_rules => {};\n\n",
"id" : "id1154"
},
"id951" : {
"name" : "new",
"id" : "id951",
"diagnostics" : [
"id954"
],
"call" : "$class->new( $type, $name, %options )",
"options" : [
[
"id757-id944",
"id758-id944"
],
[
"id952",
"id953"
],
[
"id765-id944",
"id766-id944"
],
[
"id763-id944",
"id764-id944"
],
[
"id759-id944",
"id760-id944"
],
[
"id761-id944",
"id762-id944"
]
],
"type" : "c_method"
},
"id385" : {
"type" : "default",
"value" : "'loc'",
"name" : "translation_function",
"id" : "id385"
},
"id53" : {
"examples" : [
"id64"
],
"call" : "$class->new( %options )",
"intro" : "The %options of the constructure configure processing options.
\n", "type" : "c_method", "id" : "id53", "name" : "new", "options" : [ [ "id62", "id63" ], [ "id58", "id59" ], [ "id60", "id61" ], [ "id54", "id55" ], [ "id56", "id57" ] ] }, "id1190" : { "type" : "section", "path" : "METHODS/Attributes", "level" : 2, "name" : "Attributes", "id" : "id1190", "subroutines" : [ "id771-id1174", "id774-id1174", "id775-id1174", "id772-id1174", "id773-id1174", "id1191" ] }, "id1302" : { "path" : "OVERLOADED", "type" : "chapter", "subroutines" : [ "id863-id217", "id861-id217", "id862-id217" ], "level" : 1, "name" : "OVERLOADED", "id" : "id1302" }, "id804" : { "nest" : [ "id805", "id806" ], "path" : "DETAILS/Processing the message", "type" : "section", "name" : "Processing the message", "id" : "id804", "level" : 2 }, "id430-id697" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Extract::addPot()
", "extends" : "id430", "id" : "id430-id697", "name" : "addPot", "call" : "$obj->addPot( $domain, $pot, %options )" }, "id490" : { "subroutine" : "id489", "id" : "id490", "name" : "translation already exists for '$msgid' with '$ctxt'.", "type" : "error" }, "id1264" : { "name" : "Processing the message", "id" : "id1264", "level" : 2, "nest" : [ "id1265", "id1266" ], "path" : "DETAILS/Processing the message", "type" : "section" }, "id743" : { "type" : "i_method", "intro" : "This method needs to be called after setting (reading or creating) a new\ntable header, to interpret the plural algorithm as specified in the\nPlural-Forms header field. [1.09] The header field is not required\nwhen not used.
A full list of plural forms per language can be found at\nhttps://docs.translatehouse.org/projects/localization-guide/en/latest/l10n/pluralforms.html
\n", "id" : "id743", "name" : "setupPluralAlgorithm", "diagnostics" : [ "id744" ], "call" : "$obj->setupPluralAlgorithm" }, "id335" : { "params" : "CLASS", "type" : "option", "intro" : "Use your own extension to Log::Report::Template::Textdomain.
\n", "id" : "id335", "name" : "textdomain_class" }, "id58" : { "id" : "id58", "name" : "encode_for", "type" : "option", "params" : "\\%rules|'HTML'", "intro" : "[0.91] The format string and the inserted values will get encoded according to\nsome %rules. Function encode_entities() provided by HTML::Entities\nis used when you specify the predefined string HTML. See encodeFor()\nand Output encoding.
Read the settings from the $file. The parameters found in the file are\nused as default for the parameters above. This parameter is especially\nuseful for the context_rules, which need to be shared between the\nrunning application and xgettext-perl. See readConfig()
\n", "id" : "id1145", "name" : "config" }, "id540" : { "intro" : "Returns the actual msgid_plural, which can be undef.
Inherited, see Log::Report::Minimal::Domain::isConfigured()
", "id" : "id171-id375", "name" : "isConfigured", "extends" : "id171", "call" : "$obj->isConfigured" }, "id245" : { "type" : "i_method", "call" : "$obj->error", "id" : "id245", "name" : "error" }, "id182" : { "id" : "id182", "name" : "NAME", "type" : "chapter", "path" : "NAME", "intro" : "Log::Report::Util - helpful routines to Log::Report
\n", "level" : 1 }, "id1200" : { "type" : "overload", "intro" : "Always returns true: the exception object exists.
This module uses standard gettext PO-translation tables via the\nLog::Report::Lexicon distribution. An important role here is\nfor the 'textdomain': the name of the set of translation tables.
\n\nFor code, you say \"use Log::Report '<textdomain>;\" in each related\nmodule (pm file). We cannot do achieve comparible syntax with\nTemplate Toolkit: you must specify the textdomain before the\ntemplates get processed.
\n\nYour website may contain multiple separate sets of templates. For\ninstance, a standard website implementation with some local extensions.\nThe only way to get that to work, is by using different translation\nfunctions: one textdomain may use 'loc()', where an other uses 'trans()'.
\n", "path" : "DETAILS/Textdomains", "name" : "Textdomains", "id" : "id363", "nest" : [ "id364", "id365" ] }, "id1074" : { "id" : "id1074", "name" : "run-time change mode of a dispatcher\n", "type" : "example", "intro" : "To change the running mode of the dispatcher, you can do
\n\n dispatcher mode => DEBUG => 'myname';\n\n\n
However, be warned that this does not change the types of messages\naccepted by the dispatcher! So: probably you will not receive\nthe trace, assert, and info messages after all. So, probably you\nneed to replace the dispatcher with a new one with the same name:
\n\n dispatcher FILE => 'myname', to => ..., mode => 'DEBUG';\n\n\n
This may reopen connections (depends on the actual dispatcher), which\nmight be not what you wish to happened. In that case, you must take\nthe following approach:
\n\n # at the start of your program, overrule the default 'NOTICE-' !!\n dispatcher FILE => 'myname', to => ..., accept => 'ALL';\n\n # now it works\n dispatcher mode => DEBUG => 'myname'; # debugging on\n ...\n dispatcher mode => NORMAL => 'myname'; # debugging off\n\n\n
Of course, this comes with a small overall performance penalty.
\n" }, "id319" : { "name" : "Use in combination with contexts", "id" : "id319", "type" : "section", "intro" : "This example extends the previous with using context sensitive translations,\nas implemented by Log::Report::Translator::Context.
\n\nLet's say that the translation of some of the sentences on the website depend\non the gender of the addressed person. An example of the use in a TT2\ntemplate:
\n\n [% loc(\"{name<gender} forgot his key\", name => person.name) %]\n\n\nThe extraction script xgettext-perl will expand this into two records\nin the PO file, respectively with msgctxt attribute 'gender=male' and\n'gender=female'.
\n\nWhen your PO-files are not generated by 'xgettext-perl', you do not need\na separate domain configuration file:
\n\n $domain->configure(\n context_rules => +{gender => ['male','female']},\n translator => $translator,\n );\n\n\nWhen your PO-files are generated by 'xgettext-perl', you need to share\nthe context-rules between that msgid extractor and your runtime code. That\nsame file needs to be passed with the 'domain' parameter to the script.
\n\n # add context_rules either explicit or via 'config' filename\n $domain->configure(\n config => 'my/own/$domain.conf',\n translator => $translator,\n );\n\n\n
Now, when you generate the pages, you need to set-up the right context.\nIn this case, we set-up the gender of the person who gets addressed.\n(The name 'gender' is good for examples, but quite non-descriptive.\nMaybe 'user_gender' is more maintainable)
\n\n $domain->setContext( +{gender => 'male'} ); # or ('gender=male')\n $domain->setContext( \"gender=male\" ); # same\n\n\n\n=encoding utf-8
\n", "path" : "DETAILS/Use in combination with contexts", "level" : 2 }, "id771-id818" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::name()
", "id" : "id771-id818", "name" : "name", "extends" : "id771", "call" : "$obj->name" }, "id143" : { "type" : "function", "call" : "failure( $message )", "name" : "failure", "id" : "id143" }, "id927" : { "intro" : "Convert the data of this message into a (nested) HASH which optimally\npreserves its content. Pass this to thaw() to get the object back.
\n\nThe returned HASH can be serialized safely with (for instance) YAML\nor JSON. Then, it can be reconstructed from the de-serialized data.\nAt the moment, all facts can be preserved.
\n", "type" : "i_method", "examples" : [ "id928" ], "call" : "$obj->freeze( %options )", "name" : "freeze", "id" : "id927" }, "id1226" : { "examples" : [ "id1227" ], "call" : "$obj->print( [$fh] )", "type" : "i_method", "intro" : "The default filehandle is STDOUT.
\n", "id" : "id1226", "name" : "print" }, "id401" : { "id" : "id401", "name" : "translateTo", "call" : "$obj->translateTo( $lang )", "type" : "i_method", "intro" : "Set the language to translate to for $lang, for this domain only. This may\nbe useful when various text domains do not support the same destination languages.\nBut in general, you can best use Log::Report::Template::translateTo().
\n" }, "id781-id944" : { "name" : "addSkipStack", "id" : "id781-id944", "extends" : "id781", "call" : "$any->addSkipStack( @CODE )", "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::addSkipStack()
" }, "id780-id1090" : { "extends" : "id780", "id" : "id780-id1090", "name" : "collectStack", "call" : "$any->collectStack( [$maxdepth] )", "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::collectStack()
" }, "id320" : { "id" : "id320", "name" : "Log::Report::Template", "title" : "Template Toolkit with translations", "is_pure_pod" : false, "distribution" : "Log-Report-Template", "package" : "Log::Report::Template", "inheritance" : { "extends" : [ "Template" ] }, "version" : "1.05", "chapters" : [ "id321", "id1317", "id322", "id323", "id324", "id362" ] }, "id782" : { "id" : "id782", "intro" : "By default, all lines in the Log::Report packages are skipped from\ndisplay, with a simple CODE as this:
\n\n sub in_lr { $_[0][0] =~ m/^Log\\:\\:Report(?:\\:\\:|$)/ }\n Log::Report::Dispatcher->addSkipStack(\\&in_lr);\n\n\nThe only parameter to in_lr is the return of caller(). The first\nelement of that ARRAY is the package name of a stack line.
\n", "type" : "example" }, "id262" : { "name" : "Logging DBIC database queries and errors", "id" : "id262", "level" : 3, "type" : "subsection", "path" : "DETAILS/In use/Logging DBIC database queries and errors", "intro" : "If you use manual DBIx::Class in your application, you can easily integrate\nits logging and exceptions. To log SQL queries:
\n\n # Log all queries and execution time\n $schema->storage->debugobj(new Log::Report::DBIC::Profiler);\n $schema->storage->debug(1);\n\n\n
By default, exceptions from DBIC are classified at the level \"error\". This\nis normally a user level error, and thus may be filtered as normal program\noperation. If you do not expect to receive any DBIC exceptions, then it\nis better to class them at the level \"panic\":
\n\n # panic() DBIC errors\n $schema->exception_action(sub { panic @_ });\n # Optionally get a stracktrace too\n $schema->stacktrace(1);\n\n\nIf you are occasionally running queries where you expect to naturally\nget exceptions (such as not inserting multiple values on a unique constraint),\nthen you can catch these separately:
\n\n try { $self->schema->resultset('Unique')->create() };\n # Log any messages from try block, but only as trace\n $@->reportAll(reason => 'TRACE');\n\n"
},
"id968" : {
"intro" : "See reasonToLevel().
\n", "type" : "option", "params" : "ARRAY-of-PAIRS", "id" : "id968", "name" : "to_level" }, "id880-id217" : { "intro" : "Inherited, see Log::Report::Message::new(_prepend)
", "type" : "default", "value" : "undef",
"extends" : "id880",
"name" : "_prepend",
"id" : "id880-id217"
},
"id878" : {
"type" : "default",
"name" : "_category",
"id" : "id878",
"value" : "undef"
},
"id732" : {
"level" : 2,
"id" : "id732",
"name" : "Attributes",
"type" : "section",
"path" : "METHODS/Attributes"
},
"id1252" : {
"type" : "fault",
"subroutine" : "id1249",
"name" : "cannot write log into $file: $!",
"id" : "id1252"
},
"id859" : {
"name" : "DESCRIPTION",
"id" : "id859",
"level" : 1,
"type" : "chapter",
"path" : "DESCRIPTION",
"intro" : "Any use of a constructor function exported by Log::Report, like\n__() (the function is named underscore-underscore) or __x()\n(underscore-underscore-x) will result in this Message object. It will capture\nsome environmental information as well.
The optional translation is delayed until it is really needed.\nCreating an object first and translating it later, might be slower than\ntranslating it immediately. However (by design decissions of Log::Report)\non the location where the message is produced, we do not yet know in\nwhat language to translate it to: that depends on the actual log dispatcher\nconfigurations in the main program.
\n" }, "id895" : { "params" : "ISO", "type" : "option", "intro" : "[1.00] Override language setting from locale, for instance because that\nis not configured correctly (yet). This does not extend to prepended\nor appended translated message object.
\n", "id" : "id895", "name" : "_lang" }, "id906" : { "intro" : "Returns the string or Log::Report::Message object which is appended\nafter this one. Usually undef.
Inherited, see Log::Report::Dispatcher::stackTraceLine(call)
", "extends" : "id792", "id" : "id792-id958", "name" : "call" }, "id222" : { "type" : "i_method", "intro" : "Get or set the reason of a message
\n", "name" : "reason", "id" : "id222", "call" : "$obj->reason" }, "id928" : { "intro" : "my $clone = Log::Report::Message->thaw($msg->freeze);\n\n", "type" : "example", "id" : "id928", "name" : "to thaw a frozen\n" }, "id914-id217" : { "intro" : "
Inherited, see Log::Report::Message::to()
", "type" : "i_method", "call" : "$obj->to( [$name] )", "extends" : "id914", "name" : "to", "id" : "id914-id217" }, "id1149" : { "intro" : "Helper method, which simply parses the content $filename into a HASH to be\nused as parameters to configure(). The filename must end on '.pl',\nto indicate that it uses perl syntax (can be processed with Perl's do\ncommand) or end on '.json'. See also chapter Configuring below.
Currently, this file can be in Perl native format (when ending on .pl)\nor JSON (when it ends with .json). Various modules may explain parts\nof what can be found in these files, for instance\nLog::Report::Translator::Context.
Process the $template into $output, filling in the %vars.
\n" }, "id1162" : { "name" : "configuring global values", "id" : "id1162", "type" : "subsection", "intro" : "Say, you log for a (Dancer) webserver, where you wish to include the website\nname in some of the log lines. For this, (ab)use the translation context:
\n\n ### first, enable translation contexts\n use Log::Report 'my-domain', context_rules => { ... };\n\n # or\n use Log::Report 'my-domain';\n textdomain->configure(context_rules => { ... });\n\n # or\n textdomain 'my-domain', content_rules => { ... };\n\n ### every time you start working for a different virtual host\n (textdomain 'my-domain')->setContext(host => $host);\n\n ### now you can use that in your code\n package My::Package;\n use Log::Report 'my-domain';\n error __x\"in {_context.host} not logged-in {user}\", user => $username;\n\n",
"path" : "DETAILS/Configuring/configuring global values",
"level" : 3
},
"id786-id818" : {
"id" : "id786-id818",
"name" : "package",
"extends" : "id786",
"type" : "option",
"params" : "CLASS",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
" }, "id1230" : { "name" : "SYNOPSIS", "id" : "id1230", "level" : 1, "type" : "chapter", "path" : "SYNOPSIS", "intro" : " dispatcher Log::Report::Dispatcher::File => 'stderr',\n to => \\*STDERR, accept => 'NOTICE-';\n\n # close a dispatcher\n dispatcher close => 'stderr';\n\n # let dispatcher open and close the file\n dispatcher FILE => 'mylog', to => '/var/log/mylog', charset => 'utf-8';\n ...\n dispatcher close => 'mylog'; # will close file\n\n # open yourself, then also close yourself\n open OUT, \">:encoding('iso-8859-1')\", '/var/log/mylog'\n or fault \"...\";\n dispatcher FILE => 'mylog', to => \\*OUT;\n ...\n dispatcher close => 'mylog';\n close OUT;\n\n # dispatch into a scalar\n my $output = '';\n open $outfile, '>', \\$output;\n dispatcher FILE => 'into-scalar', to => \\$outfile;\n ...\n dispatcher close => 'into-scalar';\n print $output;\n\n"
},
"id796-id1174" : {
"type" : "option",
"params" : "INTEGER",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "name" : "max_line", "id" : "id796-id1174", "extends" : "id796" }, "id877" : { "id" : "id877", "name" : "_category", "intro" : "The category when the real gettext library is used, for instance\nLC_MESSAGES.
\n", "type" : "option", "params" : "INTEGER" }, "id543" : { "intro" : "Add multiple lines to the translator's comment block. Returns an\nempty string if there are no comments.
\n", "type" : "i_method", "call" : "$obj->addComment( @lines|\\@lines|$text )", "name" : "addComment", "id" : "id543" }, "id493" : { "intro" : "The translation of a blank MSGID is used to store a MIME header, which\ncontains some meta-data. When only a $field is specified, that content is\nlooked-up (case-insensitive) and returned. When a $content is specified,\nthe knowledge will be stored. In latter case, the header structure\nmay get created. When the $content is set to undef, the field will\nbe removed.
undef"
},
"id433-id697" : {
"extends" : "id433",
"id" : "id433-id697",
"name" : "cleanup",
"call" : "$obj->cleanup( %options )",
"type" : "i_method",
"options" : [
[
"id434-id697",
"id435-id697"
]
],
"intro" : "Inherited, see Log::Report::Extract::cleanup()
" }, "id742-id637" : { "extends" : "id742", "id" : "id742-id637", "name" : "there is no Plural-Forms field in the header, but needed.", "subroutine" : "id741", "type" : "error", "intro" : "Inherited, see Log::Report::Lexicon::Table::pluralIndex()
" }, "id740" : { "id" : "id740", "name" : "only acceptable parameter is 'ACTIVE'", "subroutine" : "id739", "type" : "error" }, "id175-id1127" : { "name" : "where", "id" : "id175-id1127", "extends" : "id175", "value" : "<required>", "type" : "default", "intro" : "Inherited, see Log::Report::Minimal::Domain::configure(where)
" }, "id1332" : { "level" : 1, "intro" : "Log::Report::Lexicon::POTcompact\n is a Log::Report::Lexicon::Table\n\n", "path" : "INHERITANCE", "type" : "chapter", "id" : "id1332", "name" : "INHERITANCE" }, "id73" : { "intro" : "
use String::Print 'oo'; # do not import the functions\n\n my $sp = String::Print->new(\n modifiers => [ EUR => sub {sprintf \"%5.2f e\", $_[0]} ],\n serializers => [ UNDEF => sub {'-'} ],\n defaults => [ DT => { standard => 'ISO' } ],\n );\n\n $sp->printi(\"price: {p EUR}\", p => 3.1415); # price: ␣␣3.14 e\n $sp->printi(\"count: {c}\", c => undef); # count: -\n my $s = $sp->sprinti(\"price: {p EUR}\", p => 7); # output in $s\n\n",
"type" : "example",
"id" : "id73"
},
"id967" : {
"intro" : "The Log::Log4perl infrastructure has all settings in a configuration\nfile. In that file, you should find a category with the $name.
\n", "type" : "c_method", "options" : [ [ "id757-id958", "id972" ], [ "id765-id958", "id766-id958" ], [ "id970", "id971" ], [ "id763-id958", "id764-id958" ], [ "id759-id958", "id760-id958" ], [ "id761-id958", "id762-id958" ], [ "id968", "id969" ] ], "call" : "$class->new( $type, $name, %options )", "diagnostics" : [ "id973" ], "name" : "new", "id" : "id967" }, "id962" : { "name" : "Reasons <--> Levels", "id" : "id962", "type" : "section", "intro" : "The REASONs for a message in Log::Report are names quite similar to\nthe log levels used by Log::Log4perl. The default mapping is list\nbelow. You can change the mapping using new(to_level).
\n\n TRACE => $DEBUG ERROR => $ERROR\n ASSERT => $DEBUG FAULT => $ERROR\n INFO => $INFO ALERT => $FATAL\n NOTICE => $INFO FAILURE => $FATAL\n WARNING => $WARN PANIC => $FATAL\n MISTAKE => $WARN\n\n", "path" : "DESCRIPTION/Reasons <--> Levels", "level" : 2 }, "id268" : { "name" : "METHODS", "id" : "id268", "level" : 1, "type" : "chapter", "nest" : [ "id269", "id270", "id272" ], "path" : "METHODS" }, "id686" : { "subroutine" : "id685", "name" : "tags value must have form `a=b', found `$this' in `$source'", "id" : "id686", "type" : "error" }, "id788" : { "id" : "id788", "name" : "filename", "type" : "option", "params" : "STRING" }, "id636" : { "subroutine" : "id634", "id" : "id636", "name" : "read table $file as $class for $dname in $locale.", "type" : "info" }, "id738" : { "type" : "i_method", "intro" : "
Add the information from a $po into this POT. If the msgid of the $po\nis already known, that is an error.
\n", "id" : "id738", "name" : "add", "call" : "$obj->add( $po )" }, "id872" : { "name" : "_count", "id" : "id872", "value" : "undef",
"type" : "default"
},
"id206" : {
"intro" : "The domain for the registered $package is returned.
\n\nWith $domain, $filename and $line, this registers a location where\nthe textdomain is specified first. Each $package can only belong to\none $domain.
\n", "type" : "function", "call" : "pkg2domain( $package, [$domain, $filename, $line] )", "diagnostics" : [ "id207" ], "name" : "pkg2domain", "id" : "id206" }, "id109" : { "id" : "id109", "name" : "Stacking modifiers", "type" : "subsection", "intro" : "You can add more than one modifier. The modifiers detect the extend of\ntheir own information (via a regular expression), and therefore the\nformatter understands where one ends and the next begins.
\n\nThe modifiers are called in order:
\n\n printi \"price: {p€%9s}\\n\", p => $p; # price: ␣␣␣123.45\n printi \"!{t TIME%10s}!\", t => $now; # !␣␣12:59:17!\n\n printp \"price: %9{€}s\\n\", $p; # price: ␣␣␣123.45\n printp \"!%10{TIME}s!\", $now; # !␣␣12:59:17!\n\n",
"path" : "DETAILS/Interpolation: Modifiers/Stacking modifiers",
"level" : 3
},
"id754" : {
"level" : 1,
"id" : "id754",
"name" : "METHODS",
"path" : "METHODS",
"nest" : [
"id755",
"id770",
"id776"
],
"type" : "chapter"
},
"id92" : {
"level" : 2,
"path" : "DETAILS/Interpolation: keys",
"intro" : "A key is a bareword (like a variable name) or a list of barewords\nseparated by dots (no blanks!)
\n\nPlease use explanatory key names, to help the translation\nprocess once you need that (in the future).
\n", "type" : "section", "id" : "id92", "name" : "Interpolation: keys", "nest" : [ "id93", "id94" ] }, "id613" : { "name" : "SYNOPSIS", "id" : "id613", "level" : 1, "intro" : "# normal use (end-users view)\n\n textdomain 'my-domain',\n translator => Log::Report::Translator::Gettext->new;\n\n print __\"Hello World\\n\"; # language determined by environment\n\n # internal use\n\n my $msg = Log::Report::Message->new(\n _msgid => \"Hello World\\n\",\n _textdomain => 'my-domain',\n );\n\n print Log::Report::Translator::Gettext->new\n ->translate($msg, 'nl-BE');\n\n", "path" : "SYNOPSIS", "type" : "chapter" }, "id227" : { "name" : "DESCRIPTION", "id" : "id227", "level" : 1, "intro" : "
The Log::Report exception/translation framework defines a large\nnumber of logging back-ends. The same log messages can be sent to\nmultiple destinations at the same time via flexible dispatchers.\nWhen you use this logger in your Dancer application, it will nicely\nintegrate with non-Dancer modules which need logging.
\n\nMany log back-ends, like syslog, have more levels of system messages.\nModules who explicitly load this module can use the missing assert,\nnotice, panic, and alert log levels. The trace name is\nprovided as well: when you are debugging, you add a 'trace' to your\nprogram... its just a better name than 'debug'.
You probably want to set a very simple logger_format, because the\ndispatchers do already add some of the fields that the default\nsimple format adds. For instance, to get the filename/line-number\nin messages depends on the dispatcher 'mode' (f.i. 'DEBUG').
You also want to set the log level to debug, because level filtering\nis controlled per dispatcher (as well)
Inherited, see Log::Report::Dispatcher::stackTraceLine(max_line)
", "type" : "default", "value" : "undef",
"extends" : "id797",
"name" : "max_line",
"id" : "id797-id958"
},
"id1286" : {
"path" : "DETAILS/Processing the message/Addition information",
"type" : "subsection",
"level" : 3,
"name" : "Addition information",
"id" : "id1286"
},
"id1066" : {
"level" : 3,
"path" : "DETAILS/Introduction/Lightweight Log::Report::Optional",
"intro" : "When you want to use Log::Report features as cheap as possible, you\nmay use Log::Report::Optional in your module. In this case, your\nmodule can use error() and __x() with very little cost: they\nwill not build internal objects and support translations. It's fast\nand few dependencies.
The beauty is, then when the main program which uses module does\ninitiate the full Log::Report functionality, then your module will\nalso switch to full support mode.
\n", "type" : "subsection", "id" : "id1066", "name" : "Lightweight Log::Report::Optional" }, "id737" : { "level" : 3, "id" : "id737", "name" : "Administration", "subroutines" : [ "id741", "id745", "id743", "id746", "id738", "id739" ], "type" : "subsection", "path" : "METHODS/Managing PO's/Administration" }, "id96" : { "nest" : [ "id97", "id100", "id101", "id102", "id103", "id104", "id105", "id106", "id107", "id108", "id109" ], "id" : "id96", "name" : "Interpolation: Modifiers", "type" : "section", "intro" : "Modifiers are used to change the value to be inserted, before\nthe characters get interpolated in the line. This is a powerful\nsimplification. Some useful modifiers are already provided by default.\nThey are also good examples how to write your own.
\n\nLet's discuss this with an example.\nIn traditional (gnu) gettext, you would write:
\n\n printf(gettext(\"approx pi: %.6f\\n\"), PI);\n\n\n
to get PI printed with six digits in the fragment.\nLocale::TextDomain has two ways to achieve that:
\n\n printf __\"approx pi: %.6f\\n\", PI;\n print __x\"approx pi: {approx}\\n\", approx => sprintf(\"%.6f\", PI);\n\n\nThe first does not respect the wish to be able to reorder the arguments\nduring translation (although there are ways to work around that) The\nsecond version is quite long. The string to be translated differs\nbetween the two examples.
\n\nWith Log::Report, above syntaxes do work as well, but you can also do:
\n # with optional translations\n print __x\"approx pi: {pi%.6f}\\n\", pi => PI;\n\n\nThe base for __x() is the printi() provided by this module. Internally,\nit will call printi to fill-in parameters:
\n printi \"approx pi: {pi%.6f}\\n\", pi => PI;\n\n\nAnother example:
\n\n printi \"{perms} {links%2d} {user%-8s} {size%10d} {fn}\\n\",\n perms => '-rw-r--r--', links => 7, user => 'me',\n size => 12345, fn => $filename;\n\n\nAn additional advantage (when you use translation) is the fact that not\nall languages produce comparable length strings. Now, the translators\ncan change the format, such that the layout of tables is optimal for their\nlanguage.
\n\nAbove example in printp() syntax, shorter but less maintainable:
\n\n printp \"%s %2d %-8s 10d %s\\n\",\n '-rw-r--r--', 7, 'me', 12345, $filename;\n\n", "path" : "DETAILS/Interpolation: Modifiers", "level" : 2 }, "id87" : { "name" : "sprintp", "id" : "id87", "type" : "function", "intro" : "
Where sprinti() uses named parameters --especially useful when the\nstrings need translation-- this function stays close to the standard\nsprintf(). All features of POSIX formats are supported. This\nshould say enough: you can use %3$0#5.*d, if you like.
It may be useful to know that the positional $format is rewritten and\nthen fed into sprinti(). Be careful with the length of the @positionals:\nsuperfluous parameter %options are passed along to sprinti(), and\nshould only contain \"specials\": parameter names which start with '_'.
# usually, the context information is in a separate file\n textdomain 'my-domain', config => $filename;\n\n", "type" : "chapter", "level" : 1 }, "id787" : { "type" : "default", "name" : "package", "id" : "id787", "value" : "<required>" }, "id267" : { "level" : 1, "type" : "chapter", "path" : "DESCRIPTION", "intro" : "
This template engine allows you to use manual Template::Toolkit in manual Dancer2,\nincluding the translation extensions offered by Log::Report::Template.
\n", "id" : "id267", "name" : "DESCRIPTION" }, "id922" : { "type" : "i_method", "intro" : "[1.11] Translate the message, and then entity encode HTML volatile characters.
\n\n[1.20] When used in combination with a templating system, you may want to\nuse content_for => 'HTML' in Log::Report::Domain::configure(formatter).
Inherited, see Log::Report::Dispatcher::stackTraceLine(max_params)
", "params" : "INTEGER", "type" : "option" }, "id228" : { "distribution" : "Dancer2-Plugin-LogReport", "package" : "Dancer2::Plugin::LogReport", "inheritance" : { "extends" : [ "Dancer2::Plugin" ] }, "id" : "id228", "name" : "Dancer2::Plugin::LogReport", "title" : "logging, exceptions and translations in Dancer2 via Log::Report", "is_pure_pod" : false, "chapters" : [ "id229", "id1318", "id230", "id231", "id232", "id252" ], "version" : "2.03" }, "id1276" : { "path" : "METHODS/Managing PO's/Translation", "type" : "subsection", "subroutines" : [ "id488", "id487" ], "id" : "id1276", "name" : "Translation", "level" : 3 }, "id509" : { "call" : "ms_install_codepage_id", "id" : "id509", "name" : "ms_install_codepage_id", "intro" : "Returns the numeric language ID for the installed codepage language.\nThis is like ms_codepage_id(), but refers to the codepage that was\nthe default when Windows was first installed.
\n", "type" : "function" }, "id775-id958" : { "intro" : "Inherited, see Log::Report::Dispatcher::needs()
", "type" : "i_method", "call" : "$obj->needs( [$reason] )", "id" : "id775-id958", "name" : "needs", "extends" : "id775" }, "id1147" : { "type" : "error", "subroutine" : "id1138", "id" : "id1147", "name" : "the native_language '$locale' is not a valid locale" }, "id64" : { "intro" : " my $f = String::Print->new(\n modifiers => [ EUR => sub {sprintf \"%5.2f e\", $_[0]} ],\n serializers => [ UNDEF => sub {'-'} ],\n encode_for => 'HTML',\n );\n\n $f->printi(\"price: {p EUR}\", p => 3.1415); # price: ␣␣3.14 e\n $f->printi(\"count: {c}\", c => undef); # count: -\n\n",
"type" : "example",
"id" : "id64"
},
"id784-id958" : {
"type" : "ci_method",
"intro" : "Inherited, see Log::Report::Dispatcher::collectLocation()
", "extends" : "id784", "name" : "collectLocation", "id" : "id784-id958", "call" : "$any->collectLocation" }, "id680" : { "subroutines" : [ "id687", "id685", "id681" ], "name" : "Action", "id" : "id680", "level" : 2, "path" : "METHODS/Action", "type" : "section" }, "id841" : { "type" : "example", "intro" : " my $parent_try = dispatcher 'active-try';\n $parent_try->hide('ALL');\n\n",
"id" : "id841",
"name" : "change the setting of the running block\n"
},
"id117" : {
"distribution" : "Log-Report-Optional",
"inheritance" : {
"extends" : [
"Exporter"
]
},
"package" : "Log::Report::Minimal",
"name" : "Log::Report::Minimal",
"id" : "id117",
"is_pure_pod" : false,
"title" : "simulate Log::Report functions simple",
"chapters" : [
"id118",
"id1320",
"id119",
"id120",
"id121"
],
"version" : "1.08"
},
"id200" : {
"path" : "FUNCTIONS/Other",
"type" : "section",
"subroutines" : [
"id204",
"id202",
"id206",
"id201",
"id203"
],
"name" : "Other",
"id" : "id200",
"level" : 2
},
"id630" : {
"type" : "section",
"path" : "METHODS/Attributes",
"level" : 2,
"name" : "Attributes",
"id" : "id630",
"subroutines" : [
"id632",
"id631"
]
},
"id781-id1082" : {
"type" : "ci_method",
"intro" : "Inherited, see Log::Report::Dispatcher::addSkipStack()
", "id" : "id781-id1082", "name" : "addSkipStack", "extends" : "id781", "call" : "$any->addSkipStack( @CODE )" }, "id505" : { "type" : "function", "intro" : "Returns the numeric value of the codepage. The $iso may look like\nthis: xx_YY. Then, first the xx_YY is looked-up. If that does\nnot exist, xx is tried.
Inherited, see Log::Report::Dispatcher::translate()
", "type" : "i_method" }, "id1217" : { "type" : "error", "name" : "message() of exception expects Log::Report::Message, got $what.", "id" : "id1217", "subroutine" : "id1215" }, "id518" : { "params" : "$msgid", "type" : "option", "name" : "msgid", "id" : "id518" }, "id642" : { "type" : "section", "path" : "METHODS/Constructors", "level" : 2, "id" : "id642", "name" : "Constructors", "subroutines" : [ "id731-id637", "id643" ] }, "id118" : { "type" : "chapter", "intro" : "Log::Report::Minimal - simulate Log::Report functions simple
\n", "path" : "NAME", "level" : 1, "id" : "id118", "name" : "NAME" }, "id1006" : { "id" : "id1006", "name" : "the 'needs' sub-command parameter '$need' is not a reason.", "subroutine" : "id1003", "type" : "error" }, "id105" : { "name" : "Modifier: EL or EL($width, [$replace])", "id" : "id105", "level" : 3, "intro" : "[1.00] When the string is larger than $width columns, then chop it\nshort and add a 'mid-line ellipsis' character: ⋯ . You may also\npick another replacement string. The comma is optional
Attention: \"columns\" not \"characters\": it is aware of wide fonts, like\nchinese characters (see %S above). The default ellipsis is also two\ncolumns wide.
\n \"Intro: {text EL(10)}\"; # Intro: 12345678⋯ \n \"Intro: {text EL(10,⋮)}\"; # Intro: 123456789⋮ \n \"Intro: {text EL(10⋮)}\"; # Intro: 123456789⋮ \n \"Intro: {text EL(10,XY)}\"; # Intro: 12345678XY \n \"Intro: {text EL(10XY)}\"; # Intro: 12345678XY \n\n\nThe defaults for EL are '20' and '⋯' (mid-dots). You can changes these\nwith setDefaults():
\n\n $sp->setDefaults(EL => { width => 10, replace => '⋮' });\n $sp->printi(\"Intro: {text EL}\"); # Intro: 12345678⋯ \n\n",
"path" : "DETAILS/Interpolation: Modifiers/Modifier: EL or EL($width, [$replace])",
"type" : "subsection"
},
"id517" : {
"type" : "c_method",
"options" : [
[
"id530",
"id531"
],
[
"id526",
"id527"
],
[
"id534",
"id535"
],
[
"id528",
"id529"
],
[
"id524",
"id525"
],
[
"id518",
"id519"
],
[
"id520",
"id521"
],
[
"id522",
"id523"
],
[
"id532",
"id533"
]
],
"diagnostics" : [
"id536"
],
"name" : "new",
"id" : "id517",
"call" : "$class->new( %options )"
},
"id794" : {
"name" : "params",
"id" : "id794",
"params" : "ARRAY",
"type" : "option"
},
"id302" : {
"id" : "id302",
"name" : "domain",
"call" : "$obj->domain",
"type" : "i_method"
},
"id1318" : {
"level" : 1,
"type" : "chapter",
"intro" : "Dancer2::Plugin::LogReport\n is a Dancer2::Plugin\n\n", "path" : "INHERITANCE", "id" : "id1318", "name" : "INHERITANCE" }, "id757-id958" : { "id" : "id757-id958", "name" : "accept", "extends" : "id757", "intro" : "
Inherited, see Log::Report::Dispatcher::new(accept)
", "type" : "option", "params" : "$reasons|\\@reasons" }, "id165-id375" : { "intro" : "Inherited, see Log::Report::Minimal::Domain::new(name)
", "params" : "STRING", "type" : "option", "id" : "id165-id375", "name" : "name", "extends" : "id165" }, "id307" : { "id" : "id307", "name" : "charset", "value" : "'utf-8'", "type" : "default" }, "id921-id217" : { "call" : "$obj->toString( [$locale] )", "extends" : "id921", "id" : "id921-id217", "name" : "toString", "intro" : "Inherited, see Log::Report::Message::toString()
", "type" : "i_method" }, "id1219" : { "call" : "$obj->taggedWith( $tag|Regexp )", "name" : "taggedWith", "id" : "id1219", "intro" : "[1.44] Check whether any of the classes listed in the message match $tag\n(string) or the Regexp. This uses Log::Report::Message::taggedWith().
\n", "type" : "i_method" }, "id512" : { "path" : "NAME", "intro" : "Log::Report::Lexicon::PO - one translation definition
\n", "type" : "chapter", "level" : 1, "id" : "id512", "name" : "NAME" }, "id453" : { "type" : "default", "name" : "version", "id" : "id453", "value" : "undef"
},
"id326" : {
"call" : "$class->new( %options )",
"id" : "id326",
"name" : "new",
"diagnostics" : [
"id337"
],
"intro" : "Create a new translator object. You may pass the %options as HASH or\nPAIRS. By convension, all basic Template Toolkit options are in capitals.\nRead Template::Config about what they mean. Extension options provided\nby this module are all in lower-case.
\n\nIn a web-environment, you want to start this before your webserver starts\nforking.
\n", "options" : [ [ "id331", "id332" ], [ "id327", "id328" ], [ "id329", "id330" ], [ "id335", "id336" ], [ "id333", "id334" ] ], "type" : "c_method" }, "id786-id1090" : { "type" : "option", "params" : "CLASS", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "id" : "id786-id1090", "name" : "package", "extends" : "id786" }, "id647" : { "subroutine" : "id643", "id" : "id647", "name" : "cannot read mo from file $fn: $!", "type" : "fault" }, "id900" : { "type" : "default", "id" : "id900", "name" : "_msgctxt", "value" : "undef"
},
"id886-id217" : {
"id" : "id886-id217",
"name" : "_tags",
"value" : "[]",
"extends" : "id886",
"intro" : "Inherited, see Log::Report::Message::new(_tags)
", "type" : "default" }, "id366" : { "level" : 2, "name" : "Supported syntax", "id" : "id366", "type" : "section", "path" : "DETAILS/Supported syntax", "nest" : [ "id367", "id368", "id369" ] }, "id434-id289" : { "extends" : "id434", "name" : "keep", "id" : "id434-id289", "intro" : "Inherited, see Log::Report::Extract::cleanup(keep)
", "params" : "HASH|ARRAY", "type" : "option" }, "id1013" : { "call" : "info( $message )", "id" : "id1013", "name" : "info", "intro" : "Short for report INFO => $message
Log::Report::Template::Textdomain\n is a Log::Report::Domain\n is a Log::Report::Minimal::Domain\n\n" }, "id315" : { "subroutine" : "id305", "id" : "id315", "name" : "template syntax error, no END in $fn line $line.", "type" : "error" }, "id308" : { "params" : "PREDEFINED|CODE", "type" : "option", "intro" : "
Read the DETAILS section about this.
\n", "id" : "id308", "name" : "pattern" }, "id51" : { "nest" : [ "id52", "id65", "id72" ], "id" : "id51", "name" : "METHODS", "type" : "chapter", "intro" : "See functions printi(), sprinti(), printp(), and sprintp(): you\ncan also call them as method.
\n\n use String::Print 'oo';\n my $f = String::Print->new(%config);\n $f->printi($format, @params);\n\n # exactly the same functionality:\n use String::Print 'printi', %config;\n printi $format, @params;\n\n\n
The Object Oriented interface wins when you need the same configuration\nin multiple source files, or when you need different configurations\nwithin one program. In these cases, the hassle of explicitly using the\nobject has some benefits.
\n", "path" : "METHODS", "level" : 1 }, "id1102" : { "name" : "facility", "id" : "id1102", "intro" : "The possible values for this depend (a little) on the system. POSIX\nonly defines user, and local0 up to local7.
Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
" }, "id780-id818" : { "call" : "$any->collectStack( [$maxdepth] )", "extends" : "id780", "name" : "collectStack", "id" : "id780-id818", "intro" : "Inherited, see Log::Report::Dispatcher::collectStack()
", "type" : "ci_method" }, "id112" : { "level" : 3, "type" : "subsection", "path" : "DETAILS/Output encoding/Output encoding exclusion", "intro" : "In some cases, the data which is inserted is already encoded in the\noutput syntax. For instance, you already have HTML to be included.
\n\nThe default exclusion rule for HTML output is qr/html$/i, which\nmeans that all inserted named parameters, where the name ends on html\nwill not get html-entity encoded.
This will work by default:
\n\n # with encodeFor('HTML')\n printp \"Me & Co: {name}, {description_html}\",\n name => 'RenE<eacute>', description_html => $descr;\n\n\nThis may result in:
\n\n Me & Co: RenE<amp>eacute;, <font color=\"red\">new member</font>\n\n\n
Better not to have HTML in your program: leave it to the template. But\nin some cases, you have no choice.
\n", "name" : "Output encoding exclusion", "id" : "id112" }, "id760-id1228" : { "intro" : "Inherited, see Log::Report::Dispatcher::new(locale)
", "type" : "default", "name" : "locale", "id" : "id760-id1228", "extends" : "id760", "value" : "<system locale>" }, "id743-id441" : { "extends" : "id743", "id" : "id743-id441", "name" : "setupPluralAlgorithm", "type" : "i_method", "intro" : "Inherited, see Log::Report::Lexicon::Table::setupPluralAlgorithm()
", "diagnostics" : [ "id744-id441" ], "call" : "$obj->setupPluralAlgorithm" }, "id871-id217" : { "type" : "option", "params" : "INTEGER|ARRAY|HASH", "intro" : "Inherited, see Log::Report::Message::new(_count)
", "name" : "_count", "id" : "id871-id217", "extends" : "id871" }, "id746" : { "type" : "i_method", "intro" : "The translation of a blank MSGID is used to store a MIME header, which\ncontains some meta-data. The $field value is looked-up (case-insensitive)\nand returned.
\n", "name" : "header", "id" : "id746", "call" : "$obj->header( $field )" }, "id1234" : { "type" : "c_method", "options" : [ [ "id757-id1228", "id758-id1228" ], [ "id765-id1228", "id1239" ], [ "id1240", "id1241" ], [ "id763-id1228", "id764-id1228" ], [ "id759-id1228", "id760-id1228" ], [ "id761-id1228", "id762-id1228" ], [ "id1237", "id1238" ], [ "id1235", "id1236" ] ], "diagnostics" : [ "id1242", "id1243" ], "id" : "id1234", "name" : "new", "call" : "$class->new( $type, $name, %options )" }, "id648" : { "type" : "fault", "id" : "id648", "name" : "cannot read magic from $fn: $!", "subroutine" : "id643" }, "id429-id697" : { "intro" : "Inherited, see Log::Report::Extract::pots()
", "type" : "i_method", "call" : "$obj->pots( $domain )", "id" : "id429-id697", "name" : "pots", "extends" : "id429" }, "id1292" : { "level" : 3, "name" : "Filters", "id" : "id1292", "type" : "subsection", "path" : "DETAILS/Processing the message/Filters" }, "id855" : { "name" : "showStatus", "id" : "id855", "call" : "$obj->showStatus", "type" : "i_method", "intro" : "If this object is kept in $@, and someone uses this as string, we\nwant to show the fatal error message.
The message is not very informative for the good cause: we do not want\npeople to simply print the $@, but wish for a re-cast of the message\nusing reportAll() or reportFatal().
Inherited, see Log::Report::Dispatcher::name()
", "type" : "i_method" }, "id899" : { "intro" : "[1.22] Message $context in the translation file, the traditional use. Cannot\nbe combined with _context on the same msgids.
\n", "type" : "option", "params" : "$context", "name" : "_msgctxt", "id" : "id899" }, "id435-id289" : { "type" : "default", "intro" : "Inherited, see Log::Report::Extract::cleanup(keep)
", "name" : "keep", "id" : "id435-id289", "extends" : "id435", "value" : "[]" }, "id838" : { "type" : "i_method", "intro" : "Returns all collected Log::Report::Exception objects. The last of\nthem may be a fatal one. The other are non-fatal.
\n", "id" : "id838", "name" : "exceptions", "call" : "$obj->exceptions" }, "id772" : { "intro" : "The dispatcher type, which is usually the same as the class of this\nobject, but not in case of wrappers like for Log::Dispatch.
\n", "type" : "i_method", "call" : "$obj->type", "name" : "type", "id" : "id772" }, "id314" : { "type" : "warning", "id" : "id314", "name" : "msgid '$msgid' contains html escapes, don't do that. File $file line $linenr.", "subroutine" : "id305" }, "id771-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::name()
", "type" : "i_method", "call" : "$obj->name", "extends" : "id771", "name" : "name", "id" : "id771-id944" }, "id428" : { "id" : "id428", "name" : "domains", "call" : "$obj->domains", "type" : "i_method", "intro" : "Returns a sorted list of all known domain names.
\n" }, "id888" : { "type" : "default", "id" : "id888", "name" : "_classes", "value" : "undef"
},
"id761-id1228" : {
"type" : "option",
"params" : "'NORMAL'|'VERBOSE'|'ASSERT'|'DEBUG'|0..3",
"intro" : "Inherited, see Log::Report::Dispatcher::new(mode)
", "id" : "id761-id1228", "name" : "mode", "extends" : "id761" }, "id870-id217" : { "name" : "_domain", "id" : "id870-id217", "extends" : "id870", "value" : "<from \"use Log::Report\">", "intro" : "Inherited, see Log::Report::Message::new(_domain)
", "type" : "default" }, "id781-id818" : { "extends" : "id781", "id" : "id781-id818", "name" : "addSkipStack", "call" : "$any->addSkipStack( @CODE )", "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::addSkipStack()
" }, "id791-id1174" : { "extends" : "id791", "value" : "<required>", "name" : "linenr", "id" : "id791-id1174", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(linenr)
", "type" : "default" }, "id1031" : { "type" : "example", "intro" : " print __nx \"one file\", \"{_count} files\", $nr_files;\n print __nx \"one file\", \"{_count} files\", @files;\n\n local $\" = ', ';\n print __nx \"one file: {f}\", \"{_count} files: {f}\", @files, f => \\@files;\n\n",
"id" : "id1031",
"name" : "how to use __nx()\n"
},
"id1112" : {
"type" : "option",
"params" : "CODE",
"intro" : "[1.10] With a CODE reference you get your hands on the text before\nit gets sent to syslog. The three parameters are: the (translated) text,\nthe related text domain object, and the message object. You may want to\nuse context information from the latter.
\n\n[1.19] After the three positional parameters, there may be a list of\npairs (named parameters) with additional info. This may contain a\nlocation with an ARRAY of information produced by caller() about the\norigin of the exception.
Read the POT information from $filename.
\n", "id" : "id467", "name" : "read", "diagnostics" : [ "id470", "id471", "id472", "id473", "id474" ], "call" : "$class->read( $filename, %options )" }, "id854" : { "type" : "default", "value" : "undef",
"id" : "id854",
"name" : "class"
},
"id1003" : {
"name" : "dispatcher",
"id" : "id1003",
"type" : "function",
"intro" : "The dispatcher function controls access to dispatchers: the back-ends\nwhich process messages, do the logging. Dispatchers are global entities,\naddressed by a symbolic $name. Please read Log::Report::Dispatcher as\nwell.
The Log::Report suite has its own dispatcher types, but also connects\nto external dispatching frameworks. Each need some (minor) conversions,\nespecially with respect to translation of REASONS of the reports\ninto log-levels as the back-end understands.
[1.10] When you open a dispatcher with a $name which is already in use,\nthat existing dispatcher gets closed. Except when you have given an\n'dispatcher \"do-not-reopen\"' earlier, in which case the first object\nstays alive, and the second attempt ignored. [1.11] The automatically\ncreated default dispatcher will get replaced, even when this option\nis given, by another dispatcher which is named 'default'.
\n\nThe %options are a mixture of parameters needed for the\nLog::Report dispatcher wrapper and the settings of the back-end.\nSee Log::Report::Dispatcher, the documentation for the back-end specific\nwrappers, and the back-ends for more details.
\n\nImplemented COMMANDs are close, find, list, disable,\nenable, mode, filter, needs, active-try, and do-not-reopen.
Most commands are followed by a LIST of dispatcher @names to be addressed.\nFor mode see section Run modes; it requires a MODE argument\nbefore the LIST of NAMEs. Non-existing names will be ignored. When\nALL is specified, then all existing dispatchers will get addressed.\nFor filter see Filters; it requires a CODE\nreference before the @names of the dispatchers which will have the it\napplied (defaults to all).
With needs, you only provide a REASON: it will return the list of\ndispatchers which need to be called in case of a message with the REASON\nis triggered. The active-try [1.09] returns the closest surrounding\nexception catcher, a Log::Report::Dispatcher::Try object.
For both the creation as COMMANDs version of this method, all objects\ninvolved are returned as LIST, non-existing ones skipped. In SCALAR\ncontext with only one name, the one object is returned.
\n", "diagnostics" : [ "id1005", "id1006", "id1007" ], "call" : "dispatcher( <$type, $name, %options>|<$command, @names> )", "examples" : [ "id1004" ] }, "id993" : { "type" : "default", "id" : "id993", "name" : "location", "value" : "undef"
},
"id919-id217" : {
"intro" : "Inherited, see Log::Report::Message::taggedWith()
", "type" : "i_method", "call" : "$obj->taggedWith( $tag|Regexp )", "extends" : "id919", "name" : "taggedWith", "id" : "id919-id217" }, "id427" : { "id" : "id427", "name" : "charset", "call" : "$obj->charset", "type" : "i_method", "intro" : "Returns the character-set used inside the POT files.
\n" }, "id1199" : { "intro" : "Produces \"reason: message\" via toString().
\n", "type" : "overload", "call" : "overload \"\"; stringification", "id" : "id1199", "name" : "\"\"" }, "id77" : { "intro" : "Result of the translation process: when Log::Report::__xn() is\nare used for count-sensitive translation. Those function may add\nmore specials to the parameter list.
\n", "params" : "INTEGER", "type" : "option", "id" : "id77", "name" : "_count" }, "id901" : { "type" : "i_method", "intro" : "Returns a new object which copies info from original, and updates it\nwith the specified %options and $variables. The advantage is that the\ncached translations are shared between the objects.
\n", "examples" : [ "id902" ], "call" : "$obj->clone( %options, $variables )", "id" : "id901", "name" : "clone" }, "id887" : { "id" : "id887", "name" : "_classes", "intro" : "Deprecated alternative for _tag.
\n", "params" : "$tags|\\@tags", "type" : "option" }, "id1235" : { "intro" : "You can either specify a $file by name, which is opened in append mode with\nautoflush on. Or pass any kind of file handle $fh, or some OBJECT which\nimplements a print() method. You probably want to have autoflush\nenabled on your file-handles.
When cleaning-up the dispatcher, the file will only be closed in case\nof a named $file.
\n\n[1.10] When you pass a CODE, then for each log message the function is\ncalled with two arguments: this dispatcher object and the message object.\nIn some way (maybe via the message context) you have to determine the\nlog filename. This means that probably many log-files are open at the\nsame time.
\n\n # configuration time\n dispatcher FILE => 'logfile', to =>\n sub { my ($disp, $msg) = @_; $msg->context->{logfile} };\n\n # whenever you want to change the logfile\n textdomain->updateContext(logfile => '/var/log/app');\n (textdomain 'mydomain')->setContext(logfile => '/var/log/app');\n\n # or\n error __x\"help\", _context => {logfile => '/dev/tty'};\n error __x\"help\", _context => \"logfile=/dev/tty\";\n\n",
"params" : "$file|$fh|OBJECT|CODE",
"type" : "option",
"name" : "to",
"id" : "id1235"
},
"id786-id944" : {
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
", "type" : "option", "params" : "CLASS", "id" : "id786-id944", "name" : "package", "extends" : "id786" }, "id837" : { "intro" : "The exit $text or object ($@) of the eval'ed block, in its unprocessed state.\nThey will always return true when they where deadly, and it always stringifies\ninto something useful.
Log::Report::Dispatcher::Log4perl\n is a Log::Report::Dispatcher\n\n", "level" : 1, "id" : "id1344", "name" : "INHERITANCE" }, "id406" : { "name" : "no counting positional for '$msgid'", "id" : "id406", "subroutine" : "id402", "type" : "error" }, "id1209" : { "type" : "default", "value" : "<required>", "name" : "message", "id" : "id1209" }, "id920-id217" : { "type" : "i_method", "intro" : "
Inherited, see Log::Report::Message::inClass()
", "extends" : "id920", "name" : "inClass", "id" : "id920-id217", "call" : "$obj->inClass( $tag|Regexp )" }, "id468" : { "name" : "charset", "id" : "id468", "params" : "STRING", "type" : "option", "intro" : "The character-set which is used for the file. You must specify\nthis explicitly.
\n" }, "id1308" : { "id" : "id1308", "name" : "Why use format strings?", "level" : 2, "path" : "DETAILS/Why use format strings?", "type" : "section" }, "id293" : { "path" : "METHODS", "nest" : [ "id294", "id301", "id304" ], "type" : "chapter", "level" : 1, "name" : "METHODS", "id" : "id293" }, "id104" : { "type" : "subsection", "path" : "DETAILS/Interpolation: Modifiers/Modifier: '=' (show name)", "intro" : "[0.96] As (always trailing) modifier, this will show the interpolated\nname before the value. It might simplify debugging statements.
\n\n \"visitors: {count=}\", count => 1; # visitors: count=1\n \"v: {count %-8,d =}X\", count => 10000; # v: count=10,000␣␣X\n\n",
"level" : 3,
"name" : "Modifier: '=' (show name)",
"id" : "id104"
},
"id759" : {
"id" : "id759",
"name" : "locale",
"intro" : "Overrules the global locale setting. Can be overruled itself by\nLog::Report::report(locale).
\n", "params" : "LOCALE", "type" : "option" }, "id676" : { "params" : "HASH", "type" : "option", "name" : "rules", "id" : "id676" }, "id778" : { "call" : "$obj->log( \\%options, $reason, $message, $domain )", "id" : "id778", "name" : "log", "intro" : "This method is called by Log::Report::report() and should not be called\ndirectly. Internally, it will call translate(), which does most of\nthe work.
\n", "type" : "i_method" }, "id832" : { "name" : "hide", "id" : "id832", "type" : "option", "params" : "$reasons|\\@reasons|'ALL'|'NONE'", "intro" : "[1.09] see hide()
\n" }, "id795" : { "id" : "id795", "name" : "params", "value" : "<required>", "type" : "default" }, "id422" : { "name" : "charset", "id" : "id422", "value" : "'utf-8'", "type" : "default" }, "id1016" : { "type" : "function", "intro" : "Short for report MISTAKE => $message
undef",
"type" : "default"
},
"id785-id958" : {
"call" : "$any->stackTraceLine( %options )",
"extends" : "id785",
"id" : "id785-id958",
"name" : "stackTraceLine",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine()
", "type" : "ci_method", "options" : [ [ "id800-id958", "id801-id958" ], [ "id792-id958", "id793-id958" ], [ "id788-id958", "id789-id958" ], [ "id790-id958", "id791-id958" ], [ "id796-id958", "id797-id958" ], [ "id798-id958", "id799-id958" ], [ "id786-id958", "id787-id958" ], [ "id794-id958", "id795-id958" ] ] }, "id1207" : { "name" : "reason", "id" : "id1207", "value" : "<required>", "type" : "default" }, "id462" : { "type" : "option", "params" : "STRING", "intro" : "Overrule the date which is included in the generated header.
\n", "name" : "date", "id" : "id462" }, "id83" : { "type" : "option", "params" : "STRING|OBJECT", "intro" : "Text as STRING appended after $format, without interpolation.
\n", "id" : "id83", "name" : "_append" }, "id780-id1082" : { "extends" : "id780", "id" : "id780-id1082", "name" : "collectStack", "call" : "$any->collectStack( [$maxdepth] )", "type" : "ci_method", "intro" : "Inherited, see Log::Report::Dispatcher::collectStack()
" }, "id631" : { "type" : "i_method", "intro" : "Returns a list of Log::Report::Lexicon::Index objects, where the\ntranslation files may be located.
\n", "name" : "lexicons", "id" : "id631", "call" : "$obj->lexicons" }, "id504" : { "intro" : "Translate windows $codepage into ISO code. The $codepage is numeric\nor a hex string like '0x0304'.
\n", "type" : "function", "call" : "codepage_to_iso( $codepage )", "id" : "id504", "name" : "codepage_to_iso" }, "id201" : { "intro" : "Replace all escape characters into their readable counterpart. For\ninstance, a new-line is replaced by backslash-n.
\n", "type" : "function", "call" : "escape_chars( STRING )", "name" : "escape_chars", "id" : "id201" }, "id763-id958" : { "type" : "option", "params" : "'UPPERCASE'|'LOWERCASE'|'UCFIRST'|'IGNORE'|CODE", "intro" : "Inherited, see Log::Report::Dispatcher::new(format_reason)
", "extends" : "id763", "id" : "id763-id958", "name" : "format_reason" }, "id777" : { "intro" : "Terminate this dispatcher activities. The dispatcher gets disabled,\nto avoid the case it accidentally gets used. Returns undef (false)\nif the dispatcher was already closed.
[1.09] By default, the try will only catch messages which stop the\nexecution of the block (errors etc, internally a 'die'). Other messages\nare passed to the parent dispatchers.
\n\nThis option gives the opportunity to stop, for instance, trace messages.\nThose messages are still collected inside the try object (unless excluded\nby new(accept)), so may get passed-on later via reportAll() if\nyou like.
\n\nBe warned: Using this method will reset the whole 'hide' configuration:\nit's a set not an add.
\n", "call" : "$obj->hide( @reasons )", "examples" : [ "id841" ] }, "id1197" : { "level" : 1, "path" : "DESCRIPTION", "intro" : "In Log::Report, exceptions are not as extended as available in\nlanguages as Java: you do not create classes for them. The only\nthing an exception object does, is capture some information about\nan (untranslated) report.
\n", "type" : "chapter", "id" : "id1197", "name" : "DESCRIPTION" }, "id681" : { "type" : "i_method", "intro" : "Returns a pair of the MSGID stripped from context markup, and the\ncontext evaluated into the msgctxt string. The $message is a\nLog::Report::Message object. The $context is the default context\nfor a certain textdomain.
\n\n my ($msgid, $msgctxt) = $context->ctxtFor($msg, $lang, $context);\n\n", "name" : "ctxtFor", "id" : "id681", "diagnostics" : [ "id682", "id683", "id684" ], "call" : "$obj->ctxtFor( $message, $lang, [$context] )" }, "id88" : { "id" : "id88", "name" : "of the rewrite\n", "type" : "example", "intro" : "
# positional parameters\n my $x = sprintp \"dumpfiles: %s\\n\", \\@dumpfiles, _join => ':';\n\n # is rewritten into, and then processed as\n my $x = sprinti \"dumpfiles: {_1}\\n\", _1 => \\@dumpfiles, _join => ':';\n\n"
},
"id789-id958" : {
"extends" : "id789",
"value" : "<required>",
"name" : "filename",
"id" : "id789-id958",
"type" : "default",
"intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(filename)
" }, "id1087" : { "subroutines" : [ "id756-id1082" ], "id" : "id1087", "name" : "Constructors", "level" : 2, "path" : "METHODS/Constructors", "type" : "section" }, "id670" : { "level" : 1, "type" : "chapter", "intro" : "Log::Report::Translator::Context - handle translation contexts
\n", "path" : "NAME", "id" : "id670", "name" : "NAME" }, "id1138" : { "name" : "configure", "id" : "id1138", "diagnostics" : [ "id1147", "id1148" ], "call" : "$obj->configure( %options )", "options" : [ [ "id1145", "id1146" ], [ "id1143", "id1144" ], [ "id176-id1127", "id177-id1127" ], [ "id1141", "id1142" ], [ "id1139", "id1140" ], [ "id174-id1127", "id175-id1127" ] ], "type" : "i_method", "intro" : "The import is automatically called when the package is compiled. For all\nbut one packages in your distribution, it will only contain the name of\nthe DOMAIN. For one package, it will contain configuration information.\nThese %options are used for all packages which use the same DOMAIN.\nSee chapter Configuring below.
\n" }, "id774-id958" : { "type" : "i_method", "intro" : "Inherited, see Log::Report::Dispatcher::isDisabled()
", "id" : "id774-id958", "name" : "isDisabled", "extends" : "id774", "call" : "$obj->isDisabled" }, "id771-id1082" : { "call" : "$obj->name", "id" : "id771-id1082", "name" : "name", "extends" : "id771", "intro" : "Inherited, see Log::Report::Dispatcher::name()
", "type" : "i_method" }, "id1029" : { "name" : "how to use__n()\n",
"id" : "id1029",
"type" : "example",
"intro" : " print __n \"one\", \"more\", $a;\n print __n(\"one\", \"more\", $a), \"\\n\";\n print +(__n \"one\", \"more\", $a), \"\\n\";\n\n # new-lines are ignore at lookup, but printed.\n print __n \"one\\n\", \"more\\n\", $a;\n\n # count is in scalar context\n # the value is also available as _count\n print __n \"found one\\n\", \"found {_count}\\n\", @r;\n\n # ARRAYs and HASHes are counted\n print __n \"one\", \"more\", \\@r;\n\n"
},
"id1157" : {
"name" : "defaultContext",
"id" : "id1157",
"call" : "$obj->defaultContext",
"type" : "i_method",
"intro" : "Returns the current default translation context settings as HASH. You should\nnot modify the content of that HASH: change it by called setContext() or\nupdateContext().
\n" }, "id253" : { "id" : "id253", "name" : "Larger example", "intro" : "In its simplest form, this module can be used for more flexible logging
\n\n get '/route' => sub {\n # Stop execution, redirect, and display an error to the user\n $name or error \"Please enter a name\";\n\n # The same but translated\n $name or error __\"Please enter a name\";\n\n # The same but translated and with variables\n $name or error __x\"{name} is not valid\", name => $name;\n\n # Show the user a warning, but continue execution\n mistake \"Not sure that's what you wanted\";\n\n # Add debug information, can be caught in syslog by adding\n # the (for instance) syslog dispatcher\n trace \"Hello world\";\n };\n\n",
"path" : "DETAILS/Larger example",
"type" : "section",
"level" : 2
},
"id1267" : {
"type" : "chapter",
"path" : "DETAILS",
"nest" : [
"id1268",
"id1269"
],
"level" : 1,
"id" : "id1267",
"name" : "DETAILS"
},
"id755" : {
"subroutines" : [
"id756"
],
"id" : "id755",
"name" : "Constructors",
"level" : 2,
"path" : "METHODS/Constructors",
"type" : "section"
},
"id1223" : {
"intro" : "Prints the reason and the message. Differently from throw(), this\nonly represents the textual content: it does not re-cast the exceptions to\nhigher levels.
\n", "type" : "i_method", "examples" : [ "id1224" ], "call" : "$obj->toString( [$locale] )", "id" : "id1223", "name" : "toString" }, "id799" : { "type" : "default", "value" : "8", "name" : "max_params", "id" : "id799" }, "id786-id1082" : { "id" : "id786-id1082", "name" : "package", "extends" : "id786", "params" : "CLASS", "type" : "option", "intro" : "Inherited, see Log::Report::Dispatcher::stackTraceLine(package)
" }, "id1077" : { "name" : "Translation", "id" : "id1077", "type" : "subsection", "intro" : "Translating is optional.
\n\nDistribution Log::Report::Lexicon handles translations. It will help\nyou manage all __x() (and friends) format strings in GNU's PO file\nformat (https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html)
\n\nWith Log::Report::Template, you can use Log::Report with translations\nin various website template systems.
\n\nThen, Dancer2::Plugin::LogReport brings Log::Report with exceptions\nand translations to the Dancer2 web framework.
\n", "path" : "DETAILS/Interpolation via formats/Translation", "level" : 3 }, "id846" : { "type" : "i_method", "intro" : "Re-cast only the fatal message to the defined dispatchers. If the\nblock was left without problems, then nothing will be done. The %options\nwill end-up as HASH of %options to Log::Report::report(); see\nLog::Report::Exception::throw() which does the job.
\n", "id" : "id846", "name" : "reportFatal", "call" : "$obj->reportFatal( %options )" }, "id1027" : { "name" : "even length parameter list for __x at $where", "id" : "id1027", "subroutine" : "id1025", "type" : "error" }, "id915-id217" : { "extends" : "id915", "id" : "id915-id217", "name" : "errno", "call" : "$obj->errno( [$errno] )", "type" : "i_method", "intro" : "Inherited, see Log::Report::Message::errno()
" }, "id1159" : { "nest" : [ "id1160" ], "path" : "DETAILS", "type" : "chapter", "id" : "id1159", "name" : "DETAILS", "level" : 1 }, "id741" : { "intro" : "Returns the msgstr index used to translate a value of $count.
\n", "type" : "i_method", "call" : "$obj->pluralIndex( $count )", "id" : "id741", "name" : "pluralIndex", "diagnostics" : [ "id742" ] }, "id876-id217" : { "type" : "default", "intro" : "Inherited, see Log::Report::Message::new(_msgid)
", "value" : "undef",
"extends" : "id876",
"id" : "id876-id217",
"name" : "_msgid"
},
"id1273" : {
"type" : "subsection",
"path" : "METHODS/Managing PO's/Administration",
"name" : "Administration",
"id" : "id1273",
"level" : 3,
"subroutines" : [
"id741-id569",
"id745-id569",
"id743-id569",
"id746-id569",
"id738-id569",
"id739-id569"
]
},
"id908-id217" : {
"intro" : "Inherited, see Log::Report::Message::count()
", "type" : "i_method", "call" : "$obj->count", "name" : "count", "id" : "id908-id217", "extends" : "id908" }, "id1089" : { "level" : 2, "id" : "id1089", "name" : "Logging", "subroutines" : [ "id781-id1082", "id785-id1082", "id778-id1082", "id784-id1082", "id777-id1082", "id780-id1082", "id783-id1082", "id779-id1082" ], "type" : "section", "path" : "METHODS/Logging" }, "id1063" : { "id" : "id1063", "type" : "example", "intro" : " if(Log::Report->needs('TRACE'))\n { my @args = ...expensive calculation...;\n trace \"your options are: @args\";\n }\n\n"
},
"id174-id1127" : {
"params" : "ARRAY",
"type" : "option",
"intro" : "Inherited, see Log::Report::Minimal::Domain::configure(where)
", "extends" : "id174", "name" : "where", "id" : "id174-id1127" }, "id361" : { "type" : "i_method", "intro" : "If the 'processing_errors' option is 'NATIVE' (default), you have to\ncollect the error like this:
\n\n $tt->process($template_fn, $vars, ...)\n or die $tt->error;\n\n\n
When the 'procesing_errors' option is set to 'EXCEPTION', the error is\ntranslated into a Log::Report::Exception:
\n\n use Log::Report;\n try { $tt->process($template_fn, $vars, ...) };\n print $@->wasFatal if $@;\n\n\nIn the latter solution, the try() is probably only on the level of the\nhighest level: the request handler which catches all kinds of serious\nerrors at once.
\n", "id" : "id361", "name" : "error", "call" : "$obj->error" }, "id439-id289" : { "intro" : "Inherited, see Log::Report::Extract::store()
", "type" : "i_method", "call" : "$obj->store( $domain, $filename, $linenr, $context, $msg, [$msg_plural] )", "diagnostics" : [ "id440-id289" ], "id" : "id439-id289", "name" : "store", "extends" : "id439" }, "id1079" : { "id" : "id1079", "name" : "die/warn/Carp", "level" : 3, "intro" : "Perl's built-in exception system is very primitive: \"die\" and \"warn\".\nMost programming languages provide a much more detailed exception\nmechanism.
\n\nA typical perl program can look like this:
\n\n my $dir = '/etc';\n\n File::Spec->file_name is_absolute($dir)\n or die \"ERROR: directory name must be absolute.\\n\";\n\n -d $dir\n or die \"ERROR: what platform are you on?\";\n\n until(opendir DIR, $dir)\n { warn \"ERROR: cannot read system directory $dir: $!\";\n sleep 60;\n }\n\n print \"Processing directory $dir\\n\"\n if $verbose;\n\n while(defined(my $file = readdir DIR))\n { if($file =~ m/\\.bak$/)\n { warn \"WARNING: found backup file $dir/$f\\n\";\n next;\n }\n\n die \"ERROR: file $dir/$file is binary\"\n if $debug && -B \"$dir/$file\";\n\n print \"DEBUG: processing file $dir/$file\\n\"\n if $debug;\n\n open my $fh, \"<:encoding(UTF-8)\", \"$dir/$file\"\n or die \"ERROR: cannot read from $dir/$f: $!\";\n\n $fh->close\n or croak \"ERROR: read errors in $dir/$file: $!\";\n }\n\n\nWhere die, warn, and print are used for various tasks. With\nLog::Report, you would write
\n use Log::Report;\n\n # can be left-out when there is no debug/verbose\n dispatcher PERL => 'default', mode => 'DEBUG';\n\n my $dir = '/etc';\n\n File::Spec->file_name is_absolute($dir)\n or mistake \"directory name must be absolute\";\n\n -d $dir\n or panic \"what platform are you on?\";\n\n until(opendir DIR, $dir)\n { alert \"cannot read system directory $dir\";\n sleep 60;\n }\n\n info \"Processing directory $dir\";\n\n while(defined(my $file = readdir DIR))\n { if($file =~ m/\\.bak$/)\n { notice \"found backup file $dir/$f\";\n next;\n }\n\n assert \"file $dir/$file is binary\"\n if -B \"$dir/$file\";\n\n trace \"processing file $dir/$file\";\n\n unless(open my $fh, \"<:encoding(UTF-8)\", \"$dir/$file\")\n { error \"no permission to read from $dir/$f\" if $!==ENOPERM;\n fault \"unable to read from $dir/$f\"; # or better\n }\n\n $fh->close\n or failure \"read errors in $dir/$file\";\n }\n\n\nA lot of things are quite visibly different, and there are a few smaller\nchanges. There is no need for a new-line after the text of the message.\nWhen applicable (error about system problem), then the $! is added\nautomatically.
Inherited, see Log::Report::Lexicon::Table::new()
", "type" : "c_method", "call" : "$class->new( %options )", "extends" : "id731", "id" : "id731-id637", "name" : "new" }, "id907-id217" : { "intro" : "Inherited, see Log::Report::Message::domain()
", "type" : "i_method", "call" : "$obj->domain", "extends" : "id907", "id" : "id907-id217", "name" : "domain" }, "id1283" : { "id" : "id1283", "name" : "DETAILS", "level" : 1, "type" : "chapter", "nest" : [ "id1284", "id1285" ], "path" : "DETAILS" }, "id881-id217" : { "name" : "_append", "id" : "id881-id217", "extends" : "id881", "params" : "$text|$message", "type" : "option", "intro" : "Inherited, see Log::Report::Message::new(_append)
" }, "id1340" : { "intro" : "Log::Report::Die\n is an Exporter\n\n", "path" : "INHERITANCE", "type" : "chapter", "level" : 1, "id" : "id1340", "name" : "INHERITANCE" }, "id321" : { "name" : "NAME", "id" : "id321", "intro" : "
Log::Report::Template - Template Toolkit with translations
\n", "path" : "NAME", "type" : "chapter", "level" : 1 }, "id781-id1090" : { "call" : "$any->addSkipStack( @CODE )", "id" : "id781-id1090", "name" : "addSkipStack", "extends" : "id781", "intro" : "Inherited, see Log::Report::Dispatcher::addSkipStack()
", "type" : "ci_method" }, "id780-id944" : { "intro" : "Inherited, see Log::Report::Dispatcher::collectStack()
", "type" : "ci_method", "call" : "$any->collectStack( [$maxdepth] )", "name" : "collectStack", "id" : "id780-id944", "extends" : "id780" }, "id1269" : { "id" : "id1269", "name" : "Processing the message", "level" : 2, "type" : "section", "nest" : [ "id1270", "id1271" ], "path" : "DETAILS/Processing the message" }, "id400" : { "path" : "METHODS/Translating", "type" : "section", "subroutines" : [ "id180-id375", "id1153-id375", "id1158-id375", "id1156-id375", "id1157-id375", "id401", "id402" ], "level" : 2, "name" : "Translating", "id" : "id400" }, "id424-id697" : { "intro" : "Inherited, see Log::Report::Extract::new()
", "type" : "fault", "subroutine" : "id418", "name" : "cannot create lexicon directory $dir: $!", "id" : "id424-id697", "extends" : "id424" }, "id953" : { "id" : "id953", "name" : "callback", "value" : "<required>", "type" : "default" }, "id1242" : { "type" : "error", "name" : "dispatcher $name needs parameter 'to'", "id" : "id1242", "subroutine" : "id1234" }, "id894" : { "value" : "$\" $LIST_SEPARATOR",
"id" : "id894",
"name" : "_join",
"type" : "default"
}
},
"meta" : {
"main_manual" : "Log::Report"
},
"generated_by" : {
"program_version" : null,
"oodoc_version" : "3.06",
"created" : "2026-04-10 11:17:58",
"program" : "/home/markov/local/perl-git/OODoc/bin/oodist"
},
"distributions" : {
"Log-Report" : {
"generated_by" : "ExtUtils::MakeMaker version 7.76, CPAN::Meta::Converter version 2.150010",
"author" : [
"Mark Overmeer