package Type::Library;
use 5.008001;
use strict;
use warnings;
BEGIN {
$Type::Library::AUTHORITY = 'cpan:TOBYINK';
$Type::Library::VERSION = '2.000001';
}
$Type::Library::VERSION =~ tr/_//d;
use Eval::TypeTiny qw< eval_closure set_subname type_to_coderef NICE_PROTOTYPES >;
use Scalar::Util qw< blessed refaddr >;
use Type::Tiny ();
use Types::TypeTiny ();
require Exporter::Tiny;
our @ISA = 'Exporter::Tiny';
sub _croak ($;@) { require Error::TypeTiny; goto \&Error::TypeTiny::croak }
####
#### Hooks for Exporter::Tiny
####
# Handling for -base, -extends, and -utils tags.
#
sub _exporter_validate_opts {
my ( $class, $opts ) = ( shift, @_ );
$class->setup_type_library( @{$opts}{qw/ into utils extends /} )
if $_[0]{base} || $_[0]{extends};
return $class->SUPER::_exporter_validate_opts( @_ );
}
# In Exporter::Tiny, this method takes a sub name, a 'value' (i.e.
# potentially an options hashref for the export), and some global
# options, and returns a list of name+coderef pairs to actually
# export. We override it to provide some useful features.
#
sub _exporter_expand_sub {
my $class = shift;
my ( $name, $value, $globals ) = @_;
# Handle exporting '+Type'.
#
# Note that this recurses, so if used in conjunction with the other
# special cases handled by this method, will still work.
#
if ( $name =~ /^\+(.+)/ and $class->has_type( "$1" ) ) {
my $type = $class->get_type( "$1" );
my $exported = $type->exportables;
return map $class->_exporter_expand_sub(
$_->{name},
+{ %{ $value || {} } },
$globals,
), @$exported;
}
# Is the function being exported one which is associated with a
# type constraint? If so, which one. If not, then forget the rest
# and just use the superclass method.
#
if ( my $f = $class->meta->{'functions'}{$name}
and defined $class->meta->{'functions'}{$name}{'type'} ) {
my $type = $f->{type};
my $tag = $f->{tags}[0];
my $typename = $type->name;
# If $value has `of` or `where` options, then this is a
# custom type.
#
my $custom_type = 0;
for my $param ( qw/ of where / ) {
exists $value->{$param} or next;
defined $value->{-as} or _croak( "Parameter '-as' not supplied" );
$type = $type->$param( $value->{$param} );
$name = $value->{-as};
++$custom_type;
}
# If we're exporting a type itself, then export a custom
# function if they customized the type or want a Moose/Mouse
# type constraint.
#
if ( $tag eq 'types' ) {
my $post_method = q();
$post_method = '->mouse_type' if $globals->{mouse};
$post_method = '->moose_type' if $globals->{moose};
return ( $name => type_to_coderef( $type, post_method => $post_method ) )
if $post_method || $custom_type;
}
# If they're exporting some other type of function, like
# 'to', 'is', or 'assert', then find the correct exportable
# by tag name, and return that.
#
# XXX: this will fail for tags like 'constants' where there
# will be multiple exportables which match!
#
if ( $custom_type and $tag ne 'types' ) {
my $exportable = $type->exportables_by_tag( $tag, $typename );
return ( $value->{-as} || $exportable->{name}, $exportable->{code} );
}
}
# In all other cases, the superclass method will work.
#
return $class->SUPER::_exporter_expand_sub( @_ );
}
# Mostly just rely on superclass to do the actual export, but add
# a couple of useful behaviours.
#
sub _exporter_install_sub {
my $class = shift;
my ( $name, $value, $globals, $sym ) = @_;
my $into = $globals->{into};
my $type = $class->meta->{'functions'}{$name}{'type'};
my $tags = $class->meta->{'functions'}{$name}{'tags'};
# Issue a warning if exporting a deprecated type constraint.
#
Exporter::Tiny::_carp(
"Exporting deprecated type %s to %s",
$type->qualified_name,
ref( $into ) ? "reference" : "package $into",
) if ( defined $type and $type->deprecated and not $globals->{allow_deprecated} );
# If exporting a type constraint into a real package, then
# add it to the package's type registry.
#
if ( !ref $into
and $into ne '-lexical'
and defined $type
and grep $_ eq 'types', @$tags ) {
# If they're renaming it, figure out what name, and use that.
# XXX: `-as` can be a coderef, and can be in $globals in that case.
my ( $prefix ) = grep defined, $value->{-prefix}, $globals->{prefix}, q();
my ( $suffix ) = grep defined, $value->{-suffix}, $globals->{suffix}, q();
my $as = $prefix . ( $value->{-as} || $name ) . $suffix;
$INC{'Type/Registry.pm'}
? 'Type::Registry'->for_class( $into )->add_type( $type, $as )
: ( $Type::Registry::DELAYED{$into}{$as} = $type );
}
$class->SUPER::_exporter_install_sub( @_ );
} #/ sub _exporter_install_sub
sub _exporter_fail {
my $class = shift;
my ( $name, $value, $globals ) = @_;
# Passing the `-declare` flag means that if a type isn't found, then
# we export a placeholder function instead of failing.
if ( $globals->{declare} ) {
return (
$name,
type_to_coderef(
undef,
type_name => $name,
type_library => $globals->{into} || _croak( "Parameter 'into' not supplied" ),
),
);
} #/ if ( $globals->{declare...})
return $class->SUPER::_exporter_fail( @_ );
} #/ sub _exporter_fail
####
#### Type library functionality
####
sub setup_type_library {
my ( $class, $type_library, $install_utils, $extends ) = @_;
my @extends = ref( $extends ) ? @$extends : $extends ? $extends : ();
unshift @extends, $class if $class ne __PACKAGE__;
if ( not ref $type_library ) {
no strict "refs";
push @{"$type_library\::ISA"}, $class;
( my $file = $type_library ) =~ s{::}{/}g;
$INC{"$file.pm"} ||= __FILE__;
}
if ( $install_utils ) {
require Type::Utils;
'Type::Utils'->import( { into => $type_library }, '-default' );
}
if ( @extends and not ref $type_library ) {
require Type::Utils;
my $wrapper = eval "sub { package $type_library; &Type::Utils::extends; }";
$wrapper->( @extends );
}
}
sub meta {
no strict "refs";
no warnings "once";
return $_[0] if blessed $_[0];
${"$_[0]\::META"} ||= bless {}, $_[0];
}
sub add_type {
my $meta = shift->meta;
my $class = blessed( $meta ) ;
_croak( 'Type library is immutable' ) if $meta->{immutable};
my $type =
ref( $_[0] ) =~ /^Type::Tiny\b/ ? $_[0] :
blessed( $_[0] ) ? Types::TypeTiny::to_TypeTiny( $_[0] ) :
ref( $_[0] ) eq q(HASH) ? 'Type::Tiny'->new( library => $class, %{ $_[0] } ) :
"Type::Tiny"->new( library => $class, @_ );
my $name = $type->{name};
_croak( 'Type %s already exists in this library', $name ) if $meta->has_type( $name );
_croak( 'Type %s conflicts with coercion of same name', $name ) if $meta->has_coercion( $name );
_croak( 'Cannot add anonymous type to a library' ) if $type->is_anon;
$meta->{types} ||= {};
$meta->{types}{$name} = $type;
no strict "refs";
no warnings "redefine", "prototype";
for my $exportable ( @{ $type->exportables } ) {
my $name = $exportable->{name};
my $code = $exportable->{code};
my $tags = $exportable->{tags};
*{"$class\::$name"} = set_subname( "$class\::$name", $code );
push @{"$class\::EXPORT_OK"}, $name;
push @{ ${"$class\::EXPORT_TAGS"}{$_} ||= [] }, $name for @$tags;
$meta->{'functions'}{$name} = { type => $type, tags => $tags };
}
$INC{'Type/Registry.pm'}
? 'Type::Registry'->for_class( $class )->add_type( $type, $name )
: ( $Type::Registry::DELAYED{$class}{$name} = $type );
return $type;
} #/ sub add_type
sub get_type {
my $meta = shift->meta;
$meta->{types}{ $_[0] };
}
sub has_type {
my $meta = shift->meta;
exists $meta->{types}{ $_[0] };
}
sub type_names {
my $meta = shift->meta;
keys %{ $meta->{types} };
}
sub add_coercion {
my $meta = shift->meta;
my $class = blessed( $meta );
_croak( 'Type library is immutable' ) if $meta->{immutable};
require Type::Coercion;
my $c = blessed( $_[0] ) ? $_[0] : "Type::Coercion"->new( @_ );
my $name = $c->name;
_croak( 'Coercion %s already exists in this library', $name ) if $meta->has_coercion( $name );
_croak( 'Coercion %s conflicts with type of same name', $name ) if $meta->has_type( $name );
_croak( 'Cannot add anonymous type to a library' ) if $c->is_anon;
$meta->{coercions} ||= {};
$meta->{coercions}{$name} = $c;
no strict "refs";
no warnings "redefine", "prototype";
*{"$class\::$name"} = type_to_coderef( $c );
push @{"$class\::EXPORT_OK"}, $name;
push @{ ${"$class\::EXPORT_TAGS"}{'coercions'} ||= [] }, $name;
$meta->{'functions'}{$name} = { coercion => $c, tags => [ 'coercions' ] };
return $c;
} #/ sub add_coercion
sub get_coercion {
my $meta = shift->meta;
$meta->{coercions}{ $_[0] };
}
sub has_coercion {
my $meta = shift->meta;
exists $meta->{coercions}{ $_[0] };
}
sub coercion_names {
my $meta = shift->meta;
keys %{ $meta->{coercions} };
}
sub make_immutable {
my $meta = shift->meta;
my $class = ref( $meta );
no strict "refs";
no warnings "redefine", "prototype";
for my $type ( values %{ $meta->{types} } ) {
$type->coercion->freeze;
next unless $type->has_coercion && $type->coercion->frozen;
for my $e ( $type->exportables_by_tag( 'to' ) ) {
my $qualified_name = $class . '::' . $e->{name};
*$qualified_name = set_subname( $qualified_name, $e->{code} );
}
}
$meta->{immutable} = 1;
}
1;
__END__
=pod
=encoding utf-8
=for stopwords Moo(se)-compatible MooseX::Types-like
=head1 NAME
Type::Library - tiny, yet Moo(se)-compatible type libraries
=head1 SYNOPSIS
=for test_synopsis
BEGIN { die "SKIP: crams multiple modules into single example" };
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't 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);
}
=head1 STATUS
This module is covered by the
L<Type-Tiny stability policy|Type::Tiny::Manual::Policies/"STABILITY">.
=head1 DESCRIPTION
L<Type::Library> is a tiny class for creating MooseX::Types-like type
libraries which are compatible with Moo, Moose and Mouse.
If you're reading this because you want to create a type library, then
you're probably better off reading L<Type::Tiny::Manual::Libraries>.
=head2 Type library methods
A type library is a singleton class. Use the C<meta> method to get a blessed
object which other methods can get called on. For example:
Types::Mine->meta->add_type($foo);
=begin trustme
=item meta
=end trustme
=over
=item C<< add_type($type) >> or C<< add_type(%opts) >>
Add a type to the library. If C<< %opts >> is given, then this method calls
C<< Type::Tiny->new(%opts) >> first, and adds the resultant type.
Adding a type named "Foo" to the library will automatically define four
functions in the library's namespace:
=over
=item C<< Foo >>
Returns the Type::Tiny object.
=item C<< is_Foo($value) >>
Returns true iff $value passes the type constraint.
=item C<< assert_Foo($value) >>
Returns $value iff $value passes the type constraint. Dies otherwise.
=item C<< to_Foo($value) >>
Coerces the value to the type.
=back
=item C<< get_type($name) >>
Gets the C<Type::Tiny> object corresponding to the name.
=item C<< has_type($name) >>
Boolean; returns true if the type exists in the library.
=item C<< type_names >>
List all types defined by the library.
=item C<< add_coercion($c) >> or C<< add_coercion(%opts) >>
Add a standalone coercion to the library. If C<< %opts >> is given, then
this method calls C<< Type::Coercion->new(%opts) >> first, and adds the
resultant coercion.
Adding a coercion named "FooFromBar" to the library will automatically
define a function in the library's namespace:
=over
=item C<< FooFromBar >>
Returns the Type::Coercion object.
=back
=item C<< get_coercion($name) >>
Gets the C<Type::Coercion> object corresponding to the name.
=item C<< has_coercion($name) >>
Boolean; returns true if the coercion exists in the library.
=item C<< coercion_names >>
List all standalone coercions defined by the library.
=item C<< import(@args) >>
Type::Library-based libraries are exporters.
=item C<< make_immutable >>
Prevents new type constraints and coercions from being added to the
library, and also calls C<< $type->coercion->freeze >> on every
type constraint in the library.
=back
=head2 Type library exported functions
Type libraries are exporters. For the purposes of the following examples,
assume that the C<Types::Mine> library defines types C<Number> and C<String>.
# 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 );
Type libraries automatically inherit from L<Exporter::Tiny>; see the
documentation of that module for tips and tricks importing from libraries.
=head2 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.
=over
=item C<< setup_type_library( $package, $utils, \@extends ) >>
Sets up a package to be a type library. C<< $utils >> is a boolean
indicating whether to import L<Type::Utils> into the package.
C<< @extends >> is a list of existing type libraries the package
should extend.
=back
=head1 BUGS
Please report any bugs to
L<https://github.com/tobyink/p5-type-tiny/issues>.
=head1 SEE ALSO
L<Type::Tiny::Manual>.
L<Type::Tiny>, L<Type::Utils>, L<Types::Standard>, L<Type::Coercion>.
L<Moose::Util::TypeConstraints>,
L<Mouse::Util::TypeConstraints>.
=head1 AUTHOR
Toby Inkster E<lt>tobyink@cpan.orgE<gt>.
=head1 COPYRIGHT AND LICENCE
This software is copyright (c) 2013-2014, 2017-2022 by Toby Inkster.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=head1 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.