Current File : /home/opti/perl/usr/man/man3/Type::Tiny::Manual::Libraries.3pm
.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Type::Tiny::Manual::Libraries 3"
.TH Type::Tiny::Manual::Libraries 3 "2018-07-29" "perl v5.16.3" "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::Libraries \- how to build a type library with Type::Tiny, Type::Library and Type::Utils
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
A type library is a collection of type constraints, optionally with coercions.
.PP
The following is an example type library:
.PP
.Vb 1
\& package Example::Types;
\&
\& use Type::Library
\& \-base,
\& \-declare => qw( Datetime DatetimeHash EpochHash );
\& use Type::Utils \-all;
\& use Types::Standard \-types;
\&
\& class_type Datetime, { class => "DateTime" };
\&
\& declare DatetimeHash,
\& as Dict[
\& year => Int,
\& month => Optional[ Int ],
\& day => Optional[ Int ],
\& hour => Optional[ Int ],
\& minute => Optional[ Int ],
\& second => Optional[ Int ],
\& nanosecond => Optional[ Int ],
\& time_zone => Optional[ Str ],
\& ];
\&
\& declare EpochHash,
\& as Dict[ epoch => Int ];
\&
\& coerce Datetime,
\& from Int, via { "DateTime"\->from_epoch(epoch => $_) },
\& from Undef, via { "DateTime"\->now },
\& from DatetimeHash, via { "DateTime"\->new(%$_) },
\& from EpochHash, via { "DateTime"\->from_epoch(%$_) };
\&
\& 1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Here's a line by line description of what's going on in the type library.
.PP
.Vb 1
\& package Example::Types;
.Ve
.PP
Type libraries are packages. It is recommended that re-usable type libraries
be given a name in the \f(CW\*(C`Types::*\*(C'\fR namespace. For application-specific
type libraries, assuming your application's namespace is \f(CW\*(C`MyApp::*\*(C'\fR then
name the type library \f(CW\*(C`MyApp::Types\*(C'\fR, or if more than one is needed, use
the \f(CW\*(C`MyApp::Types::*\*(C'\fR namespace.
.PP
.Vb 3
\& use Type::Library
\& \-base,
\& \-declare => qw( Datetime DatetimeHash EpochHash );
.Ve
.PP
The \f(CW\*(C`\-base\*(C'\fR part is used to establish inheritance. It makes
\&\f(CW\*(C`Example::Types\*(C'\fR a child class of \f(CW\*(C`Type::Library\*(C'\fR.
.PP
Declaring the types we're going to define ahead of their definition allows
us to use them as barewords later on. (Note that in code which \fIuses\fR
our type library, the types will always be available as barewords. The
declaration above just allows us to use them within the library itself.)
.PP
.Vb 1
\& use Type::Utils \-all;
.Ve
.PP
Imports some utility functions from Type::Utils. These will be useful
for defining our types and the relationships between them.
.PP
.Vb 1
\& use Types::Standard \-types;
.Ve
.PP
Here we import a standard set of type constraints from Types::Standard.
There is no need to do this, but it's often helpful to have a base set of
types which we can define our own in terms of.
.PP
Note that although we've imported the types to be able to use in our library,
we haven't \fIadded\fR the types to our library. We've imported \f(CW\*(C`Str\*(C'\fR, but other
people won't be able to re-import \f(CW\*(C`Str\*(C'\fR from our library. If you actually
want your library to \fIextend\fR another library, do this instead:
.PP
.Vb 1
\& BEGIN { extends "Types::AnotherLibrary" };
.Ve
.PP
(Note: if your code breaks here when you upgrade from version 0.006 or
below, saying that the 'extends' keyword has not been declared, just add
\&'\-all' after use Type::Utils.)
.PP
\&\s-1OK,\s0 now we're ready to declare a few types.
.PP
.Vb 1
\& class_type Datetime, { class => "DateTime" };
.Ve
.PP
This creates a type constraint named \*(L"Datetime\*(R" which is all objects blessed
into the DateTime package. Because this type constraint is not anonymous
(it has a name), it will be automagically installed into the type library.
.PP
The next two statements declare two further types constraints, using type
constraints from the Types::Standard library. Let's look at \f(CW\*(C`EpochHash\*(C'\fR in
more detail. This is a hashref with one key called \*(L"epoch\*(R" and a value which
is an integer.
.PP
.Vb 2
\& declare EpochHash,
\& as Dict[ epoch => Int ];
.Ve
.PP
\&\f(CW\*(C`EpochHash\*(C'\fR inherits from the \f(CW\*(C`Dict\*(C'\fR type defined in Types::Standard. It
equally could have been defined as:
.PP
.Vb 3
\& declare EpochHash,
\& as HashRef[Int],
\& where { scalar(keys(%$_))==1 and exists $_\->{epoch} };
.Ve
.PP
Or even:
.PP
.Vb 6
\& declare EpochHash,
\& where {
\& ref($_) eq "HASH"
\& and scalar(keys(%$_))==1
\& and exists $_\->{epoch}
\& };
.Ve
.PP
Lastly we set up coercions. It's best to define all your types before you
define any coercions.
.PP
.Vb 5
\& coerce Datetime,
\& from Int, via { "DateTime"\->from_epoch(epoch => $_) },
\& from Undef, via { "DateTime"\->now },
\& from DatetimeHash, via { "DateTime"\->new(%$_) },
\& from EpochHash, via { "DateTime"\->from_epoch(%$_) };
.Ve
.PP
These are simply coderefs that will be fired when you want a Datetime,
but are given something else. For more information on coercions, see
Type::Tiny::Manual::Coercions.
.SS "Using Your Library"
.IX Subsection "Using Your Library"
Use a custom types library just like you would Types::Standard:
.PP
.Vb 4
\& package MyClass;
\& use Moose;
\& use DateTime;
\& use Example::Types qw( Datetime ); # import the custom type
\&
\& has \*(Aqsometime\*(Aq => (
\& is => \*(Aqrw\*(Aq,
\& isa => Datetime,
\& coerce => 1,
\& );
.Ve
.PP
Type libraries defined with Type::Library are also able to export
some convenience functions:
.PP
.Vb 1
\& use Example::Types qw( is_Datetime to_Datetime assert_Datetime );
\&
\& my $dt = Foo::get_datetime;
\&
\& unless ( is_Datetime $dt )
\& {
\& $dt = to_Datetime $dt;
\& }
\&
\& assert_Datetime $dt;
.Ve
.PP
These functions act as shortcuts for:
.PP
.Vb 1
\& use Example::Types qw( Datetime );
\&
\& my $dt = Foo::get_datetime;
\&
\& unless ( Datetime\->check($dt) )
\& {
\& $dt = Datetime\->coerce($dt);
\& }
\&
\& Datetime\->assert_return($dt);
.Ve
.PP
Pick whichever style you think is clearer!
.PP
Type::Library\-based libraries provide a shortcut for importing a type
constraint along with all its associated convenience functions:
.PP
.Vb 3
\& # Shortcut for qw( DateTime is_Datetime to_Datetime assert_Datetime )
\& #
\& use Example::Types qw( +Datetime );
.Ve
.PP
See Type::Tiny::Manual for other ways to make use of type libraries.
.SH "ADVANCED TOPICS"
.IX Header "ADVANCED TOPICS"
.SS "Messages"
.IX Subsection "Messages"
It is sometimes nice to be able to emit a more useful error message than
the standard:
.PP
.Vb 1
\& Value "Foo" did not pass type constraint "Bar"
.Ve
.PP
It is possible to define custom error messages for types.
.PP
.Vb 7
\& declare MediumInteger, as Integer,
\& where { $_ >= 10 and $_ < 20 },
\& message {
\& return Integer\->get_message($_) if !Integer\->check($_);
\& return "$_ is too small!" if $_ < 10;
\& return "$_ is so very, very big!";
\& };
.Ve
.SS "Parameterized Constraints"
.IX Subsection "Parameterized Constraints"
Parameterized type constraints are those that can generate simple child type
constraints by passing parameters to their \f(CW\*(C`parameterize\*(C'\fR method. For
example, ArrayRef in Types::Standard:
.PP
.Vb 1
\& use Types::Standard;
\&
\& my $ArrayRef = Types::Standard::ArrayRef;
\& my $Int = Types::Standard::Int;
\& my $ArrayRef_of_Ints = $ArrayRef\->parameterize($Int);
.Ve
.PP
Type libraries provide some convenient sugar for this:
.PP
.Vb 1
\& use Types::Standard qw( ArrayRef Int );
\&
\& my $ArrayRef_of_Ints = ArrayRef[Int];
.Ve
.PP
Unlike Moose which has separate meta classes for parameterizable,
parameterized and non-parameterizable type constraints, Type::Tiny handles
all that in one.
.PP
To create a parameterizable type constraint, you'll need to pass an extra
named parameter to \f(CW\*(C`declare\*(C'\fR. Let's imagine that we want to make our earlier
\&\f(CW\*(C`NonEmptyHash\*(C'\fR constraint accept a parameter telling it the minimum size of
the hash. For example \f(CW\*(C`NonEmptyHash[4]\*(C'\fR would need to contain at least
four key-value pairs. Here's how you'd do it:
.PP
.Vb 10
\& declare NonEmptyHash, as HashLike,
\& where { scalar values %$_ },
\& inline_as {
\& my ($constraint, $varname) = @_;
\& return sprintf(
\& \*(Aq%s and scalar values %%{%s}\*(Aq,
\& $constraint\->parent\->inline_check($varname),
\& $varname,
\& );
\& },
\& # Generate a new "where" coderef...
\& constraint_generator => sub {
\& my ($minimum) = @_;
\& die "parameter must be positive" unless int($minimum) > 0;
\& return sub {
\& scalar(values(%$_)) >= int($minimum);
\& };
\& },
\& # Generate a new "inline_as" coderef...
\& inline_generator => sub {
\& my ($minimum) = @_;
\& return sub {
\& my ($constraint, $varname) = @_;
\& return sprintf(
\& \*(Aq%s and scalar(values(%%{%s})) >= %d\*(Aq,
\& $constraint\->parent\->inline_check($varname),
\& $varname,
\& $minimum,
\& );
\& };
\& };
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Some type libraries on \s-1CPAN:\s0
.IP "\(bu" 4
Types::Standard
.IP "\(bu" 4
Types::Path::Tiny
.IP "\(bu" 4
Types::XSD / Types::XSD::Lite
.IP "\(bu" 4
Types::Set
.IP "\(bu" 4
more <https://github.com/tobyink/p5-type-tiny/wiki/Type-libraries>!
.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\-2018 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
Mini Shell