From: Stevan Little Date: Wed, 7 May 2008 17:08:32 +0000 (+0000) Subject: 0.02 X-Git-Tag: 0.04~12 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=56e78a9caff840fb68085ead8837a64c839740de;p=gitmo%2FMooseX-MetaDescription.git 0.02 --- diff --git a/Changes b/Changes index 99f4dde..8978051 100644 --- a/Changes +++ b/Changes @@ -1,6 +1,8 @@ Revision history for Perl extension MooseX::MetaDescription -0.02 +0.02 Wed. May 7, 2008 + ~~ documentation added for all modules ~~ + * MooseX::MetaDescription::Meta::Trait - making metadescription attribute default also load the metadescription class diff --git a/README b/README index 8cc32f7..6b9a211 100644 --- a/README +++ b/README @@ -1,4 +1,4 @@ -MooseX::MetaDescription version 0.01 +MooseX::MetaDescription version 0.02 =========================== See the individual module documentation for more information diff --git a/lib/MooseX/MetaDescription.pm b/lib/MooseX/MetaDescription.pm index e88653c..2695293 100644 --- a/lib/MooseX/MetaDescription.pm +++ b/lib/MooseX/MetaDescription.pm @@ -1,7 +1,7 @@ package MooseX::MetaDescription; use Moose; -our $VERSION = '0.01'; +our $VERSION = '0.02'; our $AUTHORITY = 'cpan:STEVAN'; use MooseX::MetaDescription::Meta::Class; @@ -20,40 +20,40 @@ MooseX::MetaDescription - A framework for adding additional metadata to Moose cl =head1 SYNOPSIS - package Foo; - use metaclass 'MooseX::MetaDescription::Meta::Class' => ( - # add class-level metadata - description => { - 'Hello' => 'World' - } - ); - use Moose; - - has 'bar' => ( - metaclass => 'MooseX::MetaDescription::Meta::Attribute', - is => 'ro', - isa => 'Str', - default => sub { Bar->new() }, - # add attribute level metadata - description => { - node_type => 'element', - } - ); - - my $foo = Foo->new; - - $foo->meta->description; # { 'Hello' => 'World' } - - my $bar = $foo->meta->get_attribute('bar'); - - # access the desciption HASH directly - $bar->description; # { node_type => 'element' } - - # or access the instance of MooseX::MetaDescription::Description - $bar->metadescription; - - # access the original attribute metaobject from the metadesc too - $bar->metadescription->descriptor == $bar; + package Foo; + use metaclass 'MooseX::MetaDescription::Meta::Class' => ( + # add class-level metadata + description => { + 'Hello' => 'World' + } + ); + use Moose; + + has 'bar' => ( + metaclass => 'MooseX::MetaDescription::Meta::Attribute', + is => 'ro', + isa => 'Str', + default => sub { Bar->new() }, + # add attribute level metadata + description => { + node_type => 'element', + } + ); + + my $foo = Foo->new; + + $foo->meta->description; # { 'Hello' => 'World' } + + my $bar = $foo->meta->get_attribute('bar'); + + # access the desciption HASH directly + $bar->description; # { node_type => 'element' } + + # or access the instance of MooseX::MetaDescription::Description + $bar->metadescription; + + # access the original attribute metaobject from the metadesc too + $bar->metadescription->descriptor == $bar; =head1 DESCRIPTION @@ -62,6 +62,16 @@ metadata to your Moose classes and attributes. This will allow you to track out of band data along with attributes, which is very useful for say serializing Moose classes in HTML or XML. +=head METHODS + +=over 4 + +=item B + +The Moose metaclass. + +=back + =head1 BUGS All complex software has bugs lurking in it, and this module is no diff --git a/lib/MooseX/MetaDescription/Description.pm b/lib/MooseX/MetaDescription/Description.pm index 99ed908..03c87fd 100644 --- a/lib/MooseX/MetaDescription/Description.pm +++ b/lib/MooseX/MetaDescription/Description.pm @@ -35,6 +35,10 @@ attribute it is describing. The actual attribute that is being described. +=item B + +The Moose metaclass. + =back =head1 BUGS diff --git a/lib/MooseX/MetaDescription/Meta/Attribute.pm b/lib/MooseX/MetaDescription/Meta/Attribute.pm index 0d645c5..a46e2dd 100644 --- a/lib/MooseX/MetaDescription/Meta/Attribute.pm +++ b/lib/MooseX/MetaDescription/Meta/Attribute.pm @@ -1,7 +1,7 @@ package MooseX::MetaDescription::Meta::Attribute; use Moose; -our $VERSION = '0.01'; +our $VERSION = '0.02'; our $AUTHORITY = 'cpan:STEVAN'; extends 'Moose::Meta::Attribute'; @@ -17,10 +17,45 @@ __END__ MooseX::MetaDescription::Meta::Attribute - Custom attribute metaclass for meta-descriptions +=head1 SYNOPSIS + + package Foo; + use Moose; + + has 'bar' => ( + # use the meta description attribute metaclass for this attr + metaclass => 'MooseX::MetaDescription::Meta::Attribute', + is => 'ro', + isa => 'Str', + default => sub { 'Foo::bar' }, + description => { + baz => 'Foo::bar::baz', + gorch => 'Foo::bar::gorch', + } + ); + =head1 DESCRIPTION -Nothing worth saying yet actually, mostly internal usage only. See the -SYNPOSIS in L for an example of usage. +This module provides a custom attribute metaclass to add meta +description capabilities to your class attributes. + +=head1 METHODS + +NOTE: these are methods composed into this class from +L refer to that +module for the complete description. + +=over 4 + +=item B + +=item B + +=item B + +=item B + +=back =head1 BUGS diff --git a/lib/MooseX/MetaDescription/Meta/Class.pm b/lib/MooseX/MetaDescription/Meta/Class.pm index 80fedfe..5d1e2cc 100644 --- a/lib/MooseX/MetaDescription/Meta/Class.pm +++ b/lib/MooseX/MetaDescription/Meta/Class.pm @@ -32,10 +32,70 @@ __END__ MooseX::MetaDescription::Meta::Class - Custom class metaclass for meta-descriptions +=head1 SYNOPSIS + + package Foo; + use metaclass 'MooseX::MetaDescription::Meta::Class' => ( + description => { + 'Hello' => 'World', + } + ); + use Moose; + + package Bar; + use Moose; + + extends 'Foo'; + + # always add it *after* the extends + __PACKAGE__->meta->description->{'Hello'} = 'Earth'; + + package Baz; + use Moose; + + extends 'Bar'; + + package Gorch; + use metaclass 'MooseX::MetaDescription::Meta::Class' => ( + description => { + 'Hello' => 'World' + } + ); + use Moose; + + extends 'Baz'; + + # ... + + Foo->meta->description # { 'Hello' => 'World', 'World' => 'Hello' } + Bar->meta->description # { 'Hello' => 'Earth', 'World' => 'Hello' } # change one, inherit the other + Baz->meta->description # { 'Hello' => 'Earth', 'World' => 'Hello' } # inherit both + Gorch->meta->description # { 'Hello' => 'World' } # overrides all, no inheritance + =head1 DESCRIPTION -Nothing worth saying yet actually, mostly internal usage only. See the -SYNPOSIS in L for an example of usage. +This module provides the custom metaclass to add Meta Descriptions +to your classes. It provides a limited degree of inheritance of +meta-descriptions, the details of which are shown above in the +SYNOPSIS section. + +=head1 METHODS + +NOTE: these are methods composed into this class from +L refer to that +module for the complete description. + +=over 4 + +=item B + +=item B + +=item B + +=item B + +=back =head1 BUGS diff --git a/lib/MooseX/MetaDescription/Meta/Trait.pm b/lib/MooseX/MetaDescription/Meta/Trait.pm index babd49a..50bc1f4 100644 --- a/lib/MooseX/MetaDescription/Meta/Trait.pm +++ b/lib/MooseX/MetaDescription/Meta/Trait.pm @@ -55,10 +55,28 @@ __END__ MooseX::MetaDescription::Meta::Trait - Custom class meta-trait for meta-descriptions +=head1 SYNOPSIS + + package Foo; + use Moose; + + has 'baz' => ( + # apply this as a trait to your attribute + traits => [ 'MooseX::MetaDescription::Meta::Trait' ], + is => 'ro', + isa => 'Str', + default => sub { 'Foo::baz' }, + description => { + bar => 'Foo::baz::bar', + gorch => 'Foo::baz::gorch', + } + ); + =head1 DESCRIPTION -Nothing worth saying yet actually, mostly internal usage only. See the -SYNPOSIS in L for an example of usage. +This is the core of the Meta Description functionality, it is a role that is done +by both L and L +and can be used on it's own as a meta-attribute trait. =head1 METHODS @@ -66,10 +84,26 @@ SYNPOSIS in L for an example of usage. =item B +The description C ref is stored here. + =item B +This provides the name of the metadescription class, currently this +defaults to L. It is read only +and so can only be specified at instance construction time. + =item B +This is the instance of the class specified in C +it is generated lazily and is also read-only. In general you will never +need to set this yourself, but simply set C +and it will all just work. + + +=item B + +The L metaclass. + =back =head1 BUGS diff --git a/t/004_inheriting_class_meta_desc.t b/t/004_inheriting_class_meta_desc.t index ceff575..3a3b6bf 100644 --- a/t/004_inheriting_class_meta_desc.t +++ b/t/004_inheriting_class_meta_desc.t @@ -25,12 +25,23 @@ BEGIN { extends 'Foo'; + # always add it *after* the extends __PACKAGE__->meta->description->{'Hello'} = 'Earth'; package Baz; use Moose; extends 'Bar'; + + package Gorch; + use metaclass 'MooseX::MetaDescription::Meta::Class' => ( + description => { + 'Hello' => 'World' + } + ); + use Moose; + + extends 'Baz'; } # check the meta-desc @@ -50,6 +61,10 @@ isa_ok($baz_class, 'MooseX::MetaDescription::Meta::Class'); isa_ok($baz_class->metadescription, 'MooseX::MetaDescription::Description'); is($baz_class->metadescription->descriptor, $baz_class, '... got the circular ref'); +my $gorch_class = Gorch->meta; +isa_ok($gorch_class, 'MooseX::MetaDescription::Meta::Class'); +isa_ok($gorch_class->metadescription, 'MooseX::MetaDescription::Description'); +is($gorch_class->metadescription->descriptor, $gorch_class, '... got the circular ref'); foreach my $x ('Foo', Foo->new) { is_deeply( @@ -69,7 +84,7 @@ foreach my $x ('Bar', Bar->new) { 'Hello' => 'Earth', 'World' => 'Hello' }, - '... got the right class description' + '... got the right class description (inherited and changed)' ); } @@ -80,7 +95,16 @@ foreach my $x ('Baz', Baz->new) { 'Hello' => 'Earth', 'World' => 'Hello' }, - '... got the right class description' + '... got the right class description (inherited with changes handles correctly)' ); } +foreach my $x ('Gorch', Gorch->new) { + is_deeply( + $x->meta->description, + { + 'Hello' => 'World', + }, + '... got the right class description (with completely overriden desc)' + ); +}