README

   1 NAME
   2     MooseX::Types - Organise your Moose types in libraries
   3
   4 SYNOPSIS
   5   Library Definition
   6       package MyLibrary;
   7
   8       # predeclare our own types
   9       use MooseX::Types
  10         -declare => [qw(
  11             PositiveInt NegativeInt
  12             ArrayRefOfPositiveInt ArrayRefOfAtLeastThreeNegativeInts
  13             LotsOfInnerConstraints StrOrArrayRef
  14         )];
  15
  16       # import builtin types
  17       use MooseX::Types::Moose 'Int';
  18
  19       # type definition
  20       subtype PositiveInt,
  21           as Int,
  22           where { $_ > 0 },
  23           message { "Int is not larger than 0" };
  24
  25       subtype NegativeInt,
  26           as Int,
  27           where { $_ < 0 },
  28           message { "Int is not smaller than 0" };
  29
  30       # type coercion
  31       coerce PositiveInt,
  32           from Int,
  33               via { 1 };
  34
  35       # with parameterized constraints.
  36
  37       subtype ArrayRefOfPositiveInt,
  38         as ArrayRef[PositiveInt];
  39
  40       subtype ArrayRefOfAtLeastThreeNegativeInts,
  41         as ArrayRef[NegativeInt],
  42         where { scalar(@$_) > 2 };
  43
  44       subtype LotsOfInnerConstraints,
  45         as ArrayRef[ArrayRef[HashRef[Int]]];
  46
  47       # with TypeConstraint Unions
  48
  49       subtype StrOrArrayRef,
  50         as Str|ArrayRef;
  51
  52       1;
  53
  54   Usage
  55       package Foo;
  56       use Moose;
  57       use MyLibrary qw( PositiveInt NegativeInt );
  58
  59       # use the exported constants as type names
  60       has 'bar',
  61           isa    => PositiveInt,
  62           is     => 'rw';
  63       has 'baz',
  64           isa    => NegativeInt,
  65           is     => 'rw';
  66
  67       sub quux {
  68           my ($self, $value);
  69
  70           # test the value
  71           print "positive\n" if is_PositiveInt($value);
  72           print "negative\n" if is_NegativeInt($value);
  73
  74           # coerce the value, NegativeInt doesn't have a coercion
  75           # helper, since it didn't define any coercions.
  76           $value = to_PositiveInt($value) or die "Cannot coerce";
  77       }
  78
  79       1;
  80
  81 DESCRIPTION
  82     The types provided with Moose are by design global. This package helps
  83     you to organise and selectively import your own and the built-in types
  84     in libraries. As a nice side effect, it catches typos at compile-time
  85     too.
  86
  87     However, the main reason for this module is to provide an easy way to
  88     not have conflicts with your type names, since the internal fully
  89     qualified names of the types will be prefixed with the library's name.
  90
  91     This module will also provide you with some helper functions to make it
  92     easier to use Moose types in your code.
  93
  94 TYPE HANDLER FUNCTIONS
  95   $type
  96     A constant with the name of your type. It contains the type's fully
  97     qualified name. Takes no value, as all constants.
  98
  99   is_$type
 100     This handler takes a value and tests if it is a valid value for this
 101     $type. It will return true or false.
 102
 103   to_$type
 104     A handler that will take a value and coerce it into the $type. It will
 105     return a false value if the type could not be coerced.
 106
 107     Important Note: This handler will only be exported for types that can do
 108     type coercion. This has the advantage that a coercion to a type that
 109     cannot hasn't defined any coercions will lead to a compile-time error.
 110
 111 LIBRARY DEFINITION
 112     A MooseX::Types is just a normal Perl module. Unlike Moose itself, it
 113     does not install "use strict" and "use warnings" in your class by
 114     default, so this is up to you.
 115
 116     The only thing a library is required to do is
 117
 118       use MooseX::Types -declare => \@types;
 119
 120     with @types being a list of types you wish to define in this library.
 121     This line will install a proper base class in your package as well as
 122     the full set of handlers for your declared types. It will then hand
 123     control over to Moose::Util::TypeConstraints' "import" method to export
 124     the functions you will need to declare your types.
 125
 126     If you want to use Moose' built-in types (e.g. for subtyping) you will
 127     want to
 128
 129       use MooseX::Types::Moose @types;
 130
 131     to import the helpers from the shipped MooseX::Types::Moose library
 132     which can export all types that come with Moose.
 133
 134     You will have to define coercions for your types or your library won't
 135     export a "to_$type" coercion helper for it.
 136
 137     Note that you currently cannot define types containing "::", since
 138     exporting would be a problem.
 139
 140     You also don't need to use "warnings" and "strict", since the definition
 141     of a library automatically exports those.
 142
 143 LIBRARY USAGE
 144     You can import the "type helpers" of a library by "use"ing it with a
 145     list of types to import as arguments. If you want all of them, use the
 146     ":all" tag. For example:
 147
 148       use MyLibrary      ':all';
 149       use MyOtherLibrary qw( TypeA TypeB );
 150
 151     MooseX::Types comes with a library of Moose' built-in types called
 152     MooseX::Types::Moose.
 153
 154     The exporting mechanism is, since version 0.5, implemented via a wrapper
 155     around Sub::Exporter. This means you can do something like this:
 156
 157       use MyLibrary TypeA => { -as => 'MyTypeA' },
 158                     TypeB => { -as => 'MyTypeB' };
 159
 160 WRAPPING A LIBRARY
 161     You can define your own wrapper subclasses to manipulate the behaviour
 162     of a set of library exports. Here is an example:
 163
 164       package MyWrapper;
 165       use strict;
 166       use Class::C3;
 167       use base 'MooseX::Types::Wrapper';
 168
 169       sub coercion_export_generator {
 170           my $class = shift;
 171           my $code = $class->next::method(@_);
 172           return sub {
 173               my $value = $code->(@_);
 174               warn "Coercion returned undef!"
 175                   unless defined $value;
 176               return $value;
 177           };
 178       }
 179
 180       1;
 181
 182     This class wraps the coercion generator (e.g., "to_Int()") and warns if
 183     a coercion returned an undefined value. You can wrap any library with
 184     this:
 185
 186       package Foo;
 187       use strict;
 188       use MyWrapper MyLibrary => [qw( Foo Bar )],
 189                     Moose     => [qw( Str Int )];
 190
 191       ...
 192       1;
 193
 194     The "Moose" library name is a special shortcut for MooseX::Types::Moose.
 195
 196   Generator methods you can overload
 197     type_export_generator( $short, $full )
 198         Creates a closure returning the type's Moose::Meta::TypeConstraint
 199         object.
 200
 201     check_export_generator( $short, $full, $undef_message )
 202         This creates the closure used to test if a value is valid for this
 203         type.
 204
 205     coercion_export_generator( $short, $full, $undef_message )
 206         This is the closure that's doing coercions.
 207
 208   Provided Parameters
 209     $short
 210         The short, exported name of the type.
 211
 212     $full
 213         The fully qualified name of this type as Moose knows it.
 214
 215     $undef_message
 216         A message that will be thrown when type functionality is used but
 217         the type does not yet exist.
 218
 219 NOTES REGARDING TYPE UNIONS
 220         MooseX::Types uses MooseX::Types::TypeDecorator to do some
 221         overloading which generally allows you to easily create union types:
 222
 223           subtype StrOrArrayRef,
 224             as Str|ArrayRef;
 225
 226         As with parameterized constrains, this overloading extends to
 227         modules using the types you define in a type library.
 228
 229             use Moose;
 230             use MooseX::Types::Moose qw(HashRef Int);
 231
 232             has 'attr' => (isa=>HashRef|Int);
 233
 234         And everything should just work as you'd think.
 235
 236 METHODS
 237   import
 238         Installs the MooseX::Types::Base class into the caller and exports
 239         types according to the specification described in "LIBRARY
 240         DEFINITION". This will continue to Moose::Util::TypeConstraints'
 241         "import" method to export helper functions you will need to declare
 242         your types.
 243
 244   type_export_generator
 245         Generate a type export, e.g. "Int()". This will return either a
 246         Moose::Meta::TypeConstraint object, or alternatively a
 247         MooseX::Types::UndefinedType object if the type was not yet defined.
 248
 249   create_arged_type_constraint ($name, @args)
 250         Given a String $name with @args find the matching typeconstraint and
 251         parameterize it with @args.
 252
 253   create_base_type_constraint ($name)
 254         Given a String $name, find the matching typeconstraint.
 255
 256   create_type_decorator ($type_constraint)
 257         Given a $type_constraint, return a lightweight
 258         MooseX::Types::TypeDecorator instance.
 259
 260   coercion_export_generator
 261         This generates a coercion handler function, e.g. "to_Int($value)".
 262
 263   check_export_generator
 264         Generates a constraint check closure, e.g. "is_Int($value)".
 265
 266 CAVEATS
 267         The following are lists of gotcha's and their workarounds for
 268         developers coming from the standard string based type constraint
 269         names
 270
 271   Uniqueness
 272         A library makes the types quasi-unique by prefixing their names with
 273         (by default) the library package name. If you're only using the type
 274         handler functions provided by MooseX::Types, you shouldn't ever have
 275         to use a type's actual full name.
 276
 277   Argument separation ('=>' versus ',')
 278         The Perlop manpage has this to say about the '=>' operator: "The =>
 279         operator is a synonym for the comma, but forces any word (consisting
 280         entirely of word characters) to its left to be interpreted as a
 281         string (as of 5.001). This includes words that might otherwise be
 282         considered a constant or function call."
 283
 284         Due to this stringification, the following will NOT work as you
 285         might think:
 286
 287           subtype StrOrArrayRef => as Str|ArrayRef;
 288
 289         The 'StrOrArrayRef' will have it's stringification activated this
 290         causes the subtype to not be created. Since the bareword type
 291         constraints are not strings you really should not try to treat them
 292         that way. You will have to use the ',' operator instead. The
 293         author's of this package realize that all the Moose documention and
 294         examples nearly uniformly use the '=>' version of the comma operator
 295         and this could be an issue if you are converting code.
 296
 297         Patches welcome for discussion.
 298
 299 SEE ALSO
 300         Moose, Moose::Util::TypeConstraints, MooseX::Types::Moose,
 301         Sub::Exporter
 302
 303 AUTHOR AND COPYRIGHT
 304         Robert 'phaylon' Sedlacek "<rs@474.at>", with many thanks to the
 305         "#moose" cabal on "irc.perl.org".
 306
 307         Additional features by John Napiorkowski (jnapiorkowski)
 308         <jjnapiork@cpan.org>.
 309
 310 LICENSE
 311         This program is free software; you can redistribute it and/or modify
 312         it under the same terms as perl itself.
 313