SYNOPSIS

DESCRIPTION

It has long been noted that Perl would benefit from a does() built-in. A check that ref($thing) eq 'ARRAY' doesn't allow you to accept an object that uses overloading to provide an array-like interface.

Functions

does($scalar, $role)

Checks if a scalar is capable of performing the given role. The following (case-sensitive) roles are predefined:

SCALAR or ${}

Checks if the scalar can be used as a scalar reference.

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.

ARRAY or @{}

Checks if the scalar can be used as an array reference.

HASH or %{}

Checks if the scalar can be used as a hash reference.

CODE or &{}

Checks if the scalar can be used as a code reference.

GLOB or *{}

Checks if the scalar can be used as a glob reference.

REF

Checks if the scalar can be used as a ref reference (i.e. a reference to another reference).

LVALUE

Checks if the scalar is a reference to a special lvalue (e.g. the result of substr or splice).

IO or <>

Uses IO::Detect to check if the scalar is a filehandle or file-handle-like object.

(The <> check is slightly looser, allowing objects which overload <>, though overloading <> well can be a little tricky.)

VSTRING

Checks if the scalar is a vstring reference.

FORMAT

Checks if the scalar is a format reference.

Regexp or qr

Checks if the scalar can be used as a quoted regular expression.

bool

Checks if the scalar can be used as a boolean. (It's pretty rare for this to not be true.)

""

Checks if the scalar can be used as a string. (It's pretty rare for this to not be true.)

0+

Checks if the scalar can be used as a number. (It's pretty rare for this to not be true.)

Note that this is far looser than looks_like_number from Scalar::Util. For example, an unblessed arrayref can be used as a number (it numifies to its reference address); the string "Hello World" can be used as a number (it numifies to 0).

~~

Checks if the scalar can be used on the right hand side of a smart match.

If the given role is blessed, and provides a check method, then does delegates to that.

Otherwise, if the scalar being tested is blessed, then $scalar->DOES($role) is called, and does returns true if the method call returned true.

If the scalar being tested looks like a Perl class name, then $scalar->DOES($role) is also called, and the string "0E0" is returned for success, which evaluates to 0 in a numeric context but true in a boolean context.

does($role)

Called with a single argument, tests $_. Yes, this works with lexical $_.

given ($object) {
when(does ARRAY) { ... }
when(does HASH) { ... }
}

Note: in Scalar::Does 0.007 and below the single-argument form of does returned a curried coderef. This was changed in Scalar::Does 0.008.

overloads($scalar, $role)

A function overloads (which just checks overloading) is also available.

overloads($role)

Called with a single argument, tests $_. Yes, this works with lexical $_.

Note: in Scalar::Does 0.007 and below the single-argument form of overloads returned a curried coderef. This was changed in Scalar::Does 0.008.

blessed($scalar), reftype($scalar), looks_like_number($scalar)

For convenience, this module can also re-export these functions from Scalar::Util. looks_like_number is generally more useful than does($scalar, q[0+]).

make_role $name, where { BLOCK }

Returns an anonymous role object which can be used as a parameter to does. The block is arbitrary code which should check whether $_[0] does the role.

Constants

Export

By default, only does is exported. This module uses Exporter::Tiny, so functions can be renamed:

use Scalar::Does does => { -as => 'performs_role' };

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 does and overloads will not be left hanging around as methods of your classes. Moose::Object provides a does method, and you should be able to use Scalar::Does without interfering with that.

Relationship to Moose type constraints

Moose::Meta::TypeConstraint objects, plus the constants exported by MooseX::Types libraries all provide a check method, so again, should "just work" with Scalar::Does. Type constraint strings are not supported however.