[gitmo/MooseX-Types-Structured.git] / lib / MooseX / Types / Structured.pm

package MooseX::Types::Structured;

use 5.008;
use Moose;
use Moose::Util::TypeConstraints;
use MooseX::Meta::TypeConstraint::Structured;
use MooseX::Types -declare => [qw(Dict Tuple)];

our $VERSION = '0.05';
our $AUTHORITY = 'cpan:JJNAPIORK';

=head1 NAME

MooseX::Types::Structured - Structured Type Constraints for Moose

=head1 SYNOPSIS

The following is example usage for this module.

    package MyApp::MyClass;
	
    use Moose;
    use MooseX::Types::Moose qw(Str Int);
    use MooseX::Types::Structured qw(Dict Tuple);

    has name => (isa=>Dict[first_name=>Str, last_name=>Str]);

Then you can instantiate this class with something like:

    my $instance = MyApp::MyClass->new(
        name => {
            first_name=>'John', 
            last_name=>'Napiorkowski',
        },
    );

But all of these would cause a constraint error for the 'name' attribute:

    MyApp::MyClass->new( name=>'John' );
    MyApp::MyClass->new( name=>{first_name=>'John'} );
    MyApp::MyClass->new( name=>{first_name=>'John', age=>39} );

Please see the test cases for more examples.

=head1 DESCRIPTION

A structured type constraint is a standard container L</Moose> type constraint,
such as an arrayref or hashref, which has been enhanced to allow you to
explicitly name all the allow type constraints inside the structure.  The
generalized form is:

    TypeConstraint[TypeParameters]

Where 'TypeParameters' is an array or hash of L</Moose::Meta::TypeConstraint> 
type constraints.

This type library enables structured type constraints. It is build on top of the
L<MooseX::Types> library system, so you should review the documentation for that
if you are not familiar with it.

=head2 Comparing Parameterized types to Structured types

Parameterized constraints are built into the core Moose types 'HashRef' and
'ArrayRef'.  Structured types have similar functionality, so their syntax is
likewise similar. For example, you could define a parameterized constraint like:

    subtype ArrayOfInts,
     as Arrayref[Int];

which would constraint a value to something like [1,2,3,...] and so on.  On the
other hand, a structured type constraint explicitly names all it's allowed type
parameter constraints.  For the example:

    subtype StringFollowedByInt,
     as Tuple[Str,Int];
	
would constrain it's value to something like ['hello', 111] but ['hello', 'world']
would fail, as well as ['hello', 111, 'world'] and so on.

Structured Constraints are not limited to arrays.  You can define a structure
against a hashref with 'Dict' as in this example:

    subtype FirstNameLastName,
     as Dict[firste=>Str, lastname=>Str];

This would constrain a hashref to something like:

    {firstname=>'Vanessa', lastname=>'Li'};
    
but all the following would fail validation:

     {first=>'Vanessa', last=>'Li'};
     {firstname=>'Vanessa', lastname=>'Li', middlename=>'NA'};   
     ['Vanessa', 'Li']; 

These structures can be as simple or elaborate as you wish.  You can even
combine various structured, parameterized and simple constraints all together:

    subtype crazy,
     as Tuple[
        Int,
        Dict[name=>Str, age=>Int],
        ArrayRef[Int]
     ];
	
Which would match "[1, {name=>'John', age=>25},[10,11,12]]".  Please notice how
the type parameters can be visually arranged to your liking and to improve the
clarity of your meaning.  You don't need to run then altogether onto a single
line.

=head2 Alternatives

You should exercise some care as to whether or not your complex structured
constraints would be better off contained by a real object as in the following
example:

    package MyApp::MyStruct;
    use Moose;
    
    has $_ for qw(name age);
    
    package MyApp::MyClass;
    use Moose;
    
    has person => (isa=>'MyApp::MyStruct');		
    
    my $instance = MyApp::MyClass->new(
        person=>MyApp::MyStruct->new(name=>'John', age=>39),
    );
	
