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

       Chad Granum exodist7@gmail.com

       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.

perl v5.36.0                                       2022-12-12                                 Meta::Builder(3pm)

       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.

       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.

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

       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(...);

           ...;

       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.