.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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::Tiny::Manual::UsingWithMoo3 3"
.TH Type::Tiny::Manual::UsingWithMoo3 3 2024-03-13 "perl v5.38.2" "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::Tiny::Manual::UsingWithMoo3 \- alternative use of Type::Tiny with Moo
.SH MANUAL
.IX Header "MANUAL"
.SS "Type Registries"
.IX Subsection "Type Registries"
In all the examples so far, we have imported a collection of type constraints
into each class:
.PP
.Vb 5
\&  package Horse {
\&    use Moo;
\&    use Types::Standard qw( Str ArrayRef HashRef Int Any InstanceOf );
\&    use Types::Common::Numeric qw( PositiveInt );
\&    use Types::Common::String qw( NonEmptyStr );
\&    
\&    has name    => ( is => \*(Aqro\*(Aq, isa => Str );
\&    has father  => ( is => \*(Aqro\*(Aq, isa => InstanceOf["Horse"] );
\&    ...;
\&  }
.Ve
.PP
This creates a bunch of subs in the Horse namespace, one for each type.
We've used namespace::autoclean to clean these up later.
.PP
But it is also possible to avoid pulling all these into the Horse
namespace. Instead we'll use a type registry:
.PP
.Vb 3
\&  package Horse {
\&    use Moo;
\&    use Type::Registry qw( t );
\&    
\&    t\->add_types(\*(Aq\-Standard\*(Aq);
\&    t\->add_types(\*(Aq\-Common::String\*(Aq);
\&    t\->add_types(\*(Aq\-Common::Numeric\*(Aq);
\&    
\&    t\->alias_type(\*(AqInstanceOf["Horse"]\*(Aq => \*(AqHorsey\*(Aq);
\&    
\&    has name     => ( is => \*(Aqro\*(Aq, isa => t(\*(AqStr\*(Aq) );
\&    has father   => ( is => \*(Aqro\*(Aq, isa => t(\*(AqHorsey\*(Aq) );
\&    has mother   => ( is => \*(Aqro\*(Aq, isa => t(\*(AqHorsey\*(Aq) );
\&    has children => ( is => \*(Aqro\*(Aq, isa => t(\*(AqArrayRef[Horsey]\*(Aq) );
\&    ...;
\&  }
.Ve
.PP
You don't even need to import the \f(CWt()\fR function. Types::Registry
can be used in an entirely object-oriented way.
.PP
.Vb 3
\&  package Horse {
\&    use Moo;
\&    use Type::Registry;
\&    
\&    my $reg = Type::Registry\->for_me;
\&    
\&    $reg\->add_types(\*(Aq\-Standard\*(Aq);
\&    $reg\->add_types(\*(Aq\-Common::String\*(Aq);
\&    $reg\->add_types(\*(Aq\-Common::Numeric\*(Aq);
\&    
\&    $reg\->alias_type(\*(AqInstanceOf["Horse"]\*(Aq => \*(AqHorsey\*(Aq);
\&    
\&    has name => ( is => \*(Aqro\*(Aq, isa => $reg\->lookup(\*(AqStr\*(Aq) );
\&    ...;
\&  }
.Ve
.PP
You could create two registries with entirely different definitions for
the same named type.
.PP
.Vb 1
\&  my $dracula = Aristocrat\->new(name => \*(AqDracula\*(Aq);
\&  
\&  package AristocracyTracker {
\&    use Type::Registry;
\&    
\&    my $reg1 = Type::Registry\->new;
\&    $reg1\->add_types(\*(Aq\-Common::Numeric\*(Aq);
\&    $reg1\->alias_type(\*(AqPositiveInt\*(Aq => \*(AqCount\*(Aq);
\&    
\&    my $reg2 = Type::Registry\->new;
\&    $reg2\->add_types(\*(Aq\-Standard\*(Aq);
\&    $reg2\->alias_type(\*(AqInstanceOf["Aristocrat"]\*(Aq => \*(AqCount\*(Aq);
\&    
\&    $reg1\->lookup("Count")\->assert_valid("1");
\&    $reg2\->lookup("Count")\->assert_valid($dracula);
\&  }
.Ve
.PP
Type::Registry uses \f(CW\*(C`AUTOLOAD\*(C'\fR, so things like this work:
.PP
.Vb 1
\&  $reg\->ArrayRef\->of( $reg\->Int );
.Ve
.PP
Although you can create as many registries as you like, Type::Registry will
create a default registry for each package.
.PP
.Vb 3
\&  # Create a new empty registry.
\&  # 
\&  my $reg = Type::Registry\->new;
\&  
\&  # Get the default registry for my package.
\&  # It will be pre\-populated with any types we imported using \`use\`.
\&  #
\&  my $reg = Type::Registry\->for_me;
\&  
\&  # Get the default registry for some other package.
\&  #
\&  my $reg = Type::Registry\->for_class("Horse");
.Ve
.PP
Type registries are a convenient place to store a bunch of types without
polluting your namespace. They are not the same as type libraries though.
Types::Standard, Types::Common::String, and Types::Common::Numeric
are type libraries; packages that export types for others to use. We will
look at how to make one of those later.
.PP
For now, here's the best way to think of the difference:
.IP \(bu 4
Type registry
.Sp
Curate a collection of types for me to use here in this class.
This collection is an implementation detail.
.IP \(bu 4
Type library
.Sp
Export a collection of types to be used across multiple classes.
This collection is part of your API.
.SS "Importing Functions"
.IX Subsection "Importing Functions"
We've seen how, for instance, Types::Standard exports a sub called
\&\f(CW\*(C`Int\*(C'\fR that returns the \fBInt\fR type object.
.PP
.Vb 1
\&  use Types::Standard qw( Int );
\&  
\&  my $type = Int;
\&  $type\->check($value) or die $type\->get_message($value);
.Ve
.PP
Type libraries are also capable of exporting other convenience functions.
.PP
\fR\f(CI\*(C`is_*\*(C'\fR\fI\fR
.IX Subsection "is_*"
.PP
This is a shortcut for checking a value meets a type constraint:
.PP
.Vb 1
\&  use Types::Standard qw( is_Int );
\&  
\&  if ( is_Int $value ) {
\&    ...;
\&  }
.Ve
.PP
Calling \f(CWis_Int($value)\fR will often be marginally faster than
calling \f(CW\*(C`Int\->check($value)\*(C'\fR because it avoids a method call.
(Method calls in Perl end up slower than normal function calls.)
.PP
Using things like \f(CW\*(C`is_ArrayRef\*(C'\fR in your code might be preferable to
\&\f(CW\*(C`ref($value) eq "ARRAY"\*(C'\fR because it's neater, leads to more
consistent type checking, and might even be faster. (Type::Tiny can
be pretty fast; it is sometimes able to export these functions as
XS subs.)
.PP
If checking type constraints like \f(CW\*(C`is_ArrayRef\*(C'\fR or \f(CW\*(C`is_InstanceOf\*(C'\fR,
there's no way to give a parameter. \f(CW\*(C`is_ArrayRef[Int]($value)\*(C'\fR
doesn't work, and neither does \f(CW\*(C`is_ArrayRef(Int, $value)\*(C'\fR nor
\&\f(CW\*(C`is_ArrayRef($value, Int)\*(C'\fR. For some types like \f(CW\*(C`is_InstanceOf\*(C'\fR,
this makes them fairly useless; without being able to give a class
name, it just acts the same as \f(CW\*(C`is_Object\*(C'\fR. See 
"Exporting Parameterized Types" for a solution. Also, check out
isa.
.PP
There also exists a generic \f(CW\*(C`is\*(C'\fR function.
.PP
.Vb 2
\&  use Types::Standard qw( ArrayRef Int );
\&  use Type::Utils qw( is );
\&  
\&  if ( is ArrayRef[Int], \e@numbers ) {
\&    ...;
\&  }
.Ve
.PP
\fR\f(CI\*(C`assert_*\*(C'\fR\fI\fR
.IX Subsection "assert_*"
.PP
While \f(CWis_Int($value)\fR returns a boolean, \f(CWassert_Int($value)\fR
will throw an error if the value does not meet the constraint, and return
the value otherwise. So you can do:
.PP
.Vb 1
\&  my $sum = assert_Int($x) + assert_Int($y);
.Ve
.PP
And you will get the sum of integers \f(CW$x\fR and \f(CW$y\fR, and an explosion
if either of them is not an integer!
.PP
Assert is useful for quick parameter checks if you are avoiding
Type::Params for some strange reason:
.PP
.Vb 5
\&  sub add_numbers {
\&    my $x = assert_Num(shift);
\&    my $y = assert_Num(shift);
\&    return $x + $y;
\&  }
.Ve
.PP
You can also use a generic \f(CW\*(C`assert\*(C'\fR function.
.PP
.Vb 1
\&  use Type::Utils qw( assert );
\&  
\&  sub add_numbers {
\&    my $x = assert Num, shift;
\&    my $y = assert Num, shift;
\&    return $x + $y;
\&  }
.Ve
.PP
\fR\f(CI\*(C`to_*\*(C'\fR\fI\fR
.IX Subsection "to_*"
.PP
This is a shortcut for coercion:
.PP
.Vb 1
\&  my $truthy = to_Bool($value);
.Ve
.PP
It trusts that the coercion has worked okay. You can combine it with an
assertion if you want to make sure.
.PP
.Vb 1
\&  my $truthy = assert_Bool(to_Bool($value));
.Ve
.PP
\fIShortcuts for exporting functions\fR
.IX Subsection "Shortcuts for exporting functions"
.PP
This is a little verbose:
.PP
.Vb 1
\&  use Types::Standard qw( Bool is_Bool assert_Bool to_Bool );
.Ve
.PP
Isn't this a little bit nicer?
.PP
.Vb 1
\&  use Types::Standard qw( +Bool );
.Ve
.PP
The plus sign tells a type library to export not only the type itself,
but all of the convenience functions too.
.PP
You can also use:
.PP
.Vb 5
\&  use Types::Standard \-types;   # export Int, Bool, etc
\&  use Types::Standard \-is;      # export is_Int, is_Bool, etc
\&  use Types::Standard \-assert;  # export assert_Int, assert_Bool, etc
\&  use Types::Standard \-to;      # export to_Bool, etc
\&  use Types::Standard \-all;     # just export everything!!!
.Ve
.PP
So if you imagine the functions exported by Types::Standard are like this:
.PP
.Vb 8
\&  qw(
\&    Str             is_Str          assert_Str
\&    Num             is_Num          assert_Num
\&    Int             is_Int          assert_Int
\&    Bool            is_Bool         assert_Bool     to_Bool
\&    ArrayRef        is_ArrayRef     assert_ArrayRef
\&  );
\&  # ... and more
.Ve
.PP
Then "+" exports a horizonal group of those, and "\-" exports a vertical group.
.SS "Exporting Parameterized Types"
.IX Subsection "Exporting Parameterized Types"
It's possible to export parameterizable types like \fBArrayRef\fR, but
it is also possible to export \fIparameterized\fR types.
.PP
.Vb 4
\&  use Types::Standard qw( ArrayRef Int );
\&  use Types::Standard (
\&    \*(Aq+ArrayRef\*(Aq => { of => Int, \-as => \*(AqIntList\*(Aq },
\&  );
\&  
\&  has numbers => (is => \*(Aqro\*(Aq, isa => IntList);
.Ve
.PP
Using \f(CWis_IntList($value)\fR should be significantly faster than
\&\f(CW\*(C`ArrayRef\->of(Int)\->check($value)\*(C'\fR.
.PP
This trick only works for parameterized types that have a single
parameter, like \fBArrayRef\fR, \fBHashRef\fR, \fBInstanceOf\fR, etc.
(Sorry, \f(CW\*(C`Dict\*(C'\fR and \f(CW\*(C`Tuple\*(C'\fR!)
.SS "Lexical imports"
.IX Subsection "Lexical imports"
Type::Tiny 2.0 combined with Perl 5.37.2+ allows lexically scoped imports.
So:
.PP
.Vb 4
\&  my $is_ok = do {
\&    use Types::Standard \-lexical, qw( Str ArrayRef );
\&    ArrayRef\->of( Str )\->check( \e@things );
\&  };
\&  
\&  # The Str and ArrayRef types aren\*(Aqt defined here.
.Ve
.SS "Do What I Mean!"
.IX Subsection "Do What I Mean!"
.Vb 1
\&  use Type::Utils qw( dwim_type );
\&  
\&  dwim_type("ArrayRef[Int]")
.Ve
.PP
\&\f(CW\*(C`dwim_type\*(C'\fR will look up a type constraint from a string and attempt to
guess what you meant.
.PP
If it's a type constraint that you seem to have imported with \f(CW\*(C`use\*(C'\fR, then
it should find it. Otherwise, if you're using Moose or Mouse, it'll try
asking those. Or if it's in Types::Standard, it'll look there. And if it
still has no idea, then it will assume dwim_type("Foo") means
dwim_type("InstanceOf['Foo']").
.PP
It just does a big old bunch of guessing.
.PP
The \f(CW\*(C`is\*(C'\fR function will use \f(CW\*(C`dwim_type\*(C'\fR if you pass it a string as a type.
.PP
.Vb 1
\&  use Type::Utils qw( is );
\&  
\&  if ( is "ArrayRef[Int]", \e@numbers ) {
\&    ...;
\&  }
.Ve
.SS Types::Common
.IX Subsection "Types::Common"
Notice that in a lot of examples we're importing one or two functions
each from a few different modules:
.PP
.Vb 4
\&  use Types::Common::Numeric qw( PositiveInt );
\&  use Types::Common::String qw( NonEmptyStr );
\&  use Types::Standard qw( ArrayRef Slurpy );
\&  use Type::Params qw( signature );
.Ve
.PP
A module called Types::Common exists which acts as a single place you
can use for importing most of Type::Tiny's commonly used types and functions.
.PP
.Vb 4
\&  use Types::Common qw(
\&    PositiveInt NonEmptyStr ArrayRef Slurpy
\&    signature
\&  );
.Ve
.PP
Types::Common provides:
.IP \(bu 4
All the types from Types::Standard.
.IP \(bu 4
All the types from Types::Common::Numeric and Types::Common::String.
.IP \(bu 4
All the types from Types::TypeTiny.
.IP \(bu 4
The \f(CW\*(C`\-sigs\*(C'\fR tag from Type::Params.
.IP \(bu 4
The \f(CWt()\fR function from Type::Registry.
.SH "NEXT STEPS"
.IX Header "NEXT STEPS"
You now know pretty much everything there is to know about how to use
type libraries.
.PP
Here's your next step:
.IP \(bu 4
Type::Tiny::Manual::Libraries
.Sp
Defining your own type libraries, including extending existing
libraries, defining new types, adding coercions, defining
parameterizable types, and the declarative style.
.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"
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED
WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE.