/ 
Perl-Critic-Pulp-99
River stage two • 5 direct dependents • 18 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 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 { } 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, 2019, 2021 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/>.