1Scalar::Does(3)       User Contributed Perl Documentation      Scalar::Does(3)
2
3
4

NAME

6       Scalar::Does - like ref() but useful
7

SYNOPSIS

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

DESCRIPTION

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

BUGS

214       Please report any bugs to
215       <http://rt.cpan.org/Dist/Display.html?Queue=Scalar-Does>.
216

SEE ALSO

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

AUTHOR

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

DISCLAIMER OF WARRANTIES

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.34.0                      2022-01-21                   Scalar::Does(3)
Impressum