.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Role::Commons::Authority 3pm"
.TH Role::Commons::Authority 3pm "2021-01-05" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Role::Commons::Authority \- a class method indicating who published the package
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\& package MyApp;
\& use Role::Commons \-all;
\& BEGIN { our $AUTHORITY = \*(Aqcpan:JOEBLOGGS\*(Aq };
\&
\& say MyApp\->AUTHORITY; # says "cpan:JOEBLOGGS"
\&
\& MyApp\->AUTHORITY("cpan:JOEBLOGGS"); # does nothing much
\& MyApp\->AUTHORITY("cpan:JOHNTCITIZEN"); # croaks
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module adds an \f(CW\*(C`AUTHORITY\*(C'\fR function to your package, which works along
the same lines as the \f(CW\*(C`VERSION\*(C'\fR function.
.PP
The authority of a package can be defined like this:
.PP
.Vb 2
\& package MyApp;
\& BEGIN { our $AUTHORITY = \*(Aqcpan:JOEBLOGGS\*(Aq };
.Ve
.PP
The authority should be a \s-1URI\s0 identifying the person, team, organisation or
trained chimp responsible for the release of the package. The pseudo-URI
scheme \*(L"cpan:\*(R" is the most commonly used identifier.
.SS "Method"
.IX Subsection "Method"
.ie n .IP """AUTHORITY""" 4
.el .IP "\f(CWAUTHORITY\fR" 4
.IX Item "AUTHORITY"
Called with no parameters returns the authority of the module.
.ie n .IP """AUTHORITY($test)""" 4
.el .IP "\f(CWAUTHORITY($test)\fR" 4
.IX Item "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.)
.SS "Multiple Authorities"
.IX Subsection "Multiple Authorities"
This module allows you to indicate that your module is issued by multiple
authorities. The package variable \f(CW$AUTHORITY\fR should still be used
to indicate the primary authority for the package.
.PP
.Vb 4
\& package MyApp;
\& use Role::Commons
\& Authority => { \-authorities => [qw( cpan:ALICE cpan:BOB )] };
\& BEGIN { $MyApp::AUTHORITY = \*(Aqcpan:JOE\*(Aq; }
\&
\& package main;
\& use feature qw(say);
\& say scalar MyApp\->AUTHORITY; # says "cpan:JOE"
\& MyApp\->AUTHORITY(\*(Aqcpan:JOE\*(Aq); # lives
\& MyApp\->AUTHORITY(\*(Aqcpan:ALICE\*(Aq); # lives
\& MyApp\->AUTHORITY(\*(Aqcpan:BOB\*(Aq); # lives
\& MyApp\->AUTHORITY(\*(Aqcpan:CAROL\*(Aq); # croaks
.Ve
.PP
The main use case for shared authorities is for team projects. The team would
designate a \s-1URI\s0 to represent the team as a whole. For example,
\&\f(CW\*(C`http://datetime.perl.org/\*(C'\fR, \f(CW\*(C`http://moose.iinteractive.com/\*(C'\fR or
\&\f(CW\*(C`http://www.perlrdf.org/\*(C'\fR. Releases can then be officially stamped with
the authority of the team.
.PP
And users can check they have an module released by the official team using:
.PP
.Vb 3
\& RDF::TakeOverTheWorld\->AUTHORITY(
\& q,
\& );
.Ve
.PP
which will croak if package RDF::TakeOverTheWorld doesn't have the specified
authority.
.SH "BUGS"
.IX Header "BUGS"
An obvious limitation is that this module relies on honesty. Don't release
modules under authorities you have no authority to use.
.PP
Please report any bugs to
.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Role::Commons,
authority.
.PP
Background reading:
,
.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster .
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2012, 2014 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0