Debian Codegraph @

README

raw
1 NAME
2 Scalar::Does - like ref() but useful
3
4 SYNOPSIS
5 use Scalar::Does qw( -constants );
6
7 my $object = bless {}, 'Some::Class';
8
9 does($object, 'Some::Class'); # true
10 does($object, '%{}'); # true
11 does($object, HASH); # true
12 does($object, ARRAY); # false
13
14 DESCRIPTION
15 It has long been noted that Perl would benefit from a `does()` built-in. A
16 check that `ref($thing) eq 'ARRAY'` doesn't allow you to accept an object
17 that uses overloading to provide an array-like interface.
18
19 Functions
20 `does($scalar, $role)`
21 Checks if a scalar is capable of performing the given role. The
22 following (case-sensitive) roles are predefined:
23
24 * SCALAR or ${}
25
26 Checks if the scalar can be used as a scalar reference.
27
28 Note: this role does not check whether a scalar is a scalar (which
29 is obviously true) but whether it is a reference to another
30 scalar.
31
32 * ARRAY or @{}
33
34 Checks if the scalar can be used as an array reference.
35
36 * HASH or %{}
37
38 Checks if the scalar can be used as a hash reference.
39
40 * CODE or &{}
41
42 Checks if the scalar can be used as a code reference.
43
44 * GLOB or *{}
45
46 Checks if the scalar can be used as a glob reference.
47
48 * REF
49
50 Checks if the scalar can be used as a ref reference (i.e. a
51 reference to another reference).
52
53 * LVALUE
54
55 Checks if the scalar is a reference to a special lvalue (e.g. the
56 result of `substr` or `splice`).
57
58 * IO or <>
59
60 Uses IO::Detect to check if the scalar is a filehandle or
61 file-handle-like object.
62
63 (The `<>` check is slightly looser, allowing objects which
64 overload `<>`, though overloading `<>` well can be a little
65 tricky.)
66
67 * VSTRING
68
69 Checks if the scalar is a vstring reference.
70
71 * FORMAT
72
73 Checks if the scalar is a format reference.
74
75 * Regexp or qr
76
77 Checks if the scalar can be used as a quoted regular expression.
78
79 * bool
80
81 Checks if the scalar can be used as a boolean. (It's pretty rare
82 for this to not be true.)
83
84 * ""
85
86 Checks if the scalar can be used as a string. (It's pretty rare
87 for this to not be true.)
88
89 * 0+
90
91 Checks if the scalar can be used as a number. (It's pretty rare
92 for this to not be true.)
93
94 Note that this is far looser than `looks_like_number` from
95 Scalar::Util. For example, an unblessed arrayref can be used as a
96 number (it numifies to its reference address); the string "Hello
97 World" can be used as a number (it numifies to 0).
98
99 * ~~
100
101 Checks if the scalar can be used on the right hand side of a smart
102 match.
103
104 If the given *role* is blessed, and provides a `check` method, then
105 `does` delegates to that.
106
107 Otherwise, if the scalar being tested is blessed, then
108 `$scalar->DOES($role)` is called, and `does` returns true if the
109 method call returned true.
110
111 If the scalar being tested looks like a Perl class name, then
112 `$scalar->DOES($role)` is also called, and the string "0E0" is
113 returned for success, which evaluates to 0 in a numeric context but
114 true in a boolean context.
115
116 `does($role)`
117 Called with a single argument, tests $_. Yes, this works with lexical
118 $_.
119
120 given ($object) {
121 when(does ARRAY) { ... }
122 when(does HASH) { ... }
123 }
124
125 Note: in Scalar::Does 0.007 and below the single-argument form of
126 `does` returned a curried coderef. This was changed in Scalar::Does
127 0.008.
128
129 `overloads($scalar, $role)`
130 A function `overloads` (which just checks overloading) is also
131 available.
132
133 `overloads($role)`
134 Called with a single argument, tests $_. Yes, this works with lexical
135 $_.
136
137 Note: in Scalar::Does 0.007 and below the single-argument form of
138 `overloads` returned a curried coderef. This was changed in
139 Scalar::Does 0.008.
140
141 `blessed($scalar)`, `reftype($scalar)`, `looks_like_number($scalar)`
142 For convenience, this module can also re-export these functions from
143 Scalar::Util. `looks_like_number` is generally more useful than
144 `does($scalar, q[0+])`.
145
146 `make_role $name, where { BLOCK }`
147 Returns an anonymous role object which can be used as a parameter to
148 `does`. The block is arbitrary code which should check whether $_[0]
149 does the role.
150
151 `where { BLOCK }`
152 Syntactic sugar for `make_role`. Compatible with the `where` function
153 from Moose::Util::TypeConstraints, so don't worry about conflicts.
154
155 Constants
156 The following constants may be exported for convenience:
157
158 `SCALAR`
159 `ARRAY`
160 `HASH`
161 `CODE`
162 `GLOB`
163 `REF`
164 `LVALUE`
165 `IO`
166 `VSTRING`
167 `FORMAT`
168 `REGEXP`
169 `BOOLEAN`
170 `STRING`
171 `NUMBER`
172 `SMARTMATCH`
173
174 Export
175 By default, only `does` is exported. This module uses Exporter::Tiny, so
176 functions can be renamed:
177
178 use Scalar::Does does => { -as => 'performs_role' };
179
180 Scalar::Does also plays some tricks with namespace::clean to ensure that
181 any functions it exports to your namespace are cleaned up when you're
182 finished with them. This ensures that if you're writing object-oriented
183 code `does` and `overloads` will not be left hanging around as methods of
184 your classes. Moose::Object provides a `does` method, and you should be
185 able to use Scalar::Does without interfering with that.
186
187 You can import the constants (plus `does`) using:
188
189 use Scalar::Does -constants;
190
191 The `make_role` and `where` functions can be exported like this:
192
193 use Scalar::Does -make;
194
195 Or list specific functions/constants that you wish to import:
196
197 use Scalar::Does qw( does ARRAY HASH STRING NUMBER );
198
199 Custom Role Checks
200 use Scalar::Does
201 custom => { -as => 'does_array', -role => 'ARRAY' },
202 custom => { -as => 'does_hash', -role => 'HASH' };
203
204 does_array($thing);
205 does_hash($thing);
206
207 BUGS
208 Please report any bugs to
209 <http://rt.cpan.org/Dist/Display.html?Queue=Scalar-Does>.
210
211 SEE ALSO
212 Scalar::Util.
213
214 <http://perldoc.perl.org/5.10.0/perltodo.html#A-does()-built-in>.
215
216 Relationship to Moose roles
217 Scalar::Does is not dependent on Moose, and its role-checking is not
218 specific to Moose's idea of roles, but it does work well with Moose roles.
219
220 Moose::Object overrides `DOES`, so Moose objects and Moose roles should
221 "just work" with Scalar::Does.
222
223 {
224 package Transport;
225 use Moose::Role;
226 }
227
228 {
229 package Train;
230 use Moose;
231 with qw(Transport);
232 }
233
234 my $thomas = Train->new;
235 does($thomas, 'Train'); # true
236 does($thomas, 'Transport'); # true
237 does($thomas, Transport->meta); # not yet supported!
238
239 Mouse::Object should be compatible enough to work as well.
240
241 See also: Moose::Role, Moose::Object, UNIVERSAL.
242
243 Relationship to Moose type constraints
244 Moose::Meta::TypeConstraint objects, plus the constants exported by
245 MooseX::Types libraries all provide a `check` method, so again, should
246 "just work" with Scalar::Does. Type constraint strings are not supported
247 however.
248
249 use Moose::Util::TypeConstraints qw(find_type_constraint);
250 use MooseX::Types qw(Int);
251 use Scalar::Does qw(does);
252
253 my $int = find_type_constraint("Int");
254
255 does( "123", $int ); # true
256 does( "123", Int ); # true
257 does( "123", "Int" ); # false
258
259 Mouse::Meta::TypeConstraints and MouseX::Types should be compatible enough
260 to work as well.
261
262 See also: Moose::Meta::TypeConstraint, Moose::Util::TypeConstraints,
263 MooseX::Types, Scalar::Does::MooseTypes.
264
265 Relationship to Type::Tiny type constraints
266 Types built with Type::Tiny and Type::Library can be used exactly as Moose
267 type constraint objects above.
268
269 use Types::Standard qw(Int);
270 use Scalar::Does qw(does);
271
272 does(123, Int); # true
273
274 In fact, Type::Tiny and related libraries are used extensively in the
275 internals of Scalar::Does 0.200+.
276
277 See also: Type::Tiny, Types::Standard.
278
279 Relationship to Role::Tiny and Moo roles
280 Roles using Role::Tiny 1.002000 and above provide a `DOES` method, so
281 should work with Scalar::Does just like Moose roles. Prior to that
282 release, Role::Tiny did not provide `DOES`.
283
284 Moo's role system is based on Role::Tiny.
285
286 See also: Role::Tiny, Moo::Role.
287
288 AUTHOR
289 Toby Inkster <[email protected]>.
290
291 COPYRIGHT AND LICENCE
292 This software is copyright (c) 2012-2014, 2017 by Toby Inkster.
293
294 This is free software; you can redistribute it and/or modify it under the
295 same terms as the Perl 5 programming language system itself.
296
297 DISCLAIMER OF WARRANTIES
298 THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
299 WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
300 MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.
301