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

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