Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Log::Report::Domain(3)User Contributed Perl DocumentatioLog::Report::Domain(3)

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.

       Log::Report::Domain->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.20, built on
       June 27,	2017. Website: http://perl.overmeer.net/log-report/

LICENSE
       Copyrights 2007-2017 by [Mark Overmeer].	For other contributors see
       ChangeLog.

       This program is free software; you can redistribute it and/or modify it
       under the Artistic license.  See
       http://dev.perl.org/licenses/artistic.html

perl v5.24.1			  2017-06-27		Log::Report::Domain(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DETAILS | SEE ALSO | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Log::Report::Domain&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help