This method may take some additional time to setup but will give you more
flexibility.  However, structured constraints are highly compatible with this
method, granting some interesting possibilities for coercion.  Try:

    subtype 'MyStruct',
     as 'MyApp::MyStruct';
    
    coerce 'MyStruct',
     from (Dict[name=>Str, age=>Int]),
     via { MyApp::MyStruct->new(%$_) },
     from (Dict[last_name=>Str, first_name=>Str, dob=>DateTime]),
     via {
        my $name = $_->{first_name} .' '. $_->{last_name};
        my $age = DateTime->now - $_->{dob};
        MyApp::MyStruct->new( name=>$name, age=>$age->years );
     };
	 
=head2 Subtyping a structured subtype

You need to exercise some care when you try to subtype a structured type
as in this example:

    subtype Person,
     as Dict[name=>Str, age=>Int];
	 
    subtype FriendlyPerson,
     as Person[name=>Str, age=>Int, totalFriends=>Int];
	 
This will actually work BUT you have to take care that the subtype has a
structure that does not contradict the structure of it's parent.  For now the
above works, but I will clarify the syntax for this at a future point, so
it's recommended to avoid (should not realy be needed so much anyway).  For
now this is supported in an EXPERIMENTAL way.  Your thoughts, test cases and
patches are welcomed for discussion.

=head2 Coercions

Coercions currently work for 'one level' deep.  That is you can do:

    subtype Person,
     as Dict[name=>Str, age=>Int];
    
    subtype Fullname,
     as Dict[first=>Str, last=>Str];
    
    coerce Person,
     ## Coerce an object of a particular class
     from BlessedPersonObject,
     via { +{name=>$_->name, age=>$_->age} },
     ## Coerce from [$name, $age]
     from ArrayRef,
     via { +{name=>$_->[0], age=>$_->[1] },
     ## Coerce from {fullname=>{first=>...,last=>...}, dob=>$DateTimeObject}
     from Dict[fullname=>Fullname, dob=>DateTime],
     via {
        my $age = $_->dob - DateTime->now;
        +{
            name=> $_->{fullname}->{first} .' '. $_->{fullname}->{last},
            age=>$age->years
        }
     };
	 
And that should just work as expected.  However, if there are any 'inner'
coercions, such as a coercion on 'Fullname' or on 'DateTime', that coercion
won't currently get activated.

Please see the test '07-coerce.t' for a more detailed example.

=head1 TYPE CONSTRAINTS

This type library defines the following constraints.

=head2 Tuple[@constraints]

This defines an arrayref based constraint which allows you to validate a specific
list of constraints.  For example:

    Tuple[Int,Str]; ## Validates [1,'hello']
    Tuple[Str|Object, Int]; ##Validates ['hello', 1] or [$object, 2]

=head2 Dict [%constraints]

This defines a hashref based constraint which allowed you to validate a specific
hashref.  For example:

    Dict[name=>Str, age=>Int]; ## Validates {name=>'John', age=>39}

=head1 EXAMPLES

Here are some additional example usage for structured types.  All examples can
be found also in the 't/examples.t' test.  Your contributions are also welcomed.

=head2 Normalize a HashRef

You need a hashref to conform to a canonical structure but are required accept a
bunch of different incoming structures.  You can normalize using the Dict type
constraint and coercions.  This example also shows structured types mixed which
other MooseX::Types libraries.

    package Test::MooseX::Meta::TypeConstraint::Structured::Examples::Normalize;
    
    use Moose;
    use DateTime;
    
    use MooseX::Types::Structured qw(Dict Tuple);
    use MooseX::Types::DateTime qw(DateTime);
    use MooseX::Types::Moose qw(Int Str Object);
    use MooseX::Types -declare => [qw(Name Age Person)];
     
    subtype Person,
     as Dict[name=>Str, age=>Int];
    
    coerce Person,
     from Dict[first=>Str, last=>Str, years=>Int],
     via { +{
        name => "$_->{first} $_->{last}",
        age=>$_->{years},
     }},
     from Dict[fullname=>Dict[last=>Str, first=>Str], dob=>DateTime],
     via { +{
        name => "$_->{fullname}{first} $_->{fullname}{last}",
        age => ($_->{dob} - 'DateTime'->now)->years,
     }};
     
    has person => (is=>'rw', isa=>Person, coerce=>1);

=cut

Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
	MooseX::Meta::TypeConstraint::Structured->new(
		name => "MooseX::Types::Structured::Tuple" ,
		parent => find_type_constraint('ArrayRef'),
		constraint_generator=> sub {
			## Get the constraints and values to check
			my @type_constraints = @{shift @_};            
			my @values = @{shift @_};
			## Perform the checking
			while(@type_constraints) {
				my $type_constraint = shift @type_constraints;
				if(@values) {
					my $value = shift @values;
					unless($type_constraint->check($value)) {
						return;
					}				
				} else {
					return;
				}
			}
			## Make sure there are no leftovers.
			if(@values) {
				return;
			} elsif(@type_constraints) {
				return;
			}else {
				return 1;
			}
		}
	)
);
	
Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
	MooseX::Meta::TypeConstraint::Structured->new(
		name => "MooseX::Types::Structured::Dict",
		parent => find_type_constraint('HashRef'),
		constraint_generator=> sub {
			## Get the constraints and values to check
			my %type_constraints = @{shift @_};            
			my %values = %{shift @_};
			## Perform the checking
			while(%type_constraints) {
				my($key, $type_constraint) = each %type_constraints;
				delete $type_constraints{$key};
				if(exists $values{$key}) {
					my $value = $values{$key};
					delete $values{$key};
					unless($type_constraint->check($value)) {
						return;
					}
				} else {
					return;
				}
			}
			## Make sure there are no leftovers.
			if(%values) {
				return;
			} elsif(%type_constraints) {
				return;
			}else {
				return 1;
			}
		},
	)
);

