.\" -*- 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::UsingWithMoose 3"
.TH Type::Tiny::Manual::UsingWithMoose 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::UsingWithMoose \- how to use Type::Tiny with Moose
.SH MANUAL
.IX Header "MANUAL"
First read Type::Tiny::Manual::Moo, Type::Tiny::Manual::Moo2, and
Type::Tiny::Manual::Moo3. Everything in those parts of the manual
should work exactly the same in Moose.
.PP
This part of the manual will focus on Moose-specifics.
.SS "Why Use Type::Tiny At All?"
.IX Subsection "Why Use Type::Tiny At All?"
Moose does have a built-in type constraint system which is fairly
convenient to use, but there are several reasons you should consider
using Type::Tiny instead.
.IP \(bu 4
Type::Tiny type constraints will usually be faster than Moose built-ins.
Even without Type::Tiny::XS installed, Type::Tiny usually produces more
efficient inline code than Moose. Coercions will usually be a lot faster.
.IP \(bu 4
Type::Tiny provides helpful methods like \f(CW\*(C`where\*(C'\fR and \f(CW\*(C`plus_coercions\*(C'\fR
that allow type constraints and coercions to be easily tweaked on a
per-attribute basis.
.Sp
Something like this is much harder to do with plain Moose types:
.Sp
.Vb 7
\&  has name => (
\&    is      => "ro",
\&    isa     => Str\->plus_coercions(
\&      ArrayRef[Str], sub { join " ", @$_ },
\&    ),
\&    coerce  => 1,
\&  );
.Ve
.Sp
Moose tends to encourage defining coercions globally, so if you wanted
one \fBStr\fR attribute to be able to coerce from \fBArrayRef[Str]\fR, then
\&\fIall\fR \fBStr\fR attributes would coerce from \fBArrayRef[Str]\fR, and they'd
all do that coercion in the same way. (Even if it might make sense to
join by a space in some places, a comma in others, and a line break in
others!)
.IP \(bu 4
Type::Tiny provides automatic deep coercions, so if type \fBXyz\fR has a coercion,
the following should "just work":
.Sp
.Vb 1
\&  has xyzlist => ( is => \*(Aqro\*(Aq, isa => ArrayRef[Xyz], coerce => 1 );
.Ve
.IP \(bu 4
Type::Tiny offers a wider selection of built-in types.
.IP \(bu 4
By using Type::Tiny, you can use the same type constraints and coercions
for attributes and method parameters, in Moose and non-Moose code.
.SS Type::Utils
.IX Subsection "Type::Utils"
If you've used Moose::Util::TypeConstraints, you may be accustomed to
using a DSL for declaring type constraints:
.PP
.Vb 1
\&  use Moose::Util::TypeConstraints;
\&  
\&  subtype \*(AqNatural\*(Aq,
\&    as \*(AqInt\*(Aq,
\&    where { $_ > 0 };
.Ve
.PP
There's a module called Type::Utils that provides a very similar DSL for
declaring types in Type::Library\-based type libraries.
.PP
.Vb 4
\&  package My::Types {
\&    use Type::Library \-base;
\&    use Type::Utils;
\&    use Types::Standard qw( Int );
\&    
\&    declare \*(AqNatural\*(Aq,
\&      as Int,
\&      where { $_ > 0 };
\&  }
.Ve
.PP
Personally I prefer the more object-oriented way to declare types though.
.PP
Since Type::Library 1.012, a shortcut has been available for importing
Type::Library and Type::Utils at the same time:
.PP
.Vb 2
\&  package MyType {
\&    use Type::Library \-base, \-utils;
\&    
\&    ...;
\&  }
.Ve
.PP
In Moose you might also declare types like this within classes and roles too.
Unlike Moose, Type::Tiny doesn't keep types in a single global flat namespace,
so this doesn't work quite the same with Type::Utils. It still creates the
type, but it doesn't store it in any type library; the type is returned.
.PP
.Vb 4
\&  package My::Class {
\&    use Moose;
\&    use Type::Utils;
\&    use Types::Standard qw( Int );
\&    
\&    my $Natural =          # store type in a variable
\&      declare \*(AqNatural\*(Aq,
\&      as Int,
\&      where { $_ > 0 };
\&    
\&    has number => ( is => \*(Aqro\*(Aq, isa => $Natural );
\&  }
.Ve
.PP
But really, isn't the object-oriented way cleaner?
.PP
.Vb 3
\&  package My::Class {
\&    use Moose;
\&    use Types::Standard qw( Int );
\&    
\&    has number => (
\&      is   => \*(Aqro\*(Aq,
\&      isa  => Int\->where(\*(Aq$_ > 0\*(Aq),
\&    );
\&  }
.Ve
.SS "Type::Tiny and MooseX::Types"
.IX Subsection "Type::Tiny and MooseX::Types"
Types::Standard should be a drop-in replacement for MooseX::Types.
And Types::Common::Numeric and Types::Common::String should easily
replace MooseX::Types::Common::Numeric and MooseX::Types::Common::String.
.PP
That said, if you do with to use a mixture of Type::Tiny and MooseX::Types,
they should fit together pretty seamlessly.
.PP
.Vb 2
\&  use Types::Standard qw( ArrayRef );
\&  use MooseX::Types::Common::Numeric qw( PositiveInt );
\&  
\&  # this should just work
\&  my $list_of_nums = ArrayRef[PositiveInt];
\&  
\&  # and this
\&  my $list_or_num = ArrayRef | PositiveInt;
.Ve
.ie n .SS """\-moose"" Import Parameter"
.el .SS "\f(CW\-moose\fP Import Parameter"
.IX Subsection "-moose Import Parameter"
If you have read this far in the manual, you will know that this is the
usual way to import type constraints:
.PP
.Vb 1
\&  use Types::Standard qw( Int );
.Ve
.PP
And the \f(CW\*(C`Int\*(C'\fR which is imported is a function that takes no arguments and
returns the \fBInt\fR type constraint, which is a blessed object in the
Type::Tiny class.
.PP
Type::Tiny mocks the Moose::Meta::TypeConstraint API so well that most
Moose and MooseX code will not be able to tell the difference.
.PP
But what if you need a real Moose::Meta::TypeConstraint object?
.PP
.Vb 1
\&  use Types::Standard \-moose, qw( Int );
.Ve
.PP
Now the \f(CW\*(C`Int\*(C'\fR function imported will return a genuine native Moose type
constraint.
.PP
This flag is mostly a throwback from when Type::Tiny native objects
\&\fIdidn't\fR directly work in Moose. In 99.9% of cases, there is no
reason to use it and plenty of reasons not to. (Moose native type
constraints don't offer helpful methods like \f(CW\*(C`plus_coercions\*(C'\fR and
\&\f(CW\*(C`where\*(C'\fR.)
.ie n .SS """moose_type"" Method"
.el .SS "\f(CWmoose_type\fP Method"
.IX Subsection "moose_type Method"
Another quick way to get a native Moose type constraint object from a
Type::Tiny object is to call the \f(CW\*(C`moose_type\*(C'\fR method:
.PP
.Vb 1
\&  use Types::Standard qw( Int );
\&  
\&  my $tiny_type   = Int;
\&  my $moose_type  = $tiny_type\->moose_type;
.Ve
.PP
Internally, this is what the \f(CW\*(C`\-moose\*(C'\fR flag makes imported functions
do.
.SH "NEXT STEPS"
.IX Header "NEXT STEPS"
Here's your next step:
.IP \(bu 4
Type::Tiny::Manual::UsingWithMouse
.Sp
How to use Type::Tiny with Mouse, including the advantages of Type::Tiny
over built-in type constraints, and Mouse-specific features.
.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.