NAME

       Mixin::ExtraFields - add extra stashes of data to your objects

VERSION

       version 0.140001

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.

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".

   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

AUTHOR

       Ricardo Signes <rjbs@cpan.org>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2013 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.