=head1 SEE ALSO

The following modules or resources may be of interest.

L<Moose>, L<MooseX::TypeLibrary>, L<Moose::Meta::TypeConstraint>,
L<MooseX::Meta::TypeConstraint::Structured>

=head1 TODO

Need to clarify deep coercions, need to clarify subtypes of subtypes.

=head1 AUTHOR

John Napiorkowski, C<< <jjnapiork@cpan.org> >>

=head1 COPYRIGHT & LICENSE

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

=cut
	
1;
Commit	Line	Data
d24da8ec	1	package MooseX::Types::Structured;
d24da8ec	2
98336987	3	use 5.008;
6c2f284c	4	use Moose;
6c2f284c	5	use Moose::Util::TypeConstraints;
a30fa891	6	use MooseX::Meta::TypeConstraint::Structured;
a30fa891	7	use MooseX::Types -declare => [qw(Dict Tuple)];
011bacc6	8
d87e8b74	9	our $VERSION = '0.05';
d24da8ec	10	our $AUTHORITY = 'cpan:JJNAPIORK';
	11
	12	=head1 NAME
	13
af1d00c9	14	MooseX::Types::Structured - Structured Type Constraints for Moose
d24da8ec	15
	16	=head1 SYNOPSIS
	17
af1d00c9	18	The following is example usage for this module.
6c2f284c	19
af1d00c9	20	package MyApp::MyClass;
6c2f284c	21
af1d00c9	22	use Moose;
	23	use MooseX::Types::Moose qw(Str Int);
	24	use MooseX::Types::Structured qw(Dict Tuple);
	25
	26	has name => (isa=>Dict[first_name=>Str, last_name=>Str]);
	27
6c2f284c	28	Then you can instantiate this class with something like:
6c2f284c	29
af1d00c9	30	my $instance = MyApp::MyClass->new(
d87e8b74	31	name => {
	32	first_name=>'John',
	33	last_name=>'Napiorkowski',
	34	},
	35	);
d24da8ec	36
d87e8b74	37	But all of these would cause a constraint error for the 'name' attribute:
6c2f284c	38
d87e8b74	39	MyApp::MyClass->new( name=>'John' );
	40	MyApp::MyClass->new( name=>{first_name=>'John'} );
	41	MyApp::MyClass->new( name=>{first_name=>'John', age=>39} );
6c2f284c	42
6c2f284c	43	Please see the test cases for more examples.
d24da8ec	44
	45	=head1 DESCRIPTION
	46
