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

FreeBSD Manual Pages

  
 
  

home | help
Perl::Critic::PoliPerlUseriContributed:PerlcDocumentationDomainPlaceholders(3)

NAME
       Perl::Critic::Policy::Miscellanea::TextDomainPlaceholders - check
       placeholder names in Locale::TextDomain calls

DESCRIPTION
       This policy is part of the "Perl::Critic::Pulp" add-on.	It checks the
       placeholder arguments in	format strings to the following	functions from
       "Locale::TextDomain".

	   __x __nx __xn __px __npx

       Calls with a key	missing	from the args or args unused by	the format are
       reported.

	   print __x('Searching	for {data}',  #	bad
		     datum => 123);

	   print __nx('Read one	file',
		      'Read {num} files',     #	bad
		      $n,
		      count => 123);

       This is normally	a mistake, so this policy is under the "bugs" theme
       (see "POLICY THEMES" in Perl::Critic).  An error	can easily go
       unnoticed because (as of	Locale::TextDomain version 1.16) a placeholder
       without a corresponding arg goes	through	unexpanded and any extra args
       are ignored.

       The way Locale::TextDomain parses the format string allows anything
       between "{A }" as a key,	but for	the purposes of	this policy only
       symbols (alphanumeric plus "_") are taken to be a key.  This is almost
       certainly what you'll want to use, and it's then	possible to include
       literal braces in a format string without tickling this policy all the
       time.  (Symbol characters are per Perl "\w", so non-ASCII is supported,
       though the Gettext manual in node "Charset conversion" recommends
       message-IDs should be ASCII-only.)

Partial	Checks
       If the format string is not a literal then it might use any args, so
       all are considered used.

	   # ok, 'datum' might be used
	   __x($my_format, datum => 123);

       Literal portions	of the format are still	checked.

	   # bad, 'foo'	not present in args
	   __x("{foo} $bar", datum => 123);

       Conversely if the args have some	non-literals then they could be
       anything, so everything in the format string is considered present.

	   # ok, $something might be 'world'
	   __x('hello {world}',	$something => 123);

       But again if some args are literals they	can be checked.

	   # bad, 'blah' is not	used
	   __x('hello {world}',	$something => 123, blah	=> 456);

       If there's non-literals both in the format and in the args then nothing
       is checked, since it could all match up fine at runtime.

   "__nx" Count	Argument
       A missing count argument	to "__nx", "__xn" and "__npx" is sometimes
       noticed by this policy.	For example,

	   print __nx('Read one	file',
		      'Read {numfiles} files',
		      numfiles => $numfiles);	# bad

       If the count argument looks like	a key then it's	reported as a probable
       mistake.	 This is not the main aim of this policy but it's done because
       otherwise no violations would be	reported at all.  (The next argument
       would be	the key, and normally being an expression it would be assumed
       to fulfill the format strings at	runtime.)

SEE ALSO
       Perl::Critic::Pulp, Perl::Critic, Locale::TextDomain,
       Perl::Critic::Policy::Miscellanea::TextDomainUnused

HOME PAGE
       <http://user42.tuxfamily.org/perl-critic-pulp/index.html>

COPYRIGHT
       Copyright 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017
       Kevin Ryde

       Perl-Critic-Pulp	is free	software; you can redistribute it and/or
       modify it under the terms of the	GNU General Public License as
       published by the	Free Software Foundation; either version 3, or (at
       your option) any	later version.

       Perl-Critic-Pulp	is distributed in the hope that	it will	be useful, but
       WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A	PARTICULAR PURPOSE.  See the GNU
       General Public License for more details.

       You should have received	a copy of the GNU General Public License along
       with Perl-Critic-Pulp.  If not, see <http://www.gnu.org/licenses/>.

perl v5.24.1	  Perl::Critic::Policy::Miscellanea::TextDomainPlaceholders(3)

NAME | DESCRIPTION | Partial Checks | SEE ALSO | HOME PAGE | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Perl::Critic::Policy::Miscellanea::TextDomainPlaceholders&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help