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