.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Test::Specio 3pm"
.TH Test::Specio 3pm "2021-01-31" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Test::Specio \- Test helpers for Specio
.SH "VERSION"
.IX Header "VERSION"
version 0.47
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Test::Specio qw( test_constraint :vars );
\&
\&  test_constraint(
\&      t(\*(AqFoo\*(Aq), {
\&          accept => [ \*(Aqfoo\*(Aq, \*(Aqbar\*(Aq ],
\&          reject => [ 42,    {}, $EMPTY_STRING, $HASH_REF ],
\&      }
\&  );
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This package provides some helper functions and variables for testing Specio
types.
.SH "EXPORTS"
.IX Header "EXPORTS"
This module provides the following exports:
.ie n .SS "test_constraint( $type, $tests, [ $describer ] )"
.el .SS "test_constraint( \f(CW$type\fP, \f(CW$tests\fP, [ \f(CW$describer\fP ] )"
.IX Subsection "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 \f(CW\*(C`accept\*(C'\fR and
\&\f(CW\*(C`reject\*(C'\fR. Each key should contain an arrayref of values which the type accepts
or rejects.
.PP
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 \f(CW\*(C`describe\*(C'\fR sub, but you can provide your own.
.SS "describe($value)"
.IX Subsection "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.
.ie n .SS "builtins_tests( $GLOB, $GLOB_OVERLOAD, $GLOB_OVERLOAD_FH )"
.el .SS "builtins_tests( \f(CW$GLOB\fP, \f(CW$GLOB_OVERLOAD\fP, \f(CW$GLOB_OVERLOAD_FH\fP )"
.IX Subsection "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:
.PP
.Vb 10
\&  {
\&      Bool => {
\&          accept => [
\&              $ZERO,
\&              $ONE,
\&              $BOOL_OVERLOAD_TRUE,
\&              $BOOL_OVERLOAD_FALSE,
\&              ...,
\&          ],
\&          reject => [
\&              $INT,
\&              $NEG_INT,
\&              $NUM,
\&              $NEG_NUM,
\&              ...,
\&              $OBJECT,
\&          ],
\&      },
\&      Maybe => {...},
\&  }
.Ve
.PP
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.
.SS "Variables"
.IX Subsection "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 \f(CW\*(C`:vars\*(C'\fR import tag.
.IP "\(bu" 4
\&\f(CW$ZERO\fR
.IP "\(bu" 4
\&\f(CW$ONE\fR
.IP "\(bu" 4
\&\f(CW$INT\fR
.Sp
An arbitrary positive integer.
.IP "\(bu" 4
\&\f(CW$NEG_INT\fR
.Sp
An arbitrary negative integer.
.IP "\(bu" 4
\&\f(CW$NUM\fR
.Sp
An arbitrary positive non-integer number.
.IP "\(bu" 4
\&\f(CW$NEG_NUM\fR
.Sp
An arbitrary negative non-integer number.
.IP "\(bu" 4
\&\f(CW$EMPTY_STRING\fR
.IP "\(bu" 4
\&\f(CW$STRING\fR
.Sp
An arbitrary non-empty string.
.IP "\(bu" 4
\&\f(CW$NUM_IN_STRING\fR
.Sp
An arbitrary string which contains a number.
.IP "\(bu" 4
\&\f(CW$INT_WITH_NL1\fR
.Sp
An string containing an integer followed by a newline.
.IP "\(bu" 4
\&\f(CW$INT_WITH_NL2\fR
.Sp
An string containing a newline followed by an integer.
.IP "\(bu" 4
\&\f(CW$SCALAR_REF\fR
.IP "\(bu" 4
\&\f(CW$SCALAR_REF_REF\fR
.Sp
A reference containing a reference to a scalar.
.IP "\(bu" 4
\&\f(CW$ARRAY_REF\fR
.IP "\(bu" 4
\&\f(CW$HASH_REF\fR
.IP "\(bu" 4
\&\f(CW$CODE_REF\fR
.IP "\(bu" 4
\&\f(CW$GLOB_REF\fR
.IP "\(bu" 4
\&\f(CW$FH\fR
.Sp
An opened filehandle.
.IP "\(bu" 4
\&\f(CW$FH_OBJECT\fR
.Sp
An opened IO::File object.
.IP "\(bu" 4
\&\f(CW$REGEX\fR
.Sp
A regex created with \f(CW\*(C`qr//\*(C'\fR.
.IP "\(bu" 4
\&\f(CW$REGEX_OBJ\fR
.Sp
A regex created with \f(CW\*(C`qr//\*(C'\fR that was then blessed into class.
.IP "\(bu" 4
\&\f(CW$FAKE_REGEX\fR
.Sp
A non-regex blessed into the \f(CW\*(C`Regexp\*(C'\fR class which Perl uses internally for
\&\f(CW\*(C`qr//\*(C'\fR objects.
.IP "\(bu" 4
\&\f(CW$OBJECT\fR
.Sp
An arbitrary object.
.IP "\(bu" 4
\&\f(CW$UNDEF\fR
.IP "\(bu" 4
\&\f(CW$CLASS_NAME\fR
.Sp
A string containing a loaded package name.
.IP "\(bu" 4
\&\f(CW$BOOL_OVERLOAD_TRUE\fR
.Sp
An object which overloads boolification to return true.
.IP "\(bu" 4
\&\f(CW$BOOL_OVERLOAD_FALSE\fR
.Sp
An object which overloads boolification to return false.
.IP "\(bu" 4
\&\f(CW$STR_OVERLOAD_EMPTY\fR
.Sp
An object which overloads stringification to return an empty string.
.IP "\(bu" 4
\&\f(CW$STR_OVERLOAD_FULL\fR
.Sp
An object which overloads stringification to return a non-empty string.
.IP "\(bu" 4
\&\f(CW$STR_OVERLOAD_CLASS_NAME\fR
.Sp
An object which overloads stringification to return a loaded package name.
.IP "\(bu" 4
\&\f(CW$NUM_OVERLOAD_ZERO\fR
.IP "\(bu" 4
\&\f(CW$NUM_OVERLOAD_ONE\fR
.IP "\(bu" 4
\&\f(CW$NUM_OVERLOAD_NEG\fR
.IP "\(bu" 4
\&\f(CW$NUM_OVERLOAD_DECIMAL\fR
.IP "\(bu" 4
\&\f(CW$NUM_OVERLOAD_NEG_DECIMAL\fR
.IP "\(bu" 4
\&\f(CW$CODE_OVERLOAD\fR
.IP "\(bu" 4
\&\f(CW$SCALAR_OVERLOAD\fR
.Sp
An object which overloads scalar dereferencing to return a non-empty string.
.IP "\(bu" 4
\&\f(CW$ARRAY_OVERLOAD\fR
.Sp
An object which overloads array dereferencing to return a non-empty array.
.IP "\(bu" 4
\&\f(CW$HASH_OVERLOAD\fR
.Sp
An object which overloads hash dereferencing to return a non-empty hash.
.SS "Globs and the _T::GlobOverload package"
.IX Subsection "Globs and the _T::GlobOverload package"
To create a glob you can pass around for tests, use this code:
.PP
.Vb 4
\&  my $GLOB = do {
\&      no warnings \*(Aqonce\*(Aq;
\&      *SOME_GLOB;
\&  };
.Ve
.PP
The \f(CW\*(C`_T::GlobOverload\*(C'\fR package is defined when you load \f(CW\*(C`Test::Specio\*(C'\fR 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.
.PP
You can create such a variable like this:
.PP
.Vb 2
\&  local *FOO;
\&  my $GLOB_OVERLOAD = _T::GlobOverload\->new( \e*FOO );
.Ve
.PP
If you want to create a glob overloading object that returns a filehandle, do
this:
.PP
.Vb 3
\&  local *BAR;
\&  open BAR, \*(Aq<\*(Aq, $^X or die "Could not open $^X for the test";
\&  my $GLOB_OVERLOAD_FH = _T::GlobOverload\->new( \e*BAR );
.Ve
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/Specio/issues>.
.PP
I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for Specio can be found at <https://github.com/houseabsolute/Specio>.
.SH "AUTHOR"
.IX Header "AUTHOR"
Dave Rolsky <autarch@urth.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2012 \- 2021 by Dave Rolsky.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.