X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=lib%2FMoose%2FManual%2FTypes.pod;h=330edb594306a624f51c8ad05aca3c566893c3d6;hb=970a92fa56f1ea409c8d7c5428392479292fd8d4;hp=f70a070fc004d137f78186f815860406fb7e1533;hpb=977a5e909a7e123a00a4298fb740ef9a6454ac14;p=gitmo%2FMoose.git diff --git a/lib/Moose/Manual/Types.pod b/lib/Moose/Manual/Types.pod index f70a070..330edb5 100644 --- a/lib/Moose/Manual/Types.pod +++ b/lib/Moose/Manual/Types.pod @@ -11,17 +11,16 @@ these types to validate method parameters with the help of a MooseX module. Moose's type system is based on a combination of Perl 5's own -I types and some Perl 6 concepts. You can easily create your +I types and some Perl 6 concepts. You can create your own subtypes with custom constraints, making it easy to express any sort of validation. Types have names, and you can re-use them by name, making it easy to share types throughout a large application. -Let us be clear that is not a "real" type system. Moose does not -magically make Perl start associating types with variables. This is -just an advanced parameter checking system which allows you to -associate a name with a constraint. +However, this is not a "real" type system. Moose does not magically make Perl +start associating types with variables. This is just an advanced parameter +checking system which allows you to associate a name with a constraint. That said, it's still pretty damn useful, and we think it's one of the things that makes Moose both fun and powerful. Taking advantage of the @@ -40,10 +39,10 @@ The basic Moose type hierarchy looks like this Defined Value Str - Num - Int - ClassName - RoleName + Num + Int + ClassName + RoleName Ref ScalarRef[`a] ArrayRef[`a] @@ -51,7 +50,7 @@ The basic Moose type hierarchy looks like this CodeRef RegexpRef GlobRef - FileHandle + FileHandle Object In practice, the only difference between C and C is @@ -62,17 +61,29 @@ In particular: =over 4 -=item C accepts C<1> for true, and any value that perl treats as false for false. +=item -=item C accepts either C<`a> or C. +C accepts C<1> for true, and undef, 0, or the empty string as false. -=item C accepts anything that perl thinks looks like a number (see L). +=item -=item C and C accept strings that are either the name of a class or the name of a role. The class/role must be loaded beforehand for this to succeed. +C accepts either C<`a> or C. -=item C accepts either an object of type L or a builtin perl filehandle (see L). +=item -=item C accepts any blessed reference. +C accepts anything that perl thinks looks like a number (see L). + +=item + +C and C accept strings that are either the name of a class or the name of a role. The class/role must already be loaded when the constraint is checked. + +=item + +C accepts either an L object or a builtin perl filehandle (see L). + +=item + +C accepts any blessed reference. =back @@ -165,21 +176,6 @@ Here's a simple (and useful) subtype example: Note that the sugar functions for working with types are all exported by L. -=head2 Creating a new type (that isn't a subtype) - -You can also create new top-level types: - - type 'FourCharacters' => where { defined $_ && length $_ == 4 }; - -In practice, this example is more or less the same as subtyping -C, except you have to check definedness yourself. - -It's hard to find a case where you wouldn't want to subtype a very -broad type like C, C or C. - -Defining a new top-level type is conceptually the same as subtyping -C. - =head1 TYPE NAMES Type names are global throughout the current Perl @@ -197,25 +193,23 @@ recommend that you centralize all of these definitions in a single package, C, which can be loaded by other classes in your application. -Once you're doing this, you should almost certainly look at the -L extension which allows easy declaration of type libraries -and can export your types as perl constants so that you can refer to them -as just +However, before you do this, you should look at the L +module. This module makes it easy to create a "type library" module, which can +export your types as perl constants. has 'counter' => (is => 'rw', isa => PositiveInt); -rather than needing to fully qualify them everywhere. It also allows +This lets you use a short name rather than needing to fully qualify the name +everywhere. It also allows you to write easily create parameterized types: has 'counts' => (is => 'ro', isa => HashRef[PositiveInt]); -and similarly for the union and other syntax discussed below, which -will compile time check your use of names and is generally more robust -than the string type parsing for complex cases. +This module will check your names at compile time, and is generally more +robust than the string type parsing for complex cases. =head1 COERCION -One of the most powerful features of Moose's type system is its -coercions. A coercion is a way to convert from one type to another. +A coercion lets you tell Moose to automatically convert one type to another. subtype 'ArrayRefOfInts' => as 'ArrayRef[Int]'; @@ -224,14 +218,16 @@ coercions. A coercion is a way to convert from one type to another. => from 'Int' => via { [ $_ ] }; -You'll note that we had to create a subtype rather than coercing -C directly. This is just a quirk of how Moose -works. +You'll note that we created a subtype rather than coercing C +directly. It's a bad idea to add coercions to the raw built in +types. + +Coercions are global, just like type names, so a coercion applied to a built +in type is seen by all modules using Moose types. This is I reason +why it is good to namespace your types. -Coercions, like type names, are global. This is I reason why -it is good to namespace your types. Moose will I try to coerce -a value unless you explicitly ask for it. This is done by setting the -C attribute option to a true value: +Moose will I try to coerce a value unless you explicitly ask for +it. This is done by setting the C attribute option to a true value: package Foo; @@ -285,7 +281,7 @@ two parameterized types. Now Moose will coerce the hex numbers to integers. -However, Moose does not attempt to chain coercions, so it will not +Moose does not attempt to chain coercions, so it will not coerce a single hex number. To do that, we need to define a separate coercion: @@ -338,7 +334,7 @@ with a simple wrapper class: my $self = shift; my $fh = $self->handle(); - print $fh @_; + print {$fh} @_; } Now we can define a coercion from C to our wrapper class: @@ -377,8 +373,8 @@ object can be used wherever you would use a type name, as a parent type, or as the value for an attribute's C option: has 'size' => ( - is => 'ro', - isa => subtype('Int' => where { $_ > 0 }), + is => 'ro', + isa => subtype( 'Int' => where { $_ > 0 } ), ); This is handy when you want to create a one-off type and don't want to @@ -412,7 +408,7 @@ parameter validation using Moose types, including L, which gives you a full-blown C keyword. - method morning (Str $name) { + method morning ( Str $name ) { $self->say("Good morning ${name}!"); } @@ -422,20 +418,9 @@ Because Moose types are defined at runtime, you may run into load order problems. In particular, you may want to use a class's type constraint before that type has been defined. -We have several recommendations for ameliorating this problem. First, -define I of your custom types in one module, -C. Second, load this module in all of your other -modules. - -If you are still having load order problems, you can make use of the -C function exported by -L: - - class_type('MyApp::User') - unless find_type_constraint('MyApp::User'); - -This sort of "find or create" logic is simple to write, and will let -you work around load order issues. +In order to ameliorate this problem, we recommend defining I of your +custom types in one module, C, and then loading this module in +all of your other modules. =head1 AUTHOR