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->errno( [$errno] )

[1.38] Returns the value of the _errno key, to indicate the error number (to be returned from your script). Usually, this method will return undef. For FAILURE, FAULT, and ALERT, the errno is by default taken from $! and $?.

$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.