/ 
Scalar-Classify-0.02
River stage one • 2 direct dependents • 2 total dependents
/ Scalar::Classify

NAME

Scalar::Classify - get type and class information for scalars

SYNOPSIS

 use Scalar::Classify qw( classify classify_pair );

 # determine the type (e.g. HASH for a hashref) and the object class (if any)
 my ( $type, $class ) = classify( $some_scalar );


# warn if two args differ, supply default if one is undef
my $default_value =
  classify_pair( $arg1, $arg2 );

# Also get type and class; error out if two args differ
my ( $default_value, $type, $class ) =
  classify_pair( $arg1, $arg2, { mismatch_policy => 'error' });

# If a given ref was undef, replace it with a default value
classify_pair( $arg1, $arg2, { also_qualify => 1 });

DESCRIPTION

Scalar::Classify provides a routine named "classify" that can be used to examine a given argument to determine it's type and class (if any).

Here "type" means either the return from reftype (, or if it's a scalar, a code indicating whether it's a string or a number, and "class" it the object class, the way a reference has been blessed.

This module also provides the routine "classify_pair", which looks at a pair of variables intended to be of the same type, and if at least one of them is defined, uses that to get an appropriate default value for that type.

MOTIVATION

Perl contains a built-in "ref" function, and has some useful routines in the standard Scalar::Util library ('ref', 'looks_like_number') which can be used to examine the type of an argument. The classify routine provided here internally uses all three of these, returning a two-values that describe the kind of thing you're examining.

The immediate goal was to provide support routines for the Data::Math project.

EXPORT

None by default. Optionally:

classify

Example usage:

my ( $type, $class ) = classify( $some_var );

Returns two pieces of information, the underlying "type", and the "class" (if this is a reference blessed into a class).

The type is most often (but not limited to) one of the following:

ARRAY
HASH
:NUMBER:
:STRING:

Other possibilities are the other potential returns from ref:

CODE
GLOB
LVALUE
FORMAT
IO
VSTRING
Regexp

Internally, this uses the built-in function ref and the library functions reftype and looks_like_number (from Scalar::Util). The type is the return from "reftype" (e.g "ARRAY", "HASH") except that in the case of a simple scalar the type is a code to indicate whether it seems to be a number (":NUMBER:") or a string (":STRING:").

Note: if the argument is undefined, the returned type is undef.

classify_pair

Examines a pair of arguments that are intended to be processed in parallel and are expected to be of the same type:

If they're both defined, it checks that their types match. If at least one is defined, it generates a default of the same type by using the classify method. If both are undef, this default is also undef.

In scalar context, it returns just the default value.

In list context, it returns the default plus the type and the class (if it's a blessed reference).

An options hashref is accepted as a third argument, with allowed options:

o  mismatch_policy

   If argument types mismatch, the behavior is determined by
   the mismatch_policy option, defaulting to 'warn'.
   The other allowed values are 'error' or 'silent'.

o  also_qualify

   If the "also_qualify" option is set to a true value, then
   the given arguments may be modified in place: if one is
   undef, it will be assigned the determined default.

Examples:

my $default_value =
  classify_pair( $arg1, $arg2, { mismatch_policy => 'error' });

my ( $default_value, $type, $class ) =
  classify_pair( $arg1, $arg2, { mismatch_policy => 'error' });

classify_pair( $arg1, $arg2, { also_qualify => 1 });

Note the slightly unusual polymorphic behavior: in scalar context returns *just* the default_value, in list context, returns up to three values, the default, the type and the class.

SEE ALSO

Params::Classify

This covers the argument checking case, where you want to verify that something of the correct type was passed. The perl5-porters are interested in adding core support for this module: it's fast and likely to get faster.

AUTHOR

Joseph Brenner, <doom@kzsu.stanford.edu>

COPYRIGHT AND LICENSE

Copyright (C) 2016 by Joseph Brenner

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://dev.perl.org/licenses/ for more information.