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
-MooseX::MetaDescription version 0.01
+MooseX::MetaDescription version 0.02
===========================
See the individual module documentation for more information
package MooseX::MetaDescription;
use Moose;
-our $VERSION = '0.01';
+our $VERSION = '0.02';
our $AUTHORITY = 'cpan:STEVAN';
use MooseX::MetaDescription::Meta::Class;
=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
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<meta>
+
+The Moose metaclass.
+
+=back
+
=head1 BUGS
All complex software has bugs lurking in it, and this module is no
The actual attribute that is being described.
+=item B<meta>
+
+The Moose metaclass.
+
=back
=head1 BUGS
package MooseX::MetaDescription::Meta::Attribute;
use Moose;
-our $VERSION = '0.01';
+our $VERSION = '0.02';
our $AUTHORITY = 'cpan:STEVAN';
extends 'Moose::Meta::Attribute';
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<MooseX::MetaDescription> 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<MooseX::MetaDescription::Meta::Trait> refer to that
+module for the complete description.
+
+=over 4
+
+=item B<description>
+
+=item B<metadescription_classname>
+
+=item B<metadescription>
+
+=item B<meta>
+
+=back
=head1 BUGS
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<MooseX::MetaDescription> 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<MooseX::MetaDescription::Meta::Trait> refer to that
+module for the complete description.
+
+=over 4
+
+=item B<description>
+
+=item B<metadescription_classname>
+
+=item B<metadescription>
+
+=item B<meta>
+
+=back
=head1 BUGS
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<MooseX::MetaDescription> for an example of usage.
+This is the core of the Meta Description functionality, it is a role that is done
+by both L<MooseX::MetaDescription::Meta::Attribute> and L<MooseX::MetaDescription::Meta::Class>
+and can be used on it's own as a meta-attribute trait.
=head1 METHODS
=item B<description>
+The description C<HASH> ref is stored here.
+
=item B<metadescription_classname>
+This provides the name of the metadescription class, currently this
+defaults to L<MooseX::MetaDescription::Description>. It is read only
+and so can only be specified at instance construction time.
+
=item B<metadescription>
+This is the instance of the class specified in C<metadescription_classname>
+it is generated lazily and is also read-only. In general you will never
+need to set this yourself, but simply set C<metadescription_classname>
+and it will all just work.
+
+
+=item B<meta>
+
+The L<Moose::Role> metaclass.
+
=back
=head1 BUGS
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
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(
'Hello' => 'Earth',
'World' => 'Hello'
},
- '... got the right class description'
+ '... got the right class description (inherited and changed)'
);
}
'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)'
+ );
+}
projects / gitmo/MooseX-MetaDescription.git / commitdiff