Mixin::ExtraFields(3) User Contributed Perl DocumentationMixin::ExtraFields(3)NAMEMixin::ExtraFields - add extra stashes of data to your objects
VERSION
version 0.100971
SYNOPSIS
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',
);
}
DESCRIPTION
Sometimes your well-defined object needs a way to tack on arbirary
extra fields. This might be a set of session-specific ephemeral data,
a stash of settings that need to be easy to grow over time, or any sort
of name-and-value parameters. Adding more and more methods can be
cumbersome, and may not be helpful if the names vary greatly.
Accessing an object's guts directly is simple, but is difficult to
control when subclassing, and can make altering your object's structure
difficult.
Mixin::ExtraFields provides a simple way to add an arbitrary number of
stashes for named data. These data can be stored in the object, in a
database, or anywhere else. The storage mechanism is abstracted away
from the provided interface, so one storage mechanism can be easily
swapped for another. Multiple ExtraFields stashes can be mixed into
one class, using one or many storage mechanisms.
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 information, 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 given as a hash reference, one of
the entries in the 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" appears in the following method names, the "moniker"
argument given to the "fields" group will be 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 of this method will return
a hashref describing all information available about the entry. While
this information is driver-specific, it is required to have an entry
for the key "entry", providing the value that would have been returned
by "get_extra".
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.
delete_all_extra
$obj->delete_all_extra;
This method deletes all entries for the object.
SUBCLASSINGMixin::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".
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.
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 an
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.
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".
AUTHOR
This code was written by Ricardo SIGNES. His work in 2006 was
sponsored by Listbox.
COPYRIGHT AND LICENSE
Copyright (C) 2006, Ricardo SIGNES. This code is free software, and is
available under the same terms as perl itself.
TODO
· handle invocants without ids (classes) and drivers that don't need
ids
perl v5.14.1 2010-04-07 Mixin::ExtraFields(3)
