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.

cpanm Scalar::Type

perl -MCPAN -e shell
install Scalar::Type