README
1NAME
2 Object::AUTHORITY - adds an AUTHORITY method to your class
3
4SYNOPSIS
5 {
6 package MyClass;
7 use Object::AUTHORITY;
8 BEGIN {
9 $MyClass::AUTHORITY = 'cpan:TOBYINK';
10 $MyClass::VERSION = '0.001';
11 }
12 }
13
14 print MyClass->AUTHORITY . "\n"; # prints "cpan:TOBYINK\n";
15 MyClass->AUTHORITY('cpan:FOO'); # assertion fails, croaks.
16
17DESCRIPTION
18 This module adds an "AUTHORITY" function to your package, which works
19 along the same lines as the "VERSION" function.
20
21 The authority of a package can be defined like this:
22
23 package MyApp;
24 BEGIN { $MyApp::AUTHORITY = 'cpan:JOEBLOGGS'; }
25
26 The authority should be a URI identifying the person, team, organisation
27 or trained chimp responsible for the release of the package. The
28 pseudo-URI scheme "cpan:" is the most commonly used identifier.
29
30 "AUTHORITY"
31 Called with no parameters returns the authority of the module.
32
33 "AUTHORITY($test)"
34 If passed a test, will croak if the test fails. The authority is tested
35 against the test using something approximating Perl 5.10's smart match
36 operator. (Briefly, you can pass a string for "eq" comparison, a regular
37 expression, a code reference to use as a callback, or an array reference
38 that will be grepped.)
39
40 Utility Function
41 "Object::AUTHORITY::reasonably_smart_match($a, $b)"
42 Object::AUTHORITY exposes its smart match implementation in case
43 classes wish to reuse it for their own custom "AUTHORITY" methods.
44 (There are various interesting use cases for custom "AUTHORITY"
45 methods, just as there are for custom "can" and "isa" methods.)
46
47 The $a parameter is always assumed to be a simple scalar.
48
49BUGS
50 Please report any bugs to
51 <http://rt.cpan.org/Dist/Display.html?Queue=Object-AUTHORITY>.
52
53SEE ALSO
54 * *Object::AUTHORITY* (this module) - an AUTHORITY method for your
55 class
56
57 * authority::shared - a more sophisticated AUTHORITY method for your
58 class
59
60 * UNIVERSAL::AUTHORITY - an AUTHORITY method for every class
61 (deprecated)
62
63 * UNIVERSAL::AUTHORITY::Lexical - an AUTHORITY method for every class,
64 within a lexical scope
65
66 * authority - load modules only if they have a particular authority
67
68 Background reading: <http://feather.perl6.nl/syn/S11.html>,
69 <http://www.perlmonks.org/?node_id=694377>.
70
71AUTHOR
72 Toby Inkster <tobyink@cpan.org>.
73
74COPYRIGHT AND LICENCE
75 This software is copyright (c) 2011 by Toby Inkster.
76
77 This is free software; you can redistribute it and/or modify it under
78 the same terms as the Perl 5 programming language system itself.
79
80DISCLAIMER OF WARRANTIES
81 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
82 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
83 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
84
85