1Rose::DB::Object::MakeMUestehrodCso:n:tGreinbeurtiecdR(o3Ps)eer:l:DDBo:c:uOmbejnetcatt:i:oMnakeMethods::Generic(3)
2
3
4

NAME

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

SYNOPSIS

10         package MyDBObject;
11
12         our @ISA = qw(Rose::DB::Object);
13
14         use Rose::DB::Object::MakeMethods::Generic
15         (
16           scalar =>
17           [
18             'type' =>
19             {
20               with_init => 1,
21               check_in  => [ qw(AA AAA C D) ],
22             },
23
24             'set_type' => { hash_key => 'type' },
25           ],
26
27           character =>
28           [
29             code => { length => 6 }
30           ],
31
32           varchar =>
33           [
34             name => { length => 10 }
35           ],
36
37           boolean =>
38           [
39             'is_red',
40             'is_happy' => { default => 1 },
41           ],
42         );
43
44         sub init_type { 'C' }
45         ...
46
47         $obj = MyDBObject->new(...);
48
49         print $obj->type; # C
50
51         $obj->name('Bob');   # set
52         $obj->set_type('C'); # set
53         $obj->type('AA');    # set
54
55         $obj->set_type; # Fatal error: no argument passed to "set" method
56
57         $obj->name('C' x 40); # truncate on set
58         print $obj->name;     # 'CCCCCCCCCC'
59
60         $obj->code('ABC'); # pad on set
61         print $obj->code;  # 'ABC   '
62
63         eval { $obj->type('foo') }; # fatal error: invalid value
64
65         print $obj->name, ' is ', $obj->type; # get
66
67         $obj->is_red;         # returns undef
68         $obj->is_red('true'); # returns 1 (assuming "true" a
69                               # valid boolean literal according to
70                               # $obj->db->parse_boolean('true'))
71         $obj->is_red('');     # returns 0
72         $obj->is_red;         # returns 0
73
74         $obj->is_happy;       # returns 1
75
76         ...
77
78         package Person;
79
80         our @ISA = qw(Rose::DB::Object);
81         ...
82         use Rose::DB::Object::MakeMethods::Generic
83         (
84           scalar => 'name',
85
86           set =>
87           [
88             'nicknames',
89             'parts' => { default => [ qw(arms legs) ] },
90           ],
91
92           # See the Rose::DB::Object::Metadata::Relationship::ManyToMany
93           # documentation for a more complete example
94           objects_by_map =>
95           [
96             friends =>
97             {
98               map_class    => 'FriendMap',
99               manager_args => { sort_by => Friend->meta->table . '.name' },
100             },
101           ],
102         );
103         ...
104
105         @parts = $person->parts; # ('arms', 'legs')
106         $parts = $person->parts; # [ 'arms', 'legs' ]
107
108         $person->nicknames('Jack', 'Gimpy');   # set with list
109         $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
110
111         print join(', ', map { $_->name } $person->friends);
112         ...
113
114         package Program;
115
116         our @ISA = qw(Rose::DB::Object);
117         ...
118         use Rose::DB::Object::MakeMethods::Generic
119         (
120           objects_by_key =>
121           [
122             bugs =>
123             {
124               class => 'Bug',
125               key_columns =>
126               {
127                 # Map Program column names to Bug column names
128                 id      => 'program_id',
129                 version => 'version',
130               },
131               manager_args =>
132               {
133                 sort_by => Bug->meta->table . '.date_submitted DESC',
134               },
135               query_args   => [ state => { ne => 'closed' } ],
136             },
137           ]
138         );
139         ...
140
141         $prog = Program->new(id => 5, version => '3.0', ...);
142
143         $bugs = $prog->bugs;
144
145         # Calls (essentially):
146         #
147         # Rose::DB::Object::Manager->get_objects(
148         #   db           => $prog->db, # share_db defaults to true
149         #   object_class => 'Bug',
150         #   query =>
151         #   {
152         #     program_id => 5,     # value of $prog->id
153         #     version    => '3.0', # value of $prog->version
154         #     state      => { ne => 'closed' },
155         #   },
156         #   sort_by => 'date_submitted DESC');
157
158         ...
159
160         package Product;
161
162         our @ISA = qw(Rose::DB::Object);
163         ...
164         use Rose::DB::Object::MakeMethods::Generic
165         (
166           object_by_key =>
167           [
168             category =>
169             {
170               class => 'Category',
171               key_columns =>
172               {
173                 # Map Product column names to Category column names
174                 category_id => 'id',
175               },
176             },
177           ]
178         );
179         ...
180
181         $product = Product->new(id => 5, category_id => 99);
182
183         $category = $product->category;
184
185         # $product->category call is roughly equivalent to:
186         #
187         # $cat = Category->new(id => $product->category_id,
188         #                      db => $prog->db);
189         #
190         # $ret = $cat->load;
191         # return $ret  unless($ret);
192         # return $cat;
193

DESCRIPTION

195       Rose::DB::Object::MakeMethods::Generic is a method maker that inherits
196       from Rose::Object::MakeMethods.  See the Rose::Object::MakeMethods
197       documentation to learn about the interface.  The method types provided
198       by this module are described below.
199
200       All method types defined by this module are designed to work with
201       objects that are subclasses of (or otherwise conform to the interface
202       of) Rose::DB::Object.  In particular, the object is expected to have a
203       db method that returns a Rose::DB-derived object.  See the
204       Rose::DB::Object documentation for more details.
205

METHODS TYPES