af1d00c9	47	A structured type constraint is a standard container L</Moose> type constraint,
af1d00c9	48	such as an arrayref or hashref, which has been enhanced to allow you to
59deb858	49	explicitly name all the allow type constraints inside the structure. The
af1d00c9	50	generalized form is:
	51
	52	TypeConstraint[TypeParameters]
	53
d87e8b74	54	Where 'TypeParameters' is an array or hash of L</Moose::Meta::TypeConstraint>
d87e8b74	55	type constraints.
af1d00c9	56
59deb858	57	This type library enables structured type constraints. It is build on top of the
	58	L<MooseX::Types> library system, so you should review the documentation for that
	59	if you are not familiar with it.
	60
5632ada1	61	=head2 Comparing Parameterized types to Structured types
59deb858	62
	63	Parameterized constraints are built into the core Moose types 'HashRef' and
	64	'ArrayRef'. Structured types have similar functionality, so their syntax is
	65	likewise similar. For example, you could define a parameterized constraint like:
6c2f284c	66
d87e8b74	67	subtype ArrayOfInts,
d87e8b74	68	as Arrayref[Int];
6c2f284c	69
af1d00c9	70	which would constraint a value to something like [1,2,3,...] and so on. On the
59deb858	71	other hand, a structured type constraint explicitly names all it's allowed type
af1d00c9	72	parameter constraints. For the example:
6c2f284c	73
af1d00c9	74	subtype StringFollowedByInt,
af1d00c9	75	as Tuple[Str,Int];
6c2f284c	76
59deb858	77	would constrain it's value to something like ['hello', 111] but ['hello', 'world']
d87e8b74	78	would fail, as well as ['hello', 111, 'world'] and so on.
	79
	80	Structured Constraints are not limited to arrays. You can define a structure
	81	against a hashref with 'Dict' as in this example:
	82
	83	subtype FirstNameLastName,
	84	as Dict[firste=>Str, lastname=>Str];
	85
	86	This would constrain a hashref to something like:
	87
	88	{firstname=>'Vanessa', lastname=>'Li'};
	89
	90	but all the following would fail validation:
	91
	92	{first=>'Vanessa', last=>'Li'};
	93	{firstname=>'Vanessa', lastname=>'Li', middlename=>'NA'};
	94	['Vanessa', 'Li'];
6c2f284c	95
	96	These structures can be as simple or elaborate as you wish. You can even
	97	combine various structured, parameterized and simple constraints all together:
	98
af1d00c9	99	subtype crazy,
	100	as Tuple[
	101	Int,
	102	Dict[name=>Str, age=>Int],
	103	ArrayRef[Int]
	104	];
6c2f284c	105
af1d00c9	106	Which would match "[1, {name=>'John', age=>25},[10,11,12]]". Please notice how
59deb858	107	the type parameters can be visually arranged to your liking and to improve the
	108	clarity of your meaning. You don't need to run then altogether onto a single
	109	line.
	110
	111	=head2 Alternatives
6c2f284c	112
	113	You should exercise some care as to whether or not your complex structured
	114	constraints would be better off contained by a real object as in the following
	115	example:
	116
af1d00c9	117	package MyApp::MyStruct;
	118	use Moose;
	119
	120	has $_ for qw(name age);
	121
	122	package MyApp::MyClass;
	123	use Moose;
	124
	125	has person => (isa=>'MyApp::MyStruct');
	126
	127	my $instance = MyApp::MyClass->new(
	128	person=>MyApp::MyStruct->new(name=>'John', age=>39),
	129	);
6c2f284c	130
	131	This method may take some additional time to setup but will give you more
	132	flexibility. However, structured constraints are highly compatible with this
	133	method, granting some interesting possibilities for coercion. Try:
	134
af1d00c9	135	subtype 'MyStruct',
	136	as 'MyApp::MyStruct';
	137
	138	coerce 'MyStruct',
	139	from (Dict[name=>Str, age=>Int]),
