Toby Inkster > Role-Commons-0.101 > Role::Commons::Authority

Download:
Role-Commons-0.101.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.101   Source  

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

syntax highlighting: