1=head1 NAME 2 3Params::Classify - argument type classification 4 5=head1 SYNOPSIS 6 7 use Params::Classify qw( 8 scalar_class 9 is_undef check_undef 10 is_string check_string 11 is_number check_number 12 is_glob check_glob 13 is_regexp check_regexp 14 is_ref check_ref ref_type 15 is_blessed check_blessed blessed_class 16 is_strictly_blessed check_strictly_blessed 17 is_able check_able); 18 19 $c = scalar_class($arg); 20 21 if(is_undef($arg)) { 22 check_undef($arg); 23 24 if(is_string($arg)) { 25 check_string($arg); 26 if(is_number($arg)) { 27 check_number($arg); 28 29 if(is_glob($arg)) { 30 check_glob($arg); 31 if(is_regexp($arg)) { 32 check_regexp($arg); 33 34 if(is_ref($arg)) { 35 check_ref($arg); 36 $t = ref_type($arg); 37 if(is_ref($arg, "HASH")) { 38 check_ref($arg, "HASH"); 39 40 if(is_blessed($arg)) { 41 check_blessed($arg); 42 if(is_blessed($arg, "IO::Handle")) { 43 check_blessed($arg, "IO::Handle"); 44 $c = blessed_class($arg); 45 if(is_strictly_blessed($arg, "IO::Pipe::End")) { 46 check_strictly_blessed($arg, "IO::Pipe::End"); 47 if(is_able($arg, ["print", "flush"])) { 48 check_able($arg, ["print", "flush"]); 49 50=head1 DESCRIPTION 51 52This module provides various type-testing functions. These are intended 53for functions that, unlike most Perl code, care what type of data they 54are operating on. For example, some functions wish to behave differently 55depending on the type of their arguments (like overloaded functions 56in C++). 57 58There are two flavours of function in this module. Functions of the first 59flavour only provide type classification, to allow code to discriminate 60between argument types. Functions of the second flavour package up the 61most common type of type discrimination: checking that an argument is 62of an expected type. The functions come in matched pairs, of the two 63flavours, and so the type enforcement functions handle only the simplest 64requirements for arguments of the types handled by the classification 65functions. Enforcement of more complex types may, of course, be built 66using the classification functions, or it may be more convenient to use 67a module designed for the more complex job, such as L<Params::Validate>. 68 69This module is implemented in XS, with a pure Perl backup version for 70systems that can't handle XS. 71 72=cut 73 74package Params::Classify; 75 76{ use 5.006001; } 77use warnings; 78use strict; 79 80our $VERSION = "0.015"; 81 82use parent "Exporter"; 83our @EXPORT_OK = qw( 84 scalar_class 85 is_undef check_undef 86 is_string check_string 87 is_number check_number 88 is_glob check_glob 89 is_regexp check_regexp 90 is_ref check_ref ref_type 91 is_blessed check_blessed blessed_class 92 is_strictly_blessed check_strictly_blessed 93 is_able check_able 94); 95 96eval { local $SIG{__DIE__}; 97 require Devel::CallChecker; 98 Devel::CallChecker->VERSION(0.003); 99}; 100eval { local $SIG{__DIE__}; 101 require XSLoader; 102 XSLoader::load(__PACKAGE__, $VERSION); 103}; 104 105if($@ eq "") { 106 close(DATA); 107} else { 108 (my $filename = __FILE__) =~ tr# -~##cd; 109 local $/ = undef; 110 my $pp_code = "#line 137 \"$filename\"\n".<DATA>; 111 close(DATA); 112 { 113 local $SIG{__DIE__}; 114 eval $pp_code; 115 } 116 die $@ if $@ ne ""; 117} 118 119sub is_string($); 120sub is_number($) { 121 return 0 unless &is_string; 122 my $warned; 123 local $SIG{__WARN__} = sub { $warned = 1; }; 124 my $arg = $_[0]; 125 { no warnings "void"; 0 + $arg; } 126 return !$warned; 127} 128 129sub check_number($) { 130 die "argument is not a number\n" unless &is_number; 131} 132 1331; 134 135__DATA__ 136 137use Scalar::Util 1.01 qw(blessed reftype); 138 139=head1 TYPE CLASSIFICATION 140 141This module divides up scalar values into the following classes: 142 143=over 144 145=item * 146 147undef 148 149=item * 150 151string (defined ordinary scalar) 152 153=item * 154 155typeglob (yes, typeglobs fit into scalar variables) 156 157=item * 158 159regexp (first-class regular expression objects in Perl 5.11 onwards) 160 161=item * 162 163reference to unblessed object (further classified by physical data type 164of the referenced object) 165 166=item * 167 168reference to blessed object (further classified by class blessed into) 169 170=back 171 172These classes are mutually exclusive and should be exhaustive. This 173classification has been chosen as the most useful when one wishes to 174discriminate between types of scalar. Other classifications are possible. 175(For example, the two reference classes are distinguished by a feature of 176the referenced object; Perl does not internally treat this as a feature 177of the reference.) 178 179=head1 FUNCTIONS 180 181Each of these functions takes one scalar argument (I<ARG>) to be tested, 182possibly with other arguments specifying details of the test. Any scalar 183value is acceptable for the argument to be tested. Each C<is_> function 184returns a simple truth value result, which is true iff I<ARG> is of the 185type being checked for. Each C<check_> function will return normally 186if the argument is of the type being checked for, or will C<die> if it 187is not. 188 189=head2 Classification 190 191=over 192 193=item scalar_class(ARG) 194 195Determines which of the five classes described above I<ARG> falls into. 196Returns "B<UNDEF>", "B<STRING>", "B<GLOB>", "B<REGEXP>", "B<REF>", or 197"B<BLESSED>" accordingly. 198 199=cut 200 201sub scalar_class($) { 202 my $type = reftype(\$_[0]); 203 if($type eq "SCALAR") { 204 $type = defined($_[0]) ? "STRING" : "UNDEF"; 205 } elsif($type eq "REF") { 206 $type = "BLESSED" if defined(blessed($_[0])); 207 } 208 $type; 209} 210 211=back 212 213=head2 The Undefined Value 214 215=over 216 217=item is_undef(ARG) 218 219=item check_undef(ARG) 220 221Check whether I<ARG> is C<undef>. C<is_undef(ARG)> is precisely 222equivalent to C<!defined(ARG)>, and is included for completeness. 223 224=cut 225 226sub is_undef($) { !defined($_[0]) } 227 228sub check_undef($) { 229 die "argument is not undefined\n" unless &is_undef; 230} 231 232=back 233 234=head2 Strings 235 236=over 237 238=item is_string(ARG) 239 240=item check_string(ARG) 241 242Check whether I<ARG> is defined and is an ordinary scalar value (not a 243reference, typeglob, or regexp). This is what one usually thinks of as a 244string in Perl. In fact, any scalar (including C<undef> and references) 245can be coerced to a string, but if you're trying to classify a scalar 246then you don't want to do that. 247 248=cut 249 250sub is_string($) { defined($_[0]) && reftype(\$_[0]) eq "SCALAR" } 251 252sub check_string($) { 253 die "argument is not a string\n" unless &is_string; 254} 255 256=item is_number(ARG) 257 258=item check_number(ARG) 259 260Check whether I<ARG> is defined and an ordinary scalar (i.e., 261satisfies L</is_string> above) and is an acceptable number to Perl. 262This is what one usually thinks of as a number. 263 264Note that simple (L</is_string>-satisfying) scalars may have independent 265numeric and string values, despite the usual pretence that they have 266only one value. Such a scalar is deemed to be a number if I<either> it 267already has a numeric value (e.g., was generated by a numeric literal 268or an arithmetic computation) I<or> its string value has acceptable 269syntax for a number (so it can be converted). Where a scalar has 270separate numeric and string values (see L<Scalar::Util/dualvar>), it is 271possible for it to have an acceptable numeric value while its string 272value does I<not> have acceptable numeric syntax. Be careful to use 273such a value only in a numeric context, if you are using it as a number. 274L<Scalar::Number/scalar_num_part> extracts the numeric part of a 275scalar as an ordinary number. (C<0+ARG> suffices for that unless you 276need to preserve floating point signed zeroes.) 277 278A number may be either a native integer or a native floating point 279value, and there are several subtypes of floating point value. 280For classification, and other handling of numbers in scalars, see 281L<Scalar::Number>. For details of the two numeric data types, see 282L<Data::Integer> and L<Data::Float>. 283 284This function differs from C<looks_like_number> (see 285L<Scalar::Util/looks_like_number>; also L<perlapi/looks_like_number> 286for a lower-level description) in excluding C<undef>, typeglobs, 287and references. Why C<looks_like_number> returns true for C<undef> 288or typeglobs is anybody's guess. References, if treated as numbers, 289evaluate to the address in memory that they reference; this is useful 290for comparing references for equality, but it is not otherwise useful 291to treat references as numbers. Blessed references may have overloaded 292numeric operators, but if so then they don't necessarily behave like 293ordinary numbers. C<looks_like_number> is also confused by dualvars: 294it looks at the string portion of the scalar. 295 296=back 297 298=head2 Typeglobs 299 300=over 301 302=item is_glob(ARG) 303 304=item check_glob(ARG) 305 306Check whether I<ARG> is a typeglob. 307 308=cut 309 310sub is_glob($) { reftype(\$_[0]) eq "GLOB" } 311 312sub check_glob($) { 313 die "argument is not a typeglob\n" unless &is_glob; 314} 315 316=back 317 318=head2 Regexps 319 320=over 321 322=item is_regexp(ARG) 323 324=item check_regexp(ARG) 325 326Check whether I<ARG> is a regexp object. 327 328=cut 329 330sub is_regexp($) { reftype(\$_[0]) eq "REGEXP" } 331 332sub check_regexp($) { 333 die "argument is not a regexp\n" unless &is_regexp; 334} 335 336=back 337 338=head2 References to Unblessed Objects 339 340=over 341 342=item is_ref(ARG) 343 344=item check_ref(ARG) 345 346Check whether I<ARG> is a reference to an unblessed object. If it 347is, then the referenced data type can be determined using C<ref_type> 348(see below), which will return a string such as "HASH" or "SCALAR". 349 350=item ref_type(ARG) 351 352Returns C<undef> if I<ARG> is not a reference to an unblessed object. 353Otherwise, determines what type of object is referenced. Returns 354"B<SCALAR>", "B<ARRAY>", "B<HASH>", "B<CODE>", "B<FORMAT>", or "B<IO>" 355accordingly. 356 357Note that, unlike C<ref>, this does not distinguish between different 358types of referenced scalar. A reference to a string and a reference to 359a reference will both return "B<SCALAR>". Consequently, what C<ref_type> 360returns for a particular reference will not change due to changes in 361the value of the referent, except for the referent being blessed. 362 363=item is_ref(ARG, TYPE) 364 365=item check_ref(ARG, TYPE) 366 367Check whether I<ARG> is a reference to an unblessed object of type 368I<TYPE>, as determined by L</ref_type>. I<TYPE> must be a string. 369Possible I<TYPE>s are "B<SCALAR>", "B<ARRAY>", "B<HASH>", "B<CODE>", 370"B<FORMAT>", and "B<IO>". 371 372=cut 373 374{ 375 my %xlate_reftype = ( 376 REF => "SCALAR", 377 SCALAR => "SCALAR", 378 LVALUE => "SCALAR", 379 GLOB => "SCALAR", 380 REGEXP => "SCALAR", 381 ARRAY => "ARRAY", 382 HASH => "HASH", 383 CODE => "CODE", 384 FORMAT => "FORMAT", 385 IO => "IO", 386 ); 387 388 my %reftype_ok = map { ($_ => undef) } qw( 389 SCALAR ARRAY HASH CODE FORMAT IO 390 ); 391 392 sub ref_type($) { 393 my $reftype = &reftype; 394 return undef unless 395 defined($reftype) && !defined(blessed($_[0])); 396 my $xlated_reftype = $xlate_reftype{$reftype}; 397 die "unknown reftype `$reftype', please update Params::Classify" 398 unless defined $xlated_reftype; 399 $xlated_reftype; 400 } 401 402 sub is_ref($;$) { 403 if(@_ == 2) { 404 die "reference type argument is not a string\n" 405 unless is_string($_[1]); 406 die "invalid reference type\n" 407 unless exists $reftype_ok{$_[1]}; 408 } 409 my $reftype = reftype($_[0]); 410 return undef unless 411 defined($reftype) && !defined(blessed($_[0])); 412 return 1 if @_ != 2; 413 my $xlated_reftype = $xlate_reftype{$reftype}; 414 die "unknown reftype `$reftype', please update Params::Classify" 415 unless defined $xlated_reftype; 416 return $xlated_reftype eq $_[1]; 417 } 418} 419 420sub check_ref($;$) { 421 unless(&is_ref) { 422 die "argument is not a reference to plain ". 423 (@_ == 2 ? lc($_[1]) : "object")."\n"; 424 } 425} 426 427=back 428 429=head2 References to Blessed Objects 430 431=over 432 433=item is_blessed(ARG) 434 435=item check_blessed(ARG) 436 437Check whether I<ARG> is a reference to a blessed object. If it is, 438then the class into which the object was blessed can be determined using 439L</blessed_class>. 440 441=item is_blessed(ARG, CLASS) 442 443=item check_blessed(ARG, CLASS) 444 445Check whether I<ARG> is a reference to a blessed object that claims to 446be an instance of I<CLASS> (via its C<isa> method; see L<perlobj/isa>). 447I<CLASS> must be a string, naming a Perl class. 448 449=cut 450 451sub is_blessed($;$) { 452 die "class argument is not a string\n" 453 if @_ == 2 && !is_string($_[1]); 454 return defined(blessed($_[0])) && (@_ != 2 || $_[0]->isa($_[1])); 455} 456 457sub check_blessed($;$) { 458 unless(&is_blessed) { 459 die "argument is not a reference to blessed ". 460 (@_ == 2 ? $_[1] : "object")."\n"; 461 } 462} 463 464=item blessed_class(ARG) 465 466Returns C<undef> if I<ARG> is not a reference to a blessed object. 467Otherwise, returns the class into which the object is blessed. 468 469C<ref> (see L<perlfunc/ref>) gives the same result on references 470to blessed objects, but different results on other types of value. 471C<blessed_class> is actually identical to L<Scalar::Util/blessed>. 472 473=cut 474 475*blessed_class = \&blessed; 476 477=item is_strictly_blessed(ARG) 478 479=item check_strictly_blessed(ARG) 480 481Check whether I<ARG> is a reference to a blessed object, identically 482to L</is_blessed>. This exists only for symmetry; the useful form of 483C<is_strictly_blessed> appears below. 484 485=item is_strictly_blessed(ARG, CLASS) 486 487=item check_strictly_blessed(ARG, CLASS) 488 489Check whether I<ARG> is a reference to an object blessed into I<CLASS> 490exactly. I<CLASS> must be a string, naming a Perl class. Because this 491excludes subclasses, this is rarely what one wants, but there are some 492specialised occasions where it is useful. 493 494=cut 495 496sub is_strictly_blessed($;$) { 497 return &is_blessed unless @_ == 2; 498 die "class argument is not a string\n" unless is_string($_[1]); 499 my $blessed = blessed($_[0]); 500 return defined($blessed) && $blessed eq $_[1]; 501} 502 503sub check_strictly_blessed($;$) { 504 return &check_blessed unless @_ == 2; 505 unless(&is_strictly_blessed) { 506 die "argument is not a reference to strictly blessed $_[1]\n"; 507 } 508} 509 510=item is_able(ARG) 511 512=item check_able(ARG) 513 514Check whether I<ARG> is a reference to a blessed object, identically 515to L</is_blessed>. This exists only for symmetry; the useful form of 516C<is_able> appears below. 517 518=item is_able(ARG, METHODS) 519 520=item check_able(ARG, METHODS) 521 522Check whether I<ARG> is a reference to a blessed object that claims to 523implement the methods specified by I<METHODS> (via its C<can> method; 524see L<perlobj/can>). I<METHODS> must be either a single method name or 525a reference to an array of method names. Each method name is a string. 526This interface check is often more appropriate than a direct ancestry 527check (such as L</is_blessed> performs). 528 529=cut 530 531sub _check_methods_arg($) { 532 return if &is_string; 533 die "methods argument is not a string or array\n" 534 unless is_ref($_[0], "ARRAY"); 535 foreach(@{$_[0]}) { 536 die "method name is not a string\n" unless is_string($_); 537 } 538} 539 540sub is_able($;$) { 541 return &is_blessed unless @_ == 2; 542 _check_methods_arg($_[1]); 543 return 0 unless defined blessed $_[0]; 544 foreach my $method (ref($_[1]) eq "" ? $_[1] : @{$_[1]}) { 545 return 0 unless $_[0]->can($method); 546 } 547 return 1; 548} 549 550sub check_able($;$) { 551 return &check_blessed unless @_ == 2; 552 _check_methods_arg($_[1]); 553 unless(defined blessed $_[0]) { 554 my $desc = ref($_[1]) eq "" ? 555 "method \"$_[1]\"" 556 : @{$_[1]} == 0 ? 557 "at all" 558 : 559 "method \"".$_[1]->[0]."\""; 560 die "argument is not able to perform $desc\n"; 561 } 562 foreach my $method (ref($_[1]) eq "" ? $_[1] : @{$_[1]}) { 563 die "argument is not able to perform method \"$method\"\n" 564 unless $_[0]->can($method); 565 } 566} 567 568=back 569 570=head1 BUGS 571 572Probably ought to handle something like L<Params::Validate>'s scalar 573type specification system, which makes much the same distinctions. 574 575=head1 SEE ALSO 576 577L<Data::Float>, 578L<Data::Integer>, 579L<Params::Validate>, 580L<Scalar::Number>, 581L<Scalar::Util> 582 583=head1 AUTHOR 584 585Andrew Main (Zefram) <zefram@fysh.org> 586 587=head1 COPYRIGHT 588 589Copyright (C) 2004, 2006, 2007, 2009, 2010, 2017 590Andrew Main (Zefram) <zefram@fysh.org> 591 592Copyright (C) 2009, 2010 PhotoBox Ltd 593 594=head1 LICENSE 595 596This module is free software; you can redistribute it and/or modify it 597under the same terms as Perl itself. 598 599=cut 600 6011; 602