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, <[email protected]>

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.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.