NAME

       Role::Commons::Authority - a class method indicating who published the package

SYNOPSIS

          package MyApp;
          use Role::Commons -all;
          BEGIN { our $AUTHORITY = 'cpan:JOEBLOGGS' };

          say MyApp->AUTHORITY;   # says "cpan:JOEBLOGGS"

          MyApp->AUTHORITY("cpan:JOEBLOGGS");     # does nothing much
          MyApp->AUTHORITY("cpan:JOHNTCITIZEN");  # croaks

DESCRIPTION

       This module adds an "AUTHORITY" function to your package, which works along the same lines as the
       "VERSION" function.

       The authority of a package can be defined like this:

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

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

   Method
       "AUTHORITY"
           Called with no parameters returns the authority of the module.

       "AUTHORITY($test)"
           If  passed  a  test,  will  croak  if  the test fails. The authority is tested against the test using
           something approximating Perl 5.10's smart match operator. (Briefly, you can  pass  a  string  for  eq
           comparison,  a  regular expression, a code reference to use as a callback, or an array reference that
           will be grepped.)

   Multiple Authorities
       This module allows you to indicate that your module  is  issued  by  multiple  authorities.  The  package
       variable $AUTHORITY should still be used to indicate the primary authority for the package.

          package MyApp;
          use Role::Commons
             Authority => { -authorities => [qw( cpan:ALICE cpan:BOB )] };
          BEGIN { $MyApp::AUTHORITY = 'cpan:JOE'; }

          package main;
          use feature qw(say);
          say scalar MyApp->AUTHORITY;     # says "cpan:JOE"
          MyApp->AUTHORITY('cpan:JOE');    # lives
          MyApp->AUTHORITY('cpan:ALICE');  # lives
          MyApp->AUTHORITY('cpan:BOB');    # lives
          MyApp->AUTHORITY('cpan:CAROL');  # croaks

       The  main  use  case  for  shared  authorities  is  for  team projects. The team would designate a URI to
       represent the team as a whole. For example, "http://datetime.perl.org/", "http://moose.iinteractive.com/"
       or "http://www.perlrdf.org/". Releases can then be officially stamped with the authority of the team.

       And users can check they have an module released by the official team using:

          RDF::TakeOverTheWorld->AUTHORITY(
             q<http://www.perlrdf.org/>,
          );

       which will croak if package RDF::TakeOverTheWorld doesn't have the specified authority.

BUGS

       An obvious limitation is that this module relies on honesty. Don't release modules under authorities  you
       have no authority to use.

       Please report any bugs to <http://rt.cpan.org/Dist/Display.html?Queue=Role-Commons>.

SEE ALSO

       Role::Commons, authority.

       Background reading: <http://feather.perl6.nl/syn/S11.html>, <http://www.perlmonks.org/?node_id=694377>.

AUTHOR

       Toby Inkster <tobyink@cpan.org>.

COPYRIGHT AND LICENCE

       This software is copyright (c) 2012, 2014 by Toby Inkster.

       This  is  free  software;  you  can  redistribute  it and/or modify it under the same terms as the Perl 5
       programming language system itself.

DISCLAIMER OF WARRANTIES

       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT  ANY  EXPRESS  OR  IMPLIED  WARRANTIES,  INCLUDING,  WITHOUT
       LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.

perl v5.32.0                                       2021-01-05                      Role::Commons::Authority(3pm)