oracular (3) Test2::Tools::Type.3pm.gz

NAME

       Test2::Tools::Type - Tools for checking data types

SYNOPSIS

           use Test2::V0;
           use Test2::Tools::Type;

           is_integer(1, "is 1 integer?");         # pass, yes it is
           is_integer('1', "is '1' an integer?");  # fail, no it's a string

           SKIP: {
               skip "Your perl is too old" unless(bool_supported());
               is_bool(1 == 2, "is false a Boolean?");   # pass, yes it is
               is_bool(3.1415, "is pi a Boolean?");      # fail, no it isn't
           }

           like
               { should_be_int => 1, other_stuff => "we don't care about this" },
               hash {
                   field should_be_int => type('integer');
               },
               "is the should_be_int field an integer?";

       or if you want even more check functions:

           use Test2::V0;
           use Test2::Tools::Type qw(:extras);

           is_hashref($foo);

OVERVIEW

       Sometimes you don't want to be too precise in your tests, you just want to check that your code returns
       the right type of result but you don't care whether it's returning 192 or 193 - just checking that it
       returns an integer is good enough.

FUNCTIONS

       All these are exported by default.

   bool_supported
       Returns true if your perl is recent enough to have the Boolean type, false otherwise. It will be true if
       your perl is version 5.35.7 or higher.

   is_bool
       Emits a test pass if its argument is a Boolean - ie is the result of a comparison - and a fail otherwise.

       It is a fatal error to call this on a perl that is too old. If your tests need to run on perl 5.35.6 or
       earlier then you will need to check "bool_supported" before using it. See the "SYNOPSIS" above.

   is_integer
       Emits a test pass if its argument is an integer and a fail otherwise. Note that it can tell the
       difference between 1 (an integer) and '1' (a string).

   is_number
       Emits a test pass if its argument is a number and a fail otherwise. Note that it can tell the difference
       between 1 (a number), 1.2 (also a number) and '1' (a string).

   type
       Returns a check that you can use in a test such as:

           like
               { int => 1 },
               hash { field int => type('integer'); },
               "the 'int' field is an integer";

       You can negate the test with a "!" thus. This test will fail:

           like
               { int => 1 },
               hash { field int => !type('integer'); },
               "the 'int' field is an integer";

       You can supply more than one argument, so if you want to check that something is a positive integer, for
       example, you can do:

           is(94, type(qw(positive integer)));

       You can check something's type and value:

           # this uses 'number' from Test2::Tools::Compare
           is($foo, type('integer', number(94)));

       And indeed you can use any other Test2 checker:

           # 'in_set' also comes from Test2::Tools::Compare
           is($foo, type('integer', in_set(1, 5, 8)));

       Valid arguments are any other Test2 checker (specifically, anything that inherits from
       Test2::Compare::Base), and any of the "is_*" methods' names, with the leading "is_" removed. You can see
       a list of supported types thus:

           $ perl -MTest2::Tools::Type=show_types

       or to include the extra functions:

           $ perl -MTest2::Tools::Type=show_types,:extras

EXTRA FUNCTIONS

       By default the only check functions you get are those that are thin wrappers around Scalar::Type. If you
       pass the ":extras" argument at "use"-time then all the following are available as well:

   regex_supported
       Returns true if your perl can reliably report the difference between a regex and a reference to a scalar,
       or false otherwise. It will be true if your perl is version 5.12 or higher.

   is_positive, is_negative
       Emit a test pass/fail depending on the argument's sign. Note that 0 is considered neither positive nor
       negative.

   is_zero
       Emit a pass/fail depending on whether the argument is zero.

   is_ref
       Emit a pass/fail depending on whether the argument is a reference. This includes blessed objects.

   is_object
       Emit a pass/fail depending on whether the argument is a blessed object.

   is_regex
       Emit a test pass if its argument is a regex, and a fail otherwise.

       It is a fatal error to call this on a perl that is too old. If your tests need to run on perl 5.10.1 or
       earlier then you will need to check "regex_supported" before using it.

   is_hashref, is_arrayref, is_scalarref, is_coderef, is_globref, is_regex, is_refref
       Emit a pass/fail if the argumet is a reference to something of the appropriate type.

CAVEATS

       The definitions of Boolean, integer and number are exactly the same as those in Scalar::Type, which this
       is a thin wrapper around.

       Blessed objects will match both "is_object" and the appropriate "is_*ref". If you need to check that
       something is a ref, but is not blessed, do something like:

           is($foo, type(hashref => !type('object')));

SEE ALSO

       Scalar::Type

       Test2

BUGS

       If you find any bugs please report them on Github, preferably with a test case.

FEEDBACK

       I welcome feedback about my code, especially constructive criticism.

AUTHOR, COPYRIGHT and LICENCE

       Copyright 2024 David Cantrell <david@cantrell.org.uk>

       This software is free-as-in-speech software, and may be used, distributed, and modified under the terms
       of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you
       use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.

CONSPIRACY

       This module is also free-as-in-mason software.