59deb858	140	via { MyApp::MyStruct->new(%$_) },
af1d00c9	141	from (Dict[last_name=>Str, first_name=>Str, dob=>DateTime]),
	142	via {
	143	my $name = $_->{first_name} .' '. $_->{last_name};
	144	my $age = DateTime->now - $_->{dob};
59deb858	145	MyApp::MyStruct->new( name=>$name, age=>$age->years );
af1d00c9	146	};
a4a88fef	147
16aea7bf	148	=head2 Subtyping a structured subtype
	149
	150	You need to exercise some care when you try to subtype a structured type
a4a88fef	151	as in this example:
d24da8ec	152
af1d00c9	153	subtype Person,
d87e8b74	154	as Dict[name=>Str, age=>Int];
a4a88fef	155
af1d00c9	156	subtype FriendlyPerson,
af1d00c9	157	as Person[name=>Str, age=>Int, totalFriends=>Int];
a4a88fef	158
16aea7bf	159	This will actually work BUT you have to take care that the subtype has a
a4a88fef	160	structure that does not contradict the structure of it's parent. For now the
59deb858	161	above works, but I will clarify the syntax for this at a future point, so
a4a88fef	162	it's recommended to avoid (should not realy be needed so much anyway). For
59deb858	163	now this is supported in an EXPERIMENTAL way. Your thoughts, test cases and
59deb858	164	patches are welcomed for discussion.
16aea7bf	165
	166	=head2 Coercions
	167
	168	Coercions currently work for 'one level' deep. That is you can do:
	169
