.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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 "Type::Library 3pm"
.TH Type::Library 3pm "2023-07-21" "perl v5.36.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"
Type::Library \- tiny, yet Moo(se)\-compatible type libraries
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 4
\&   package Types::Mine {
\&      use Scalar::Util qw(looks_like_number);
\&      use Type::Library \-base;
\&      use Type::Tiny;
\&      
\&      my $NUM = "Type::Tiny"\->new(
\&         name       => "Number",
\&         constraint => sub { looks_like_number($_) },
\&         message    => sub { "$_ ain\*(Aqt a number" },
\&      );
\&      
\&      _\|_PACKAGE_\|_\->meta\->add_type($NUM);
\&      
\&      _\|_PACKAGE_\|_\->meta\->make_immutable;
\&   }
\&      
\&   package Ermintrude {
\&      use Moo;
\&      use Types::Mine qw(Number);
\&      has favourite_number => (is => "ro", isa => Number);
\&   }
\&   
\&   package Bullwinkle {
\&      use Moose;
\&      use Types::Mine qw(Number);
\&      has favourite_number => (is => "ro", isa => Number);
\&   }
\&   
\&   package Maisy {
\&      use Mouse;
\&      use Types::Mine qw(Number);
\&      has favourite_number => (is => "ro", isa => Number);
\&   }
.Ve
.SH "STATUS"
.IX Header "STATUS"
This module is covered by the
Type-Tiny stability policy.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Type::Library is a tiny class for creating MooseX::Types\-like type
libraries which are compatible with Moo, Moose and Mouse.
.PP
If you're reading this because you want to create a type library, then
you're probably better off reading Type::Tiny::Manual::Libraries.
.SS "Type library methods"
.IX Subsection "Type library methods"
A type library is a singleton class. Use the \f(CW\*(C`meta\*(C'\fR method to get a blessed
object which other methods can get called on. For example:
.PP
.Vb 1
\&   Types::Mine\->meta\->add_type($foo);
.Ve
.ie n .IP """add_type($type)"" or ""add_type(%opts)""" 4
.el .IP "\f(CWadd_type($type)\fR or \f(CWadd_type(%opts)\fR" 4
.IX Item "add_type($type) or add_type(%opts)"
Add a type to the library. If \f(CW%opts\fR is given, then this method calls
\&\f(CW\*(C`Type::Tiny\->new(%opts)\*(C'\fR first, and adds the resultant type.
.Sp
Adding a type named \*(L"Foo\*(R" to the library will automatically define four
functions in the library's namespace:
.RS 4
.ie n .IP """Foo""" 4
.el .IP "\f(CWFoo\fR" 4
.IX Item "Foo"
Returns the Type::Tiny object.
.ie n .IP """is_Foo($value)""" 4
.el .IP "\f(CWis_Foo($value)\fR" 4
.IX Item "is_Foo($value)"
Returns true iff \f(CW$value\fR passes the type constraint.
.ie n .IP """assert_Foo($value)""" 4
.el .IP "\f(CWassert_Foo($value)\fR" 4
.IX Item "assert_Foo($value)"
Returns \f(CW$value\fR iff \f(CW$value\fR passes the type constraint. Dies otherwise.
.ie n .IP """to_Foo($value)""" 4
.el .IP "\f(CWto_Foo($value)\fR" 4
.IX Item "to_Foo($value)"
Coerces the value to the type.
.RE
.RS 4
.RE
.ie n .IP """get_type($name)""" 4
.el .IP "\f(CWget_type($name)\fR" 4
.IX Item "get_type($name)"
Gets the \f(CW\*(C`Type::Tiny\*(C'\fR object corresponding to the name.
.ie n .IP """has_type($name)""" 4
.el .IP "\f(CWhas_type($name)\fR" 4
.IX Item "has_type($name)"
Boolean; returns true if the type exists in the library.
.ie n .IP """type_names""" 4
.el .IP "\f(CWtype_names\fR" 4
.IX Item "type_names"
List all types defined by the library.
.ie n .IP """add_coercion($c)"" or ""add_coercion(%opts)""" 4
.el .IP "\f(CWadd_coercion($c)\fR or \f(CWadd_coercion(%opts)\fR" 4
.IX Item "add_coercion($c) or add_coercion(%opts)"
Add a standalone coercion to the library. If \f(CW%opts\fR is given, then
this method calls \f(CW\*(C`Type::Coercion\->new(%opts)\*(C'\fR first, and adds the
resultant coercion.
.Sp
Adding a coercion named \*(L"FooFromBar\*(R" to the library will automatically
define a function in the library's namespace:
.RS 4
.ie n .IP """FooFromBar""" 4
.el .IP "\f(CWFooFromBar\fR" 4
.IX Item "FooFromBar"
Returns the Type::Coercion object.
.RE
.RS 4
.RE
.ie n .IP """get_coercion($name)""" 4
.el .IP "\f(CWget_coercion($name)\fR" 4
.IX Item "get_coercion($name)"
Gets the \f(CW\*(C`Type::Coercion\*(C'\fR object corresponding to the name.
.ie n .IP """has_coercion($name)""" 4
.el .IP "\f(CWhas_coercion($name)\fR" 4
.IX Item "has_coercion($name)"
Boolean; returns true if the coercion exists in the library.
.ie n .IP """coercion_names""" 4
.el .IP "\f(CWcoercion_names\fR" 4
.IX Item "coercion_names"
List all standalone coercions defined by the library.
.ie n .IP """import(@args)""" 4
.el .IP "\f(CWimport(@args)\fR" 4
.IX Item "import(@args)"
Type::Library\-based libraries are exporters.
.ie n .IP """make_immutable""" 4
.el .IP "\f(CWmake_immutable\fR" 4
.IX Item "make_immutable"
Prevents new type constraints and coercions from being added to the
library, and also calls \f(CW\*(C`$type\->coercion\->freeze\*(C'\fR on every
type constraint in the library.
.Sp
(Prior to Type::Library v2, \f(CW\*(C`make_immutable\*(C'\fR would call
\&\f(CW\*(C`$type\->coercion\->freeze\*(C'\fR on every constraint in the library,
but not prevent new type constraints and coercions from being added
to the library.)
.SS "Type library exported functions"
.IX Subsection "Type library exported functions"
Type libraries are exporters. For the purposes of the following examples,
assume that the \f(CW\*(C`Types::Mine\*(C'\fR library defines types \f(CW\*(C`Number\*(C'\fR and \f(CW\*(C`String\*(C'\fR.
.PP
.Vb 3
\&   # Exports nothing.
\&   # 
\&   use Types::Mine;
\&   
\&   # Exports a function "String" which is a constant returning
\&   # the String type constraint.
\&   #
\&   use Types::Mine qw( String );
\&   
\&   # Exports both String and Number as above.
\&   #
\&   use Types::Mine qw( String Number );
\&   
\&   # Same.
\&   #
\&   use Types::Mine qw( :types );
\&   
\&   # Exports "coerce_String" and "coerce_Number", as well as any other
\&   # coercions
\&   #
\&   use Types::Mine qw( :coercions );
\&   
\&   # Exports a sub "is_String" so that "is_String($foo)" is equivalent
\&   # to "String\->check($foo)".
\&   #
\&   use Types::Mine qw( is_String );
\&   
\&   # Exports "is_String" and "is_Number".
\&   #
\&   use Types::Mine qw( :is );
\&   
\&   # Exports a sub "assert_String" so that "assert_String($foo)" is
\&   # equivalent to "String\->assert_return($foo)".
\&   #
\&   use Types::Mine qw( assert_String );
\&   
\&   # Exports "assert_String" and "assert_Number".
\&   #
\&   use Types::Mine qw( :assert );
\&   
\&   # Exports a sub "to_String" so that "to_String($foo)" is equivalent
\&   # to "String\->coerce($foo)".
\&   #
\&   use Types::Mine qw( to_String );
\&   
\&   # Exports "to_String" and "to_Number".
\&   #
\&   use Types::Mine qw( :to );
\&   
\&   # Exports "String", "is_String", "assert_String" and "coerce_String".
\&   #
\&   use Types::Mine qw( +String );
\&   
\&   # Exports everything.
\&   #
\&   use Types::Mine qw( :all );
.Ve
.PP
Type libraries automatically inherit from Exporter::Tiny; see the
documentation of that module for tips and tricks importing from libraries.
.SS "Type::Library's methods"
.IX Subsection "Type::Library's methods"
The above sections describe the characteristics of libraries built with
Type::Library. The following methods are available on Type::Library itself.
.ie n .IP """setup_type_library( $package, $utils, \e@extends )""" 4
.el .IP "\f(CWsetup_type_library( $package, $utils, \e@extends )\fR" 4
.IX Item "setup_type_library( $package, $utils, @extends )"
Sets up a package to be a type library. \f(CW$utils\fR is a boolean
indicating whether to import Type::Utils into the package.
\&\f(CW@extends\fR is a list of existing type libraries the package
should extend.
.SH "BUGS"
.IX Header "BUGS"
Please report any bugs to
<https://github.com/tobyink/p5\-type\-tiny/issues>.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Type::Tiny::Manual.
.PP
Type::Tiny, Type::Utils, Types::Standard, Type::Coercion.
.PP
Moose::Util::TypeConstraints,
Mouse::Util::TypeConstraints.
.SH "AUTHOR"
.IX Header "AUTHOR"
Toby Inkster <tobyink@cpan.org>.
.SH "COPYRIGHT AND LICENCE"
.IX Header "COPYRIGHT AND LICENCE"
This software is copyright (c) 2013\-2014, 2017\-2023 by Toby Inkster.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
.SH "DISCLAIMER OF WARRANTIES"
.IX Header "DISCLAIMER OF WARRANTIES"
\&\s-1THIS PACKAGE IS PROVIDED \*(L"AS IS\*(R" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.\s0