Mixin:...Fields(3pm)

💖 Mixin::ExtraFields — the manual, but make it cute 💖

hey bestie!! so this is the page for Mixin::ExtraFields, from the User Contributed Perl Documentation crew — it's giving "add extra stashes of data to your objects" and honestly? it ate. 🎀

---

✨ NAME ✨

Mixin::ExtraFields</purl> — add extra stashes of data to your objects 💅

---

🌸 VERSION 🌸

version 0.140003 — yeah that's the number, no cap 📌

---

🦋 SYNOPSIS 🦋

okay so if you use the ExtraFields mixin in your class:

package Corporate::WorkOrder;

use Mixin::ExtraFields -fields => {
  id      => 'workorder_id',
  moniker => 'note',
  driver  => { HashGuts => { hash_key => '_notes' } }
};

…your objects will then have methods for manipulating their extra fields:

my $workorder = Corporate::WorkOrder->retrieve(1234);

if ($workorder->note_exists('debug_next')) {
  warn $workorder->note_get('debug_next');
  $workorder->note_delete('debug_next');
}

if ($workorder->note_get('time_bomb')) {
  $workorder->note_delete_all;
  $workorder->note_set(
    last_explosion  => time,
    explosion_cause => 'time bomb',
  );
}

like… the way that just WORKS. 🔥

---

💜 DESCRIPTION 💜

Sometimes your well-defined object needs a way to tack on arbitrary extra fields. Maybe it's a set of session-specific ephemeral data, maybe it's a stash of settings that need to be easy to grow over time, maybe it's literally any sort of name-and-value parameters you can dream up. Adding more and more methods gets cumbersome real fast, and it's not even helpful when the names vary a whole lot. And yeah, you could just reach into an object's guts directly — simple, sure — but that's difficult to control when subclassing, and it makes changing your object's structure a whole ordeal. 😭

Mixin::ExtraFields gives you a simple way to add an arbitrary number of stashes for named data. That data can live in the object, in a database, or literally anywhere else. The storage mechanism is abstracted away from the provided interface, so one storage mechanism can be easily swapped for another. And you can mix multiple ExtraFields stashes into one class, using one or many storage mechanisms. periodt. 👑

---

🌈 PERL VERSION 🌈

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years. fr fr, it's ancient-perl-friendly.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. so don't come for it. 💀

---

🎀 MIXING IN 🎀

To create a stash of extra fields, just use Mixin::ExtraFields and import the fields group like this:

use Mixin::ExtraFields -fields => { driver => 'SomeDriver' };

The only argument required for the group is driver, which names the driver (storage mechanism) to use. For more info, see "Specifying a Driver" below. 👇

Other valid arguments are:

id - the name of the method to call on objects to get their unique identifier
     default: id; an explicit undef will use each object's reference addr

moniker - the name to use in forming mixed-in method names
          default: extra

🧚 Specifying a Driver 🧚

The driver argument can be given as either a driver identifier or a reference to a hash of options. If you give it as a hash reference, one of the entries in that hash must be class, giving the driver identifier for the driver.

A driver identifier must be either:

• an object of a class descended from the driver base class
• a partial class name, to follow the driver base class name
• a full class name, prepended with +

The driver base class is provided by the driver_base_class method. In almost all cases, it will be Mixin::ExtraFields::Driver. ✨

---

💅 GENERATED METHODS 💅

The default implementation of Mixin::ExtraFields provides a number of methods for accessing the extras.

Wherever extra shows up in the following method names, the moniker argument you gave to the fields group gets used instead. For example, if the use statement looked like this:

use Mixin::ExtraFields -fields => { moniker => 'info', driver => 'HashGuts' };

…then a method called exists_info would be generated, rather than exists_extra. The fields group also respects renaming options documented in Sub::Exporter. 🫶

🌟 exists_extra

if ($obj->exists_extra($name)) { ... }

This method returns true if there is an entry in the extras for the given name.

🌟 get_extra

🌟 get_detailed_extra

my $value = $obj->get_extra($name);

my $value_hash = $obj->get_detailed_extra($name);

These methods return the entry for the given name. If none exists, the method returns undef. The detailed version returns a hashref describing all the information available about the entry. That info is driver-specific, but it's required to have an entry for the key entry, providing the value that get_extra would have returned. 📦

