Meta::Builder(3pm)

✨ Meta::Builder ✨

okay bestie, welcome to Meta::Builder — the Perl module that's literally in the User Contributed Perl Documentation section and is here to help you build Meta objects that track custom metrics 💖

---

🌸 NAME 🌸

Meta::Builder — tools for creating Meta objects to track custom metrics. that's it, that's the whole vibe. periodt. 💅

---

🦋 DESCRIPTION 🦋

okay so, Meta programming is becoming more and more popular. and why?? because 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. iykyk.

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.

fr fr: if a specialized Meta object tool is available to meet your needs please use it. no cap.

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. iconic behavior honestly. 👑

---

🎀 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. your choice bestie, both are valid 🫶

---

🌈 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. 🔒 the lock-in is real.

---

👑 AUTHORS 👑

Chad Granum exodist7@gmail.com — the main character who made all this happen 💅

---

🍓 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. (yes bestie, that's the dramatic part, but it's also literally the actual legal text so don't skip it 💀)

---

okay that's the whole page!! slay 💖 this was Meta::Builder, perl v5.36.0, dated 2022-12-12, filed under User Contributed Perl Documentation. go build some meta objects, you've got this 🫶✨