jammy (3) Perl::Critic::Policy::Miscellanea::TextDomainPlaceholders.3pm.gz

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)