🌟 get_all_extra

🌟 get_all_detailed_extra

my %extra = $obj->get_all_extra;

my %extra_hash = $obj->get_all_detailed_extra;

These methods return a list of name/value pairs. The values are in the same form as those returned by the get-by-name methods above. 💫

🌟 get_all_extra_names

my @names = $obj->get_all_extra_names;

This method returns the names of all existing extras.

🌟 set_extra

$obj->set_extra($name => $value);

This method sets the given extra. If no entry existed before, one is created. If one existed for this name, it is replaced. 🔁

🌟 delete_extra

$obj->delete_extra($name);

This method deletes the named entry. After deletion, no entry will exist for that name. bye bestie 👋

🌟 delete_all_extra

$obj->delete_all_extra;

This method deletes all entries for the object. total wipeout 💀✨

---

👑 SUBCLASSING 👑

Mixin::ExtraFields can be subclassed to produce different methods, provide different names, or behave differently in other ways. Subclassing Mixin::ExtraFields can produce many distinct and powerful tools. 🔧

None of the generated methods above are implemented in Mixin::ExtraFields. The methods below are its actual methods, which work together to build and export the methods that are mixed in. These are the methods you should override when subclassing Mixin::ExtraFields.

For information on writing drivers, see Mixin::ExtraFields::Driver. 📚

🌸 default_moniker

This method returns the default moniker. The default default moniker defaults to the default extra. (yes. that sentence is real. read it again.) 😭

🌸 methods

This method returns a list of base method names to construct and install. These method names will be transformed into the installed method names via method_name.

my @methods = Mixin::ExtraFields->methods;

🌸 method_name

my $method_name = Mixin::ExtraFields->method_name($method_base, $moniker);

This method returns the method name that will be installed into the importing class. Its default behavior is to join the method base (which comes from the methods method) and the moniker with an underscore, more or less.

🌸 driver_method_name

This method returns the name of the driver method used to implement the given method name. This is primarily useful in the default implementation of MixinExtraFields, where there is a one-to-one correspondence between installed methods and driver methods.

Changing this method could very easily cause incompatibility with standard driver classes, and should only be done by the wise, brave, or reckless. 🫣 you've been warned, bestie.

🌸 gen_fields_group

my $sub_href = Mixin::ExtraFields->gen_fields_group($name, \%arg, \%col);

This method is a group generator, as used by Sub::Exporter and described in its documentation. It is the method you are least likely to subclass. 🙈

🌸 build_method

my $code = Mixin::ExtraFields->build_method($method_name, \%arg);

This routine builds the requested method. It is passed a method name in the form returned by the methods method and a hashref of the following data:

id_method - the method to call on objects to get their unique id
driver    - the storage driver
moniker   - the moniker of the set of extras being built

Note! The values for the above arguments are references to the values you'd expect. That is, if the id method is foo you will be given a reference to the string foo. (This reduces the copies of common values that will be enclosed into generated code.) 🧠

🌸 default_driver_arg

my $arg = Mixin::ExtraFields->default_driver_arg;

This method a default value for the driver argument to the fields group generator. By default, this method will croak if called. 🐸 (the original says it like that, so I say it like that.)

🌸 build_driver

my $driver = Mixin::ExtraFields->build_driver($arg);

This method constructs and returns the driver object to be used by the generated methods. It is passed the driver argument given in the importing code's use statement.

🌸 driver_base_class

This is the name of the name of the class which drivers are expected to subclass. By default it returns Mixin::ExtraFields::Driver. 🏗️

---

🎯 TODO 🎯

• handle invocants without ids (classes) and drivers that don't need ids

---

🌟 AUTHOR 🌟

Ricardo Signes <cpan@semiotic.systems>

---

🫶 CONTRIBUTORS 🫶

• Ricardo SIGNES <rjbs@codesimply.com>
• Ricardo Signes <rjbs@semiotic.systems>

---

💖 COPYRIGHT AND LICENSE 💖

This software is copyright (c) 2022 by Ricardo Signes.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. 🐪

---

okay that's the whole page!! this lovely little manual was rendered by perl v5.36.0 on 2023-01-07, and it's filed under Mixin:...Fields(3pm) in the User Contributed Perl Documentation section — go forth and stash your extra fields, bestie 💅✨🎀