/ 
Perl-Critic-Pulp-18
River stage two • 5 direct dependents • 13 total dependents
/ Perl::Critic::Policy::Miscellanea::TextDomainPlaceholders

NAME

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

DESCRIPTION

This policy is part of the Perl::Critic::Pulp addon. 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 { } as a key, but for the purposes of this policy only symbol characters "a-zA-Z0-9_" 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.

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 instead it's reported as a probably mistake. This is done primarily because the following expression part is then taken as a key, and because it's not a constant it's assumed to fulfil the format strings at runtime, so no violations are otherwise reported.

SEE ALSO

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

HOME PAGE

http://www.geocities.com/user42_kevin/perl-critic-pulp/index.html

COPYRIGHT

Copyright 2008, 2009 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/.