/ 
Perl-Critic-Pulp-17
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 __x, __nx and __xn functions from Locale::TextDomain. 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',     # bad
           'Read {num} files',
           $n,
           count => 123);

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

The way TextDomain parses the format allows anything between "{ }" as a key string, 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 makes it possible to include literal braces in a format string without tickling this policy all the time.

LIMITATIONS

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.

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