Test2::Tools::Type(3pm)

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.