From: Dave Rolsky Date: Thu, 26 Mar 2009 16:33:43 +0000 (-0500) Subject: Revamp docs for M::Util::TC X-Git-Tag: 0.72_01~9 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=e7fcb7b28736f5104a80018ed8ecaac2f9c0f691;p=gitmo%2FMoose.git Revamp docs for M::Util::TC --- diff --git a/lib/Moose/Util/TypeConstraints.pm b/lib/Moose/Util/TypeConstraints.pm index 9dd4ff1..5f3bfe2 100644 --- a/lib/Moose/Util/TypeConstraints.pm +++ b/lib/Moose/Util/TypeConstraints.pm @@ -719,8 +719,6 @@ Moose::Util::TypeConstraints - Type constraint system for Moose use Moose::Util::TypeConstraints; - type 'Num' => where { Scalar::Util::looks_like_number($_) }; - subtype 'Natural' => as 'Int' => where { $_ > 0 }; @@ -736,6 +734,8 @@ Moose::Util::TypeConstraints - Type constraint system for Moose enum 'RGBColors' => qw(red green blue); + no Moose::Util::TypeConstraints; + =head1 DESCRIPTION This module provides Moose with the ability to create custom type @@ -745,33 +745,33 @@ constraints to be used in attribute definition. This is B a type system for Perl 5. These are type constraints, and they are not used by Moose unless you tell it to. No type -inference is performed, expression are not typed, etc. etc. etc. +inference is performed, expressions 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. +A type constraint is at heart a small "check if a value is valid" +function. A constraint can be associated with an attribute. This +simplifies parameter validation, and makes your code clearer to read, +because you can refer to constraints by name. =head2 Slightly Less Important Caveat -It is B a good idea to quote your type and subtype names. +It is B a good idea to quote your type 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. +This prevents Perl from trying to execute the call as an indirect +object call. This can be an issue when you have a subtype with the +same name as a valid class. -So for instance, this: +For instance: subtype DateTime => as Object => where { $_->isa('DateTime') }; -will I, while this: +will I, 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: +yet to have been created, is to quote the type name: use DateTime; subtype 'DateTime' => as 'Object' => where { $_->isa('DateTime') }; @@ -815,22 +815,21 @@ If Moose finds a name in brackets that it does not recognize as an existing type, it assumes that this is a class name, for example C. -B Unless you parameterize a type, then it is invalid to -include the square brackets. I.e. C will be -literally interpreted as a type name. +B Unless you parameterize a type, then it is invalid to include +the square brackets. I.e. C will be treated as a new type +name, I as a parameterization of C. B The C type constraint for the most part works correctly now, but edge cases may still exist, please use it sparingly. B The C type constraint does a complex package -existence check. This means that your class B be loaded for -this type constraint to pass. I know this is not ideal for all, -but it is a saner restriction than most others. +existence check. This means that your class B be loaded for this +type constraint to pass. -B The C constraint checks a string is I -which is a role, like C<'MyApp::Role::Comparable'>. The C -constraint checks that an I does the named role. +B The C constraint checks a string is a I which is a role, like C<'MyApp::Role::Comparable'>. The C +constraint checks that an I the named role. =head2 Type Constraint Naming @@ -839,17 +838,17 @@ characters, colons (:), and periods (.). 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 I type for your B -module, you would call the type I instead. +modules. So instead of creating a I type for your +B module, you would call the type +I instead. =head2 Use with Other Constraint Modules -This module should play fairly nicely with other constraint -modules with only some slight tweaking. The C clause -in types is expected to be a C reference which checks -it's first argument and returns a boolean. Since most constraint -modules work in a similar way, it should be simple to adapt -them to work with Moose. +This module can play nicely with other constraint modules with some +slight tweaking. The C clause in types is expected to be a +C reference which checks it's first argument and returns a +boolean. Since most constraint modules work in a similar way, it +should be simple to adapt them to work with Moose. For instance, this is how you could use it with L to declare a completely new type. @@ -862,8 +861,8 @@ L to declare a completely new type. ) }; -For more examples see the F -test file. +For more examples see the F test +file. Here is an example of using L and it's non-test related C function. @@ -878,32 +877,20 @@ related C function. }; For a complete example see the -F test file. +F test file. =head1 FUNCTIONS =head2 Type Constraint Constructors -The following functions are used to create type constraints. -They will then register the type constraints in a global store -where Moose can get to them if it needs to. +The following functions are used to create type constraints. They +will also register the type constraints your create in a global +registry that is used to look types up by name. See the L for an example of how to use these. =over 4 -=item B where { } ... > - -This creates a base type, which has no parent. - -The C function should either be called with the sugar helpers -(C, C, etc), or with a name and a hashref of -parameters: - - type( 'Foo', { where => ..., message => ... } ); - -The valid hashref keys are C, C, and C. - =item B as 'Parent' => where { } ...> This creates a named subtype. @@ -968,29 +955,31 @@ definition like so: isa => enum([qw[ ascending descending ]]), ); -=item B +=item B This is just sugar for the type constraint construction syntax. -=item B +It takes a single argument, which is the name of a parent type. + +=item B This is just sugar for the type constraint construction syntax. -Takes a block/code ref as an argument. When the type constraint is -tested, the supplied code is run with the value to be tested in -$_. This block should return true or false to indicate whether or not -the constraint check passed. +It takes a subroutine reference as an argument. When the type +constraint is tested, the reference is run with the value to be tested +in C<$_>. This reference should return true or false to indicate +whether or not the constraint check passed. -=item B +=item B This is just sugar for the type constraint construction syntax. -Takes a block/code ref as an argument. When the type constraint fails, -then the code block is run (with the value provided in $_). This code -ref should return a string, which will be used in the text of the -exception thrown. +It takes a subroutine reference as an argument. When the type +constraint fails, then the code block is run with the value provided +in C<$_>. This reference should return a string, which will be used in +the text of the exception thrown. -=item B +=item B This can be used to define a "hand optimized" version of your type constraint which can be used to avoid traversing a subtype @@ -1000,148 +989,171 @@ B You should only use this if you know what you are doing, all the built in types use this, so your subtypes (assuming they are shallow) will not likely need to use this. +=item B where { } ... > + +This creates a base type, which has no parent. + +The C function should either be called with the sugar helpers +(C, C, etc), or with a name and a hashref of +parameters: + + type( 'Foo', { where => ..., message => ... } ); + +The valid hashref keys are C, C, and C. + =back =head2 Type Coercion Constructors -Type constraints can also contain type coercions as well. If you -ask your accessor to coerce, then Moose 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. +You can define coercions for type constraints, which allow you to +automatically transform values to something valid for the type +constraint. If you ask your accessor to coerce, then Moose 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 L for an example of how to use these. =over 4 -=item B +=item B<< coerce 'Name' => from 'OtherName' => via { ... } >> -=item B +This defines a coercion from one type to another. The C argument +is the type you are coercing I. + +=item B This is just sugar for the type coercion construction syntax. -=item B +It takes a single type name (or type object), which is the type being +coerced I. + +=item B This is just sugar for the type coercion construction syntax. +It takes a subroutine reference. This reference will be called with +the value to be coerced in C<$_>. It is expected to return a new value +of the proper type for the coercion. + =back -=head2 Type Constraint Construction & Locating +=head2 Creating and Finding Type Constraints + +These are additional functions for creating and finding type +constraints. Most of these functions are not available for +importing. The ones that are importable as specified. =over 4 -=item B +=item B -Given a string that is expected to match a type constraint, will normalize the -string so that extra whitespace and newlines are removed. +This function can be used to locate the L +object for a named type. -=item B +This function is importable. -Given string with C<$pipe_separated_types> or a list of C<@type_constraint_names>, -this will return a L instance. +=item B -=item B +This function will register a L with the +global type registry. -Given a C<$type_name> in the form of: +This function is importable. - BaseType[ContainerType] +=item B -this will extract the base type and container type and build an instance of -L for it. +This method takes a type constraint name and returns the normalized +form. This removes any whitespace in the string. -=item B +=item B -Given a class name it will create a new L -object for that class name. +This can take a union type specification like C<'Int|ArrayRef[Int]'>, +or a list of names. It returns a new +L object. -=item B +=item B -Given a role name it will create a new L -object for that role name. +Given a C<$type_name> in the form of C<'BaseType[ContainerType]'>, +this will create a new L +object. The C must exist already exist as a parameterizable +type. -=item B +=item B -=item B +Given a class name this function will create a new +L object for that class name. -This will attempt to find or create a type constraint given the a C<$type_name>. -If it cannot find it in the registry, it will see if it should be a union or -container type an create one if appropriate +The C<$options> is a hash reference that will be passed to the +L constructor (as a hash). -=item B +=item B -This function will first call C with the type name. +Given a role name this function will create a new +L object for that role name. -If no type is found or created, but C<$options_for_anon_type> are provided, it -will create the corresponding type. +The C<$options> is a hash reference that will be passed to the +L constructor (as a hash). -This was used by the C and C parameters to L -and are now superseded by C and -C. +=item B -=item B +Given a tpye name, this first attempts to find a matching constraint +in the global registry. -=item B +If the type name is a union or parameterized type, it will create a +new object of the appropriate, but if given a "regular" type that does +not yet exist, it simply returns false. -Attempts to parse the type name using C and if -no appropriate constraint is found will create a new anonymous one. +When given a union or parameterized type, the member or base type must +already exist. -The C variant will use C and the C -variant will use C. +If it creates a new union or parameterized type, it will add it to the +global registry. -=item B +=item B -This function can be used to locate a specific type constraint -meta-object, of the class L or a -derivative. What you do with it from there is up to you :) +=item B -=item B +These functions will first call C. If +that function does not return a type, a new anonymous type object will +be created. -This function will register a named type constraint with the type registry. +The C variant will use C and the +C variant will use C. =item B -Fetch the L object which +Returns the L object which keeps track of all type constraints. =item B -This will return a list of type constraint names, you can then -fetch them using C if you -want to. +This will return a list of type constraint names in the global +registry. You can then fetch the actual type object using +C. =item B -This will return a list of builtin type constraints, meaning, -those which are defined in this module. See the section -labeled L for a complete list. +This will return a list of builtin type constraints, meaning those +which are defined in this module. See the L +section for a complete list. =item B -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. +This will export all the current type constraints as functions into +the caller's namespace (C, C, etc). Right now, this is +mostly used for testing, but it might prove useful to others. =item B -This returns all the parameterizable types that have been registered. +This returns all the parameterizable types that have been registered, +as a list of type objects. -=item B +=item B Adds C<$type> to the list of parameterizable types =back -=head2 Namespace Management - -=over 4 - -=item B - -This will remove all the type constraint keywords from the -calling class namespace. - -=back - =head1 BUGS All complex software has bugs lurking in it, and this module is no