Role::...hority(3pm)

💖 NAME 💖

Role::Commons::Authority — a class method that tells the whole world who actually published the package. It's giving "who's your daddy" but for CPAN releases. 👑

(and yes bestie, this is a 3pm man page, so it's Perl, and we're in our module era.)

---

✨ 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

Look at that. Flawless. It says the thing, and then it does NOT let an impostor say the thing. 🫶

---

🌸 DESCRIPTION 🌸

Okay so here's the tea: this module drops an AUTHORITY function into your package, and it behaves along the same lines as the VERSION function you already know and love. Same energy, different metadata. 💅

You define the authority of a package like this:

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

And that 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 one everybody actually uses — most commonly used identifier, no cap.

🎀 Method 🎀

• AUTHORITY — call it with no parameters and it hands you back the authority of the module. That's it. That's the whole vibe.
• AUTHORITY($test) — if you pass it a test, it will croak if the test fails. The authority gets tested against your test using something approximating Perl 5.10's smart match operator. (Briefly, bestie: 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.) Smart-match-flavoured detective work, essentially. 🔍

🦋 Multiple Authorities 🦋

Plot twist: this module also lets you say that your module is issued by multiple authorities. But — and listen closely — the package variable $AUTHORITY should still be the one you use to indicate the primary authority for the package. She's the main character. 👑

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

Carol is not on the list and Carol is getting croaked at. Sorry Carol. 😭

The main use case for shared authorities is 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/. Then releases can be officially stamped with the authority of the team — like a little "we made this, together, as a family" seal. 🫶

And users can check they have a 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. So if it's not the real team, you'll know instantly. Vibe check: failed. 💀

---

💀 BUGS 💀

An obvious limitation is that this module relies on honesty. Don't release modules under authorities you have no authority to use. It's the honor system, bestie — and the honor system does not have a bouncer. 🙈

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

---

🌈 SEE ALSO 🌈

• Role::Commons
• authority

Background reading (iykyk, go read it): <http://feather.perl6.nl/syn/S11.html>, <http://www.perlmonks.org/?node_id=694377>.

---

🎀 AUTHOR 🎀

Toby Inkster <tobyink@cpan.org>. Iconic behaviour, honestly. 🫡

---

⭐ 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. So like, go off, but respectfully. 💖

---

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

Translation bestie: no promises, no takebacks, use at your own risk. 😭

---

And that's the whole page, mwah. 💅 This one came from perl v5.32.0 and it's dated 2021-01-05 — so it's a little vintage, like a good thrifted jacket. 🦋 Go forth and claim your authority. 👑