af1d00c9	170	subtype Person,
16aea7bf	171	as Dict[name=>Str, age=>Int];
af1d00c9	172
16aea7bf	173	subtype Fullname,
16aea7bf	174	as Dict[first=>Str, last=>Str];
af1d00c9	175
af1d00c9	176	coerce Person,
d87e8b74	177	## Coerce an object of a particular class
af1d00c9	178	from BlessedPersonObject,
af1d00c9	179	via { +{name=>$_->name, age=>$_->age} },
d87e8b74	180	## Coerce from [$name, $age]
af1d00c9	181	from ArrayRef,
af1d00c9	182	via { +{name=>$_->[0], age=>$_->[1] },
d87e8b74	183	## Coerce from {fullname=>{first=>...,last=>...}, dob=>$DateTimeObject}
16aea7bf	184	from Dict[fullname=>Fullname, dob=>DateTime],
16aea7bf	185	via {
af1d00c9	186	my $age = $_->dob - DateTime->now;
	187	+{
	188	name=> $_->{fullname}->{first} .' '. $_->{fullname}->{last},
	189	age=>$age->years
	190	}
16aea7bf	191	};
	192
	193	And that should just work as expected. However, if there are any 'inner'
	194	coercions, such as a coercion on 'Fullname' or on 'DateTime', that coercion
	195	won't currently get activated.
	196
	197	Please see the test '07-coerce.t' for a more detailed example.
	198
	199	=head1 TYPE CONSTRAINTS
	200
	201	This type library defines the following constraints.
	202
	203	=head2 Tuple[@constraints]
	204
	205	This defines an arrayref based constraint which allows you to validate a specific
	206	list of constraints. For example:
	207
af1d00c9	208	Tuple[Int,Str]; ## Validates [1,'hello']
af1d00c9	209	Tuple[Str\|Object, Int]; ##Validates ['hello', 1] or [$object, 2]
16aea7bf	210
	211	=head2 Dict [%constraints]
	212
	213	This defines a hashref based constraint which allowed you to validate a specific
	214	hashref. For example:
	215
af1d00c9	216	Dict[name=>Str, age=>Int]; ## Validates {name=>'John', age=>39}
d24da8ec	217
59deb858	218	=head1 EXAMPLES
	219
	220	Here are some additional example usage for structured types. All examples can
	221	be found also in the 't/examples.t' test. Your contributions are also welcomed.
	222
	223	=head2 Normalize a HashRef
	224
	225	You need a hashref to conform to a canonical structure but are required accept a
	226	bunch of different incoming structures. You can normalize using the Dict type
	227	constraint and coercions. This example also shows structured types mixed which
	228	other MooseX::Types libraries.
	229
	230	package Test::MooseX::Meta::TypeConstraint::Structured::Examples::Normalize;
	231
	232	use Moose;
	233	use DateTime;
	234
	235	use MooseX::Types::Structured qw(Dict Tuple);
	236	use MooseX::Types::DateTime qw(DateTime);
	237	use MooseX::Types::Moose qw(Int Str Object);
	238	use MooseX::Types -declare => [qw(Name Age Person)];
	239
	240	subtype Person,
	241	as Dict[name=>Str, age=>Int];
	242
	243	coerce Person,
	244	from Dict[first=>Str, last=>Str, years=>Int],
	245	via { +{
	246	name => "$_->{first} $_->{last}",
	247	age=>$_->{years},
	248	}},
	249	from Dict[fullname=>Dict[last=>Str, first=>Str], dob=>DateTime],
	250	via { +{
	251	name => "$_->{fullname}{first} $_->{fullname}{last}",
	252	age => ($_->{dob} - 'DateTime'->now)->years,
	253	}};
	254
	255	has person => (is=>'rw', isa=>Person, coerce=>1);
	256
a30fa891	257	=cut
a30fa891	258
67a8bc04	259	Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
	260	MooseX::Meta::TypeConstraint::Structured->new(
	261	name => "MooseX::Types::Structured::Tuple" ,
	262	parent => find_type_constraint('ArrayRef'),
	263	constraint_generator=> sub {
	264	## Get the constraints and values to check
	265	my @type_constraints = @{shift @_};
	266	my @values = @{shift @_};
	267	## Perform the checking
	268	while(@type_constraints) {
	269	my $type_constraint = shift @type_constraints;
a30fa891	270	if(@values) {
67a8bc04	271	my $value = shift @values;
	272	unless($type_constraint->check($value)) {
	273	return;
	274	}
	275	} else {
a30fa891	276	return;
a30fa891	277	}
a30fa891	278	}
67a8bc04	279	## Make sure there are no leftovers.
	280	if(@values) {
	281	return;
	282	} elsif(@type_constraints) {
	283	return;
	284	}else {
	285	return 1;
	286	}
	287	}
	288	)
	289	);
	290
	291	Moose::Util::TypeConstraints::get_type_constraint_registry->add_type_constraint(
	292	MooseX::Meta::TypeConstraint::Structured->new(
	293	name => "MooseX::Types::Structured::Dict",
	294	parent => find_type_constraint('HashRef'),
	295	constraint_generator=> sub {
	296	## Get the constraints and values to check
	297	my %type_constraints = @{shift @_};
	298	my %values = %{shift @_};
	299	## Perform the checking
	300	while(%type_constraints) {
	301	my($key, $type_constraint) = each %type_constraints;
	302	delete $type_constraints{$key};
	303	if(exists $values{$key}) {
	304	my $value = $values{$key};
	305	delete $values{$key};
	306	unless($type_constraint->check($value)) {
a30fa891	307	return;
a30fa891	308	}
67a8bc04	309	} else {
a30fa891	310	return;
a30fa891	311	}
67a8bc04	312	}
	313	## Make sure there are no leftovers.
	314	if(%values) {
	315	return;
	316	} elsif(%type_constraints) {
	317	return;
	318	}else {
	319	return 1;
	320	}
	321	},
	322	)
	323	);
d24da8ec	324
	325	=head1 SEE ALSO
	326
	327	The following modules or resources may be of interest.
	328
a30fa891	329	L<Moose>, L<MooseX::TypeLibrary>, L<Moose::Meta::TypeConstraint>,
a30fa891	330	L<MooseX::Meta::TypeConstraint::Structured>
d24da8ec	331
16aea7bf	332	=head1 TODO
	333
	334	Need to clarify deep coercions, need to clarify subtypes of subtypes.
	335
d24da8ec	336	=head1 AUTHOR
	337
	338	John Napiorkowski, C<< <jjnapiork@cpan.org> >>
	339
	340	=head1 COPYRIGHT & LICENSE
	341
	342	This program is free software; you can redistribute it and/or modify
	343	it under the same terms as Perl itself.
	344
	345	=cut
67a8bc04	346
67a8bc04	347	1;