Coat::Types.3pm

Langue: en

Version: 2008-11-24 (debian - 07/07/09)

Section: 3 (Bibliothèques de fonctions)

NAME

Coat::Types - Type constraint system for Coat

NOTE

This is a rewrite of Moose::Util::TypeConstraint for Coat.

SYNOPSIS

   use Coat::Types;
 
   type 'Num' => where { Scalar::Util::looks_like_number($_) };
 
   subtype 'Natural'
       => as 'Num'
       => where { $_ > 0 };
 
   subtype 'NaturalLessThanTen'
       => as 'Natural'
       => where { $_ < 10 }
       => message { "This number ($_) is not less than ten!" };
 
   coerce 'Num'
       => from 'Str'
         => via { 0+$_ };
 
   enum 'RGBColors' => qw(red green blue);
 
 

DESCRIPTION

This module provides Coat with the ability to create custom type contraints to be used in attribute definition.

Important Caveat

This is NOT a type system for Perl 5. These are type constraints, and they are not used by Coat unless you tell it to. No type inference is performed, expression are not typed, etc. etc. etc.

This is simply a means of creating small constraint functions which can be used to simplify your own type-checking code, with the added side benefit of making your intentions clearer through self-documentation.

Slightly Less Important Caveat

It is always a good idea to quote your type and subtype names.

This is to prevent perl from trying to execute the call as an indirect object call. This issue only seems to come up when you have a subtype the same name as a valid class, but when the issue does arise it tends to be quite annoying to debug.

So for instance, this:

   subtype DateTime => as Object => where { $_->isa('DateTime') };
 
 

will Just Work, while this:

   use DateTime;
   subtype DateTime => as Object => where { $_->isa('DateTime') };
 
 

will fail silently and cause many headaches. The simple way to solve this, as well as future proof your subtypes from classes which have yet to have been created yet, is to simply do this:

   use DateTime;
   subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') };
 
 

Default Type Constraints

This module also provides a simple hierarchy for Perl 5 types, here is that hierarchy represented visually.
   Any
   Item
       Bool
       Undef
       Defined
           Value
               Num
                 Int
               Str
                 ClassName
           Ref
               ScalarRef
               ArrayRef[`a]
               HashRef[`a]
               CodeRef
               RegexpRef
               GlobRef
               Object
 
 

Type Constraint Naming

Since the types created by this module are global, it is suggested that you namespace your types just as you would namespace your modules. So instead of creating a Color type for your My::Graphics module, you would call the type My::Graphics::Color instead.

FUNCTIONS

Type Constraint Constructors

The following functions are used to create type constraints. They will then register the type constraints in a global store where Coat can get to them if it needs to.

See the SYNOPSIS for an example of how to use these.

type ($name, $where_clause)
This creates a base type, which has no parent.
subtype ($name, $parent, $where_clause, ?$message)
This creates a named subtype.
enum ($name, @values)
This will create a basic subtype for a given set of strings. The resulting constraint will be a subtype of "Str" and will match any of the items in @values. It is case sensitive. See the SYNOPSIS for a simple example.

NOTE: This is not a true proper enum type, it is simple a convient constraint builder.

as
This is just sugar for the type constraint construction syntax.
where
This is just sugar for the type constraint construction syntax.
message
This is just sugar for the type constraint construction syntax.

Type Coercion Constructors

Type constraints can also contain type coercions as well. If you ask your accessor to coerce, then Coat will run the type-coercion code first, followed by the type constraint check. This feature should be used carefully as it is very powerful and could easily take off a limb if you are not careful.

See the SYNOPSIS for an example of how to use these.

coerce
from
This is just sugar for the type coercion construction syntax.
via
This is just sugar for the type coercion construction syntax.

Type Constraint Construction & Locating

find_type_constraint ($type_name)
This function can be used to locate a specific type constraint meta-object, of the class Coat::Meta::TypeConstraint or a derivative. What you do with it from there is up to you :)
register_type_constraint ($type_object)
This function will register a named type constraint with the type registry.
list_all_type_constraints
This will return a list of type constraint names, you can then fetch them using "find_type_constraint ($type_name)" if you want to.
export_type_constraints_as_functions
This will export all the current type constraints as functions into the caller's namespace. Right now, this is mostly used for testing, but it might prove useful to others.

BUGS

All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.

AUTHOR

Alexis Sukrieh <sukria@sukria.net> ; based on the work done by Stevan Little <stevan@iinteractive.com> on Moose::Util::TypeConstraint Copyright 2006-2008 by Edenware - Alexis Sukrieh

<http://www.edenware.fr> - <http://www.sukria.net>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.