Provided by: librose-db-object-perl_0.815-1_all bug

NAME

       Rose::DB::Object::MakeMethods::Generic - Create generic object methods for
       Rose::DB::Object-derived objects.

SYNOPSIS

         package MyDBObject;

         our @ISA = qw(Rose::DB::Object);

         use Rose::DB::Object::MakeMethods::Generic
         (
           scalar =>
           [
             'type' =>
             {
               with_init => 1,
               check_in  => [ qw(AA AAA C D) ],
             },

             'set_type' => { hash_key => 'type' },
           ],

           character =>
           [
             code => { length => 6 }
           ],

           varchar =>
           [
             name => { length => 10 }
           ],

           boolean =>
           [
             'is_red',
             'is_happy' => { default => 1 },
           ],
         );

         sub init_type { 'C' }
         ...

         $obj = MyDBObject->new(...);

         print $obj->type; # C

         $obj->name('Bob');   # set
         $obj->set_type('C'); # set
         $obj->type('AA');    # set

         $obj->set_type; # Fatal error: no argument passed to "set" method

         $obj->name('C' x 40); # truncate on set
         print $obj->name;     # 'CCCCCCCCCC'

         $obj->code('ABC'); # pad on set
         print $obj->code;  # 'ABC   '

         eval { $obj->type('foo') }; # fatal error: invalid value

         print $obj->name, ' is ', $obj->type; # get

         $obj->is_red;         # returns undef
         $obj->is_red('true'); # returns 1 (assuming "true" a
                               # valid boolean literal according to
                               # $obj->db->parse_boolean('true'))
         $obj->is_red('');     # returns 0
         $obj->is_red;         # returns 0

         $obj->is_happy;       # returns 1

         ...

         package Person;

         our @ISA = qw(Rose::DB::Object);
         ...
         use Rose::DB::Object::MakeMethods::Generic
         (
           scalar => 'name',

           set =>
           [
             'nicknames',
             'parts' => { default => [ qw(arms legs) ] },
           ],

           # See the Rose::DB::Object::Metadata::Relationship::ManyToMany
           # documentation for a more complete example
           objects_by_map =>
           [
             friends =>
             {
               map_class    => 'FriendMap',
               manager_args => { sort_by => Friend->meta->table . '.name' },
             },
           ],
         );
         ...

         @parts = $person->parts; # ('arms', 'legs')
         $parts = $person->parts; # [ 'arms', 'legs' ]

         $person->nicknames('Jack', 'Gimpy');   # set with list
         $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref

         print join(', ', map { $_->name } $person->friends);
         ...

         package Program;

         our @ISA = qw(Rose::DB::Object);
         ...
         use Rose::DB::Object::MakeMethods::Generic
         (
           objects_by_key =>
           [
             bugs =>
             {
               class => 'Bug',
               key_columns =>
               {
                 # Map Program column names to Bug column names
                 id      => 'program_id',
                 version => 'version',
               },
               manager_args =>
               {
                 sort_by => Bug->meta->table . '.date_submitted DESC',
               },
               query_args   => [ state => { ne => 'closed' } ],
             },
           ]
         );
         ...

         $prog = Program->new(id => 5, version => '3.0', ...);

         $bugs = $prog->bugs;

         # Calls (essentially):
         #
         # Rose::DB::Object::Manager->get_objects(
         #   db           => $prog->db, # share_db defaults to true
         #   object_class => 'Bug',
         #   query =>
         #   {
         #     program_id => 5,     # value of $prog->id
         #     version    => '3.0', # value of $prog->version
         #     state      => { ne => 'closed' },
         #   },
         #   sort_by => 'date_submitted DESC');

         ...

         package Product;

         our @ISA = qw(Rose::DB::Object);
         ...
         use Rose::DB::Object::MakeMethods::Generic
         (
           object_by_key =>
           [
             category =>
             {
               class => 'Category',
               key_columns =>
               {
                 # Map Product column names to Category column names
                 category_id => 'id',
               },
             },
           ]
         );
         ...

         $product = Product->new(id => 5, category_id => 99);

         $category = $product->category;

         # $product->category call is roughly equivalent to:
         #
         # $cat = Category->new(id => $product->category_id,
         #                      db => $prog->db);
         #
         # $ret = $cat->load;
         # return $ret  unless($ret);
         # return $cat;

DESCRIPTION

       Rose::DB::Object::MakeMethods::Generic is a method maker that inherits from
       Rose::Object::MakeMethods.  See the Rose::Object::MakeMethods documentation to learn about
       the interface.  The method types provided by this module are described below.

       All method types defined by this module are designed to work with objects that are
       subclasses of (or otherwise conform to the interface of) Rose::DB::Object.  In particular,
       the object is expected to have a db method that returns a Rose::DB-derived object.  See
       the Rose::DB::Object documentation for more details.

