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.

AUTHOR

Alexis Sukrieh <[email protected]> ; based on the work done by Stevan Little <[email protected]> on Moose::Util::TypeConstraint

COPYRIGHT AND LICENSE

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.