What is the purpose of the $AUTHORITY variable in a Perl CPAN distribution?

Question

According to Dist::Zilla::Plugin::Authority :

This plugin adds the authority data to your distribution. It adds the data to your modules and metadata. Normally it looks for the PAUSE author id in your Dist::Zilla configuration.

What is the "authority data" used for? Why is it added to all the modules?

See also Dist::Zilla::Plugin::PERLANCAR::Authority

Answer 1

In Raku, a module (actually any type) can have attributes :ver<>, :auth<> and :api<>. This allows you to pass it a version, author, and/or API number, which you can subsequently introspect.

class C:ver<4.2.3>:auth<github:jane>:api<1> {}
say C.^auth;      # OUTPUT: «github:jane»

In Perl, the authority of a package can be defined like this:

package MyApp;
BEGIN { $MyApp::AUTHORITY = 'cpan:JOEBLOGGS'; }

The authority should be an URI identifying the person, team, or organisation responsible for the release of the package. The pseudo-URI scheme cpan: is the most commonly used identifier.

The $AUTHORITY package variable can be used together with the authority pragma to load a module conditionally based on its authority:

use authority 'cpan:JOE', My::Module => qw();

Assuming that the @INC path is /opt/perl/lib, then Perl will attempt to load /opt/perl/lib/cpan_3A_JOE/My/Module.pm before it tries the usual /opt/perl/lib/My/Module.pm.

Also having a defined $AUTHORITY, enables module authority introspection with UNIVERSAL::AUTHORITY::Lexical. For example:

use UNIVERSAL::AUTHORITY::Lexical;
if (HTML::HTML5::Writer->AUTHORITY ne HTML::HTML5::Builder->AUTHORITY)
{
  warn "Closely intertwined modules with different authors!\n";
  warn "There may be trouble ahead...";
}

and

use UNIVERSAL::AUTHORITY::Lexical;
# Only trust STEVAN's releases
Moose->AUTHORITY('cpan:STEVAN'); # dies if doesn't match

See also our $AUTHORITY for the original discussion on this variable.