.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Scalar::Does 3pm"
.TH Scalar::Does 3pm "2021-01-04" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Scalar::Does \- like ref() but useful
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Scalar::Does qw( \-constants );
\&  
\&  my $object = bless {}, \*(AqSome::Class\*(Aq;
\&  
\&  does($object, \*(AqSome::Class\*(Aq);   # true
\&  does($object, \*(Aq%{}\*(Aq);           # true
\&  does($object, HASH);            # true
\&  does($object, ARRAY);           # false
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
It has long been noted that Perl would benefit from a \f(CW\*(C`does()\*(C'\fR built-in.
A check that \f(CW\*(C`ref($thing) eq \*(AqARRAY\*(Aq\*(C'\fR doesn't allow you to accept an
object that uses overloading to provide an array-like interface.
.SS "Functions"
.IX Subsection "Functions"
.ie n .IP """does($scalar, $role)""" 4
.el .IP "\f(CWdoes($scalar, $role)\fR" 4
.IX Item "does($scalar, $role)"
Checks if a scalar is capable of performing the given role. The following
(case-sensitive) roles are predefined:
.RS 4
.IP "\(bu" 4
\&\fB\s-1SCALAR\s0\fR or \fB${}\fR
.Sp
Checks if the scalar can be used as a scalar reference.
.Sp
Note: this role does not check whether a scalar is a scalar (which is
obviously true) but whether it is a reference to another scalar.
.IP "\(bu" 4
\&\fB\s-1ARRAY\s0\fR or \fB@{}\fR
.Sp
Checks if the scalar can be used as an array reference.
.IP "\(bu" 4
\&\fB\s-1HASH\s0\fR or \fB%{}\fR
.Sp
Checks if the scalar can be used as a hash reference.
.IP "\(bu" 4
\&\fB\s-1CODE\s0\fR or \fB&{}\fR
.Sp
Checks if the scalar can be used as a code reference.
.IP "\(bu" 4
\&\fB\s-1GLOB\s0\fR or \fB*{}\fR
.Sp
Checks if the scalar can be used as a glob reference.
.IP "\(bu" 4
\&\fB\s-1REF\s0\fR
.Sp
Checks if the scalar can be used as a ref reference (i.e. a reference to
another reference).
.IP "\(bu" 4
\&\fB\s-1LVALUE\s0\fR
.Sp
Checks if the scalar is a reference to a special lvalue (e.g. the result
of \f(CW\*(C`substr\*(C'\fR or \f(CW\*(C`splice\*(C'\fR).
.IP "\(bu" 4
\&\fB\s-1IO\s0\fR or \fB<>\fR
.Sp
Uses IO::Detect to check if the scalar is a filehandle or file-handle-like
object.
.Sp
(The \f(CW\*(C`<>\*(C'\fR check is slightly looser, allowing objects which overload
\&\f(CW\*(C`<>\*(C'\fR, though overloading \f(CW\*(C`<>\*(C'\fR well can be a little tricky.)
.IP "\(bu" 4
\&\fB\s-1VSTRING\s0\fR
.Sp
Checks if the scalar is a vstring reference.
.IP "\(bu" 4
\&\fB\s-1FORMAT\s0\fR
.Sp
Checks if the scalar is a format reference.
.IP "\(bu" 4
\&\fBRegexp\fR or \fBqr\fR
.Sp
Checks if the scalar can be used as a quoted regular expression.
.IP "\(bu" 4
\&\fBbool\fR
.Sp
Checks if the scalar can be used as a boolean. (It's pretty rare for this
to not be true.)
.IP "\(bu" 4
\&\fB""\fR
.Sp
Checks if the scalar can be used as a string. (It's pretty rare for this
to not be true.)
.IP "\(bu" 4
\&\fB0+\fR
.Sp
Checks if the scalar can be used as a number. (It's pretty rare for this
to not be true.)
.Sp
Note that this is far looser than \f(CW\*(C`looks_like_number\*(C'\fR from Scalar::Util.
For example, an unblessed arrayref can be used as a number (it numifies to
its reference address); the string \*(L"Hello World\*(R" can be used as a number (it
numifies to 0).
.IP "\(bu" 4
\&\fB~~\fR
.Sp
Checks if the scalar can be used on the right hand side of a smart match.
.RE
.RS 4
.Sp
If the given \fIrole\fR is blessed, and provides a \f(CW\*(C`check\*(C'\fR method, then
\&\f(CW\*(C`does\*(C'\fR delegates to that.
.Sp
Otherwise, if the scalar being tested is blessed, then
\&\f(CW\*(C`$scalar\->DOES($role)\*(C'\fR is called, and \f(CW\*(C`does\*(C'\fR returns true if
the method call returned true.
.Sp
If the scalar being tested looks like a Perl class name, then 
\&\f(CW\*(C`$scalar\->DOES($role)\*(C'\fR is also called, and the string \*(L"0E0\*(R" is
returned for success, which evaluates to 0 in a numeric context but
true in a boolean context.
.RE
.ie n .IP """does($role)""" 4
.el .IP "\f(CWdoes($role)\fR" 4
.IX Item "does($role)"
Called with a single argument, tests \f(CW$_\fR. Yes, this works with lexical
\&\f(CW$_\fR.
.Sp
.Vb 4
\&  given ($object) {
\&     when(does ARRAY)  { ... }
\&     when(does HASH)   { ... }
\&  }
.Ve
.Sp
Note: in Scalar::Does 0.007 and below the single-argument form of \f(CW\*(C`does\*(C'\fR
returned a curried coderef. This was changed in Scalar::Does 0.008.
.ie n .IP """overloads($scalar, $role)""" 4
.el .IP "\f(CWoverloads($scalar, $role)\fR" 4
.IX Item "overloads($scalar, $role)"
A function \f(CW\*(C`overloads\*(C'\fR (which just checks overloading) is also available.
.ie n .IP """overloads($role)""" 4
.el .IP "\f(CWoverloads($role)\fR" 4
.IX Item "overloads($role)"
Called with a single argument, tests \f(CW$_\fR. Yes, this works with lexical
\&\f(CW$_\fR.
.Sp
Note: in Scalar::Does 0.007 and below the single-argument form of \f(CW\*(C`overloads\*(C'\fR
returned a curried coderef. This was changed in Scalar::Does 0.008.
.ie n .IP """blessed($scalar)"", ""reftype($scalar)"", ""looks_like_number($scalar)""" 4
.el .IP "\f(CWblessed($scalar)\fR, \f(CWreftype($scalar)\fR, \f(CWlooks_like_number($scalar)\fR" 4
.IX Item "blessed($scalar), reftype($scalar), looks_like_number($scalar)"
For convenience, this module can also re-export these functions from
Scalar::Util. \f(CW\*(C`looks_like_number\*(C'\fR is generally more useful than
\&\f(CW\*(C`does($scalar, q[0+])\*(C'\fR.
.ie n .IP """make_role $name, where { BLOCK }""" 4
.el .IP "\f(CWmake_role $name, where { BLOCK }\fR" 4
.IX Item "make_role $name, where { BLOCK }"
Returns an anonymous role object which can be used as a parameter to
\&\f(CW\*(C`does\*(C'\fR. The block is arbitrary code which should check whether \f(CW$_\fR[0]
does the role.
.ie n .IP """where { BLOCK }""" 4
.el .IP "\f(CWwhere { BLOCK }\fR" 4
.IX Item "where { BLOCK }"
Syntactic sugar for \f(CW\*(C`make_role\*(C'\fR. Compatible with the \f(CW\*(C`where\*(C'\fR function
from Moose::Util::TypeConstraints, so don't worry about conflicts.
.SS "Constants"
.IX Subsection "Constants"
The following constants may be exported for convenience:
.ie n .IP """SCALAR""" 4
.el .IP "\f(CWSCALAR\fR" 4
.IX Item "SCALAR"
.PD 0
.ie n .IP """ARRAY""" 4
.el .IP "\f(CWARRAY\fR" 4
.IX Item "ARRAY"
.ie n .IP """HASH""" 4
.el .IP "\f(CWHASH\fR" 4
.IX Item "HASH"
.ie n .IP """CODE""" 4
.el .IP "\f(CWCODE\fR" 4
.IX Item "CODE"
.ie n .IP """GLOB""" 4
.el .IP "\f(CWGLOB\fR" 4
.IX Item "GLOB"
.ie n .IP """REF""" 4
.el .IP "\f(CWREF\fR" 4
.IX Item "REF"
.ie n .IP """LVALUE""" 4
.el .IP "\f(CWLVALUE\fR" 4
.IX Item "LVALUE"
.ie n .IP """IO""" 4
.el .IP "\f(CWIO\fR" 4
.IX Item "IO"
.ie n .IP """VSTRING""" 4
.el .IP "\f(CWVSTRING\fR" 4
.IX Item "VSTRING"
.ie n .IP """FORMAT""" 4
.el .IP "\f(CWFORMAT\fR" 4
.IX Item "FORMAT"
.ie n .IP """REGEXP""" 4
.el .IP "\f(CWREGEXP\fR" 4
.IX Item "REGEXP"
.ie n .IP """BOOLEAN""" 4
.el .IP "\f(CWBOOLEAN\fR" 4
.IX Item "BOOLEAN"
.ie n .IP """STRING""" 4
.el .IP "\f(CWSTRING\fR" 4
.IX Item "STRING"
.ie n .IP """NUMBER""" 4
.el .IP "\f(CWNUMBER\fR" 4
.IX Item "NUMBER"
.ie n .IP """SMARTMATCH""" 4
.el .IP "\f(CWSMARTMATCH\fR" 4
.IX Item "SMARTMATCH"
.PD
.SS "Export"
.IX Subsection "Export"
By default, only \f(CW\*(C`does\*(C'\fR is exported. This module uses Exporter::Tiny, so
functions can be renamed:
.PP
.Vb 1
\&  use Scalar::Does does => { \-as => \*(Aqperforms_role\*(Aq };
.Ve
.PP
Scalar::Does also plays some tricks with namespace::clean to ensure that
any functions it exports to your namespace are cleaned up when you're finished
with them. This ensures that if you're writing object-oriented code \f(CW\*(C`does\*(C'\fR
and \f(CW\*(C`overloads\*(C'\fR will not be left hanging around as methods of your classes.
Moose::Object provides a \f(CW\*(C`does\*(C'\fR method, and you should be able to use
Scalar::Does without interfering with that.
.PP
You can import the constants (plus \f(CW\*(C`does\*(C'\fR) using:
.PP
.Vb 1
\&  use Scalar::Does \-constants;
.Ve
.PP
The \f(CW\*(C`make_role\*(C'\fR and \f(CW\*(C`where\*(C'\fR functions can be exported like this:
.PP
.Vb 1
\&  use Scalar::Does \-make;
.Ve
.PP
Or list specific functions/constants that you wish to import:
.PP
.Vb 1
\&  use Scalar::Does qw( does ARRAY HASH STRING NUMBER );
.Ve
.SS "Custom Role Checks"
.IX Subsection "Custom Role Checks"
.Vb 3
\&  use Scalar::Does
\&    custom => { \-as => \*(Aqdoes_array\*(Aq, \-role => \*(AqARRAY\*(Aq },
\&    custom => { \-as => \*(Aqdoes_hash\*(Aq,  \-role => \*(AqHASH\*(Aq  };
\&  
\&  does_array($thing);
\&  does_hash($thing);
.Ve
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs to
<http://rt.cpan.org/Dist/Display.html?Queue=Scalar\-Does>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Scalar::Util.
.PP
<http://perldoc.perl.org/5.10.0/perltodo.html#A\-\fBdoes()\fR\-built\-in>.
.SS "Relationship to Moose roles"
.IX Subsection "Relationship to Moose roles"
Scalar::Does is not dependent on Moose, and its role-checking is not specific
to Moose's idea of roles, but it does work well with Moose roles.
.PP
Moose::Object overrides \f(CW\*(C`DOES\*(C'\fR, so Moose objects and Moose roles should
\&\*(L"just work\*(R" with Scalar::Does.
.PP
.Vb 4
\&  {
\&    package Transport;
\&    use Moose::Role;
\&  }
\&  
\&  {
\&    package Train;
\&    use Moose;
\&    with qw(Transport);
\&  }
\&  
\&  my $thomas = Train\->new;
\&  does($thomas, \*(AqTrain\*(Aq);          # true
\&  does($thomas, \*(AqTransport\*(Aq);      # true
\&  does($thomas, Transport\->meta);  # not yet supported!
.Ve
.PP
Mouse::Object should be compatible enough to work as well.
.PP
See also:
Moose::Role,
Moose::Object,
\&\s-1UNIVERSAL\s0.
.SS "Relationship to Moose type constraints"
.IX Subsection "Relationship to Moose type constraints"
Moose::Meta::TypeConstraint objects, plus the constants exported by
MooseX::Types libraries all provide a \f(CW\*(C`check\*(C'\fR method, so again, should
\&\*(L"just work\*(R" with Scalar::Does. Type constraint strings are not supported
however.
.PP
.Vb 3
\&  use Moose::Util::TypeConstraints qw(find_type_constraint);
\&  use MooseX::Types qw(Int);
\&  use Scalar::Does qw(does);
\&  
\&  my $int = find_type_constraint("Int");
\&  
\&  does( "123", $int );     # true
\&  does( "123", Int );      # true
\&  does( "123", "Int" );    # false
.Ve
.PP
Mouse::Meta::TypeConstraints and MouseX::Types should be compatible
enough to work as well.
.PP
See also:
Moose::Meta::TypeConstraint,
Moose::Util::TypeConstraints,
MooseX::Types,
Scalar::Does::MooseTypes.
.SS "Relationship to Type::Tiny type constraints"
.IX Subsection "Relationship to Type::Tiny type constraints"
Types built with Type::Tiny and Type::Library can be used exactly as
Moose type constraint objects above.
.PP
.Vb 2
\&  use Types::Standard qw(Int);
\&  use Scalar::Does qw(does);
\&  
\&  does(123, Int);   # true
.Ve
.PP
In fact, Type::Tiny and related libraries are used extensively in the
internals of Scalar::Does 0.200+.
.PP
See also:
Type::Tiny,
Types::Standard.
.SS "Relationship to Role::Tiny and Moo roles"
.IX Subsection "Relationship to Role::Tiny and Moo roles"
Roles using Role::Tiny 1.002000 and above provide a \f(CW\*(C`DOES\*(C'\fR method, so
should work with Scalar::Does just like Moose roles. Prior to that release,
Role::Tiny did not provide \f(CW\*(C`DOES\*(C'\fR.
.PP
Moo's role system is based on Role::Tiny.
.PP
See also:
Role::Tiny,
Moo::Role.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2012\-2014, 2017 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0