Meta::...r::Base(3pm)

🌸 NAME 🌸

Meta::Builder::Base — the base class for all Meta::Builder Meta Objects. it's giving "blueprint of blueprints", bestie. 💖

---

✨ DESCRIPTION ✨

okay so, this is the base class for every Meta::Builder Meta object out there. This is literally where the methods that define brand-new metrics and actions live. The whole point of this class is that it lets you create dynamic meta objects. yes queen, dynamic. 🔥

---

🦋 SYNOPSIS 🦋

so first up, your My/Meta.pm:

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

use base 'Meta::Builder::Base';

# Name the accessor that will be defined in the class that uses the meta object
# It is used to retrieve the classes meta object.
__PACKAGE__->set_accessor( "mymeta" );

# Add a metric with two actions
__PACKAGE__->add_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
__PACKAGE__->add_action( 'mymetric', get_ref => sub { shift });

# Add some predefined metric types + actions
__PACKAGE__->add_hash_metric( 'my_hashmetric' );
__PACKAGE__->add_lists_metric( 'my_listsmetric' );

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

...;

periodt. that's the whole vibe. 💅

---

👑 PACKAGE METRIC 👑

so every single time you make a new instance of a meta-object, you must hand over the name of the package that the meta-object belongs to. The 'package' metric gets set to that package name, and you can grab it back with the 'package' method: $meta->package(). easy. 🎀

---

🍓 HASH METRICS 🍓

Hash metrics are metrics that hold key/value pairs. You define one either with the "hash_metric()" function or with the "$meta->add_hash_metric()" method. And guess what — these actions come auto-defined for hash metrics, no extra work:

• $meta->add_METRIC( $key, $value ) — adds a key/value pair to the metric. ⚠️ it will throw an exception if the metric already has a value for that key, so watch out bestie.
• $value = $meta->get_METRIC( $key ) — gets the value for a specified key.
• $bool = $meta->has_METRIC( $key ) — checks that the metric actually has that key defined.
• $meta->clear_METRIC( $key ) — clears the specified key/value pair in the metric. (returns nothing, it's a void queen)
• $value = $meta->pull_METRIC( $key ) — gets the value for that key, then clears the pair from the metric. get it and dip. ✨

---

🌈 LISTS METRICS 🌈

• $meta->push_METRIC( $key, @values ) — pushes values into the specified list for the given metric.
• @values = $meta->get_METRIC( $key ) — gets the values for a specified key.
• $bool = $meta->has_METRIC( $key ) — checks that the metric has the specified list.
• $meta->clear_METRIC( $key ) — clears the specified list in the metric. (returns nothing)
• @values = $meta->pull_METRIC( $key ) — gets the values for the specified list in the metric, then clears the list. snatch and run. 💨

---

💜 CLASS METHODS 💜

• $meta = $class->new( $package, %metrics ) — creates a new instance of the meta-class and applies it to $package.
• $metadata = $class->meta_meta() — gets the meta data for the meta-class itself. (yes, the meta-class is built using meta-data. meta-meta. we love recursion.) 🌀
• $new_hashref = $class->gen_hash() — generates a new empty hashref.
• $name = $class->action_method_name( $metric, $action ) — generates the name of the method for the given metric and action. Override this if you do not like the METRIC_ACTION() method names. it's your house, redecorate it. 🏡

---

🧚 OBJECT METHODS 🧚

• $package = $meta->package() — gets the name of the package to which this meta-class applies.
• $meta->set_accessor( $name ) — sets the accessor used to retrieve the meta-object from the class it applies to.
• $meta->add_hash_metric( $metric, %actions ) — adds a hash metric (go peek at "HASH METRICS" above 👀).

%actions should contain action => sub {...} pairs for constructing actions (see add_action()).

• $meta->add_lists_metric( $metric, %actions ) — adds a lists metric (see "LISTS METRICS").

%actions should contain action => sub {...} pairs for constructing actions (see add_action()).

• $meta->add_metric( $metric, \&generator, %actions ) — adds a custom metric. The second argument should be a sub that generates a default value for the metric.

%actions should contain action => sub {...} pairs for constructing actions (see add_action()).

• $meta->add_action( $metric, $action => sub { ... } ) — adds an action for the specified metric. See "ACTION AND HOOK METHODS" for the deets on writing an action coderef.
• $meta->hook_before( $metric, $action, sub { ... }) — adds a hook for the specified metric. See "ACTION AND HOOK METHODS" for the deets on writing a hook coderef.
• $meta->hook_after( $metric, $action, sub { ... }) — adds a hook for the specified metric. See "ACTION AND HOOK METHODS" for the deets on writing a hook coderef.

---

💀 ACTION AND HOOK METHODS 💀

here's the shape of one:

sub {
    my $self = shift;
    my ( $data, $metric, $action, @args ) = @_;
    ...;
}

Action and hook methods get called when somebody calls "$meta->metric_action(...)". The order is sacred, bestie: first all the before hooks run, then the action itself, and finally the after hooks. Every single method in that chain receives the exact same unaltered arguments. And only the main action sub can return anything — everyone else, hands off. ✋

the arguments are:

0. $self — these are methods, so arg zero is the meta object itself.
1. $data — the data structure stored for the metric. This is the same as calling $meta->metric().
2. $metric — name of the metric.
3. $action — name of the action. 4+. @args — the arguments that metric_action() was called with.

---

⭐ DEFAULT ACTION METHODS ⭐

these are the default action methods used by hashmetrics and listsmetrics:

$meta->default_hash_add( $data, $metric, $action, $item, $value )
$value = $meta->default_hash_get( $data, $metric, $action, $item )
$bool = $meta->default_hash_has( $data, $metric, $action, $item )
$meta->default_hash_clear( $data, $metric, $action, $item )
$value = $meta->default_hash_pull( $data, $metric, $action, $item )
$meta->default_list_push( $data, $metric, $action, $item, @values )
@values = $meta->default_list_get( $data, $metric, $action, $item )
$bool = $meta->default_list_has( $data, $metric, $action, $item )
$meta->default_list_clear( $data, $metric, $action, $item )
@values = $meta->default_list_pull( $data, $metric, $action, $item )

---

🫶 AUTHORS 🫶

Chad Granum — exodist7@gmail.com

---

🎀 COPYRIGHT 🎀

Copyright (C) 2010 Chad Granum

Meta-Builder is free software; Standard perl licence.

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.

ngl, that all-caps warranty disclaimer is doing main character energy in a "please don't sue me" way. 💀

---

and that's a wrap, bestie! this little gem lives in the perl manual, Meta::...r::Base(3pm) (you know the one), documented for perl v5.36.0, dated 2022-12-12. go forth and build your metas. slay. 👑✨