METHODS

Constructors

$obj->clone( %options, $variables )

Returns a new object which copies info from original, and updates it with the specified %options and $variables. The advantage is that the cached translations are shared between the objects.

» Example: use of clone()
 my $s = __x "found {nr} files", nr => 5;
 my $t = $s->clone(nr => 3);
 my $t = $s->(nr => 3);      # equivalent
 print $s;     # found 5 files
 print $t;     # found 3 files
$class->fromTemplateToolkit( $domain, $msgid, $params )

See Log::Report::Extract::Template on the details how to integrate Log::Report translations with Template::Toolkit (version 1 and 2)

$class->new( %options )

End-users: do not use this method directly, but use Log::Report::__() and friends. The %options is a mixed list of object initiation parameters (all with a leading underscore) and variables to be filled in into the translated _msgid string.

Option Default

_append

undef

_category

undef

_class

[]

_classes

[]

_context

undef

_count

undef

_domain

<from "use Log::Report">

_expand

false

_join

$" $LIST_SEPARATOR

_lang

<from locale>

_msgctxt

undef

_msgid

undef

_plural

undef

_prepend

undef

_to

<undef>

_append => STRING|MESSAGE
Text as STRING or MESSAGE object to be displayed after the display of this message.
_category => INTEGER
The category when the real gettext library is used, for instance LC_MESSAGES.
_class => STRING|ARRAY
When messages are used for exception based programming, you add _class parameters to the argument list. Later, with for instance Log::Report::Dispatcher::Try::wasFatal(class), you can check the category of the message.
One message can be part of multiple classes. The STRING is used as comma- and/or blank separated list of class tokens (barewords), the ARRAY lists all tokens separately. See classes().
_classes => STRING|ARRAY
Alternative for _class, which cannot be used at the same time.
_context => WORDS|ARRAY
[1.00] Set keywords which can be used to select alternatives between translations. Read the DETAILS section in Log::Report::Translator::Context
_count => INTEGER|ARRAY|HASH
When defined, the _plural need to be defined as well. When an ARRAY is provided, the length of the ARRAY is taken. When a HASH is given, the number of keys in the HASH is used.
_domain => STRING
The text-domain (translation table) to which this _msgid belongs.
With this parameter, your can "borrow" translations from other textdomains. Be very careful with this (although there are good use-cases) The xgettext msgid extractor may add the used msgid to this namespace as well. To avoid that, add a harmless '+':
  print __x(+"errors", _domain => 'global');
The extractor will not take the msgid when it is an expression. The '+' has no effect on the string at runtime.
_expand => BOOLEAN
Indicates whether variables are to be filled-in.
_join => STRING
Which STRING to be used then an ARRAY is being filled-in.
_lang => ISO
[1.00] Override language setting from locale, for instance because that is not configured correctly (yet). This does not extend to prepended or appended translated message object.
_msgctxt => STRING
[1.22] Message context in the translation file, the traditional use. Cannot be combined with _context on the same msgids.
_msgid => MSGID
The message label, which refers to some translation information. Usually a string which is close the English version of the message. This will also be used if there is no translation possible/known.
Leading white-space \s will be added to _prepend. Trailing white-space will be added before _append.
_plural => MSGID
Can be used together with _count. This plural form of the _msgid text is used to simplify the work of translators, and as fallback when no translation is possible: therefore, this can best resemble an English message.
White-space at the beginning and end of the string are stripped off. The white-space provided by the _msgid will be used.
_prepend => STRING|MESSAGE
Text as STRING or MESSAGE object to be displayed before the display of this message.
_to => NAME
Specify the NAME of a dispatcher as destination explicitly. Short for < report {to = NAME}, ... >> See to()

Accessors

$obj->append

Returns the string or Log::Report::Message object which is appended after this one. Usually undef.

$obj->classes

Returns the LIST of classes which are defined for this message; message group indicators, as often found in exception-based programming.

$obj->context

Returns an HASH if there is a context defined for this message.

$obj->count

Returns the count, which is used to select the translation alternatives.

$obj->domain

Returns the domain of the first translatable string in the structure.

$obj->msgctxt

The message context for the translation table lookup.

$obj->msgid

Returns the msgid which will later be translated.

$obj->prepend

Returns the string which is prepended to this one. Usually undef.

$obj->to( [$name] )

Returns the $name of a dispatcher if explicitly specified with the '_to' key. Can also be used to set it. Usually, this will return undef, because usually all dispatchers get all messages.

$obj->valueOf( $parameter )

Lookup the named $parameter for the message. All pre-defined names have their own method which should be used with preference.

» Example:

When the message was produced with

  my @files = qw/one two three/;
  my $msg = __xn "found one file: {file}"
               , "found {nrfiles} files: {files}"
               , scalar @files
               , file    => $files[0]
               , files   => \@files
               , nrfiles => @files+0
               , _class  => 'IO, files'
               , _join   => ', ';

then the values can be takes from the produced message as

  my $files = $msg->valueOf('files');  # returns ARRAY reference
  print @$files;              # 3
  my $count = $msg->count;    # 3
  my @class = $msg->classes;  # 'IO', 'files'
  if($msg->inClass('files'))  # true

Simplified, the above example can also be written as:

  local $" = ', ';
  my $msg  = __xn "found one file: {files}"
                , "found {_count} files: {files}"
                , @files      # has scalar context
                , files   => \@files
                , _class  => 'IO, files';

Processing

$obj->concat( STRING|$object, [$prepend] )

This method implements the overloading of concatenation, which is needed to delay translations even longer. When $prepend is true, the STRING or $object (other Log::Report::Message) needs to prepended, otherwise it is appended.

» Example: of concatenation
 print __"Hello" . ' ' . __"World!";
 print __("Hello")->concat(' ')->concat(__"World!")->concat("\n");
$obj->inClass( $class|Regexp )

Returns true if the message is in the specified $class (string) or matches the Regexp. The trueth value is the (first matching) class.

$obj->toHTML( [$locale] )

[1.11] Translate the message, and then entity encode HTML volatile characters.

[1.20] When used in combination with a templating system, you may want to use <content_for = 'HTML'>> in Log::Report::Domain::configure(formatter).

» Example:
  print $msg->toHTML('NL');
$obj->toString( [$locale] )

Translate a message. If not specified, the default locale is used.

$obj->untranslated

Return the concatenation of the prepend, msgid, and append strings. Variable expansions within the msgid is not performed.