phpman > perldoc > Test::Specio(3pm)

NAME
    Test::Specio - Test helpers for Specio

VERSION
    version 0.47

SYNOPSIS
      use Test::Specio qw( test_constraint :vars );

      test_constraint(
          t('Foo'), {
              accept => [ 'foo', 'bar' ],
              reject => [ 42,    {}, $EMPTY_STRING, $HASH_REF ],
          }
      );

DESCRIPTION
    This package provides some helper functions and variables for testing Specio types.

EXPORTS
    This module provides the following exports:

  test_constraint( $type, $tests, [ $describer ] )
    This subroutine accepts two arguments. The first should be a Specio type object. The second is
    hashref which can contain the keys "accept" and "reject". Each key should contain an arrayref of
    values which the type accepts or rejects.

    The third argument is optional. This is a sub reference which will be called to generate a
    description of the value being tested. This defaults to calling this package's "describe" sub,
    but you can provide your own.

  describe($value)
    Given a value, this subroutine returns a string describing that value in a useful way for test
    output. It know about the various classes used for the variables exported by this package and
    will do something intelligent when such a variable.

  builtins_tests( $GLOB, $GLOB_OVERLOAD, $GLOB_OVERLOAD_FH )
    This subroutine returns a hashref containing test variables for all builtin types. The hashref
    has a form like this:

      {
          Bool => {
              accept => [
                  $ZERO,
                  $ONE,
                  $BOOL_OVERLOAD_TRUE,
                  $BOOL_OVERLOAD_FALSE,
                  ...,
              ],
              reject => [
                  $INT,
                  $NEG_INT,
                  $NUM,
                  $NEG_NUM,
                  ...,
                  $OBJECT,
              ],
          },
          Maybe => {...},
      }

    You need to pass in a glob, an object which overloads globification, and an object which
    overloads globification to return an open filehandle. See below for more details on how to
    create these things.

  Variables
    This module also exports many variables containing values which are useful for testing
    constraints. Note that references are always empty unless stated otherwise. You can import these
    variables individually or import all of them with the ":vars" import tag.

    *   $ZERO

    *   $ONE

    *   $INT

        An arbitrary positive integer.

    *   $NEG_INT

        An arbitrary negative integer.

    *   $NUM

        An arbitrary positive non-integer number.

    *   $NEG_NUM

        An arbitrary negative non-integer number.

    *   $EMPTY_STRING

    *   $STRING

        An arbitrary non-empty string.

    *   $NUM_IN_STRING

        An arbitrary string which contains a number.

    *   $INT_WITH_NL1

        An string containing an integer followed by a newline.

    *   $INT_WITH_NL2

        An string containing a newline followed by an integer.

    *   $SCALAR_REF

    *   $SCALAR_REF_REF

        A reference containing a reference to a scalar.

    *   $ARRAY_REF

    *   $HASH_REF

    *   $CODE_REF

    *   $GLOB_REF

    *   $FH

        An opened filehandle.

    *   $FH_OBJECT

        An opened IO::File object.

    *   $REGEX

        A regex created with "qr//".

    *   $REGEX_OBJ

        A regex created with "qr//" that was then blessed into class.

    *   $FAKE_REGEX

        A non-regex blessed into the "Regexp" class which Perl uses internally for "qr//" objects.

    *   $OBJECT

        An arbitrary object.

    *   $UNDEF

    *   $CLASS_NAME

        A string containing a loaded package name.

    *   $BOOL_OVERLOAD_TRUE

        An object which overloads boolification to return true.

    *   $BOOL_OVERLOAD_FALSE

        An object which overloads boolification to return false.

    *   $STR_OVERLOAD_EMPTY

        An object which overloads stringification to return an empty string.

    *   $STR_OVERLOAD_FULL

        An object which overloads stringification to return a non-empty string.

    *   $STR_OVERLOAD_CLASS_NAME

        An object which overloads stringification to return a loaded package name.

    *   $NUM_OVERLOAD_ZERO

    *   $NUM_OVERLOAD_ONE

    *   $NUM_OVERLOAD_NEG

    *   $NUM_OVERLOAD_DECIMAL

    *   $NUM_OVERLOAD_NEG_DECIMAL

    *   $CODE_OVERLOAD

    *   $SCALAR_OVERLOAD

        An object which overloads scalar dereferencing to return a non-empty string.

    *   $ARRAY_OVERLOAD

        An object which overloads array dereferencing to return a non-empty array.

    *   $HASH_OVERLOAD

        An object which overloads hash dereferencing to return a non-empty hash.

  Globs and the _T::GlobOverload package
    To create a glob you can pass around for tests, use this code:

      my $GLOB = do {
          no warnings 'once';
          *SOME_GLOB;
      };

    The "_T::GlobOverload" package is defined when you load "Test::Specio" so you can create your
    own glob overloading objects. Such objects cannot be exported because the glob they return does
    not transfer across packages properly.

    You can create such a variable like this:

      local *FOO;
      my $GLOB_OVERLOAD = _T::GlobOverload->new( \*FOO );

    If you want to create a glob overloading object that returns a filehandle, do this:

      local *BAR;
      open BAR, '<', $^X or die "Could not open $^X for the test";
      my $GLOB_OVERLOAD_FH = _T::GlobOverload->new( \*BAR );

SUPPORT
    Bugs may be submitted at <https://github.com/houseabsolute/Specio/issues>.

    I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".

SOURCE
    The source code repository for Specio can be found at <https://github.com/houseabsolute/Specio>.

AUTHOR
    Dave Rolsky <autarch AT urth.org>

COPYRIGHT AND LICENSE
    This software is Copyright (c) 2012 - 2021 by Dave Rolsky.

    This is free software, licensed under:

      The Artistic License 2.0 (GPL Compatible)

    The full text of the license can be found in the LICENSE file included with this distribution.