1Role::Commons::AuthoritUys(e3r)Contributed Perl DocumentRaotlieo:n:Commons::Authority(3)
2
3
4

NAME

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

SYNOPSIS

10          package MyApp;
11          use Role::Commons -all;
12          BEGIN { our $AUTHORITY = 'cpan:JOEBLOGGS' };
13
14          say MyApp->AUTHORITY;   # says "cpan:JOEBLOGGS"
15
16          MyApp->AUTHORITY("cpan:JOEBLOGGS");     # does nothing much
17          MyApp->AUTHORITY("cpan:JOHNTCITIZEN");  # croaks
18

DESCRIPTION

20       This module adds an "AUTHORITY" function to your package, which works
21       along the same lines as the "VERSION" function.
22
23       The authority of a package can be defined like this:
24
25          package MyApp;
26          BEGIN { our $AUTHORITY = 'cpan:JOEBLOGGS' };
27
28       The authority should be a URI identifying the person, team,
29       organisation or trained chimp responsible for the release of the
30       package. The pseudo-URI scheme "cpan:" is the most commonly used
31       identifier.
32
33   Method
34       "AUTHORITY"
35           Called with no parameters returns the authority of the module.
36
37       AUTHORITY($test)
38           If passed a test, will croak if the test fails. The authority is
39           tested against the test using something approximating Perl 5.10's
40           smart match operator. (Briefly, you can pass a string for eq
41           comparison, a regular expression, a code reference to use as a
42           callback, or an array reference that will be grepped.)
43
44   Multiple Authorities
45       This module allows you to indicate that your module is issued by
46       multiple authorities. The package variable $AUTHORITY should still be
47       used to indicate the primary authority for the package.
48
49          package MyApp;
50          use Role::Commons
51             Authority => { -authorities => [qw( cpan:ALICE cpan:BOB )] };
52          BEGIN { $MyApp::AUTHORITY = 'cpan:JOE'; }
53
54          package main;
55          use feature qw(say);
56          say scalar MyApp->AUTHORITY;     # says "cpan:JOE"
57          MyApp->AUTHORITY('cpan:JOE');    # lives
58          MyApp->AUTHORITY('cpan:ALICE');  # lives
59          MyApp->AUTHORITY('cpan:BOB');    # lives
60          MyApp->AUTHORITY('cpan:CAROL');  # croaks
61
62       The main use case for shared authorities is for team projects. The team
63       would designate a URI to represent the team as a whole. For example,
64       "http://datetime.perl.org/", "http://moose.iinteractive.com/" or
65       "http://www.perlrdf.org/". Releases can then be officially stamped with
66       the authority of the team.
67
68       And users can check they have an module released by the official team
69       using:
70
71          RDF::TakeOverTheWorld->AUTHORITY(
72             q<http://www.perlrdf.org/>,
73          );
74
75       which will croak if package RDF::TakeOverTheWorld doesn't have the
76       specified authority.
77

BUGS

79       An obvious limitation is that this module relies on honesty. Don't
80       release modules under authorities you have no authority to use.
81
82       Please report any bugs to
83       <http://rt.cpan.org/Dist/Display.html?Queue=Role-Commons>.
84

SEE ALSO

86       Role::Commons, authority.
87
88       Background reading: <http://feather.perl6.nl/syn/S11.html>,
89       <http://www.perlmonks.org/?node_id=694377>.
90

AUTHOR

92       Toby Inkster <tobyink@cpan.org>.
93

95       This software is copyright (c) 2012, 2014 by Toby Inkster.
96
97       This is free software; you can redistribute it and/or modify it under
98       the same terms as the Perl 5 programming language system itself.
99

DISCLAIMER OF WARRANTIES

101       THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
102       WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
103       MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
104
105
106
107perl v5.38.0                      2023-07-21       Role::Commons::Authority(3)
Impressum