207       array
208           Create get/set methods for "array" attributes.   A "array" column
209           in a database table contains an ordered list of values.  Not all
210           databases support an "array" column type.  Check the Rose::DB
211           documentation for your database type.
212
213           Options
214               default VALUE
215                   Determines the default value of the attribute.  The value
216                   should be a reference to an array.
217
218               hash_key NAME
219                   The key inside the hash-based object to use for the storage
220                   of this attribute.  Defaults to the name of the method.
221
222               interface NAME
223                   Choose the interface.  The default is "get_set".
224
225           Interfaces
226               get_set
227                   Creates a get/set method for a "array" object attribute.  A
228                   "array" column in a database table contains an ordered list
229                   of values.
230
231                   When setting the attribute, the value is passed through the
232                   parse_array method of the object's db attribute.
233
234                   When saving to the database, if the attribute value is
235                   defined, the method will pass the attribute value through
236                   the format_array method of the object's db attribute before
237                   returning it.
238
239                   When not saving to the database, the method returns the
240                   array as a list in list context, or as a reference to the
241                   array in scalar context.
242
243               get Creates an accessor method for a "array" object attribute.
244                   A "array" column in a database table contains an ordered
245                   list of values.
246
247                   When saving to the database, if the attribute value is
248                   defined, the method will pass the attribute value through
249                   the format_array method of the object's db attribute before
250                   returning it.
251
252                   When not saving to the database, the method returns the
253                   array as a list in list context, or as a reference to the
254                   array in scalar context.
255
256               set Creates a mutator method for a "array" object attribute.  A
257                   "array" column in a database table contains an ordered list
258                   of values.
259
260                   When setting the attribute, the value is passed through the
261                   parse_array method of the object's db attribute.
262
263                   When saving to the database, if the attribute value is
264                   defined, the method will pass the attribute value through
265                   the format_array method of the object's db attribute before
266                   returning it.
267
268                   When not saving to the database, the method returns the
269                   array as a list in list context, or as a reference to the
270                   array in scalar context.
271
272                   If called with no arguments, a fatal error will occur.
273
274           Example:
275
276               package Person;
277
278               our @ISA = qw(Rose::DB::Object);
279               ...
280               use Rose::DB::Object::MakeMethods::Generic
281               (
282                 array =>
283                 [
284                   'nicknames',
285                   set_nicks => { interface => 'set', hash_key => 'nicknames' },
286                   parts     => { default => [ qw(arms legs) ] },
287                 ],
288               );
289               ...
290
291               @parts = $person->parts; # ('arms', 'legs')
292               $parts = $person->parts; # [ 'arms', 'legs' ]
293
294               $person->nicknames('Jack', 'Gimpy');   # set with list
295               $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
296
297               $person->set_nicks('Jack', 'Gimpy');   # set with list
298               $person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref
299
300       bitfield
301           Create get/set methods for bitfield attributes.
302
303           Options
304               default VALUE
305                   Determines the default value of the attribute.
306
307               hash_key NAME
308                   The key inside the hash-based object to use for the storage
309                   of this attribute.  Defaults to the name of the method.
310
311               interface NAME
312                   Choose the interface.  The default is "get_set".
313
314               intersects NAME
315                   Set the name of the "intersects" method.  (See
316                   "with_intersects" below.)  Defaults to the bitfield
317                   attribute method name with "_intersects" appended.
318
319               bits INT
320                   The number of bits in the bitfield.  Defaults to 32.
321
322               with_intersects BOOL
323                   This option is only applicable with the "get_set"
324                   interface.
325
326                   If true, create an "intersects" helper method in addition
327                   to the "get_set" method.  The intersection method name will
328                   be the attribute method name with "_intersects" appended,
329                   or the value of the "intersects" option, if it is passed.
330
331                   The "intersects" method will return true if there is any
332                   intersection between its arguments and the value of the
333                   bitfield attribute (i.e., if Bit::Vector's Intersection
334                   method returns a value greater than zero), false (but
335                   defined) otherwise.  Its argument is passed through the
336                   parse_bitfield method of the object's db attribute before
337                   being tested for intersection.  Returns undef if the
338                   bitfield is not defined.
339
340           Interfaces
341               get_set
342                   Creates a get/set method for a bitfield attribute.  When
343                   setting the attribute, the value is passed through the
344                   parse_bitfield method of the object's db attribute before
345                   being assigned.
346
347                   When saving to the database, the method will pass the
348                   attribute value through the format_bitfield method of the
349                   object's db attribute before returning it.  Otherwise, the
350                   value is returned as-is.
351
352               get Creates an accessor method for a bitfield attribute.  When
353                   saving to the database, the method will pass the attribute
354                   value through the format_bitfield method of the object's db
355                   attribute before returning it.  Otherwise, the value is
356                   returned as-is.
357
358               set Creates a mutator method for a bitfield attribute.  When
359                   setting the attribute, the value is passed through the
360                   parse_bitfield method of the object's db attribute before
361                   being assigned.
362
363                   When saving to the database, the method will pass the
364                   attribute value through the format_bitfield method of the
365                   object's db attribute before returning it.  Otherwise, the
366                   value is returned as-is.
367
368                   If called with no arguments, a fatal error will occur.
369
370           Example:
371
372               package MyDBObject;
373
374               our @ISA = qw(Rose::DB::Object);
375
376               use Rose::DB::Object::MakeMethods::Generic
377               (
378                 bitfield =>
379                 [
380                   'flags' => { size => 32, default => 2 },
381                   'bits'  => { size => 16, with_intersects => 1 },
382                 ],
383               );
384
385               ...
386
387               print $o->flags->to_Bin; # 00000000000000000000000000000010
388
389               $o->bits('101');
390
391               $o->bits_intersects('100'); # true
392               $o->bits_intersects('010'); # false
393
394       boolean
395           Create get/set methods for boolean attributes.
396
397           Options
398               default VALUE
399                   Determines the default value of the attribute.
400
401               hash_key NAME
402                   The key inside the hash-based object to use for the storage
403                   of this attribute.  Defaults to the name of the method.
404
405               interface NAME
406                   Choose the interface.  The default is "get_set".
407
408           Interfaces
409               get_set
410                   Creates a get/set method for a boolean attribute.  When
411                   setting the attribute, if the value is "true" according to
412                   Perl's rules, it is compared to a list of "common" true and
413                   false values: 1, 0, 1.0 (with any number of zeros), 0.0
414                   (with any number of zeros), t, true, f, false, yes, no.
415                   (All are case-insensitive.)  If the value matches, then it
416                   is set to true (1) or false (0) accordingly.
417
418                   If the value does not match any of those, then it is passed
419                   through the parse_boolean method of the object's db
420                   attribute.  If parse_boolean returns true (1) or false (0),
421                   then the attribute is set accordingly.  If parse_boolean
422                   returns undef, a fatal error will occur.  If the value is
423                   "false" according to Perl's rules, the attribute is set to
424                   zero (0).
425
426                   When saving to the database, the method will pass the
427                   attribute value through the format_boolean method of the
428                   object's db attribute before returning it.  Otherwise, the
429                   value is returned as-is.
430
431               get Creates an accessor method for a boolean attribute.  When
432                   saving to the database, the method will pass the attribute
433                   value through the format_boolean method of the object's db
434                   attribute before returning it.  Otherwise, the value is
435                   returned as-is.
436
437               set Creates a mutator method for a boolean attribute.  When
438                   setting the attribute, if the value is "true" according to
439                   Perl's rules, it is compared to a list of "common" true and
440                   false values: 1, 0, 1.0 (with any number of zeros), 0.0
441                   (with any number of zeros), t, true, f, false, yes, no.
442                   (All are case-insensitive.)  If the value matches, then it
443                   is set to true (1) or false (0) accordingly.
444
445                   If the value does not match any of those, then it is passed
446                   through the parse_boolean method of the object's db
447                   attribute.  If parse_boolean returns true (1) or false (0),
448                   then the attribute is set accordingly.  If parse_boolean
449                   returns undef, a fatal error will occur.  If the value is
450                   "false" according to Perl's rules, the attribute is set to
451                   zero (0).
452
453                   If called with no arguments, a fatal error will occur.
454
455           Example:
456
457               package MyDBObject;
458
459               our @ISA = qw(Rose::DB::Object);
460
461               use Rose::DB::Object::MakeMethods::Generic
462               (
463                 boolean =>
464                 [
465                   'is_red',
466                   'is_happy'  => { default => 1 },
467                   'set_happy' => { interface => 'set', hash_key => 'is_happy' },
468                 ],
469               );
470
471               $obj->is_red;         # returns undef
472               $obj->is_red('true'); # returns 1 (assuming "true" a
473                                     # valid boolean literal according to
474                                     # $obj->db->parse_boolean('true'))
475               $obj->is_red('');     # returns 0
476               $obj->is_red;         # returns 0
477
478               $obj->is_happy;       # returns 1
479               $obj->set_happy(0);   # returns 0
480               $obj->is_happy;       # returns 0
481
482       character
483           Create get/set methods for fixed-length character string
484           attributes.
485
486           Options
487               check_in ARRAYREF
488                   A reference to an array of valid values.  When setting the
489                   attribute, if the new value is not equal (string
490                   comparison) to one of the valid values, a fatal error will
491                   occur.
492
493               default VALUE
494                   Determines the default value of the attribute.
495
496               hash_key NAME
497                   The key inside the hash-based object to use for the storage
498                   of this attribute.  Defaults to the name of the method.
499
500               init_method NAME
501                   The name of the method to call when initializing the value
502                   of an undefined attribute.  Defaults to the method name
503                   with the prefix "init_" added.  This option implies
504                   "with_init".
505
506               interface NAME
507                   Choose the interface.  The default is "get_set".
508
509               length INT
510                   The number of characters in the string.  Any strings
511                   shorter than this will be padded with spaces to meet the
512                   length requirement.  If length is omitted, the string will
513                   be left unmodified.
514
515               overflow BEHAVIOR
516                   Determines the behavior when the value is greater than the
517                   number of characters specified by the "length" option.
518                   Valid values for BEHAVIOR are:
519
520                   fatal
521                       Throw an exception.
522
523                   truncate
524                       Truncate the value to the correct length.
525
526                   warn
527                       Print a warning message.
528
529               with_init BOOL
530                   Modifies the behavior of the "get_set" and "get"
531                   interfaces.  If the attribute is undefined, the method
532                   specified by the "init_method" option is called and the
533                   attribute is set to the return value of that method.
534
535           Interfaces
536               get_set
537                   Creates a get/set method for a fixed-length character
538                   string attribute.  When setting, any strings longer than
539                   "length" will be truncated, and any strings shorter will be
540                   padded with spaces to meet the length requirement.  If
541                   "length" is omitted, the string will be left unmodified.
542
543               get Creates an accessor method for a fixed-length character
544                   string attribute.
545
546               set Creates a mutator method for a fixed-length character
547                   string attribute.  Any strings longer than "length" will be
548                   truncated, and any strings shorter will be padded with
549                   spaces to meet the length requirement.  If "length" is
550                   omitted, the string will be left unmodified.
551
552           Example:
553
554               package MyDBObject;
555
556               our @ISA = qw(Rose::DB::Object);
557
558               use Rose::DB::Object::MakeMethods::Generic
559               (
560                 character =>
561                 [
562                   'name' => { length => 3 },
563                 ],
564               );
565
566               ...
567
568               $o->name('John'); # truncates on set
569               print $o->name;   # 'Joh'
570
571               $o->name('A'); # pads on set
572               print $o->name;   # 'A  '
573
574       enum
575           Create get/set methods for enum attributes.
576
577           Options
578               default VALUE
579                   Determines the default value of the attribute.
580
581               values ARRAYREF
582                   A reference to an array of the enum values.  This attribute
583                   is required.  When setting the attribute, if the new value
584                   is not equal (string comparison) to one of the enum values,
585                   a fatal error will occur.
586
587               hash_key NAME
588                   The key inside the hash-based object to use for the storage
589                   of this attribute.  Defaults to the name of the method.
590
591               init_method NAME
592                   The name of the method to call when initializing the value
593                   of an undefined attribute.  Defaults to the method name
594                   with the prefix "init_" added.  This option implies
595                   "with_init".
596
597               interface NAME
598                   Choose the interface.  The "get_set" interface is the
599                   default.
600
601               with_init BOOL
602                   Modifies the behavior of the "get_set" and "get"
603                   interfaces.  If the attribute is undefined, the method
604                   specified by the "init_method" option is called and the
605                   attribute is set to the return value of that method.
606
607           Interfaces
608               get_set
609                   Creates a get/set method for an enum attribute.  When
610                   called with an argument, the value of the attribute is set.
611                   If the value is invalid, a fatal error will occur.  The
612                   current value of the attribute is returned.
613
614               get Creates an accessor method for an object attribute that
615                   returns the current value of the attribute.
616
617               set Creates a mutator method for an object attribute.  When
618                   called with an argument, the value of the attribute is set.
619                   If the value is invalid, a fatal error will occur.  If
620                   called with no arguments, a fatal error will occur.
621
622           Example:
623
624               package MyDBObject;
625
626               our @ISA = qw(Rose::DB::Object);
627
628               use Rose::DB::Object::MakeMethods::Generic
629               (
630                 enum =>
631                 [
632                   type  => { values => [ qw(main aux extra) ], default => 'aux' },
633                   stage => { values => [ qw(new std old) ], with_init => 1 },
634                 ],
635               );
636
637               sub init_stage { 'new' }
638               ...
639
640               $o = MyDBObject->new(...);
641
642               print $o->type;   # aux
643               print $o->stage;  # new
644
645               $o->type('aux');  # set
646               $o->stage('old'); # set
647
648               eval { $o->type('foo') }; # fatal error: invalid value
649
650               print $o->type, ' is at stage ', $o->stage; # get
651
652       integer
653           Create get/set methods for integer attributes.
654
655           Options
656               default VALUE
657                   Determines the default value of the attribute.
658
659               hash_key NAME
660                   The key inside the hash-based object to use for the storage
661                   of this attribute.  Defaults to the name of the method.
662
663               init_method NAME
664                   The name of the method to call when initializing the value
665                   of an undefined attribute.  Defaults to the method name
666                   with the prefix "init_" added.  This option implies
667                   "with_init".
668
669               interface NAME
670                   Choose the interface.  The "get_set" interface is the
671                   default.
672
673               with_init BOOL
674                   Modifies the behavior of the "get_set" and "get"
675                   interfaces.  If the attribute is undefined, the method
676                   specified by the "init_method" option is called and the
677                   attribute is set to the return value of that method.
678
679           Interfaces
680               get_set
681                   Creates a get/set method for an integer object attribute.
682                   When called with an argument, the value of the attribute is
683                   set.  The current value of the attribute is returned.
684
685               get Creates an accessor method for an integer object attribute
686                   that returns the current value of the attribute.
687
688               set Creates a mutator method for an integer object attribute.
689                   When called with an argument, the value of the attribute is
690                   set.  If called with no arguments, a fatal error will
691                   occur.
692
693           Example:
694
695               package MyDBObject;
696
697               our @ISA = qw(Rose::DB::Object);
698
699               use Rose::DB::Object::MakeMethods::Generic
700               (
701                 integer =>
702                 [
703                   code => { default => 99  },
704                   type => { with_init => 1 }
705                 ],
706               );
707
708               sub init_type { 123 }
709               ...
710
711               $o = MyDBObject->new(...);
712
713               print $o->code; # 99
714               print $o->type; # 123
715
716               $o->code(8675309); # set
717               $o->type(42);      # set
718
719       objects_by_key
720           Create get/set methods for an array of Rose::DB::Object-derived
721           objects fetched based on a key formed from attributes of the
722           current object.
723
724           Options
725               class CLASS
726                   The name of the Rose::DB::Object-derived class of the
727                   objects to be fetched.  This option is required.
728
729               hash_key NAME
730                   The key inside the hash-based object to use for the storage
731                   of the fetched objects.  Defaults to the name of the
732                   method.
733
734               key_columns HASHREF
735                   A reference to a hash that maps column names in the current
736                   object to those in the objects to be fetched.  This option
737                   is required.
738
739               manager_args HASHREF
740                   A reference to a hash of arguments passed to the
741                   "manager_class" when fetching objects.  If "manager_class"
742                   defaults to Rose::DB::Object::Manager, the following
743                   argument is added to the "manager_args" hash: "object_class
744                   => CLASS", where CLASS is the value of the "class" option
745                   (see above).  If "manager_args" includes a "sort_by"
746                   argument, be sure to prefix each column name with the
747                   appropriate table name.  (See the synopsis for examples.)
748
749               manager_class CLASS
750                   The name of the Rose::DB::Object::Manager-derived class
751                   used to fetch the objects.  The "manager_method" class
752                   method is called on this class.  Defaults to
753                   Rose::DB::Object::Manager.
754
755               manager_method NAME
756                   The name of the class method to call on "manager_class" in
757                   order to fetch the objects.  Defaults to "get_objects".
758
759               manager_count_method NAME
760                   The name of the class method to call on "manager_class" in
761                   order to count the objects.  Defaults to
762                   "get_objects_count".
763
764               interface NAME
765                   Choose the interface.  The "get_set" interface is the
766                   default.
767
768               relationship OBJECT
769                   The Rose::DB::Object::Metadata::Relationship object that
770                   describes the "key" through which the "objects_by_key" are
771                   fetched.  This is required when using the "add_now",
772                   "add_on_save", and "get_set_on_save" interfaces.
773
774               share_db BOOL
775                   If true, the db attribute of the current object is shared
776                   with all of the objects fetched.  Defaults to true.
777
778               query_args ARRAYREF
779                   A reference to an array of arguments added to the value of
780                   the "query" parameter passed to the call to
781                   "manager_class"'s "manager_method" class method.
782
783           Interfaces
784               count
785                   Creates a method that will attempt to count
786                   Rose::DB::Object-derived objects based on a key formed from
787                   attributes of the current object, plus any additional
788                   parameters passed to the method call.  Note that this
789                   method counts the objects in the database at the time of
790                   the call.  This may be different than the number of objects
791                   attached to the current object or otherwise in memory.
792
793                   Since the objects counted are partially determined by the
794                   arguments passed to the method, the count is not retained.
795                   It is simply returned.  Each call counts the specified
796                   objects again, even if the arguments are the same as the
797                   previous call.
798
799                   If the first argument is a reference to a hash or array, it
800                   is converted to a reference to an array (if necessary) and
801                   taken as the value of the "query" parameter.  All arguments
802                   are passed on to the "manager_class"'s
803                   "manager_count_method" method, augmented by the key formed
804                   from attributes of the current object.  Query parameters
805                   are added to the existing contents of the "query"
806                   parameter.  Other parameters replace existing parameters if
807                   the existing values are simple scalars, or augment existing
808                   parameters if the existing values are references to hashes
809                   or arrays.
810
811                   The count may fail for several reasons.  The count will not
812                   even be attempted if any of the key attributes in the
813                   current object are undefined.  Instead, undef (in scalar
814                   context) or an empty list (in list context) will be
815                   returned.  If the call to "manager_class"'s
816                   "manager_count_method" method returns undef, the behavior
817                   is determined by the metadata object's error_mode.  If the
818                   mode is "return", that false value (in scalar context) or
819                   an empty list (in list context) is returned.
820
821                   If the count succeeds, the number is returned.  (If the
822                   count finds zero objects, the count will be 0.  This is
823                   still considered success.)
824
825               find
826                   Creates a method that will attempt to fetch
827                   Rose::DB::Object-derived objects based on a key formed from
828                   attributes of the current object, plus any additional
829                   parameters passed to the method call.  Since the objects
830                   fetched are partially determined by the arguments passed to
831                   the method, the list of objects is not retained.  It is
832                   simply returned.  Each call fetches the requested objects
833                   again, even if the arguments are the same as the previous
834                   call.
835
836                   If the first argument is a reference to a hash or array, it
837                   is converted to a reference to an array (if necessary) and
838                   taken as the value of the "query" parameter.  All arguments
839                   are passed on to the "manager_class"'s "manager_method"
840                   method, augmented by the key formed from attributes of the
841                   current object.  Query parameters are added to the existing
842                   contents of the "query" parameter.  Other parameters
843                   replace existing parameters if the existing values are
844                   simple scalars, or augment existing parameters if the
845                   existing values are references to hashes or arrays.
846
847                   The fetch may fail for several reasons.  The fetch will not
848                   even be attempted if any of the key attributes in the
849                   current object are undefined.  Instead, undef (in scalar
850                   context) or an empty list (in list context) will be
851                   returned.  If the call to "manager_class"'s
852                   "manager_method" method returns false, the behavior is
853                   determined by the metadata object's error_mode.  If the
854                   mode is "return", that false value (in scalar context) or
855                   an empty list (in list context) is returned.
856
857                   If the fetch succeeds, a list (in list context) or a
858                   reference to the array of objects (in scalar context) is
859                   returned.  (If the fetch finds zero objects, the list or
860                   array reference will simply be empty.  This is still
861                   considered success.)
862
863               iterator
864                   Behaves just like find but returns an iterator rather than
865                   an array or arrayref.
866
867               get_set
868                   Creates a method that will attempt to fetch
869                   Rose::DB::Object-derived objects based on a key formed from
870                   attributes of the current object.
871
872                   If passed a single argument of undef, the "hash_key" used
873                   to store the objects is set to undef.  Otherwise, the
874                   argument(s) must be a list or reference to an array
875                   containing items in one or more of the following formats:
876
877                   •   An object of type "class".
878
879                   •   A reference to a hash containing method name/value
880                       pairs.
881
882                   •   A single scalar primary key value.
883
884                   The latter two formats will be used to construct an object
885                   of type "class".  A single primary key value is only a
886                   valid argument format if the "class" in question has a
887                   single-column primary key.  A hash reference argument must
888                   contain sufficient information for the object to be
889                   uniquely identified.
890
891                   The list of object is assigned to "hash_key".  Note that
892                   these objects are not added to the database.  Use the
893                   "get_set_now" or "get_set_on_save" interface to do that.
894
895                   If called with no arguments and the hash key used to store
896                   the list of objects is defined, the list (in list context)
897                   or a reference to that array (in scalar context) of objects
898                   is returned.  Otherwise, the objects are fetched.
899
900                   The fetch may fail for several reasons.  The fetch will not
901                   even be attempted if any of the key attributes in the
902                   current object are undefined.  Instead, undef (in scalar
903                   context) or an empty list (in list context) will be
904                   returned.  If the call to "manager_class"'s
905                   "manager_method" method returns false, the behavior is
906                   determined by the metadata object's error_mode.  If the
907                   mode is "return", that false value (in scalar context) or
908                   an empty list (in list context) is returned.
909
910                   If the fetch succeeds, a list (in list context) or a
911                   reference to the array of objects (in scalar context) is
912                   returned.  (If the fetch finds zero objects, the list or
913                   array reference will simply be empty.  This is still
914                   considered success.)
915
916               get_set_now
917                   Creates a method that will attempt to fetch
918                   Rose::DB::Object-derived objects based on a key formed from
919                   attributes of the current object, and will also save the
920                   objects to the database when called with arguments.  The
921                   objects do not have to already exist in the database; they
922                   will be inserted if needed.
923
924                   If passed a single argument of undef, the list of objects
925                   is set to undef, causing it to be reloaded the next time
926                   the method is called with no arguments.  (Pass a reference
927                   to an empty array to cause all of the existing objects to
928                   be deleted from the database.)  Any pending "set_on_save"
929                   or "add_on_save" actions are discarded.
930
931                   Otherwise, the argument(s) must be a list or reference to
932                   an array containing items in one or more of the following
933                   formats:
934
935                   •   An object of type "class".
936
937                   •   A reference to a hash containing method name/value
938                       pairs.
939
940                   •   A single scalar primary key value.
941
942                   The latter two formats will be used to construct an object
943                   of type "class".  A single primary key value is only a
944                   valid argument format if the "class" in question has a
945                   single-column primary key.  A hash reference argument must
946                   contain sufficient information for the object to be
947                   uniquely identified.
948
949                   The list of object is assigned to "hash_key", the old
950                   objects are deleted from the database, and the new ones are
951                   added to the database.  Any pending "set_on_save" or
952                   "add_on_save" actions are discarded.
953
954                   When adding each object, if the object does not already
955                   exists in the database, it will be inserted.  If the object
956                   was previously loaded from or saved to the database, it
957                   will be updated.  Otherwise, it will be loaded.
958
959                   The parent object must have been loaded or saved prior to
960                   setting the list of objects.  If this method is called with
961                   arguments before the object has been  loaded or saved, a
962                   fatal error will occur.
963
964                   If called with no arguments and the hash key used to store
965                   the list of objects is defined, the list (in list context)
966                   or a reference to that array (in scalar context) of objects
967                   is returned.  Otherwise, the objects are fetched.
968
969                   The fetch may fail for several reasons.  The fetch will not
970                   even be attempted if any of the key attributes in the
971                   current object are undefined.  Instead, undef (in scalar
972                   context) or an empty list (in list context) will be
973                   returned.  If the call to "manager_class"'s
974                   "manager_method" method returns false, the behavior is
975                   determined by the metadata object's error_mode.  If the
976                   mode is "return", that false value (in scalar context) or
977                   an empty list (in list context) is returned.
978
979                   If the fetch succeeds, a list (in list context) or a
980                   reference to the array of objects (in scalar context) is
981                   returned.  (If the fetch finds zero objects, the list or
982                   array reference will simply be empty.  This is still
983                   considered success.)
984
985               get_set_on_save
986                   Creates a method that will attempt to fetch
987                   Rose::DB::Object-derived objects based on a key formed from
988                   attributes of the current object, and will also save the
989                   objects to the database when the "parent" object is saved.
990                   The objects do not have to already exist in the database;
991                   they will be inserted if needed.
992
993                   If passed a single argument of undef, the list of objects
994                   is set to undef, causing it to be reloaded the next time
995                   the method is called with no arguments.  (Pass a reference
996                   to an empty array to cause all of the existing objects to
997                   be deleted from the database when the parent is saved.)
998
999                   Otherwise, the argument(s) must be a list or reference to
1000                   an array containing items in one or more of the following
1001                   formats:
1002
1003                   •   An object of type "class".
1004
1005                   •   A reference to a hash containing method name/value
1006                       pairs.
1007
1008                   •   A single scalar primary key value.
1009
1010                   The latter two formats will be used to construct an object
1011                   of type "class".  A single primary key value is only a
1012                   valid argument format if the "class" in question has a
1013                   single-column primary key.  A hash reference argument must
1014                   contain sufficient information for the object to be
1015                   uniquely identified.
1016
1017                   The list of object is assigned to "hash_key".  The old
1018                   objects are scheduled to be deleted from the database and
1019                   the new ones are scheduled to be added to the database when
1020                   the parent is saved.  Any pending "set_on_save" or
1021                   "add_on_save" actions are discarded.
1022
1023                   When adding each object when the parent is saved, if the
1024                   object does not already exists in the database, it will be
1025                   inserted.  If the object was previously loaded from or
1026                   saved to the database, it will be updated.  Otherwise, it
1027                   will be loaded.
1028
1029                   If called with no arguments and the hash key used to store
1030                   the list of objects is defined, the list (in list context)
1031                   or a reference to that array (in scalar context) of objects
1032                   is returned.  Otherwise, the objects are fetched.
1033
1034                   The fetch may fail for several reasons.  The fetch will not
1035                   even be attempted if any of the key attributes in the
1036                   current object are undefined.  Instead, undef (in scalar
1037                   context) or an empty list (in list context) will be
1038                   returned.  If the call to "manager_class"'s
1039                   "manager_method" method returns false, the behavior is
1040                   determined by the metadata object's error_mode.  If the
1041                   mode is "return", that false value (in scalar context) or
1042                   an empty list (in list context) is returned.
1043
1044                   If the fetch succeeds, a list (in list context) or a
1045                   reference to the array of objects (in scalar context) is
1046                   returned.  (If the fetch finds zero objects, the list or
1047                   array reference will simply be empty.  This is still
1048                   considered success.)
1049
1050               add_now
1051                   Creates a method that will add to a list of
1052                   Rose::DB::Object-derived objects that are related to the
1053                   current object by a key formed from attributes of the
1054                   current object.  The objects do not have to already exist
1055                   in the database; they will be inserted if needed.
1056
1057                   This method returns the list of objects added when called
1058                   in list context, and the number of objects added when
1059                   called in scalar context.  If one or more objects could not
1060                   be added, undef (in scalar context) or an empty list (in
1061                   list context) is returned and the parent object's error
1062                   attribute is set.
1063
1064                   If passed an empty list, the method does nothing and the
1065                   parent object's error attribute is set.
1066
1067                   If passed any arguments, the parent object must have been
1068                   loaded or saved prior to adding to the list of objects.  If
1069                   this method is called with a non-empty list as an argument
1070                   before the parent object has been  loaded or saved, a fatal
1071                   error will occur.
1072
1073                   The argument(s) must be a list or reference to an array
1074                   containing items in one or more of the following formats:
1075
1076                   •   An object of type "class".
1077
1078                   •   A reference to a hash containing method name/value
1079                       pairs.
1080
1081                   •   A single scalar primary key value.
1082
1083                   The latter two formats will be used to construct an object
1084                   of type "class".  A single primary key value is only a
1085                   valid argument format if the "class" in question has a
1086                   single-column primary key.  A hash reference argument must
1087                   contain sufficient information for the object to be
1088                   uniquely identified.
1089
1090                   These objects are linked to the parent object (by setting
1091                   the appropriate key attributes) and then added to the
1092                   database.
1093
1094                   When adding each object, if the object does not already
1095                   exists in the database, it will be inserted.  If the object
1096                   was previously loaded from or saved to the database, it
1097                   will be updated.  Otherwise, it will be loaded.
1098
1099                   The parent object's list of related objects is then set to
1100                   undef, causing the related objects to be reloaded from the
1101                   database the next time they're needed.
1102
1103               add_on_save
1104                   Creates a method that will add to a list of
1105                   Rose::DB::Object-derived objects that are related to the
1106                   current object by a key formed from attributes of the
1107                   current object.  The objects will be added to the database
1108                   when the parent object is saved.  The objects do not have
1109                   to already exist in the database; they will be inserted if
1110                   needed.
1111
1112                   This method returns the list of objects to be added when
1113                   called in list context, and the number of items to be added
1114                   when called in scalar context.
1115
1116                   If passed an empty list, the method does nothing and the
1117                   parent object's error attribute is set.
1118
1119                   Otherwise, the argument(s) must be a list or reference to
1120                   an array containing items in one or more of the following
1121                   formats:
1122
1123                   •   An object of type "class".
1124
1125                   •   A reference to a hash containing method name/value
1126                       pairs.
1127
1128                   •   A single scalar primary key value.
1129
1130                   The latter two formats will be used to construct an object
1131                   of type "class".  A single primary key value is only a
1132                   valid argument format if the "class" in question has a
1133                   single-column primary key.  A hash reference argument must
1134                   contain sufficient information for the object to be
1135                   uniquely identified.
1136
1137                   These objects are linked to the parent object (by setting
1138                   the appropriate key attributes, whether or not they're
1139                   defined in the parent object) and are scheduled to be added
1140                   to the database when the parent object is saved.  They are
1141                   also added to the parent object's current list of related
1142                   objects, if the list is defined at the time of the call.
1143
1144                   When adding each object when the parent is saved, if the
1145                   object does not already exists in the database, it will be
1146                   inserted.  If the object was previously loaded from or
1147                   saved to the database, it will be updated.  Otherwise, it
1148                   will be loaded.
1149
1150           Example setup:
1151
1152               # CLASS     DB TABLE
1153               # -------   --------
1154               # Program   programs
1155               # Bug       bugs
1156
1157               package Program;
1158
1159               our @ISA = qw(Rose::DB::Object);
1160               ...
1161               # You will almost never call the method-maker directly
1162               # like this.  See the Rose::DB::Object::Metadata docs
1163               # for examples of more common usage.
1164               use Rose::DB::Object::MakeMethods::Generic
1165               (
1166                 objects_by_key =>
1167                 [
1168                   find_bugs =>
1169                   {
1170                     interface => 'find',
1171                     class     => 'Bug',
1172                     key_columns =>
1173                     {
1174                       # Map Program column names to Bug column names
1175                       id      => 'program_id',
1176                       version => 'version',
1177                     },
1178                     manager_args => { sort_by => 'date_submitted DESC' },
1179                   },
1180
1181                   bugs =>
1182                   {
1183                     interface => '...', # get_set, get_set_now, get_set_on_save
1184                     class     => 'Bug',
1185                     key_columns =>
1186                     {
1187                       # Map Program column names to Bug column names
1188                       id      => 'program_id',
1189                       version => 'version',
1190                     },
1191                     manager_args => { sort_by => 'date_submitted DESC' },
1192                     query_args   => { state => { ne => 'closed' } },
1193                   },
1194
1195                   add_bugs =>
1196                   {
1197                     interface => '...', # add_now or add_on_save
1198                     class     => 'Bug',
1199                     key_columns =>
1200                     {
1201                       # Map Program column names to Bug column names
1202                       id      => 'program_id',
1203                       version => 'version',
1204                     },
1205                     manager_args => { sort_by => 'date_submitted DESC' },
1206                     query_args   => { state => { ne => 'closed' } },
1207                   },
1208                 ]
1209               );
1210               ...
1211
1212           Example - find interface:
1213
1214               # Read from the programs table
1215               $prog = Program->new(id => 5)->load;
1216
1217               # Read from the bugs table
1218               $bugs = $prog->find_bugs;
1219
1220               # Calls (essentially):
1221               #
1222               # Rose::DB::Object::Manager->get_objects(
1223               #   db           => $prog->db, # share_db defaults to true
1224               #   object_class => 'Bug',
1225               #   query =>
1226               #   [
1227               #     program_id => 5,     # value of $prog->id
1228               #     version    => '3.0', # value of $prog->version
1229               #   ],
1230               #   sort_by => 'date_submitted DESC');
1231
1232               # Augment query
1233               $bugs = $prog->find_bugs({ state => 'open' });
1234
1235               # Calls (essentially):
1236               #
1237               # Rose::DB::Object::Manager->get_objects(
1238               #   db           => $prog->db, # share_db defaults to true
1239               #   object_class => 'Bug',
1240               #   query =>
1241               #   [
1242               #     program_id => 5,     # value of $prog->id
1243               #     version    => '3.0', # value of $prog->version
1244               #     state      => 'open',
1245               #   ],
1246               #   sort_by => 'date_submitted DESC');
1247               ...
1248
1249               # Augment query and replace sort_by value
1250               $bugs = $prog->find_bugs(query   => [ state => 'defunct' ],
1251                                        sort_by => 'name');
1252
1253               # Calls (essentially):
1254               #
1255               # Rose::DB::Object::Manager->get_objects(
1256               #   db           => $prog->db, # share_db defaults to true
1257               #   object_class => 'Bug',
1258               #   query =>
1259               #   [
1260               #     program_id => 5,     # value of $prog->id
1261               #     version    => '3.0', # value of $prog->version
1262               #     state      => 'defunct',
1263               #   ],
1264               #   sort_by => 'name');
1265               ...
1266
1267           Example - get_set interface:
1268
1269               # Read from the programs table
1270               $prog = Program->new(id => 5)->load;
1271
1272               # Read from the bugs table
1273               $bugs = $prog->bugs;
1274
1275               # Calls (essentially):
1276               #
1277               # Rose::DB::Object::Manager->get_objects(
1278               #   db           => $prog->db, # share_db defaults to true
1279               #   object_class => 'Bug',
1280               #   query =>
1281               #   [
1282               #     program_id => 5,     # value of $prog->id
1283               #     version    => '3.0', # value of $prog->version
1284               #     state      => { ne => 'closed' },
1285               #   ],
1286               #   sort_by => 'date_submitted DESC');
1287               ...
1288               $prog->version($new_version); # Does not hit the db
1289               $prog->bugs(@new_bugs);       # Does not hit the db
1290
1291               # @new_bugs can contain any mix of these types:
1292               #
1293               # @new_bugs =
1294               # (
1295               #   123,                 # primary key value
1296               #   { id => 456 },       # method name/value pairs
1297               #   Bug->new(id => 789), # object
1298               # );
1299
1300               # Write to the programs table only.  The bugs table is not
1301               # updated. See the get_set_now and get_set_on_save method
1302               # types for ways to write to the bugs table.
1303               $prog->save;
1304
1305           Example - get_set_now interface:
1306
1307               # Read from the programs table
1308               $prog = Program->new(id => 5)->load;
1309
1310               # Read from the bugs table
1311               $bugs = $prog->bugs;
1312
1313               $prog->name($new_name); # Does not hit the db
1314
1315               # Writes to the bugs table, deleting existing bugs and
1316               # replacing them with @new_bugs (which must be an array
1317               # of Bug objects, either existing or new)
1318               $prog->bugs(@new_bugs);
1319
1320               # @new_bugs can contain any mix of these types:
1321               #
1322               # @new_bugs =
1323               # (
1324               #   123,                 # primary key value
1325               #   { id => 456 },       # method name/value pairs
1326               #   Bug->new(id => 789), # object
1327               # );
1328
1329               # Write to the programs table
1330               $prog->save;
1331
1332           Example - get_set_on_save interface:
1333
1334               # Read from the programs table
1335               $prog = Program->new(id => 5)->load;
1336
1337               # Read from the bugs table
1338               $bugs = $prog->bugs;
1339
1340               $prog->name($new_name); # Does not hit the db
1341               $prog->bugs(@new_bugs); # Does not hit the db
1342
1343               # @new_bugs can contain any mix of these types:
1344               #
1345               # @new_bugs =
1346               # (
1347               #   123,                 # primary key value
1348               #   { id => 456 },       # method name/value pairs
1349               #   Bug->new(id => 789), # object
1350               # );
1351
1352               # Write to the programs table and the bugs table, deleting any
1353               # existing bugs and replacing them with @new_bugs (which must be
1354               # an array of Bug objects, either existing or new)
1355               $prog->save;
1356
1357           Example - add_now interface:
1358
1359               # Read from the programs table
1360               $prog = Program->new(id => 5)->load;
1361
1362               # Read from the bugs table
1363               $bugs = $prog->bugs;
1364
1365               $prog->name($new_name); # Does not hit the db
1366
1367               # Writes to the bugs table, adding @new_bugs to the current
1368               # list of bugs for this program
1369               $prog->add_bugs(@new_bugs);
1370
1371               # @new_bugs can contain any mix of these types:
1372               #
1373               # @new_bugs =
1374               # (
1375               #   123,                 # primary key value
1376               #   { id => 456 },       # method name/value pairs
1377               #   Bug->new(id => 789), # object
1378               # );
1379
1380               # Read from the bugs table, getting the full list of bugs,
1381               # including the ones that were added above.
1382               $bugs = $prog->bugs;
1383
1384               # Write to the programs table only
1385               $prog->save;
1386
1387           Example - add_on_save interface:
1388
1389               # Read from the programs table
1390               $prog = Program->new(id => 5)->load;
1391
1392               # Read from the bugs table
1393               $bugs = $prog->bugs;
1394
1395               $prog->name($new_name);      # Does not hit the db
1396               $prog->add_bugs(@new_bugs);  # Does not hit the db
1397               $prog->add_bugs(@more_bugs); # Does not hit the db
1398
1399               # @new_bugs and @more_bugs can contain any mix of these types:
1400               #
1401               # @new_bugs =
1402               # (
1403               #   123,                 # primary key value
1404               #   { id => 456 },       # method name/value pairs
1405               #   Bug->new(id => 789), # object
1406               # );
1407
1408               # Write to the programs table and the bugs table, adding
1409               # @new_bugs to the current list of bugs for this program
1410               $prog->save;
1411
1412       objects_by_map
1413           Create methods that fetch Rose::DB::Object-derived objects via an
1414           intermediate Rose::DB::Object-derived class that maps between two
1415           other Rose::DB::Object-derived classes.  See the
1416           Rose::DB::Object::Metadata::Relationship::ManyToMany documentation
1417           for a more complete example of this type of method in action.
1418
1419           Options
1420               hash_key NAME
1421                   The key inside the hash-based object to use for the storage
1422                   of the fetched objects.  Defaults to the name of the
1423                   method.
1424
1425               interface NAME
1426                   Choose the interface.  The "get_set" interface is the
1427                   default.
1428
1429               manager_args HASHREF
1430                   A reference to a hash of arguments passed to the
1431                   "manager_class" when fetching objects.  If "manager_args"
1432                   includes a "sort_by" argument, be sure to prefix each
1433                   column name with the appropriate table name.  (See the
1434                   synopsis for examples.)
1435
1436               manager_class CLASS
1437                   The name of the Rose::DB::Object::Manager-derived class
1438                   that the "map_class" will use to fetch records.  Defaults
1439                   to Rose::DB::Object::Manager.
1440
1441               manager_method NAME
1442                   The name of the class method to call on "manager_class" in
1443                   order to fetch the objects.  Defaults to "get_objects".
1444
1445               manager_count_method NAME
1446                   The name of the class method to call on "manager_class" in
1447                   order to count the objects.  Defaults to
1448                   "get_objects_count".
1449
1450               map_class CLASS
1451                   The name of the Rose::DB::Object-derived class that maps
1452                   between the other two Rose::DB::Object-derived classes.
1453                   This class must have a foreign key and/or "many to one"
1454                   relationship for each of the two tables that it maps
1455                   between.
1456
1457               map_from NAME
1458                   The name of the "many to one" relationship or foreign key
1459                   in "map_class" that points to the object of the class that
1460                   this relationship exists in.  Setting this value is only
1461                   necessary if the "map_class" has more than one foreign key
1462                   or "many to one" relationship that points to one of the
1463                   classes that it maps between.
1464
1465               map_to NAME
1466                   The name of the "many to one" relationship or foreign key
1467                   in "map_class" that points to the "foreign" object to be
1468                   fetched.  Setting this value is only necessary if the
1469                   "map_class" has more than one foreign key or "many to one"
1470                   relationship that points to one of the classes that it maps
1471                   between.
1472
1473               relationship OBJECT
1474                   The Rose::DB::Object::Metadata::Relationship object that
1475                   describes the "key" through which the "objects_by_key" are
1476                   fetched.  This option is required.
1477
1478               share_db BOOL
1479                   If true, the db attribute of the current object is shared
1480                   with all of the objects fetched.  Defaults to true.
1481
1482               query_args ARRAYREF
1483                   A reference to an array of arguments added to the value of
1484                   the "query" parameter passed to the call to
1485                   "manager_class"'s "manager_method" class method.
1486
1487           Interfaces
1488               count
1489                   Creates a method that will attempt to count
1490                   Rose::DB::Object-derived objects that are related to the
1491                   current object through the "map_class", plus any additional
1492                   parameters passed to the method call.  Note that this
1493                   method counts the objects in the database at the time of
1494                   the call.  This may be different than the number of objects
1495                   attached to the current object or otherwise in memory.
1496
1497                   Since the objects counted are partially determined by the
1498                   arguments passed to the method, the count is not retained.
1499                   It is simply returned.  Each call counts the specified
1500                   objects again, even if the arguments are the same as the
1501                   previous call.
1502
1503                   If the first argument is a reference to a hash or array, it
1504                   is converted to a reference to an array (if necessary) and
1505                   taken as the value of the "query" parameter.  All arguments
1506                   are passed on to the "manager_class"'s
1507                   "manager_count_method" method, augmented by the mapping to
1508                   the current object.  Query parameters are added to the
1509                   existing contents of the "query" parameter.  Other
1510                   parameters replace existing parameters if the existing
1511                   values are simple scalars, or augment existing parameters
1512                   if the existing values are references to hashes or arrays.
1513
1514                   The count may fail for several reasons.  The count will not
1515                   even be attempted if any of the key attributes in the
1516                   current object are undefined.  Instead, undef (in scalar
1517                   context) or an empty list (in list context) will be
1518                   returned.  If the call to "manager_class"'s
1519                   "manager_count_method" method returns undef, the behavior
1520                   is determined by the metadata object's error_mode.  If the
1521                   mode is "return", that false value (in scalar context) or
1522                   an empty list (in list context) is returned.
1523
1524                   If the count succeeds, the number is returned.  (If the
1525                   count finds zero objects, the count will be 0.  This is
1526                   still considered success.)
1527
1528               find
1529                   Creates a method that will attempt to fetch
1530                   Rose::DB::Object-derived that are related to the current
1531                   object through the "map_class", plus any additional
1532                   parameters passed to the method call.  Since the objects
1533                   fetched are partially determined by the arguments passed to
1534                   the method, the list of objects is not retained.  It is
1535                   simply returned.  Each call fetches the requested objects
1536                   again, even if the arguments are the same as the previous
1537                   call.
1538
1539                   If the first argument is a reference to a hash or array, it
1540                   is converted to a reference to an array (if necessary) and
1541                   taken as the value of the "query" parameter.  All arguments
1542                   are passed on to the "manager_class"'s "manager_method"
1543                   method, augmented by the mapping to the current object.
1544                   Query parameters are added to the existing contents of the
1545                   "query" parameter.  Other parameters replace existing
1546                   parameters if the existing values are simple scalars, or
1547                   augment existing parameters if the existing values are
1548                   references to hashes or arrays.
1549
1550                   The fetch may fail for several reasons.  The fetch will not
1551                   even be attempted if any of the key attributes in the
1552                   current object are undefined.  Instead, undef (in scalar
1553                   context) or an empty list (in list context) will be
1554                   returned.  If the call to "manager_class"'s
1555                   "manager_method" method returns false, the behavior is
1556                   determined by the metadata object's error_mode.  If the
1557                   mode is "return", that false value (in scalar context) or
1558                   an empty list (in list context) is returned.
1559
1560                   If the fetch succeeds, a list (in list context) or a
1561                   reference to the array of objects (in scalar context) is
1562                   returned.  (If the fetch finds zero objects, the list or
1563                   array reference will simply be empty.  This is still
1564                   considered success.)
1565
1566               iterator
1567                   Behaves just like find but returns an iterator rather than
1568                   an array or arrayref.
1569
1570               get_set
1571                   Creates a method that will attempt to fetch
1572                   Rose::DB::Object-derived objects that are related to the
1573                   current object through the "map_class".
1574
1575                   If passed a single argument of undef, the "hash_key" used
1576                   to store the objects is set to undef.  Otherwise, the
1577                   argument(s) must be a list or reference to an array
1578                   containing items in one or more of the following formats:
1579
1580                   •   An object of type "class".
1581
1582                   •   A reference to a hash containing method name/value
1583                       pairs.
1584
1585                   •   A single scalar primary key value.
1586
1587                   The latter two formats will be used to construct an object
1588                   of type "class".  A single primary key value is only a
1589                   valid argument format if the "class" in question has a
1590                   single-column primary key.  A hash reference argument must
1591                   contain sufficient information for the object to be
1592                   uniquely identified.
1593
1594                   The list of object is assigned to "hash_key".  Note that
1595                   these objects are not added to the database.  Use the
1596                   "get_set_now" or "get_set_on_save" interface to do that.
1597
1598                   If called with no arguments and the hash key used to store
1599                   the list of objects is defined, the list (in list context)
1600                   or a reference to that array (in scalar context) of objects
1601                   is returned.  Otherwise, the objects are fetched.
1602
1603                   When fetching objects from the database, if the call to
1604                   "manager_class"'s "manager_method" method returns false,
1605                   that false value (in scalar context) or an empty list (in
1606                   list context) is returned.
1607
1608                   If the fetch succeeds, a list (in list context) or a
1609                   reference to the array of objects (in scalar context) is
1610                   returned.  (If the fetch finds zero objects, the list or
1611                   array reference will simply be empty.  This is still
1612                   considered success.)
1613
1614               get_set_now
1615                   Creates a method that will attempt to fetch
1616                   Rose::DB::Object-derived objects that are related to the
1617                   current object through the "map_class", and will also save
1618                   objects to the database and map them to the parent object
1619                   when called with arguments.  The objects do not have to
1620                   already exist in the database; they will be inserted if
1621                   needed.
1622
1623                   If passed a single argument of undef, the list of objects
1624                   is set to undef, causing it to be reloaded the next time
1625                   the method is called with no arguments.  (Pass a reference
1626                   to an empty array to cause all of the existing objects to
1627                   be "unmapped"--that is, to have their entries in the
1628                   mapping table deleted from the database.)  Any pending
1629                   "set_on_save" or "add_on_save" actions are discarded.
1630
1631                   Otherwise, the argument(s) must be a list or reference to
1632                   an array containing items in one or more of the following
1633                   formats:
1634
1635                   •   An object of type "class".
1636
1637                   •   A reference to a hash containing method name/value
1638                       pairs.
1639
1640                   •   A single scalar primary key value.
1641
1642                   The latter two formats will be used to construct an object
1643                   of type "class".  A single primary key value is only a
1644                   valid argument format if the "class" in question has a
1645                   single-column primary key.  A hash reference argument must
1646                   contain sufficient information for the object to be
1647                   uniquely identified.
1648
1649                   The list of object is assigned to "hash_key", the old
1650                   entries are deleted from the mapping table in the database,
1651                   and the new objects are added to the database, along with
1652                   their corresponding mapping entries.  Any pending
1653                   "set_on_save" or "add_on_save" actions are discarded.
1654
1655                   When adding each object, if the object does not already
1656                   exists in the database, it will be inserted.  If the object
1657                   was previously loaded from or saved to the database, it
1658                   will be updated.  Otherwise, it will be loaded.
1659
1660                   The parent object must have been loaded or saved prior to
1661                   setting the list of objects.  If this method is called with
1662                   arguments before the object has been  loaded or saved, a
1663                   fatal error will occur.
1664
1665                   If called with no arguments and the hash key used to store
1666                   the list of objects is defined, the list (in list context)
1667                   or a reference to that array (in scalar context) of objects
1668                   is returned.  Otherwise, the objects are fetched.
1669
1670                   When fetching, if the call to "manager_class"'s
1671                   "manager_method" method returns false, that false value (in
1672                   scalar context) or an empty list (in list context) is
1673                   returned.
1674
1675                   If the fetch succeeds, a list (in list context) or a
1676                   reference to the array of objects (in scalar context) is
1677                   returned.  (If the fetch finds zero objects, the list or
1678                   array reference will simply be empty.  This is still
1679                   considered success.)
1680
1681               get_set_on_save
1682                   Creates a method that will attempt to fetch
1683                   Rose::DB::Object-derived objects that are related to the
1684                   current object through the "map_class", and will also save
1685                   objects to the database and map them to the parent object
1686                   when the "parent" object is saved.  The objects do not have
1687                   to already exist in the database; they will be inserted if
1688                   needed.
1689
1690                   If passed a single argument of undef, the list of objects
1691                   is set to undef, causing it to be reloaded the next time
1692                   the method is called with no arguments.  (Pass a reference
1693                   to an empty array to cause all of the existing objects to
1694                   be "unmapped"--that is, to have their entries in the
1695                   mapping table deleted from the database.)  Any pending
1696                   "set_on_save" or "add_on_save" actions are discarded.
1697
1698                   Otherwise, the argument(s) must be a list or reference to
1699                   an array containing items in one or more of the following
1700                   formats:
1701
1702                   •   An object of type "class".
1703
1704                   •   A reference to a hash containing method name/value
1705                       pairs.
1706
1707                   •   A single scalar primary key value.
1708
1709                   The latter two formats will be used to construct an object
1710                   of type "class".  A single primary key value is only a
1711                   valid argument format if the "class" in question has a
1712                   single-column primary key.  A hash reference argument must
1713                   contain sufficient information for the object to be
1714                   uniquely identified.
1715
1716                   The list of object is assigned to "hash_key". The mapping
1717                   table records that mapped the old objects to the parent
1718                   object are scheduled to be deleted from the database and
1719                   new ones are scheduled to be added to the database when the
1720                   parent is saved.  Any previously pending "set_on_save" or
1721                   "add_on_save" actions are discarded.
1722
1723                   When adding each object when the parent is saved, if the
1724                   object does not already exists in the database, it will be
1725                   inserted.  If the object was previously loaded from or
1726                   saved to the database, it will be updated.  Otherwise, it
1727                   will be loaded.
1728
1729                   If called with no arguments and the hash key used to store
1730                   the list of objects is defined, the list (in list context)
1731                   or a reference to that array (in scalar context) of objects
1732                   is returned.  Otherwise, the objects are fetched.
1733
1734                   When fetching, if the call to "manager_class"'s
1735                   "manager_method" method returns false, that false value (in
1736                   scalar context) or an empty list (in list context) is
1737                   returned.
1738
1739                   If the fetch succeeds, a list (in list context) or a
1740                   reference to the array of objects (in scalar context) is
1741                   returned.  (If the fetch finds zero objects, the list or
1742                   array reference will simply be empty.  This is still
1743                   considered success.)
1744
1745               add_now
1746                   Creates a method that will add to a list of
1747                   Rose::DB::Object-derived objects that are related to the
1748                   current object through the "map_class", and will also save
1749                   objects to the database and map them to the parent object.
1750                   The objects do not have to already exist in the database;
1751                   they will be inserted if needed.
1752
1753                   This method returns the list of objects added when called
1754                   in list context, and the number of objects added when
1755                   called in scalar context.  If one or more objects could not
1756                   be added, undef (in scalar context) or an empty list (in
1757                   list context) is returned and the parent object's error
1758                   attribute is set.
1759
1760                   If passed an empty list, the method does nothing and the
1761                   parent object's error attribute is set.
1762
1763                   If passed any arguments, the parent object must have been
1764                   loaded or saved prior to adding to the list of objects.  If
1765                   this method is called with a non-empty list as an argument
1766                   before the parent object has been  loaded or saved, a fatal
1767                   error will occur.
1768
1769                   The argument(s) must be a list or reference to an array
1770                   containing items in one or more of the following formats:
1771
1772                   •   An object of type "class".
1773
1774                   •   A reference to a hash containing method name/value
1775                       pairs.
1776
1777                   •   A single scalar primary key value.
1778
1779                   The latter two formats will be used to construct an object
1780                   of type "class".  A single primary key value is only a
1781                   valid argument format if the "class" in question has a
1782                   single-column primary key.  A hash reference argument must
1783                   contain sufficient information for the object to be
1784                   uniquely identified.
1785
1786                   The parent object's list of related objects is then set to
1787                   undef, causing the related objects to be reloaded from the
1788                   database the next time they're needed.
1789
1790               add_on_save
1791                   Creates a method that will add to a list of
1792                   Rose::DB::Object-derived objects that are related to the
1793                   current object through the "map_class", and will also save
1794                   objects to the database and map them to the parent object
1795                   when the "parent" object is saved.  The objects and map
1796                   records will be added to the database when the parent
1797                   object is saved.  The objects do not have to already exist
1798                   in the database; they will be inserted if needed.
1799
1800                   This method returns the list of objects to be added when
1801                   called in list context, and the number of items to be added
1802                   when called in scalar context.
1803
1804                   If passed an empty list, the method does nothing and the
1805                   parent object's error attribute is set.
1806
1807                   Otherwise, the argument(s) must be a list or reference to
1808                   an array containing items in one or more of the following
1809                   formats:
1810
1811                   •   An object of type "class".
1812
1813                   •   A reference to a hash containing method name/value
1814                       pairs.
1815
1816                   •   A single scalar primary key value.
1817
1818                   The latter two formats will be used to construct an object
1819                   of type "class".  A single primary key value is only a
1820                   valid argument format if the "class" in question has a
1821                   single-column primary key.  A hash reference argument must
1822                   contain sufficient information for the object to be
1823                   uniquely identified.
1824
1825                   These objects are scheduled to be added to the database and
1826                   mapped to the parent object when the parent object is
1827                   saved.  They are also added to the parent object's current
1828                   list of related objects, if the list is defined at the time
1829                   of the call.
1830
1831           For a complete example of this method type in action, see the
1832           Rose::DB::Object::Metadata::Relationship::ManyToMany documentation.
1833
1834       object_by_key
1835           Create a get/set methods for a single Rose::DB::Object-derived
1836           object loaded based on a primary key formed from attributes of the
1837           current object.
1838
1839           Options
1840               class CLASS
1841                   The name of the Rose::DB::Object-derived class of the
1842                   object to be loaded.  This option is required.
1843
1844               foreign_key OBJECT
1845                   The Rose::DB::Object::Metadata::ForeignKey object that
1846                   describes the "key" through which the "object_by_key" is
1847                   fetched.  This (or the "relationship" parameter) is
1848                   required when using the "delete_now", "delete_on_save", and
1849                   "get_set_on_save" interfaces.
1850
1851               hash_key NAME
1852                   The key inside the hash-based object to use for the storage
1853                   of the object.  Defaults to the name of the method.
1854
1855               if_not_found CONSEQUENCE
1856                   This setting determines what happens when the key_columns
1857                   have defined values, but the foreign object they point to
1858                   is not found.  Valid values for CONSEQUENCE are "fatal",
1859                   which will throw an exception if the foreign object is not
1860                   found, and "ok" which will merely cause the relevant
1861                   method(s) to return undef.  The default is "fatal".
1862
1863               key_columns HASHREF
1864                   A reference to a hash that maps column names in the current
1865                   object to those of the primary key in the object to be
1866                   loaded.  This option is required.
1867
1868               interface NAME
1869                   Choose the interface.  The default is "get_set".
1870
1871               relationship OBJECT
1872                   The Rose::DB::Object::Metadata::Relationship-derived object
1873                   that describes the relationship through which the object is
1874                   fetched.  This (or the "foreign_key" parameter) is required
1875                   when using the "delete_now", "delete_on_save", and
1876                   "get_set_on_save" interfaces.
1877
1878               referential_integrity BOOL
1879                   If true, then a fatal error will occur when a method in one
1880                   of the "get*" interfaces is called and no related object is
1881                   found.  The default is determined by the
1882                   referential_integrity attribute of the "foreign_key"
1883                   object, or true if no "foreign_key" parameter is passed.
1884
1885                   This parameter conflicts with the "required" parameter.
1886                   Only one of the two should be passed.
1887
1888               required BOOL
1889                   If true, then a fatal error will occur when a method in one
1890                   of the "get*" interfaces is called and no related object is
1891                   found.  The default is determined by the required attribute
1892                   of the "relationship" object, or true if no "relationship"
1893                   parameter is passed.
1894
1895                   This parameter conflicts with the "referential_integrity"
1896                   parameter.  Only one of the two should be passed.
1897
1898               share_db BOOL
1899                   If true, the db attribute of the current object is shared
1900                   with the object loaded.  Defaults to true.
1901
1902           Interfaces
1903               delete_now
1904                   Deletes a Rose::DB::Object-derived object from the database
1905                   based on a primary key formed from attributes of the
1906                   current object.  If "referential_integrity" or "required"
1907                   is true, then the "parent" object will have all of its
1908                   attributes that refer to the "foreign" object (except any
1909                   columns that are also part of the primary key) set to null
1910                   , and it will be saved into the database.  This needs to be
1911                   done first because a database that enforces referential
1912                   integrity will not allow a row to be deleted if it is still
1913                   referenced by a foreign key in another table.
1914
1915                   Any previously pending "get_set_on_save" action is
1916                   discarded.
1917
1918                   The entire process takes place within a transaction if the
1919                   database supports it.  If not currently in a transaction, a
1920                   new one is started and then committed on success and rolled
1921                   back on failure.
1922
1923                   Returns true if the foreign object was deleted successfully
1924                   or did not exist in the database, false if any of the keys
1925                   that refer to the foreign object were undef, and triggers
1926                   the normal Rose::DB::Object error handling in the case of
1927                   any other kind of failure.
1928
1929               delete_on_save
1930                   Deletes a Rose::DB::Object-derived object from the database
1931                   when the "parent" object is saved, based on a primary key
1932                   formed from attributes of the current object.  If
1933                   "referential_integrity" or "required" is true, then the
1934                   "parent" object will have all of its attributes that refer
1935                   to the "foreign" object (except any columns that are also
1936                   part of the primary key) set to null immediately, but the
1937                   actual delete will not be done until the parent is saved.
1938
1939                   Any previously pending "get_set_on_save" action is
1940                   discarded.
1941
1942                   The entire process takes place within a transaction if the
1943                   database supports it.  If not currently in a transaction, a
1944                   new one is started and then committed on success and rolled
1945                   back on failure.
1946
1947                   Returns true if the foreign object was deleted successfully
1948                   or did not exist in the database, false if any of the keys
1949                   that refer to the foreign object were undef, and triggers
1950                   the normal Rose::DB::Object error handling in the case of
1951                   any other kind of failure.
1952
1953               get_set
1954                   Creates a method that will attempt to create and load a
1955                   Rose::DB::Object-derived object based on a primary key
1956                   formed from attributes of the current object.
1957
1958                   If passed a single argument of undef, the "hash_key" used
1959                   to store the object is set to undef.  If
1960                   "referential_integrity" or "required" is true, then the
1961                   columns that participate in the key are set to undef.  (If
1962                   any key column is part of the primary key, however, it is
1963                   not set to undef.)  Otherwise, the argument must be one of
1964                   the following:
1965
1966                   •   An object of type "class"
1967
1968                   •   A list of method name/value pairs.
1969
1970                   •   A reference to a hash containing method name/value
1971                       pairs.
1972
1973                   •   A single scalar primary key value.
1974
1975                   The latter three argument types will be used to construct
1976                   an object of type "class".  A single primary key value is
1977                   only valid if the "class" in question has a single-column
1978                   primary key.  A hash reference argument must contain
1979                   sufficient information for the object to be uniquely
1980                   identified.
1981
1982                   The object is assigned to "hash_key" after having its
1983                   "key_columns" set to their corresponding values in the
1984                   current object.
1985
1986                   If called with no arguments and the "hash_key" used to
1987                   store the object is defined, the object is returned.
1988                   Otherwise, the object is created and loaded.
1989
1990                   The load may fail for several reasons.  The load will not
1991                   even be attempted if any of the key attributes in the
1992                   current object are undefined.  Instead, undef will be
1993                   returned.
1994
1995                   If the call to the newly created object's load method
1996                   returns false, then the normal Rose::DB::Object error
1997                   handling is triggered.  The false value returned by the
1998                   call to the load method is returned (assuming no exception
1999                   was raised).
2000
2001                   If the load succeeds, the object is returned.
2002
2003               get_set_now
2004                   Creates a method that will attempt to create and load a
2005                   Rose::DB::Object-derived object based on a primary key
2006                   formed from attributes of the current object, and will also
2007                   save the object to the database when called with an
2008                   appropriate object as an argument.
2009
2010                   If passed a single argument of undef, the "hash_key" used
2011                   to store the object is set to undef.  If
2012                   "referential_integrity" or "required" is true, then the
2013                   columns that participate in the key are set to undef.  (If
2014                   any key column is part of the primary key, however, it is
2015                   not set to undef.) Otherwise, the argument must be one of
2016                   the following:
2017
2018                   •   An object of type "class"
2019
2020                   •   A list of method name/value pairs.
2021
2022                   •   A reference to a hash containing method name/value
2023                       pairs.
2024
2025                   •   A single scalar primary key value.
2026
2027                   The latter three argument types will be used to construct
2028                   an object of type "class".  A single primary key value is
2029                   only a valid argument format if the "class" in question has
2030                   a single-column primary key.  A hash reference argument
2031                   must contain sufficient information for the object to be
2032                   uniquely identified.
2033
2034                   The object is assigned to "hash_key" after having its
2035                   "key_columns" set to their corresponding values in the
2036                   current object.  The object is then immediately saved to
2037                   the database.
2038
2039                   If the object does not already exists in the database, it
2040                   will be inserted.  If the object was previously loaded from
2041                   or saved to the database, it will be updated.  Otherwise,
2042                   it will be loaded.
2043
2044                   The parent object must have been loaded or saved prior to
2045                   setting the list of objects.  If this method is called with
2046                   arguments before the object has been  loaded or saved, a
2047                   fatal error will occur.
2048
2049                   If called with no arguments and the "hash_key" used to
2050                   store the object is defined, the object is returned.
2051                   Otherwise, the object is created and loaded.
2052
2053                   The load may fail for several reasons.  The load will not
2054                   even be attempted if any of the key attributes in the
2055                   current object are undefined.  Instead, undef will be
2056                   returned.
2057
2058                   If the call to the newly created object's load method
2059                   returns false, then the normal Rose::DB::Object error
2060                   handling is triggered.  The false value returned by the
2061                   call to the load method is returned (assuming no exception
2062                   was raised).
2063
2064                   If the load succeeds, the object is returned.
2065
2066               get_set_on_save
2067                   Creates a method that will attempt to create and load a
2068                   Rose::DB::Object-derived object based on a primary key
2069                   formed from attributes of the current object, and save the
2070                   object when the "parent" object is saved.
2071
2072                   If passed a single argument of undef, the "hash_key" used
2073                   to store the object is set to undef.  If
2074                   "referential_integrity" or "required" is true, then the
2075                   columns that participate in the key are set to undef.  (If
2076                   any key column is part of the primary key, however, it is
2077                   not set to undef.) Otherwise, the argument must be one of
2078                   the following:
2079
2080                   •   An object of type "class"
2081
2082                   •   A list of method name/value pairs.
2083
2084                   •   A reference to a hash containing method name/value
2085                       pairs.
2086
2087                   •   A single scalar primary key value.
2088
2089                   The latter three argument types will be used to construct
2090                   an object of type "class".  A single primary key value is
2091                   only a valid argument format if the "class" in question has
2092                   a single-column primary key.  A hash reference argument
2093                   must contain sufficient information for the object to be
2094                   uniquely identified.
2095
2096                   The object is assigned to "hash_key" after having its
2097                   "key_columns" set to their corresponding values in the
2098                   current object.  The object will be saved into the database
2099                   when the "parent" object is saved.  Any previously pending
2100                   "get_set_on_save" action is discarded.
2101
2102                   If the object does not already exists in the database, it
2103                   will be inserted.  If the object was previously loaded from
2104                   or saved to the database, it will be updated.  Otherwise,
2105                   it will be loaded.
2106
2107                   If called with no arguments and the "hash_key" used to
2108                   store the object is defined, the object is returned.
2109                   Otherwise, the object is created and loaded from the
2110                   database.
2111
2112                   The load may fail for several reasons.  The load will not
2113                   even be attempted if any of the key attributes in the
2114                   current object are undefined.  Instead, undef will be
2115                   returned.
2116
2117                   If the call to the newly created object's load method
2118                   returns false, then the normal Rose::DB::Object error
2119                   handling is triggered.  The false value returned by the
2120                   call to the load method is returned (assuming no exception
2121                   was raised).
2122
2123                   If the load succeeds, the object is returned.
2124
2125           Example setup:
2126
2127               # CLASS     DB TABLE
2128               # -------   --------
2129               # Product   products
2130               # Category  categories
2131
2132               package Product;
2133
2134               our @ISA = qw(Rose::DB::Object);
2135               ...
2136
2137               # You will almost never call the method-maker directly
2138               # like this.  See the Rose::DB::Object::Metadata docs
2139               # for examples of more common usage.
2140               use Rose::DB::Object::MakeMethods::Generic
2141               (
2142                 object_by_key =>
2143                 [
2144                   category =>
2145                   {
2146                     interface   => 'get_set',
2147                     class       => 'Category',
2148                     key_columns =>
2149                     {
2150                       # Map Product column names to Category column names
2151                       category_id => 'id',
2152                     },
2153                   },
2154                 ]
2155               );
2156               ...
2157
2158           Example - get_set interface:
2159
2160               $product = Product->new(id => 5, category_id => 99);
2161
2162               # Read from the categories table
2163               $category = $product->category;
2164
2165               # $product->category call is roughly equivalent to:
2166               #
2167               # $cat = Category->new(id => $product->category_id
2168               #                      db => $prog->db);
2169               #
2170               # $ret = $cat->load;
2171               # return $ret  unless($ret);
2172               # return $cat;
2173
2174               # Does not write to the db
2175               $product->category(Category->new(...));
2176
2177               $product->save; # writes to products table only
2178
2179           Example - get_set_now interface:
2180
2181               # Read from the products table
2182               $product = Product->new(id => 5)->load;
2183
2184               # Read from the categories table
2185               $category = $product->category;
2186
2187               # Write to the categories table:
2188               # (all possible argument formats show)
2189
2190               # Object argument
2191               $product->category(Category->new(...));
2192
2193               # Primary key value
2194               $product->category(123);
2195
2196               # Method name/value pairs in a hashref
2197               $product->category(id => 123);
2198
2199               # Method name/value pairs in a hashref
2200               $product->category({ id => 123 });
2201
2202               # Write to the products table
2203               $product->save;
2204
2205           Example - get_set_on_save interface:
2206
2207               # Read from the products table
2208               $product = Product->new(id => 5)->load;
2209
2210               # Read from the categories table
2211               $category = $product->category;
2212
2213               # These do not write to the db:
2214
2215               # Object argument
2216               $product->category(Category->new(...));
2217
2218               # Primary key value
2219               $product->category(123);
2220
2221               # Method name/value pairs in a hashref
2222               $product->category(id => 123);
2223
2224               # Method name/value pairs in a hashref
2225               $product->category({ id => 123 });
2226
2227               # Write to both the products and categories tables
2228               $product->save;
2229
2230           Example - delete_now interface:
2231
2232               # Read from the products table
2233               $product = Product->new(id => 5)->load;
2234
2235               # Write to both the categories and products tables
2236               $product->delete_category();
2237
2238           Example - delete_on_save interface:
2239
2240               # Read from the products table
2241               $product = Product->new(id => 5)->load;
2242
2243               # Does not write to the db
2244               $product->delete_category();
2245
2246               # Write to both the products and categories tables
2247               $product->save;
2248
2249       scalar
2250           Create get/set methods for scalar attributes.
2251
2252           Options
2253               default VALUE
2254                   Determines the default value of the attribute.
2255
2256               check_in ARRAYREF
2257                   A reference to an array of valid values.  When setting the
2258                   attribute, if the new value is not equal (string
2259                   comparison) to one of the valid values, a fatal error will
2260                   occur.
2261
2262               hash_key NAME
2263                   The key inside the hash-based object to use for the storage
2264                   of this attribute.  Defaults to the name of the method.
2265
2266               init_method NAME
2267                   The name of the method to call when initializing the value
2268                   of an undefined attribute.  Defaults to the method name
2269                   with the prefix "init_" added.  This option implies
2270                   "with_init".
2271
2272               interface NAME
2273                   Choose the interface.  The "get_set" interface is the
2274                   default.
2275
2276               length INT
2277                   The maximum number of characters in the string.
2278
2279               overflow BEHAVIOR
2280                   Determines the behavior when the value is greater than the
2281                   number of characters specified by the "length" option.
2282                   Valid values for BEHAVIOR are:
2283
2284                   fatal
2285                       Throw an exception.
2286
2287                   truncate
2288                       Truncate the value to the correct length.
2289
2290                   warn
2291                       Print a warning message.
2292
2293               with_init BOOL
2294                   Modifies the behavior of the "get_set" and "get"
2295                   interfaces.  If the attribute is undefined, the method
2296                   specified by the "init_method" option is called and the
2297                   attribute is set to the return value of that method.
2298
2299           Interfaces
2300               get_set
2301                   Creates a get/set method for an object attribute.  When
2302                   called with an argument, the value of the attribute is set.
2303                   The current value of the attribute is returned.
2304
2305               get Creates an accessor method for an object attribute that
2306                   returns the current value of the attribute.
2307
2308               set Creates a mutator method for an object attribute.  When
2309                   called with an argument, the value of the attribute is set.
2310                   If called with no arguments, a fatal error will occur.
2311
2312           Example:
2313
2314               package MyDBObject;
2315
2316               our @ISA = qw(Rose::DB::Object);
2317
2318               use Rose::DB::Object::MakeMethods::Generic
2319               (
2320                 scalar =>
2321                 [
2322                   name => { default => 'Joe' },
2323                   type =>
2324                   {
2325                     with_init => 1,
2326                     check_in  => [ qw(AA AAA C D) ],
2327                   }
2328                   set_type =>
2329                   {
2330                     check_in  => [ qw(AA AAA C D) ],
2331                   }
2332                 ],
2333               );
2334
2335               sub init_type { 'C' }
2336               ...
2337
2338               $o = MyDBObject->new(...);
2339
2340               print $o->name; # Joe
2341               print $o->type; # C
2342
2343               $o->name('Bob'); # set
2344               $o->type('AA');  # set
2345
2346               eval { $o->type('foo') }; # fatal error: invalid value
2347
2348               print $o->name, ' is ', $o->type; # get
2349
2350       set Create get/set methods for "set" attributes.   A "set" column in a
2351           database table contains an unordered group of values.  Not all
2352           databases support a "set" column type.  Check the Rose::DB
2353           documentation for your database type.
2354
2355           Options
2356               default ARRAYREF
2357                   Determines the default value of the attribute.  The value
2358                   should be a reference to an array.
2359
2360               hash_key NAME
2361                   The key inside the hash-based object to use for the storage
2362                   of this attribute.  Defaults to the name of the method.
2363
2364               interface NAME
2365                   Choose the interface.  The default is "get_set".
2366
2367               values ARRAYREF
2368                   A reference to an array of valid values for the set.  If
2369                   present, attempting to use an invalid value will cause a
2370                   fatal error.
2371
2372           Interfaces
2373               get_set
2374                   Creates a get/set method for a "set" object attribute.  A
2375                   "set" column in a database table contains an unordered
2376                   group of values.  On the Perl side of the fence, an ordered
2377                   list (an array) is used to store the values, but keep in
2378                   mind that the order is not significant, nor is it
2379                   guaranteed to be preserved.
2380
2381                   When setting the attribute, the value is passed through the
2382                   parse_set method of the object's db attribute.
2383
2384                   When saving to the database, if the attribute value is
2385                   defined, the method will pass the attribute value through
2386                   the format_set method of the object's db attribute before
2387                   returning it.
2388
2389                   When not saving to the database, the method returns the set
2390                   as a list in list context, or as a reference to the array
2391                   in scalar context.
2392
2393               get Creates an accessor method for a "set" object attribute.  A
2394                   "set" column in a database table contains an unordered
2395                   group of values.  On the Perl side of the fence, an ordered
2396                   list (an array) is used to store the values, but keep in
2397                   mind that the order is not significant, nor is it
2398                   guaranteed to be preserved.
2399
2400                   When saving to the database, if the attribute value is
2401                   defined, the method will pass the attribute value through
2402                   the format_set method of the object's db attribute before
2403                   returning it.
2404
2405                   When not saving to the database, the method returns the set
2406                   as a list in list context, or as a reference to the array
2407                   in scalar context.
2408
2409               set Creates a mutator method for a "set" object attribute.  A
2410                   "set" column in a database table contains an unordered
2411                   group of values.  On the Perl side of the fence, an ordered
2412                   list (an array) is used to store the values, but keep in
2413                   mind that the order is not significant, nor is it
2414                   guaranteed to be preserved.
2415
2416                   When setting the attribute, the value is passed through the
2417                   parse_set method of the object's db attribute.
2418
2419                   When saving to the database, if the attribute value is
2420                   defined, the method will pass the attribute value through
2421                   the format_set method of the object's db attribute before
2422                   returning it.
2423
2424                   When not saving to the database, the method returns the set
2425                   as a list in list context, or as a reference to the array
2426                   in scalar context.
2427
2428           Example:
2429
2430               package Person;
2431
2432               our @ISA = qw(Rose::DB::Object);
2433               ...
2434               use Rose::DB::Object::MakeMethods::Generic
2435               (
2436                 set =>
2437                 [
2438                   'nicknames',
2439                   'set_nicks' => { interface => 'set', hash_key => 'nicknames' },
2440
2441                   'parts' => { default => [ qw(arms legs) ] },
2442                 ],
2443               );
2444               ...
2445
2446               @parts = $person->parts; # ('arms', 'legs')
2447               $parts = $person->parts; # [ 'arms', 'legs' ]
2448
2449               $person->nicknames('Jack', 'Gimpy');   # set with list
2450               $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
2451
2452               $person->set_nicks('Jack', 'Gimpy');   # set with list
2453               $person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref
2454
2455       varchar
2456           Create get/set methods for variable-length character string
2457           attributes.
2458
2459           Options
2460               default VALUE
2461                   Determines the default value of the attribute.
2462
2463               hash_key NAME
2464                   The key inside the hash-based object to use for the storage
2465                   of this attribute.  Defaults to the name of the method.
2466
2467               init_method NAME
2468                   The name of the method to call when initializing the value
2469                   of an undefined attribute.  Defaults to the method name
2470                   with the prefix "init_" added.  This option implies
2471                   "with_init".
2472
2473               interface NAME
2474                   Choose the interface.  The "get_set" interface is the
2475                   default.
2476
2477               length INT
2478                   The maximum number of characters in the string.
2479
2480               overflow BEHAVIOR
2481                   Determines the behavior when the value is greater than the
2482                   number of characters specified by the "length" option.
2483                   Valid values for BEHAVIOR are:
2484
2485                   fatal
2486                       Throw an exception.
2487
2488                   truncate
2489                       Truncate the value to the correct length.
2490
2491                   warn
2492                       Print a warning message.
2493
2494               with_init BOOL
2495                   Modifies the behavior of the "get_set" and "get"
2496                   interfaces.  If the attribute is undefined, the method
2497                   specified by the "init_method" option is called and the
2498                   attribute is set to the return value of that method.
2499
2500           Interfaces
2501               get_set
2502                   Creates a get/set accessor method for a fixed-length
2503                   character string attribute.  When setting, any strings
2504                   longer than "length" will be truncated.  If "length" is
2505                   omitted, the string will be left unmodified.
2506
2507           Example:
2508
2509               package MyDBObject;
2510
2511               our @ISA = qw(Rose::DB::Object);
2512
2513               use Rose::DB::Object::MakeMethods::Generic
2514               (
2515                 varchar =>
2516                 [
2517                   'name' => { length => 3 },
2518                 ],
2519               );
2520
2521               ...
2522
2523               $o->name('John'); # truncates on set
2524               print $o->name;   # 'Joh'
2525

AUTHOR

2527       John C. Siracusa (siracusa@gmail.com)
2528

LICENSE

2530       Copyright (c) 2010 by John C. Siracusa.  All rights reserved.  This
2531       program is free software; you can redistribute it and/or modify it
2532       under the same terms as Perl itself.
2533
2534
2535
2536perl v5.36.0                      2022R-o0s7e-:2:2DB::Object::MakeMethods::Generic(3)
Impressum