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