Scalar::Does3pm

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.

"where { BLOCK }"

Syntactic sugar for "make_role". Compatible with the "where" function from Moose::Util::TypeConstraints, so don't worry about conflicts.

Constants

The following constants may be exported for convenience:

"SCALAR"

"ARRAY"

"HASH"

"CODE"

"GLOB"

"REF"

"LVALUE"

"IO"

"VSTRING"

"FORMAT"

"REGEXP"

"BOOLEAN"

"STRING"

"NUMBER"

"SMARTMATCH"

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.

You can import the constants (plus "does") using:

  use Scalar::Does -constants;

The "make_role" and "where" functions can be exported like this:

  use Scalar::Does -make;

Or list specific functions/constants that you wish to import:

  use Scalar::Does qw( does ARRAY HASH STRING NUMBER );

Custom Role Checks

  use Scalar::Does
    custom => { -as => 'does_array', -role => 'ARRAY' },
    custom => { -as => 'does_hash',  -role => 'HASH'  };
  
  does_array($thing);
  does_hash($thing);