METHODS TYPES

       array
           Create get/set methods for "array" attributes.   A "array" column in a database table
           contains an ordered list of values.  Not all databases support an "array" column type.
           Check the Rose::DB documentation for your database type.

           Options
               default VALUE
                   Determines the default value of the attribute.  The value should be a
                   reference to an array.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               interface NAME
                   Choose the interface.  The default is "get_set".

           Interfaces
               get_set
                   Creates a get/set method for a "array" object attribute.  A "array" column in
                   a database table contains an ordered list of values.

                   When setting the attribute, the value is passed through the parse_array method
                   of the object's db attribute.

                   When saving to the database, if the attribute value is defined, the method
                   will pass the attribute value through the format_array method of the object's
                   db attribute before returning it.

                   When not saving to the database, the method returns the array as a list in
                   list context, or as a reference to the array in scalar context.

               get Creates an accessor method for a "array" object attribute.  A "array" column
                   in a database table contains an ordered list of values.

                   When saving to the database, if the attribute value is defined, the method
                   will pass the attribute value through the format_array method of the object's
                   db attribute before returning it.

                   When not saving to the database, the method returns the array as a list in
                   list context, or as a reference to the array in scalar context.

               set Creates a mutator method for a "array" object attribute.  A "array" column in
                   a database table contains an ordered list of values.

                   When setting the attribute, the value is passed through the parse_array method
                   of the object's db attribute.

                   When saving to the database, if the attribute value is defined, the method
                   will pass the attribute value through the format_array method of the object's
                   db attribute before returning it.

                   When not saving to the database, the method returns the array as a list in
                   list context, or as a reference to the array in scalar context.

                   If called with no arguments, a fatal error will occur.

           Example:

               package Person;

               our @ISA = qw(Rose::DB::Object);
               ...
               use Rose::DB::Object::MakeMethods::Generic
               (
                 array =>
                 [
                   'nicknames',
                   set_nicks => { interface => 'set', hash_key => 'nicknames' },
                   parts     => { default => [ qw(arms legs) ] },
                 ],
               );
               ...

               @parts = $person->parts; # ('arms', 'legs')
               $parts = $person->parts; # [ 'arms', 'legs' ]

               $person->nicknames('Jack', 'Gimpy');   # set with list
               $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref

               $person->set_nicks('Jack', 'Gimpy');   # set with list
               $person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref

       bitfield
           Create get/set methods for bitfield attributes.

           Options
               default VALUE
                   Determines the default value of the attribute.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               interface NAME
                   Choose the interface.  The default is "get_set".

               intersects NAME
                   Set the name of the "intersects" method.  (See "with_intersects" below.)
                   Defaults to the bitfield attribute method name with "_intersects" appended.

               bits INT
                   The number of bits in the bitfield.  Defaults to 32.

               with_intersects BOOL
                   This option is only applicable with the "get_set" interface.

                   If true, create an "intersects" helper method in addition to the "get_set"
                   method.  The intersection method name will be the attribute method name with
                   "_intersects" appended, or the value of the "intersects" option, if it is
                   passed.

                   The "intersects" method will return true if there is any intersection between
                   its arguments and the value of the bitfield attribute (i.e., if Bit::Vector's
                   Intersection method returns a value greater than zero), false (but defined)
                   otherwise.  Its argument is passed through the parse_bitfield method of the
                   object's db attribute before being tested for intersection.  Returns undef if
                   the bitfield is not defined.

           Interfaces
               get_set
                   Creates a get/set method for a bitfield attribute.  When setting the
                   attribute, the value is passed through the parse_bitfield method of the
                   object's db attribute before being assigned.

                   When saving to the database, the method will pass the attribute value through
                   the format_bitfield method of the object's db attribute before returning it.
                   Otherwise, the value is returned as-is.

               get Creates an accessor method for a bitfield attribute.  When saving to the
                   database, the method will pass the attribute value through the format_bitfield
                   method of the object's db attribute before returning it.  Otherwise, the value
                   is returned as-is.

               set Creates a mutator method for a bitfield attribute.  When setting the
                   attribute, the value is passed through the parse_bitfield method of the
                   object's db attribute before being assigned.

                   When saving to the database, the method will pass the attribute value through
                   the format_bitfield method of the object's db attribute before returning it.
                   Otherwise, the value is returned as-is.

                   If called with no arguments, a fatal error will occur.

           Example:

               package MyDBObject;

               our @ISA = qw(Rose::DB::Object);

               use Rose::DB::Object::MakeMethods::Generic
               (
                 bitfield =>
                 [
                   'flags' => { size => 32, default => 2 },
                   'bits'  => { size => 16, with_intersects => 1 },
                 ],
               );

               ...

               print $o->flags->to_Bin; # 00000000000000000000000000000010

               $o->bits('101');

               $o->bits_intersects('100'); # true
               $o->bits_intersects('010'); # false

       boolean
           Create get/set methods for boolean attributes.

           Options
               default VALUE
                   Determines the default value of the attribute.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               interface NAME
                   Choose the interface.  The default is "get_set".

           Interfaces
               get_set
                   Creates a get/set method for a boolean attribute.  When setting the attribute,
                   if the value is "true" according to Perl's rules, it is compared to a list of
                   "common" true and false values: 1, 0, 1.0 (with any number of zeros), 0.0
                   (with any number of zeros), t, true, f, false, yes, no.  (All are case-
                   insensitive.)  If the value matches, then it is set to true (1) or false (0)
                   accordingly.

                   If the value does not match any of those, then it is passed through the
                   parse_boolean method of the object's db attribute.  If parse_boolean returns
                   true (1) or false (0), then the attribute is set accordingly.  If
                   parse_boolean returns undef, a fatal error will occur.  If the value is
                   "false" according to Perl's rules, the attribute is set to zero (0).

                   When saving to the database, the method will pass the attribute value through
                   the format_boolean method of the object's db attribute before returning it.
                   Otherwise, the value is returned as-is.

               get Creates an accessor method for a boolean attribute.  When saving to the
                   database, the method will pass the attribute value through the format_boolean
                   method of the object's db attribute before returning it.  Otherwise, the value
                   is returned as-is.

               set Creates a mutator method for a boolean attribute.  When setting the attribute,
                   if the value is "true" according to Perl's rules, it is compared to a list of
                   "common" true and false values: 1, 0, 1.0 (with any number of zeros), 0.0
                   (with any number of zeros), t, true, f, false, yes, no.  (All are case-
                   insensitive.)  If the value matches, then it is set to true (1) or false (0)
                   accordingly.

                   If the value does not match any of those, then it is passed through the
                   parse_boolean method of the object's db attribute.  If parse_boolean returns
                   true (1) or false (0), then the attribute is set accordingly.  If
                   parse_boolean returns undef, a fatal error will occur.  If the value is
                   "false" according to Perl's rules, the attribute is set to zero (0).

                   If called with no arguments, a fatal error will occur.

           Example:

               package MyDBObject;

               our @ISA = qw(Rose::DB::Object);

               use Rose::DB::Object::MakeMethods::Generic
               (
                 boolean =>
                 [
                   'is_red',
                   'is_happy'  => { default => 1 },
                   'set_happy' => { interface => 'set', hash_key => 'is_happy' },
                 ],
               );

               $obj->is_red;         # returns undef
               $obj->is_red('true'); # returns 1 (assuming "true" a
                                     # valid boolean literal according to
                                     # $obj->db->parse_boolean('true'))
               $obj->is_red('');     # returns 0
               $obj->is_red;         # returns 0

               $obj->is_happy;       # returns 1
               $obj->set_happy(0);   # returns 0
               $obj->is_happy;       # returns 0

       character
           Create get/set methods for fixed-length character string attributes.

           Options
               check_in ARRAYREF
                   A reference to an array of valid values.  When setting the attribute, if the
                   new value is not equal (string comparison) to one of the valid values, a fatal
                   error will occur.

               default VALUE
                   Determines the default value of the attribute.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               init_method NAME
                   The name of the method to call when initializing the value of an undefined
                   attribute.  Defaults to the method name with the prefix "init_" added.  This
                   option implies "with_init".

               interface NAME
                   Choose the interface.  The default is "get_set".

               length INT
                   The number of characters in the string.  Any strings shorter than this will be
                   padded with spaces to meet the length requirement.  If length is omitted, the
                   string will be left unmodified.

               overflow BEHAVIOR
                   Determines the behavior when the value is greater than the number of
                   characters specified by the "length" option.  Valid values for BEHAVIOR are:

                   fatal
                       Throw an exception.

                   truncate
                       Truncate the value to the correct length.

                   warn
                       Print a warning message.

               with_init BOOL
                   Modifies the behavior of the "get_set" and "get" interfaces.  If the attribute
                   is undefined, the method specified by the "init_method" option is called and
                   the attribute is set to the return value of that method.

           Interfaces
               get_set
                   Creates a get/set method for a fixed-length character string attribute.  When
                   setting, any strings longer than "length" will be truncated, and any strings
                   shorter will be padded with spaces to meet the length requirement.  If
                   "length" is omitted, the string will be left unmodified.

               get Creates an accessor method for a fixed-length character string attribute.

               set Creates a mutator method for a fixed-length character string attribute.  Any
                   strings longer than "length" will be truncated, and any strings shorter will
                   be padded with spaces to meet the length requirement.  If "length" is omitted,
                   the string will be left unmodified.

           Example:

               package MyDBObject;

               our @ISA = qw(Rose::DB::Object);

               use Rose::DB::Object::MakeMethods::Generic
               (
                 character =>
                 [
                   'name' => { length => 3 },
                 ],
               );

               ...

               $o->name('John'); # truncates on set
               print $o->name;   # 'Joh'

               $o->name('A'); # pads on set
               print $o->name;   # 'A  '

       enum
           Create get/set methods for enum attributes.

           Options
               default VALUE
                   Determines the default value of the attribute.

               values ARRAYREF
                   A reference to an array of the enum values.  This attribute is required.  When
                   setting the attribute, if the new value is not equal (string comparison) to
                   one of the enum values, a fatal error will occur.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               init_method NAME
                   The name of the method to call when initializing the value of an undefined
                   attribute.  Defaults to the method name with the prefix "init_" added.  This
                   option implies "with_init".

               interface NAME
                   Choose the interface.  The "get_set" interface is the default.

               with_init BOOL
                   Modifies the behavior of the "get_set" and "get" interfaces.  If the attribute
                   is undefined, the method specified by the "init_method" option is called and
                   the attribute is set to the return value of that method.

           Interfaces
               get_set
                   Creates a get/set method for an enum attribute.  When called with an argument,
                   the value of the attribute is set.  If the value is invalid, a fatal error
                   will occur.  The current value of the attribute is returned.

               get Creates an accessor method for an object attribute that returns the current
                   value of the attribute.

               set Creates a mutator method for an object attribute.  When called with an
                   argument, the value of the attribute is set.  If the value is invalid, a fatal
                   error will occur.  If called with no arguments, a fatal error will occur.

           Example:

               package MyDBObject;

               our @ISA = qw(Rose::DB::Object);

               use Rose::DB::Object::MakeMethods::Generic
               (
                 enum =>
                 [
                   type  => { values => [ qw(main aux extra) ], default => 'aux' },
                   stage => { values => [ qw(new std old) ], with_init => 1 },
                 ],
               );

               sub init_stage { 'new' }
               ...

               $o = MyDBObject->new(...);

               print $o->type;   # aux
               print $o->stage;  # new

               $o->type('aux');  # set
               $o->stage('old'); # set

               eval { $o->type('foo') }; # fatal error: invalid value

               print $o->type, ' is at stage ', $o->stage; # get

       integer
           Create get/set methods for integer attributes.

           Options
               default VALUE
                   Determines the default value of the attribute.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               init_method NAME
                   The name of the method to call when initializing the value of an undefined
                   attribute.  Defaults to the method name with the prefix "init_" added.  This
                   option implies "with_init".

               interface NAME
                   Choose the interface.  The "get_set" interface is the default.

               with_init BOOL
                   Modifies the behavior of the "get_set" and "get" interfaces.  If the attribute
                   is undefined, the method specified by the "init_method" option is called and
                   the attribute is set to the return value of that method.

           Interfaces
               get_set
                   Creates a get/set method for an integer object attribute.  When called with an
                   argument, the value of the attribute is set.  The current value of the
                   attribute is returned.

               get Creates an accessor method for an integer object attribute that returns the
                   current value of the attribute.

               set Creates a mutator method for an integer object attribute.  When called with an
                   argument, the value of the attribute is set.  If called with no arguments, a
                   fatal error will occur.

           Example:

               package MyDBObject;

               our @ISA = qw(Rose::DB::Object);

               use Rose::DB::Object::MakeMethods::Generic
               (
                 integer =>
                 [
                   code => { default => 99  },
                   type => { with_init => 1 }
                 ],
               );

               sub init_type { 123 }
               ...

               $o = MyDBObject->new(...);

               print $o->code; # 99
               print $o->type; # 123

               $o->code(8675309); # set
               $o->type(42);      # set

       objects_by_key
           Create get/set methods for an array of Rose::DB::Object-derived objects fetched based
           on a key formed from attributes of the current object.

           Options
               class CLASS
                   The name of the Rose::DB::Object-derived class of the objects to be fetched.
                   This option is required.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of the fetched
                   objects.  Defaults to the name of the method.

               key_columns HASHREF
                   A reference to a hash that maps column names in the current object to those in
                   the objects to be fetched.  This option is required.

               manager_args HASHREF
                   A reference to a hash of arguments passed to the "manager_class" when fetching
                   objects.  If "manager_class" defaults to Rose::DB::Object::Manager, the
                   following argument is added to the "manager_args" hash: "object_class =>
                   CLASS", where CLASS is the value of the "class" option (see above).  If
                   "manager_args" includes a "sort_by" argument, be sure to prefix each column
                   name with the appropriate table name.  (See the synopsis for examples.)

               manager_class CLASS
                   The name of the Rose::DB::Object::Manager-derived class used to fetch the
                   objects.  The "manager_method" class method is called on this class.  Defaults
                   to Rose::DB::Object::Manager.

               manager_method NAME
                   The name of the class method to call on "manager_class" in order to fetch the
                   objects.  Defaults to "get_objects".

               manager_count_method NAME
                   The name of the class method to call on "manager_class" in order to count the
                   objects.  Defaults to "get_objects_count".

               interface NAME
                   Choose the interface.  The "get_set" interface is the default.

               relationship OBJECT
                   The Rose::DB::Object::Metadata::Relationship object that describes the "key"
                   through which the "objects_by_key" are fetched.  This is required when using
                   the "add_now", "add_on_save", and "get_set_on_save" interfaces.

               share_db BOOL
                   If true, the db attribute of the current object is shared with all of the
                   objects fetched.  Defaults to true.

               query_args ARRAYREF
                   A reference to an array of arguments added to the value of the "query"
                   parameter passed to the call to "manager_class"'s "manager_method" class
                   method.

           Interfaces
               count
                   Creates a method that will attempt to count Rose::DB::Object-derived objects
                   based on a key formed from attributes of the current object, plus any
                   additional parameters passed to the method call.  Note that this method counts
                   the objects in the database at the time of the call.  This may be different
                   than the number of objects attached to the current object or otherwise in
                   memory.

                   Since the objects counted are partially determined by the arguments passed to
                   the method, the count is not retained.  It is simply returned.  Each call
                   counts the specified objects again, even if the arguments are the same as the
                   previous call.

                   If the first argument is a reference to a hash or array, it is converted to a
                   reference to an array (if necessary) and taken as the value of the "query"
                   parameter.  All arguments are passed on to the "manager_class"'s
                   "manager_count_method" method, augmented by the key formed from attributes of
                   the current object.  Query parameters are added to the existing contents of
                   the "query" parameter.  Other parameters replace existing parameters if the
                   existing values are simple scalars, or augment existing parameters if the
                   existing values are references to hashes or arrays.

                   The count may fail for several reasons.  The count will not even be attempted
                   if any of the key attributes in the current object are undefined.  Instead,
                   undef (in scalar context) or an empty list (in list context) will be returned.
                   If the call to "manager_class"'s "manager_count_method" method returns undef,
                   the behavior is determined by the metadata object's error_mode.  If the mode
                   is "return", that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the count succeeds, the number is returned.  (If the count finds zero
                   objects, the count will be 0.  This is still considered success.)

               find
                   Creates a method that will attempt to fetch Rose::DB::Object-derived objects
                   based on a key formed from attributes of the current object, plus any
                   additional parameters passed to the method call.  Since the objects fetched
                   are partially determined by the arguments passed to the method, the list of
                   objects is not retained.  It is simply returned.  Each call fetches the
                   requested objects again, even if the arguments are the same as the previous
                   call.

                   If the first argument is a reference to a hash or array, it is converted to a
                   reference to an array (if necessary) and taken as the value of the "query"
                   parameter.  All arguments are passed on to the "manager_class"'s
                   "manager_method" method, augmented by the key formed from attributes of the
                   current object.  Query parameters are added to the existing contents of the
                   "query" parameter.  Other parameters replace existing parameters if the
                   existing values are simple scalars, or augment existing parameters if the
                   existing values are references to hashes or arrays.

                   The fetch may fail for several reasons.  The fetch will not even be attempted
                   if any of the key attributes in the current object are undefined.  Instead,
                   undef (in scalar context) or an empty list (in list context) will be returned.
                   If the call to "manager_class"'s "manager_method" method returns false, the
                   behavior is determined by the metadata object's error_mode.  If the mode is
                   "return", that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the fetch succeeds, a list (in list context) or a reference to the array of
                   objects (in scalar context) is returned.  (If the fetch finds zero objects,
                   the list or array reference will simply be empty.  This is still considered
                   success.)

               iterator
                   Behaves just like find but returns an iterator rather than an array or
                   arrayref.

               get_set
                   Creates a method that will attempt to fetch Rose::DB::Object-derived objects
                   based on a key formed from attributes of the current object.

                   If passed a single argument of undef, the "hash_key" used to store the objects
                   is set to undef.  Otherwise, the argument(s) must be a list or reference to an
                   array containing items in one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   The list of object is assigned to "hash_key".  Note that these objects are not
                   added to the database.  Use the "get_set_now" or "get_set_on_save" interface
                   to do that.

                   If called with no arguments and the hash key used to store the list of objects
                   is defined, the list (in list context) or a reference to that array (in scalar
                   context) of objects is returned.  Otherwise, the objects are fetched.

                   The fetch may fail for several reasons.  The fetch will not even be attempted
                   if any of the key attributes in the current object are undefined.  Instead,
                   undef (in scalar context) or an empty list (in list context) will be returned.
                   If the call to "manager_class"'s "manager_method" method returns false, the
                   behavior is determined by the metadata object's error_mode.  If the mode is
                   "return", that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the fetch succeeds, a list (in list context) or a reference to the array of
                   objects (in scalar context) is returned.  (If the fetch finds zero objects,
                   the list or array reference will simply be empty.  This is still considered
                   success.)

               get_set_now
                   Creates a method that will attempt to fetch Rose::DB::Object-derived objects
                   based on a key formed from attributes of the current object, and will also
                   save the objects to the database when called with arguments.  The objects do
                   not have to already exist in the database; they will be inserted if needed.

                   If passed a single argument of undef, the list of objects is set to undef,
                   causing it to be reloaded the next time the method is called with no
                   arguments.  (Pass a reference to an empty array to cause all of the existing
                   objects to be deleted from the database.)  Any pending "set_on_save" or
                   "add_on_save" actions are discarded.

                   Otherwise, the argument(s) must be a list or reference to an array containing
                   items in one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   The list of object is assigned to "hash_key", the old objects are deleted from
                   the database, and the new ones are added to the database.  Any pending
                   "set_on_save" or "add_on_save" actions are discarded.

                   When adding each object, if the object does not already exists in the
                   database, it will be inserted.  If the object was previously loaded from or
                   saved to the database, it will be updated.  Otherwise, it will be loaded.

                   The parent object must have been loaded or saved prior to setting the list of
                   objects.  If this method is called with arguments before the object has been
                   loaded or saved, a fatal error will occur.

                   If called with no arguments and the hash key used to store the list of objects
                   is defined, the list (in list context) or a reference to that array (in scalar
                   context) of objects is returned.  Otherwise, the objects are fetched.

                   The fetch may fail for several reasons.  The fetch will not even be attempted
                   if any of the key attributes in the current object are undefined.  Instead,
                   undef (in scalar context) or an empty list (in list context) will be returned.
                   If the call to "manager_class"'s "manager_method" method returns false, the
                   behavior is determined by the metadata object's error_mode.  If the mode is
                   "return", that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the fetch succeeds, a list (in list context) or a reference to the array of
                   objects (in scalar context) is returned.  (If the fetch finds zero objects,
                   the list or array reference will simply be empty.  This is still considered
                   success.)

               get_set_on_save
                   Creates a method that will attempt to fetch Rose::DB::Object-derived objects
                   based on a key formed from attributes of the current object, and will also
                   save the objects to the database when the "parent" object is saved.  The
                   objects do not have to already exist in the database; they will be inserted if
                   needed.

                   If passed a single argument of undef, the list of objects is set to undef,
                   causing it to be reloaded the next time the method is called with no
                   arguments.  (Pass a reference to an empty array to cause all of the existing
                   objects to be deleted from the database when the parent is saved.)

                   Otherwise, the argument(s) must be a list or reference to an array containing
                   items in one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   The list of object is assigned to "hash_key".  The old objects are scheduled
                   to be deleted from the database and the new ones are scheduled to be added to
                   the database when the parent is saved.  Any pending "set_on_save" or
                   "add_on_save" actions are discarded.

                   When adding each object when the parent is saved, if the object does not
                   already exists in the database, it will be inserted.  If the object was
                   previously loaded from or saved to the database, it will be updated.
                   Otherwise, it will be loaded.

                   If called with no arguments and the hash key used to store the list of objects
                   is defined, the list (in list context) or a reference to that array (in scalar
                   context) of objects is returned.  Otherwise, the objects are fetched.

                   The fetch may fail for several reasons.  The fetch will not even be attempted
                   if any of the key attributes in the current object are undefined.  Instead,
                   undef (in scalar context) or an empty list (in list context) will be returned.
                   If the call to "manager_class"'s "manager_method" method returns false, the
                   behavior is determined by the metadata object's error_mode.  If the mode is
                   "return", that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the fetch succeeds, a list (in list context) or a reference to the array of
                   objects (in scalar context) is returned.  (If the fetch finds zero objects,
                   the list or array reference will simply be empty.  This is still considered
                   success.)

               add_now
                   Creates a method that will add to a list of Rose::DB::Object-derived objects
                   that are related to the current object by a key formed from attributes of the
                   current object.  The objects do not have to already exist in the database;
                   they will be inserted if needed.

                   This method returns the list of objects added when called in list context, and
                   the number of objects added when called in scalar context.  If one or more
                   objects could not be added, undef (in scalar context) or an empty list (in
                   list context) is returned and the parent object's error attribute is set.

                   If passed an empty list, the method does nothing and the parent object's error
                   attribute is set.

                   If passed any arguments, the parent object must have been loaded or saved
                   prior to adding to the list of objects.  If this method is called with a non-
                   empty list as an argument before the parent object has been  loaded or saved,
                   a fatal error will occur.

                   The argument(s) must be a list or reference to an array containing items in
                   one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   These objects are linked to the parent object (by setting the appropriate key
                   attributes) and then added to the database.

                   When adding each object, if the object does not already exists in the
                   database, it will be inserted.  If the object was previously loaded from or
                   saved to the database, it will be updated.  Otherwise, it will be loaded.

                   The parent object's list of related objects is then set to undef, causing the
                   related objects to be reloaded from the database the next time they're needed.

               add_on_save
                   Creates a method that will add to a list of Rose::DB::Object-derived objects
                   that are related to the current object by a key formed from attributes of the
                   current object.  The objects will be added to the database when the parent
                   object is saved.  The objects do not have to already exist in the database;
                   they will be inserted if needed.

                   This method returns the list of objects to be added when called in list
                   context, and the number of items to be added when called in scalar context.

                   If passed an empty list, the method does nothing and the parent object's error
                   attribute is set.

                   Otherwise, the argument(s) must be a list or reference to an array containing
                   items in one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   These objects are linked to the parent object (by setting the appropriate key
                   attributes, whether or not they're defined in the parent object) and are
                   scheduled to be added to the database when the parent object is saved.  They
                   are also added to the parent object's current list of related objects, if the
                   list is defined at the time of the call.

                   When adding each object when the parent is saved, if the object does not
                   already exists in the database, it will be inserted.  If the object was
                   previously loaded from or saved to the database, it will be updated.
                   Otherwise, it will be loaded.

           Example setup:

               # CLASS     DB TABLE
               # -------   --------
               # Program   programs
               # Bug       bugs

               package Program;

               our @ISA = qw(Rose::DB::Object);
               ...
               # You will almost never call the method-maker directly
               # like this.  See the Rose::DB::Object::Metadata docs
               # for examples of more common usage.
               use Rose::DB::Object::MakeMethods::Generic
               (
                 objects_by_key =>
                 [
                   find_bugs =>
                   {
                     interface => 'find',
                     class     => 'Bug',
                     key_columns =>
                     {
                       # Map Program column names to Bug column names
                       id      => 'program_id',
                       version => 'version',
                     },
                     manager_args => { sort_by => 'date_submitted DESC' },
                   },

                   bugs =>
                   {
                     interface => '...', # get_set, get_set_now, get_set_on_save
                     class     => 'Bug',
                     key_columns =>
                     {
                       # Map Program column names to Bug column names
                       id      => 'program_id',
                       version => 'version',
                     },
                     manager_args => { sort_by => 'date_submitted DESC' },
                     query_args   => { state => { ne => 'closed' } },
                   },

                   add_bugs =>
                   {
                     interface => '...', # add_now or add_on_save
                     class     => 'Bug',
                     key_columns =>
                     {
                       # Map Program column names to Bug column names
                       id      => 'program_id',
                       version => 'version',
                     },
                     manager_args => { sort_by => 'date_submitted DESC' },
                     query_args   => { state => { ne => 'closed' } },
                   },
                 ]
               );
               ...

           Example - find interface:

               # Read from the programs table
               $prog = Program->new(id => 5)->load;

               # Read from the bugs table
               $bugs = $prog->find_bugs;

               # Calls (essentially):
               #
               # Rose::DB::Object::Manager->get_objects(
               #   db           => $prog->db, # share_db defaults to true
               #   object_class => 'Bug',
               #   query =>
               #   [
               #     program_id => 5,     # value of $prog->id
               #     version    => '3.0', # value of $prog->version
               #   ],
               #   sort_by => 'date_submitted DESC');

               # Augment query
               $bugs = $prog->find_bugs({ state => 'open' });

               # Calls (essentially):
               #
               # Rose::DB::Object::Manager->get_objects(
               #   db           => $prog->db, # share_db defaults to true
               #   object_class => 'Bug',
               #   query =>
               #   [
               #     program_id => 5,     # value of $prog->id
               #     version    => '3.0', # value of $prog->version
               #     state      => 'open',
               #   ],
               #   sort_by => 'date_submitted DESC');
               ...

               # Augment query and replace sort_by value
               $bugs = $prog->find_bugs(query   => [ state => 'defunct' ],
                                        sort_by => 'name');

               # Calls (essentially):
               #
               # Rose::DB::Object::Manager->get_objects(
               #   db           => $prog->db, # share_db defaults to true
               #   object_class => 'Bug',
               #   query =>
               #   [
               #     program_id => 5,     # value of $prog->id
               #     version    => '3.0', # value of $prog->version
               #     state      => 'defunct',
               #   ],
               #   sort_by => 'name');
               ...

           Example - get_set interface:

               # Read from the programs table
               $prog = Program->new(id => 5)->load;

               # Read from the bugs table
               $bugs = $prog->bugs;

               # Calls (essentially):
               #
               # Rose::DB::Object::Manager->get_objects(
               #   db           => $prog->db, # share_db defaults to true
               #   object_class => 'Bug',
               #   query =>
               #   [
               #     program_id => 5,     # value of $prog->id
               #     version    => '3.0', # value of $prog->version
               #     state      => { ne => 'closed' },
               #   ],
               #   sort_by => 'date_submitted DESC');
               ...
               $prog->version($new_version); # Does not hit the db
               $prog->bugs(@new_bugs);       # Does not hit the db

               # @new_bugs can contain any mix of these types:
               #
               # @new_bugs =
               # (
               #   123,                 # primary key value
               #   { id => 456 },       # method name/value pairs
               #   Bug->new(id => 789), # object
               # );

               # Write to the programs table only.  The bugs table is not
               # updated. See the get_set_now and get_set_on_save method
               # types for ways to write to the bugs table.
               $prog->save;

           Example - get_set_now interface:

               # Read from the programs table
               $prog = Program->new(id => 5)->load;

               # Read from the bugs table
               $bugs = $prog->bugs;

               $prog->name($new_name); # Does not hit the db

               # Writes to the bugs table, deleting existing bugs and
               # replacing them with @new_bugs (which must be an array
               # of Bug objects, either existing or new)
               $prog->bugs(@new_bugs);

               # @new_bugs can contain any mix of these types:
               #
               # @new_bugs =
               # (
               #   123,                 # primary key value
               #   { id => 456 },       # method name/value pairs
               #   Bug->new(id => 789), # object
               # );

               # Write to the programs table
               $prog->save;

           Example - get_set_on_save interface:

               # Read from the programs table
               $prog = Program->new(id => 5)->load;

               # Read from the bugs table
               $bugs = $prog->bugs;

               $prog->name($new_name); # Does not hit the db
               $prog->bugs(@new_bugs); # Does not hit the db

               # @new_bugs can contain any mix of these types:
               #
               # @new_bugs =
               # (
               #   123,                 # primary key value
               #   { id => 456 },       # method name/value pairs
               #   Bug->new(id => 789), # object
               # );

               # Write to the programs table and the bugs table, deleting any
               # existing bugs and replacing them with @new_bugs (which must be
               # an array of Bug objects, either existing or new)
               $prog->save;

           Example - add_now interface:

               # Read from the programs table
               $prog = Program->new(id => 5)->load;

               # Read from the bugs table
               $bugs = $prog->bugs;

               $prog->name($new_name); # Does not hit the db

               # Writes to the bugs table, adding @new_bugs to the current
               # list of bugs for this program
               $prog->add_bugs(@new_bugs);

               # @new_bugs can contain any mix of these types:
               #
               # @new_bugs =
               # (
               #   123,                 # primary key value
               #   { id => 456 },       # method name/value pairs
               #   Bug->new(id => 789), # object
               # );

               # Read from the bugs table, getting the full list of bugs,
               # including the ones that were added above.
               $bugs = $prog->bugs;

               # Write to the programs table only
               $prog->save;

           Example - add_on_save interface:

               # Read from the programs table
               $prog = Program->new(id => 5)->load;

               # Read from the bugs table
               $bugs = $prog->bugs;

               $prog->name($new_name);      # Does not hit the db
               $prog->add_bugs(@new_bugs);  # Does not hit the db
               $prog->add_bugs(@more_bugs); # Does not hit the db

               # @new_bugs and @more_bugs can contain any mix of these types:
               #
               # @new_bugs =
               # (
               #   123,                 # primary key value
               #   { id => 456 },       # method name/value pairs
               #   Bug->new(id => 789), # object
               # );

               # Write to the programs table and the bugs table, adding
               # @new_bugs to the current list of bugs for this program
               $prog->save;

       objects_by_map
           Create methods that fetch Rose::DB::Object-derived objects via an intermediate
           Rose::DB::Object-derived class that maps between two other Rose::DB::Object-derived
           classes.  See the Rose::DB::Object::Metadata::Relationship::ManyToMany documentation
           for a more complete example of this type of method in action.

           Options
               hash_key NAME
                   The key inside the hash-based object to use for the storage of the fetched
                   objects.  Defaults to the name of the method.

               interface NAME
                   Choose the interface.  The "get_set" interface is the default.

               manager_args HASHREF
                   A reference to a hash of arguments passed to the "manager_class" when fetching
                   objects.  If "manager_args" includes a "sort_by" argument, be sure to prefix
                   each column name with the appropriate table name.  (See the synopsis for
                   examples.)

               manager_class CLASS
                   The name of the Rose::DB::Object::Manager-derived class that the "map_class"
                   will use to fetch records.  Defaults to Rose::DB::Object::Manager.

               manager_method NAME
                   The name of the class method to call on "manager_class" in order to fetch the
                   objects.  Defaults to "get_objects".

               manager_count_method NAME
                   The name of the class method to call on "manager_class" in order to count the
                   objects.  Defaults to "get_objects_count".

               map_class CLASS
                   The name of the Rose::DB::Object-derived class that maps between the other two
                   Rose::DB::Object-derived classes.  This class must have a foreign key and/or
                   "many to one" relationship for each of the two tables that it maps between.

               map_from NAME
                   The name of the "many to one" relationship or foreign key in "map_class" that
                   points to the object of the class that this relationship exists in.  Setting
                   this value is only necessary if the "map_class" has more than one foreign key
                   or "many to one" relationship that points to one of the classes that it maps
                   between.

               map_to NAME
                   The name of the "many to one" relationship or foreign key in "map_class" that
                   points to the "foreign" object to be fetched.  Setting this value is only
                   necessary if the "map_class" has more than one foreign key or "many to one"
                   relationship that points to one of the classes that it maps between.

               relationship OBJECT
                   The Rose::DB::Object::Metadata::Relationship object that describes the "key"
                   through which the "objects_by_key" are fetched.  This option is required.

               share_db BOOL
                   If true, the db attribute of the current object is shared with all of the
                   objects fetched.  Defaults to true.

               query_args ARRAYREF
                   A reference to an array of arguments added to the value of the "query"
                   parameter passed to the call to "manager_class"'s "manager_method" class
                   method.

           Interfaces
               count
                   Creates a method that will attempt to count Rose::DB::Object-derived objects
                   that are related to the current object through the "map_class", plus any
                   additional parameters passed to the method call.  Note that this method counts
                   the objects in the database at the time of the call.  This may be different
                   than the number of objects attached to the current object or otherwise in
                   memory.

                   Since the objects counted are partially determined by the arguments passed to
                   the method, the count is not retained.  It is simply returned.  Each call
                   counts the specified objects again, even if the arguments are the same as the
                   previous call.

                   If the first argument is a reference to a hash or array, it is converted to a
                   reference to an array (if necessary) and taken as the value of the "query"
                   parameter.  All arguments are passed on to the "manager_class"'s
                   "manager_count_method" method, augmented by the mapping to the current object.
                   Query parameters are added to the existing contents of the "query" parameter.
                   Other parameters replace existing parameters if the existing values are simple
                   scalars, or augment existing parameters if the existing values are references
                   to hashes or arrays.

                   The count may fail for several reasons.  The count will not even be attempted
                   if any of the key attributes in the current object are undefined.  Instead,
                   undef (in scalar context) or an empty list (in list context) will be returned.
                   If the call to "manager_class"'s "manager_count_method" method returns undef,
                   the behavior is determined by the metadata object's error_mode.  If the mode
                   is "return", that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the count succeeds, the number is returned.  (If the count finds zero
                   objects, the count will be 0.  This is still considered success.)

               find
                   Creates a method that will attempt to fetch Rose::DB::Object-derived that are
                   related to the current object through the "map_class", plus any additional
                   parameters passed to the method call.  Since the objects fetched are partially
                   determined by the arguments passed to the method, the list of objects is not
                   retained.  It is simply returned.  Each call fetches the requested objects
                   again, even if the arguments are the same as the previous call.

                   If the first argument is a reference to a hash or array, it is converted to a
                   reference to an array (if necessary) and taken as the value of the "query"
                   parameter.  All arguments are passed on to the "manager_class"'s
                   "manager_method" method, augmented by the mapping to the current object.
                   Query parameters are added to the existing contents of the "query" parameter.
                   Other parameters replace existing parameters if the existing values are simple
                   scalars, or augment existing parameters if the existing values are references
                   to hashes or arrays.

                   The fetch may fail for several reasons.  The fetch will not even be attempted
                   if any of the key attributes in the current object are undefined.  Instead,
                   undef (in scalar context) or an empty list (in list context) will be returned.
                   If the call to "manager_class"'s "manager_method" method returns false, the
                   behavior is determined by the metadata object's error_mode.  If the mode is
                   "return", that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the fetch succeeds, a list (in list context) or a reference to the array of
                   objects (in scalar context) is returned.  (If the fetch finds zero objects,
                   the list or array reference will simply be empty.  This is still considered
                   success.)

               iterator
                   Behaves just like find but returns an iterator rather than an array or
                   arrayref.

               get_set
                   Creates a method that will attempt to fetch Rose::DB::Object-derived objects
                   that are related to the current object through the "map_class".

                   If passed a single argument of undef, the "hash_key" used to store the objects
                   is set to undef.  Otherwise, the argument(s) must be a list or reference to an
                   array containing items in one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   The list of object is assigned to "hash_key".  Note that these objects are not
                   added to the database.  Use the "get_set_now" or "get_set_on_save" interface
                   to do that.

                   If called with no arguments and the hash key used to store the list of objects
                   is defined, the list (in list context) or a reference to that array (in scalar
                   context) of objects is returned.  Otherwise, the objects are fetched.

                   When fetching objects from the database, if the call to "manager_class"'s
                   "manager_method" method returns false, that false value (in scalar context) or
                   an empty list (in list context) is returned.

                   If the fetch succeeds, a list (in list context) or a reference to the array of
                   objects (in scalar context) is returned.  (If the fetch finds zero objects,
                   the list or array reference will simply be empty.  This is still considered
                   success.)

               get_set_now
                   Creates a method that will attempt to fetch Rose::DB::Object-derived objects
                   that are related to the current object through the "map_class", and will also
                   save objects to the database and map them to the parent object when called
                   with arguments.  The objects do not have to already exist in the database;
                   they will be inserted if needed.

                   If passed a single argument of undef, the list of objects is set to undef,
                   causing it to be reloaded the next time the method is called with no
                   arguments.  (Pass a reference to an empty array to cause all of the existing
                   objects to be "unmapped"--that is, to have their entries in the mapping table
                   deleted from the database.)  Any pending "set_on_save" or "add_on_save"
                   actions are discarded.

                   Otherwise, the argument(s) must be a list or reference to an array containing
                   items in one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   The list of object is assigned to "hash_key", the old entries are deleted from
                   the mapping table in the database, and the new objects are added to the
                   database, along with their corresponding mapping entries.  Any pending
                   "set_on_save" or "add_on_save" actions are discarded.

                   When adding each object, if the object does not already exists in the
                   database, it will be inserted.  If the object was previously loaded from or
                   saved to the database, it will be updated.  Otherwise, it will be loaded.

                   The parent object must have been loaded or saved prior to setting the list of
                   objects.  If this method is called with arguments before the object has been
                   loaded or saved, a fatal error will occur.

                   If called with no arguments and the hash key used to store the list of objects
                   is defined, the list (in list context) or a reference to that array (in scalar
                   context) of objects is returned.  Otherwise, the objects are fetched.

                   When fetching, if the call to "manager_class"'s "manager_method" method
                   returns false, that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the fetch succeeds, a list (in list context) or a reference to the array of
                   objects (in scalar context) is returned.  (If the fetch finds zero objects,
                   the list or array reference will simply be empty.  This is still considered
                   success.)

               get_set_on_save
                   Creates a method that will attempt to fetch Rose::DB::Object-derived objects
                   that are related to the current object through the "map_class", and will also
                   save objects to the database and map them to the parent object when the
                   "parent" object is saved.  The objects do not have to already exist in the
                   database; they will be inserted if needed.

                   If passed a single argument of undef, the list of objects is set to undef,
                   causing it to be reloaded the next time the method is called with no
                   arguments.  (Pass a reference to an empty array to cause all of the existing
                   objects to be "unmapped"--that is, to have their entries in the mapping table
                   deleted from the database.)  Any pending "set_on_save" or "add_on_save"
                   actions are discarded.

                   Otherwise, the argument(s) must be a list or reference to an array containing
                   items in one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   The list of object is assigned to "hash_key". The mapping table records that
                   mapped the old objects to the parent object are scheduled to be deleted from
                   the database and new ones are scheduled to be added to the database when the
                   parent is saved.  Any previously pending "set_on_save" or "add_on_save"
                   actions are discarded.

                   When adding each object when the parent is saved, if the object does not
                   already exists in the database, it will be inserted.  If the object was
                   previously loaded from or  saved to the database, it will be updated.
                   Otherwise, it will be loaded.

                   If called with no arguments and the hash key used to store the list of objects
                   is defined, the list (in list context) or a reference to that array (in scalar
                   context) of objects is returned.  Otherwise, the objects are fetched.

                   When fetching, if the call to "manager_class"'s "manager_method" method
                   returns false, that false value (in scalar context) or an empty list (in list
                   context) is returned.

                   If the fetch succeeds, a list (in list context) or a reference to the array of
                   objects (in scalar context) is returned.  (If the fetch finds zero objects,
                   the list or array reference will simply be empty.  This is still considered
                   success.)

               add_now
                   Creates a method that will add to a list of Rose::DB::Object-derived objects
                   that are related to the current object through the "map_class", and will also
                   save objects to the database and map them to the parent object.  The objects
                   do not have to already exist in the database; they will be inserted if needed.

                   This method returns the list of objects added when called in list context, and
                   the number of objects added when called in scalar context.  If one or more
                   objects could not be added, undef (in scalar context) or an empty list (in
                   list context) is returned and the parent object's error attribute is set.

                   If passed an empty list, the method does nothing and the parent object's error
                   attribute is set.

                   If passed any arguments, the parent object must have been loaded or saved
                   prior to adding to the list of objects.  If this method is called with a non-
                   empty list as an argument before the parent object has been  loaded or saved,
                   a fatal error will occur.

                   The argument(s) must be a list or reference to an array containing items in
                   one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   The parent object's list of related objects is then set to undef, causing the
                   related objects to be reloaded from the database the next time they're needed.

               add_on_save
                   Creates a method that will add to a list of Rose::DB::Object-derived objects
                   that are related to the current object through the "map_class", and will also
                   save objects to the database and map them to the parent object when the
                   "parent" object is saved.  The objects and map records will be added to the
                   database when the parent object is saved.  The objects do not have to already
                   exist in the database; they will be inserted if needed.

                   This method returns the list of objects to be added when called in list
                   context, and the number of items to be added when called in scalar context.

                   If passed an empty list, the method does nothing and the parent object's error
                   attribute is set.

                   Otherwise, the argument(s) must be a list or reference to an array containing
                   items in one or more of the following formats:

                   ·   An object of type "class".

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter two formats will be used to construct an object of type "class".  A
                   single primary key value is only a valid argument format if the "class" in
                   question has a single-column primary key.  A hash reference argument must
                   contain sufficient information for the object to be uniquely identified.

                   These objects are scheduled to be added to the database and mapped to the
                   parent object when the parent object is saved.  They are also added to the
                   parent object's current list of related objects, if the list is defined at the
                   time of the call.

           For a complete example of this method type in action, see the
           Rose::DB::Object::Metadata::Relationship::ManyToMany documentation.

       object_by_key
           Create a get/set methods for a single Rose::DB::Object-derived object loaded based on
           a primary key formed from attributes of the current object.

           Options
               class CLASS
                   The name of the Rose::DB::Object-derived class of the object to be loaded.
                   This option is required.

               foreign_key OBJECT
                   The Rose::DB::Object::Metadata::ForeignKey object that describes the "key"
                   through which the "object_by_key" is fetched.  This (or the "relationship"
                   parameter) is required when using the "delete_now", "delete_on_save", and
                   "get_set_on_save" interfaces.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of the object.
                   Defaults to the name of the method.

               if_not_found CONSEQUENCE
                   This setting determines what happens when the key_columns have defined values,
                   but the foreign object they point to is not found.  Valid values for
                   CONSEQUENCE are "fatal", which will throw an exception if the foreign object
                   is not found, and "ok" which will merely cause the relevant method(s) to
                   return undef.  The default is "fatal".

               key_columns HASHREF
                   A reference to a hash that maps column names in the current object to those of
                   the primary key in the object to be loaded.  This option is required.

               interface NAME
                   Choose the interface.  The default is "get_set".

               relationship OBJECT
                   The Rose::DB::Object::Metadata::Relationship-derived object that describes the
                   relationship through which the object is fetched.  This (or the "foreign_key"
                   parameter) is required when using the "delete_now", "delete_on_save", and
                   "get_set_on_save" interfaces.

               referential_integrity BOOL
                   If true, then a fatal error will occur when a method in one of the "get*"
                   interfaces is called and no related object is found.  The default is
                   determined by the referential_integrity attribute of the "foreign_key" object,
                   or true if no "foreign_key" parameter is passed.

                   This parameter conflicts with the "required" parameter.  Only one of the two
                   should be passed.

               required BOOL
                   If true, then a fatal error will occur when a method in one of the "get*"
                   interfaces is called and no related object is found.  The default is
                   determined by the required attribute of the "relationship" object, or true if
                   no "relationship" parameter is passed.

                   This parameter conflicts with the "referential_integrity" parameter.  Only one
                   of the two should be passed.

               share_db BOOL
                   If true, the db attribute of the current object is shared with the object
                   loaded.  Defaults to true.

           Interfaces
               delete_now
                   Deletes a Rose::DB::Object-derived object from the database based on a primary
                   key formed from attributes of the current object.  If "referential_integrity"
                   or "required" is true, then the "parent" object will have all of its
                   attributes that refer to the "foreign" object (except any columns that are
                   also part of the primary key) set to null , and it will be saved into the
                   database.  This needs to be done first because a database that enforces
                   referential integrity will not allow a row to be deleted if it is still
                   referenced by a foreign key in another table.

                   Any previously pending "get_set_on_save" action is discarded.

                   The entire process takes place within a transaction if the database supports
                   it.  If not currently in a transaction, a new one is started and then
                   committed on success and rolled back on failure.

                   Returns true if the foreign object was deleted successfully or did not exist
                   in the database, false if any of the keys that refer to the foreign object
                   were undef, and triggers the normal Rose::DB::Object error handling in the
                   case of any other kind of failure.

               delete_on_save
                   Deletes a Rose::DB::Object-derived object from the database when the "parent"
                   object is saved, based on a primary key formed from attributes of the current
                   object.  If "referential_integrity" or "required" is true, then the "parent"
                   object will have all of its attributes that refer to the "foreign" object
                   (except any columns that are also part of the primary key) set to null
                   immediately, but the actual delete will not be done until the parent is saved.

                   Any previously pending "get_set_on_save" action is discarded.

                   The entire process takes place within a transaction if the database supports
                   it.  If not currently in a transaction, a new one is started and then
                   committed on success and rolled back on failure.

                   Returns true if the foreign object was deleted successfully or did not exist
                   in the database, false if any of the keys that refer to the foreign object
                   were undef, and triggers the normal Rose::DB::Object error handling in the
                   case of any other kind of failure.

               get_set
                   Creates a method that will attempt to create and load a
                   Rose::DB::Object-derived object based on a primary key formed from attributes
                   of the current object.

                   If passed a single argument of undef, the "hash_key" used to store the object
                   is set to undef.  If "referential_integrity" or "required" is true, then the
                   columns that participate in the key are set to undef.  (If any key column is
                   part of the primary key, however, it is not set to undef.)  Otherwise, the
                   argument must be one of the following:

                   ·   An object of type "class"

                   ·   A list of method name/value pairs.

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter three argument types will be used to construct an object of type
                   "class".  A single primary key value is only valid if the "class" in question
                   has a single-column primary key.  A hash reference argument must contain
                   sufficient information for the object to be uniquely identified.

                   The object is assigned to "hash_key" after having its "key_columns" set to
                   their corresponding values in the current object.

                   If called with no arguments and the "hash_key" used to store the object is
                   defined, the object is returned.  Otherwise, the object is created and loaded.

                   The load may fail for several reasons.  The load will not even be attempted if
                   any of the key attributes in the current object are undefined.  Instead, undef
                   will be returned.

                   If the call to the newly created object's load method returns false, then the
                   normal Rose::DB::Object error handling is triggered.  The false value returned
                   by the call to the load method is returned (assuming no exception was raised).

                   If the load succeeds, the object is returned.

               get_set_now
                   Creates a method that will attempt to create and load a
                   Rose::DB::Object-derived object based on a primary key formed from attributes
                   of the current object, and will also save the object to the database when
                   called with an appropriate object as an argument.

                   If passed a single argument of undef, the "hash_key" used to store the object
                   is set to undef.  If "referential_integrity" or "required" is true, then the
                   columns that participate in the key are set to undef.  (If any key column is
                   part of the primary key, however, it is not set to undef.) Otherwise, the
                   argument must be one of the following:

                   ·   An object of type "class"

                   ·   A list of method name/value pairs.

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter three argument types will be used to construct an object of type
                   "class".  A single primary key value is only a valid argument format if the
                   "class" in question has a single-column primary key.  A hash reference
                   argument must contain sufficient information for the object to be uniquely
                   identified.

                   The object is assigned to "hash_key" after having its "key_columns" set to
                   their corresponding values in the current object.  The object is then
                   immediately saved to the database.

                   If the object does not already exists in the database, it will be inserted.
                   If the object was previously loaded from or saved to the database, it will be
                   updated.  Otherwise, it will be loaded.

                   The parent object must have been loaded or saved prior to setting the list of
                   objects.  If this method is called with arguments before the object has been
                   loaded or saved, a fatal error will occur.

                   If called with no arguments and the "hash_key" used to store the object is
                   defined, the object is returned.  Otherwise, the object is created and loaded.

                   The load may fail for several reasons.  The load will not even be attempted if
                   any of the key attributes in the current object are undefined.  Instead, undef
                   will be returned.

                   If the call to the newly created object's load method returns false, then the
                   normal Rose::DB::Object error handling is triggered.  The false value returned
                   by the call to the load method is returned (assuming no exception was raised).

                   If the load succeeds, the object is returned.

               get_set_on_save
                   Creates a method that will attempt to create and load a
                   Rose::DB::Object-derived object based on a primary key formed from attributes
                   of the current object, and save the object when the "parent" object is saved.

                   If passed a single argument of undef, the "hash_key" used to store the object
                   is set to undef.  If "referential_integrity" or "required" is true, then the
                   columns that participate in the key are set to undef.  (If any key column is
                   part of the primary key, however, it is not set to undef.) Otherwise, the
                   argument must be one of the following:

                   ·   An object of type "class"

                   ·   A list of method name/value pairs.

                   ·   A reference to a hash containing method name/value pairs.

                   ·   A single scalar primary key value.

                   The latter three argument types will be used to construct an object of type
                   "class".  A single primary key value is only a valid argument format if the
                   "class" in question has a single-column primary key.  A hash reference
                   argument must contain sufficient information for the object to be uniquely
                   identified.

                   The object is assigned to "hash_key" after having its "key_columns" set to
                   their corresponding values in the current object.  The object will be saved
                   into the database when the "parent" object is saved.  Any previously pending
                   "get_set_on_save" action is discarded.

                   If the object does not already exists in the database, it will be inserted.
                   If the object was previously loaded from or saved to the database, it will be
                   updated.  Otherwise, it will be loaded.

                   If called with no arguments and the "hash_key" used to store the object is
                   defined, the object is returned.  Otherwise, the object is created and loaded
                   from the database.

                   The load may fail for several reasons.  The load will not even be attempted if
                   any of the key attributes in the current object are undefined.  Instead, undef
                   will be returned.

                   If the call to the newly created object's load method returns false, then the
                   normal Rose::DB::Object error handling is triggered.  The false value returned
                   by the call to the load method is returned (assuming no exception was raised).

                   If the load succeeds, the object is returned.

           Example setup:

               # CLASS     DB TABLE
               # -------   --------
               # Product   products
               # Category  categories

               package Product;

               our @ISA = qw(Rose::DB::Object);
               ...

               # You will almost never call the method-maker directly
               # like this.  See the Rose::DB::Object::Metadata docs
               # for examples of more common usage.
               use Rose::DB::Object::MakeMethods::Generic
               (
                 object_by_key =>
                 [
                   category =>
                   {
                     interface   => 'get_set',
                     class       => 'Category',
                     key_columns =>
                     {
                       # Map Product column names to Category column names
                       category_id => 'id',
                     },
                   },
                 ]
               );
               ...

           Example - get_set interface:

               $product = Product->new(id => 5, category_id => 99);

               # Read from the categories table
               $category = $product->category;

               # $product->category call is roughly equivalent to:
               #
               # $cat = Category->new(id => $product->category_id
               #                      db => $prog->db);
               #
               # $ret = $cat->load;
               # return $ret  unless($ret);
               # return $cat;

               # Does not write to the db
               $product->category(Category->new(...));

               $product->save; # writes to products table only

           Example - get_set_now interface:

               # Read from the products table
               $product = Product->new(id => 5)->load;

               # Read from the categories table
               $category = $product->category;

               # Write to the categories table:
               # (all possible argument formats show)

               # Object argument
               $product->category(Category->new(...));

               # Primary key value
               $product->category(123);

               # Method name/value pairs in a hashref
               $product->category(id => 123);

               # Method name/value pairs in a hashref
               $product->category({ id => 123 });

               # Write to the products table
               $product->save;

           Example - get_set_on_save interface:

               # Read from the products table
               $product = Product->new(id => 5)->load;

               # Read from the categories table
               $category = $product->category;

               # These do not write to the db:

               # Object argument
               $product->category(Category->new(...));

               # Primary key value
               $product->category(123);

               # Method name/value pairs in a hashref
               $product->category(id => 123);

               # Method name/value pairs in a hashref
               $product->category({ id => 123 });

               # Write to both the products and categories tables
               $product->save;

           Example - delete_now interface:

               # Read from the products table
               $product = Product->new(id => 5)->load;

               # Write to both the categories and products tables
               $product->delete_category();

           Example - delete_on_save interface:

               # Read from the products table
               $product = Product->new(id => 5)->load;

               # Does not write to the db
               $product->delete_category();

               # Write to both the products and categories tables
               $product->save;

       scalar
           Create get/set methods for scalar attributes.

           Options
               default VALUE
                   Determines the default value of the attribute.

               check_in ARRAYREF
                   A reference to an array of valid values.  When setting the attribute, if the
                   new value is not equal (string comparison) to one of the valid values, a fatal
                   error will occur.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               init_method NAME
                   The name of the method to call when initializing the value of an undefined
                   attribute.  Defaults to the method name with the prefix "init_" added.  This
                   option implies "with_init".

               interface NAME
                   Choose the interface.  The "get_set" interface is the default.

               length INT
                   The maximum number of characters in the string.

               overflow BEHAVIOR
                   Determines the behavior when the value is greater than the number of
                   characters specified by the "length" option.  Valid values for BEHAVIOR are:

                   fatal
                       Throw an exception.

                   truncate
                       Truncate the value to the correct length.

                   warn
                       Print a warning message.

               with_init BOOL
                   Modifies the behavior of the "get_set" and "get" interfaces.  If the attribute
                   is undefined, the method specified by the "init_method" option is called and
                   the attribute is set to the return value of that method.

           Interfaces
               get_set
                   Creates a get/set method for an object attribute.  When called with an
                   argument, the value of the attribute is set.  The current value of the
                   attribute is returned.

               get Creates an accessor method for an object attribute that returns the current
                   value of the attribute.

               set Creates a mutator method for an object attribute.  When called with an
                   argument, the value of the attribute is set.  If called with no arguments, a
                   fatal error will occur.

           Example:

               package MyDBObject;

               our @ISA = qw(Rose::DB::Object);

               use Rose::DB::Object::MakeMethods::Generic
               (
                 scalar =>
                 [
                   name => { default => 'Joe' },
                   type =>
                   {
                     with_init => 1,
                     check_in  => [ qw(AA AAA C D) ],
                   }
                   set_type =>
                   {
                     check_in  => [ qw(AA AAA C D) ],
                   }
                 ],
               );

               sub init_type { 'C' }
               ...

               $o = MyDBObject->new(...);

               print $o->name; # Joe
               print $o->type; # C

               $o->name('Bob'); # set
               $o->type('AA');  # set

               eval { $o->type('foo') }; # fatal error: invalid value

               print $o->name, ' is ', $o->type; # get

       set Create get/set methods for "set" attributes.   A "set" column in a database table
           contains an unordered group of values.  Not all databases support a "set" column type.
           Check the Rose::DB documentation for your database type.

           Options
               default ARRAYREF
                   Determines the default value of the attribute.  The value should be a
                   reference to an array.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               interface NAME
                   Choose the interface.  The default is "get_set".

               values ARRAYREF
                   A reference to an array of valid values for the set.  If present, attempting
                   to use an invalid value will cause a fatal error.

           Interfaces
               get_set
                   Creates a get/set method for a "set" object attribute.  A "set" column in a
                   database table contains an unordered group of values.  On the Perl side of the
                   fence, an ordered list (an array) is used to store the values, but keep in
                   mind that the order is not significant, nor is it guaranteed to be preserved.

                   When setting the attribute, the value is passed through the parse_set method
                   of the object's db attribute.

                   When saving to the database, if the attribute value is defined, the method
                   will pass the attribute value through the format_set method of the object's db
                   attribute before returning it.

                   When not saving to the database, the method returns the set as a list in list
                   context, or as a reference to the array in scalar context.

               get Creates an accessor method for a "set" object attribute.  A "set" column in a
                   database table contains an unordered group of values.  On the Perl side of the
                   fence, an ordered list (an array) is used to store the values, but keep in
                   mind that the order is not significant, nor is it guaranteed to be preserved.

                   When saving to the database, if the attribute value is defined, the method
                   will pass the attribute value through the format_set method of the object's db
                   attribute before returning it.

                   When not saving to the database, the method returns the set as a list in list
                   context, or as a reference to the array in scalar context.

               set Creates a mutator method for a "set" object attribute.  A "set" column in a
                   database table contains an unordered group of values.  On the Perl side of the
                   fence, an ordered list (an array) is used to store the values, but keep in
                   mind that the order is not significant, nor is it guaranteed to be preserved.

                   When setting the attribute, the value is passed through the parse_set method
                   of the object's db attribute.

                   When saving to the database, if the attribute value is defined, the method
                   will pass the attribute value through the format_set method of the object's db
                   attribute before returning it.

                   When not saving to the database, the method returns the set as a list in list
                   context, or as a reference to the array in scalar context.

           Example:

               package Person;

               our @ISA = qw(Rose::DB::Object);
               ...
               use Rose::DB::Object::MakeMethods::Generic
               (
                 set =>
                 [
                   'nicknames',
                   'set_nicks' => { interface => 'set', hash_key => 'nicknames' },

                   'parts' => { default => [ qw(arms legs) ] },
                 ],
               );
               ...

               @parts = $person->parts; # ('arms', 'legs')
               $parts = $person->parts; # [ 'arms', 'legs' ]

               $person->nicknames('Jack', 'Gimpy');   # set with list
               $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref

               $person->set_nicks('Jack', 'Gimpy');   # set with list
               $person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref

       varchar
           Create get/set methods for variable-length character string attributes.

           Options
               default VALUE
                   Determines the default value of the attribute.

               hash_key NAME
                   The key inside the hash-based object to use for the storage of this attribute.
                   Defaults to the name of the method.

               init_method NAME
                   The name of the method to call when initializing the value of an undefined
                   attribute.  Defaults to the method name with the prefix "init_" added.  This
                   option implies "with_init".

               interface NAME
                   Choose the interface.  The "get_set" interface is the default.

               length INT
                   The maximum number of characters in the string.

               overflow BEHAVIOR
                   Determines the behavior when the value is greater than the number of
                   characters specified by the "length" option.  Valid values for BEHAVIOR are:

                   fatal
                       Throw an exception.

                   truncate
                       Truncate the value to the correct length.

                   warn
                       Print a warning message.

               with_init BOOL
                   Modifies the behavior of the "get_set" and "get" interfaces.  If the attribute
                   is undefined, the method specified by the "init_method" option is called and
                   the attribute is set to the return value of that method.

           Interfaces
               get_set
                   Creates a get/set accessor method for a fixed-length character string
                   attribute.  When setting, any strings longer than "length" will be truncated.
                   If "length" is omitted, the string will be left unmodified.

           Example:

               package MyDBObject;

               our @ISA = qw(Rose::DB::Object);

               use Rose::DB::Object::MakeMethods::Generic
               (
                 varchar =>
                 [
                   'name' => { length => 3 },
                 ],
               );

               ...

               $o->name('John'); # truncates on set
               print $o->name;   # 'Joh'

AUTHOR

       John C. Siracusa (siracusa@gmail.com)

LICENSE

       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This program is free
       software; you can redistribute it and/or modify it under the same terms as Perl itself.