Provided by: liblog-report-perl_1.34-1_all bug

NAME

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

INHERITANCE

        Log::Report::Domain
          is a Log::Report::Minimal::Domain

        Log::Report::Domain is extended by
          Log::Report::Template::Textdomain

SYNOPSIS

        # internal usage
        use Log::Report::Domain;
        my $domain = Log::Report::Domain->new(name => $name);

        # find a ::Domain object
        use Log::Report 'my-domain';
        my $domain = textdomain 'my-domain'; # find domain config
        my $domain = textdomain;             # config of this package

        # explicit domain configuration
        package My::Package;
        use Log::Report 'my-domain';         # set textdomain for package

        textdomain $name, %configure;        # set config, once per program
        (textdomain $name)->configure(%configure); # same
        textdomain->configure(%configure);   # same if current package in $name

        # implicit domain configuration
        package My::Package;
        use Log::Report 'my-domain', %configure;

        # external file for configuration (perl or json format)
        use Log::Report 'my-domain', config => $filename;

        use Log::Report 'my-domain';
        textdomain->configure(config => $filename);

DESCRIPTION

       Log::Report can handle multiple sets of packages at the same time: in the usual case a
       program consists of more than one software distribution, each containing a number of
       packages.  Each module in an application belongs to one of these sets, by default the
       domain set 'default'.

       For "Log::Report", those packags sets are differentiated via the text-domain value in the
       "use" statement:

         use Log::Report 'my-domain';

       There are many things you can configure per (text)domain.  This is not only related to
       translations, but also -for instance- for text formatting configuration.  The
       administration for the configuration is managed in this package.

       Extends "DESCRIPTION" in Log::Report::Minimal::Domain.

METHODS

       Extends "METHODS" in Log::Report::Minimal::Domain.

   Constructors
       Extends "Constructors" in Log::Report::Minimal::Domain.

       Log::Report::Domain->new(%options)
           Create a new Domain object.

            -Option--Defined in                  --Default
             name    Log::Report::Minimal::Domain  <required>

           name => STRING

   Attributes
       Extends "Attributes" in Log::Report::Minimal::Domain.

       $obj->configure(%options)
           The import is automatically called when the package is compiled.  For all but one
           packages in your distribution, it will only contain the name of the DOMAIN.  For one
           package, it will contain configuration information.  These %options are used for all
           packages which use the same DOMAIN.  See chapter "Configuring" below.

            -Option         --Defined in                  --Default
             config                                         undef
             context_rules                                  undef
             formatter                                      PRINTI
             native_language                                'en_US'
             translator                                     created internally
             where            Log::Report::Minimal::Domain  <required>

           config => FILENAME
             Read the settings from the file.  The parameters found in the file are used as
             default for the parameters above.  This parameter is especially useful for the
             "context_rules", which need to be shared between the running application and
             xgettext-perl.  See readConfig()

           context_rules => HASH|OBJECT
             When rules are provided, the translator will use the "msgctxt" fields as provided by
             PO-files (gettext).  This parameter is used to initialize a
             Log::Report::Translator::Context helper object.

           formatter => CODE|HASH|'PRINTI'
             Selects the formatter used for the errors messages.  The default is "PRINTI", which
             will use String::Print::printi(): interpolation with curly braces around the
             variable names.

           native_language => CODESET
             This is the language which you have used to write the translatable and the non-
             translatable messages in.  In case no translation is needed, you still wish the
             system error messages to be in the same language as the report.  Of course, each
             textdomain can define its own.

           translator => Log::Report::Translator|HASH
             Set the object which will do the translations for this domain.

           where => ARRAY
       $obj->contextRules()
       $obj->defaultContext()
           Returns the current default translation context settings as HASH.  You should not
           modify the content of that HASH: change it by called setContext() or updateContext().

       $obj->isConfigured()
           Inherited, see "Attributes" in Log::Report::Minimal::Domain

       $obj->name()
           Inherited, see "Attributes" in Log::Report::Minimal::Domain

       $obj->nativeLanguage()
       $obj->readConfig($filename)
       Log::Report::Domain->readConfig($filename)
           Helper method, which simply parses the content $filename into a HASH to be used as
           parameters to configure(). The filename must end on '.pl', to indicate that it uses
           perl syntax (can be processed with Perl's "do" command) or end on '.json'.  See also
           chapter "Configuring" below.

           Currently, this file can be in Perl native format (when ending on ".pl") or JSON (when
           it ends with ".json").  Various modules may explain parts of what can be found in
           these files, for instance Log::Report::Translator::Context.

       $obj->setContext(STRING|HASH|ARRAY|PAIRS)
           Temporary set the default translation context for messages.  This is used when the
           message is created without a "_context" parameter. The context can be retrieved with
           defaultContext().

           Contexts are totally ignored then there are no "context_rules".  When you do not wish
           to change settings, you may simply provide a HASH.

           example:

              use Log::Report 'my-domain', context_rules => {};

       $obj->translator()
       $obj->updateContext(STRING|HASH|ARRAY|PAIRS)
           [1.10] Make changes and additions to the active context (see setContext()).

   Action
       Extends "Action" in Log::Report::Minimal::Domain.

       $obj->interpolate( $msgid, [$args] )
           Inherited, see "Action" in Log::Report::Minimal::Domain

       $obj->translate($message, $language)
           Translate the $message into the $language.

DETAILS

   Configuring
       Configuration of a domain can happen in many ways: either explicitly or implicitly.  The
       explicit form:

          package My::Package;
          use Log::Report 'my-domain';

          textdomain 'my-domain', %configuration;
          textdomain->configure(%configuration);
          textdomain->configure(\%configuration);

          textdomain->configure(conf => $filename);

       The implicit form is (no variables possible, only constants!)

          package My::Package;
          use Log::Report 'my-domain', %configuration;
          use Log::Report 'my-domain', conf => '/filename';

       You can only configure your domain in one place in your program.  The textdomain setup is
       then used for all packages in the same domain.

       This also works for Log::Report::Optional, which is a dressed-down version of Log::Report.

       configuring your own formatter

       [0.91] The "PRINTI" is a special constants for configure(formatter), and will use
       String::Print function "printi()", with the standard tricks.

         textdomain 'some-domain'
           formatter =>
             { class     => 'String::Print'    # default
             , method    => 'sprinti'          # default
             , %options    # constructor options for the class
             );

       When you want your own formatter, or configuration of "String::Print", you need to pass a
       CODE.  Be aware that you may loose magic added by Log::Report and other layers, like
       Log::Report::Template:

         textdomain 'some-domain'
           , formatter => \&my_formatter;

       configuring global values

       Say, you log for a (Dancer) webserver, where you wish to include the website name in some
       of the log lines.  For this, (ab)use the translation context:

         ### first enabled translation contexts
         use Log::Report 'my-domain', context_rules => {};
         # or
         use Log::Report 'my-domain';
         textdomain->configure(context_rules => {});
         # or
         textdomain 'my-domain'
           , content_rules => {};

         ### every time you start working for a different virtual host
         (textdomain 'my-domain')->setContext(host => $host);

         ### now you can use that in your code
         package My::Package;
         use Log::Report 'my-domain';
         error __x"in {_context.host} not logged-in {user}", user => $username;

SEE ALSO

       This module is part of Log-Report distribution version 1.34, built on September 15, 2022.
       Website: http://perl.overmeer.net/CPAN/

LICENSE

       Copyrights 2007-2022 by [Mark Overmeer <markov@cpan.org>]. For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See http://dev.perl.org/licenses/