NAME

       Meta::Builder - Tools for creating Meta objects to track custom metrics.

DESCRIPTION

       Meta programming is becoming more and more popular. The popularity of Meta programming
       comes from the fact that many problems are made significantly easier. There are a few
       specialized Meta tools out there, for instance <Class:MOP> which is used by Moose to track
       class metadata.

       Meta::Builder is designed to be a generic tool for writing Meta objects. Unlike
       specialized tools, Meta::Builder makes no assumptions about what metrics you will care
       about. Meta::Builder also makes it simple for others to extend your meta-object based
       tools by providing hooks for other packages to add metrics to your meta object.

       If a specialized Meta object tool is available to meet your needs please use it. However
       if you need a simple Meta object to track a couple metrics, use Meta::Builder.

       Meta::Builder is also low-sugar and low-dep. In most cases you will not want a class that
       needs a meta object to use your meta-object class directly. Rather you will usually want
       to create a sugar class that exports enhanced API functions that manipulate the meta
       object.

SYNOPSIS

       My/Meta.pm:

           package My::Meta;
           use strict;
           use warnings;

           use Meta::Builder;

           # Name the accessor that will be defined in the class that uses the meta object
           # It is used to retrieve the classes meta object.
           accessor "mymeta";

           # Add a metric with two actions
           metric mymetric => sub { [] },
                  pop => sub {
                      my $self = shift;
                      my ( $data ) = @_;
                      pop @$data;
                  },
                  push => sub {
                      my $self = shift;
                      my ( $data, $metric, $action, @args ) = @_;
                      push @$data => @args;
                  };

           # Add an additional action to the metric
           action mymetric => ( get_ref => sub { shift });

           # Add some predefined metric types + actions
           hash_metric 'my_hashmetric';
           lists_metric 'my_listsmetric';

       My.pm:

           package My;
           use strict;
           use warnings;

           use My::Meta;

           My::Meta->new( __PACKAGE__ );

           # My::Meta defines mymeta() as the accessor we use to get our meta object.
           # this is the ONLY way to get the meta object for this class.

           mymeta()->mymetric_push( "some data" );
           mymeta()->my_hashmetric_add( key => 'value' );
           mymeta()->my_listsmetric_push( list => qw/valueA valueB/ );

           # It works fine as an object/class method as well.
           __PACKAGE__->mymeta->do_thing(...);

           ...;

USING

       When you use Meta::Builder your class is automatically turned into a subclass of
       Meta::Builder::Base. In addition several "sugar" functions are exported into your
       namespace. To avoid the "sugar" functions you can simply subclass Meta::Builder::Base
       directly.

EXPORTS

       metric( $name, \&generator, %actions )
           Wrapper around "caller-"add_metric()>. See Meta::Builder::Base.

       action( $metric, $name, $code )
           Wrapper around "caller-"add_action()>. See Meta::Builder::Base.

       hash_metric( $name, %additional_actions )
           Wrapper around "caller-"add_hash_metric()>. See Meta::Builder::Base.

       lists_metric( $name, %additional_actions )
           Wrapper around "caller-"add_lists_metric()>. See Meta::Builder::Base.

       before( $metric, $action, $code )
           Wrapper around "caller-"hook_before()>. See Meta::Builder::Base.

       after( $metric, $action, $code )
           Wrapper around "caller-"hook_after()>. See Meta::Builder::Base.

       accessor( $name )
           Wrapper around "caller-"set_accessor()>. See Meta::Builder::Base.

       make_immutable()
           Overrides all functions/methods that alter the meta objects meta-data. This in effect
           prevents anything from adding new metrics, actions, or hooks without directly editing
           the metadata.

AUTHORS

       Chad Granum exodist7@gmail.com

COPYRIGHT

       Copyright (C) 2010 Chad Granum

       Meta-Builder is free software and is licensed under the same terms as Perl itself.

       Meta-Builder is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
       without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
       See the license for more details.