1Rose::DB::Object::MakeMUestehrodCso:n:tGreinbeurtiecdR(o3Ps)eer:l:DDBo:c:uOmbejnetcatt:i:oMnakeMethods::Generic(3)
2
6 Rose::DB::Object::MakeMethods::Generic - Create generic object methods
7 for Rose::DB::Object-derived objects.
8
10 package MyDBObject;
11 our @ISA = qw(Rose::DB::Object);
13 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 'set_type' => { hash_key => 'type' },
25 ],
26 character =>
28 [
29 code => { length => 6 }
30 ],
31 varchar =>
33 [
34 name => { length => 10 }
35 ],
36 boolean =>
38 [
39 'is_red',
40 'is_happy' => { default => 1 },
41 ],
42 );
43 sub init_type { 'C' }
45 ...
46 $obj = MyDBObject->new(...);
48 print $obj->type; # C
50 $obj->name('Bob'); # set
52 $obj->set_type('C'); # set
53 $obj->type('AA'); # set
54 $obj->set_type; # Fatal error: no argument passed to "set" method
56 $obj->name('C' x 40); # truncate on set
58 print $obj->name; # 'CCCCCCCCCC'
59 $obj->code('ABC'); # pad on set
61 print $obj->code; # 'ABC '
62 eval { $obj->type('foo') }; # fatal error: invalid value
64 print $obj->name, ' is ', $obj->type; # get
66 $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 $obj->is_happy; # returns 1
75 ...
77 package Person;
79 our @ISA = qw(Rose::DB::Object);
81 ...
82 use Rose::DB::Object::MakeMethods::Generic
83 (
84 scalar => 'name',
85 set =>
87 [
88 'nicknames',
89 'parts' => { default => [ qw(arms legs) ] },
90 ],
91 # 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 @parts = $person->parts; # ('arms', 'legs')
106 $parts = $person->parts; # [ 'arms', 'legs' ]
107 $person->nicknames('Jack', 'Gimpy'); # set with list
109 $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
110 print join(', ', map { $_->name } $person->friends);
112 ...
113 package Program;
115 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 $prog = Program->new(id => 5, version => '3.0', ...);
142 $bugs = $prog->bugs;
144 # 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 ...
159 package Product;
161 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 $product = Product->new(id => 5, category_id => 99);
182 $category = $product->category;
184 # $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
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 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
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 Options
214 default VALUE
215 Determines the default value of the attribute. The value
216 should be a reference to an array.
217 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 interface NAME
223 Choose the interface. The default is "get_set".
224 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 When setting the attribute, the value is passed through the
232 parse_array method of the object's db attribute.
233 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 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 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 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 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 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 When setting the attribute, the value is passed through the
261 parse_array method of the object's db attribute.
262 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 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 If called with no arguments, a fatal error will occur.
273 Example:
275 package Person;
277 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 @parts = $person->parts; # ('arms', 'legs')
292 $parts = $person->parts; # [ 'arms', 'legs' ]
293 $person->nicknames('Jack', 'Gimpy'); # set with list
295 $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
296 $person->set_nicks('Jack', 'Gimpy'); # set with list
298 $person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref
299 bitfield
301 Create get/set methods for bitfield attributes.
302 Options
304 default VALUE
305 Determines the default value of the attribute.
306 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 interface NAME
312 Choose the interface. The default is "get_set".
313 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 bits INT
320 The number of bits in the bitfield. Defaults to 32.
321 with_intersects BOOL
323 This option is only applicable with the "get_set"
324 interface.
325 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 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 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 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 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 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 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 If called with no arguments, a fatal error will occur.
369 Example:
371 package MyDBObject;
373 our @ISA = qw(Rose::DB::Object);
375 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 ...
386 print $o->flags->to_Bin; # 00000000000000000000000000000010
388 $o->bits('101');
390 $o->bits_intersects('100'); # true
392 $o->bits_intersects('010'); # false
393 boolean
395 Create get/set methods for boolean attributes.
396 Options
398 default VALUE
399 Determines the default value of the attribute.
400 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 interface NAME
406 Choose the interface. The default is "get_set".
407 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 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 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 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 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 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 If called with no arguments, a fatal error will occur.
454 Example:
456 package MyDBObject;
458 our @ISA = qw(Rose::DB::Object);
460 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 $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 $obj->is_happy; # returns 1
479 $obj->set_happy(0); # returns 0
480 $obj->is_happy; # returns 0
481 character
483 Create get/set methods for fixed-length character string
484 attributes.
485 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 default VALUE
494 Determines the default value of the attribute.
495 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 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 interface NAME
507 Choose the interface. The default is "get_set".
508 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 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 fatal
521 Throw an exception.
522 truncate
524 Truncate the value to the correct length.
525 warn
527 Print a warning message.
528 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 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 get Creates an accessor method for a fixed-length character
544 string attribute.
545 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 Example:
553 package MyDBObject;
555 our @ISA = qw(Rose::DB::Object);
557 use Rose::DB::Object::MakeMethods::Generic
559 (
560 character =>
561 [
562 'name' => { length => 3 },
563 ],
564 );
565 ...
567 $o->name('John'); # truncates on set
569 print $o->name; # 'Joh'
570 $o->name('A'); # pads on set
572 print $o->name; # 'A '
573 enum
575 Create get/set methods for enum attributes.
576 Options
578 default VALUE
579 Determines the default value of the attribute.
580 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 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 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 interface NAME
598 Choose the interface. The "get_set" interface is the
599 default.
600 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 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 get Creates an accessor method for an object attribute that
615 returns the current value of the attribute.
616 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 Example:
623 package MyDBObject;
625 our @ISA = qw(Rose::DB::Object);
627 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 sub init_stage { 'new' }
638 ...
639 $o = MyDBObject->new(...);
641 print $o->type; # aux
643 print $o->stage; # new
644 $o->type('aux'); # set
646 $o->stage('old'); # set
647 eval { $o->type('foo') }; # fatal error: invalid value
649 print $o->type, ' is at stage ', $o->stage; # get
651 integer
653 Create get/set methods for integer attributes.
654 Options
656 default VALUE
657 Determines the default value of the attribute.
658 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 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 interface NAME
670 Choose the interface. The "get_set" interface is the
671 default.
672 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 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 get Creates an accessor method for an integer object attribute
686 that returns the current value of the attribute.
687 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 Example:
694 package MyDBObject;
696 our @ISA = qw(Rose::DB::Object);
698 use Rose::DB::Object::MakeMethods::Generic
700 (
701 integer =>
702 [
703 code => { default => 99 },
704 type => { with_init => 1 }
705 ],
706 );
707 sub init_type { 123 }
709 ...
710 $o = MyDBObject->new(...);
712 print $o->code; # 99
714 print $o->type; # 123
715 $o->code(8675309); # set
717 $o->type(42); # set
718 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 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 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 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 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 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 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 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 interface NAME
765 Choose the interface. The "get_set" interface is the
766 default.
767 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 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 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 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 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 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 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 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 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 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 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 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 iterator
864 Behaves just like find but returns an iterator rather than
865 an array or arrayref.
866 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 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 • An object of type "class".
878 • A reference to a hash containing method name/value
880 pairs.
881 • A single scalar primary key value.
883 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 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 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 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 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 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 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 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 • An object of type "class".
936 • A reference to a hash containing method name/value
938 pairs.
939 • A single scalar primary key value.
941 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 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 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 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 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 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 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 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 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 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 • An object of type "class".
1004 • A reference to a hash containing method name/value
1006 pairs.
1007 • A single scalar primary key value.
1009 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 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 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 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 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 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 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 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 If passed an empty list, the method does nothing and the
1065 parent object's error attribute is set.
1066 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 The argument(s) must be a list or reference to an array
1074 containing items in one or more of the following formats:
1075 • An object of type "class".
1077 • A reference to a hash containing method name/value
1079 pairs.
1080 • A single scalar primary key value.
1082 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 These objects are linked to the parent object (by setting
1091 the appropriate key attributes) and then added to the
1092 database.
1093 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 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 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 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 If passed an empty list, the method does nothing and the
1117 parent object's error attribute is set.
1118 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 • An object of type "class".
1124 • A reference to a hash containing method name/value
1126 pairs.
1127 • A single scalar primary key value.
1129 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 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 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 Example setup:
1151 # CLASS DB TABLE
1153 # ------- --------
1154 # Program programs
1155 # Bug bugs
1156 package Program;
1158 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 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 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 Example - find interface:
1213 # Read from the programs table
1215 $prog = Program->new(id => 5)->load;
1216 # Read from the bugs table
1218 $bugs = $prog->find_bugs;
1219 # 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 # Augment query
1233 $bugs = $prog->find_bugs({ state => 'open' });
1234 # 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 # Augment query and replace sort_by value
1250 $bugs = $prog->find_bugs(query => [ state => 'defunct' ],
1251 sort_by => 'name');
1252 # 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 Example - get_set interface:
1268 # Read from the programs table
1270 $prog = Program->new(id => 5)->load;
1271 # Read from the bugs table
1273 $bugs = $prog->bugs;
1274 # 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 # @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 # 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 Example - get_set_now interface:
1306 # Read from the programs table
1308 $prog = Program->new(id => 5)->load;
1309 # Read from the bugs table
1311 $bugs = $prog->bugs;
1312 $prog->name($new_name); # Does not hit the db
1314 # 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 # @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 # Write to the programs table
1330 $prog->save;
1331 Example - get_set_on_save interface:
1333 # Read from the programs table
1335 $prog = Program->new(id => 5)->load;
1336 # Read from the bugs table
1338 $bugs = $prog->bugs;
1339 $prog->name($new_name); # Does not hit the db
1341 $prog->bugs(@new_bugs); # Does not hit the db
1342 # @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 # 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 Example - add_now interface:
1358 # Read from the programs table
1360 $prog = Program->new(id => 5)->load;
1361 # Read from the bugs table
1363 $bugs = $prog->bugs;
1364 $prog->name($new_name); # Does not hit the db
1366 # 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 # @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 # Read from the bugs table, getting the full list of bugs,
1381 # including the ones that were added above.
1382 $bugs = $prog->bugs;
1383 # Write to the programs table only
1385 $prog->save;
1386 Example - add_on_save interface:
1388 # Read from the programs table
1390 $prog = Program->new(id => 5)->load;
1391 # Read from the bugs table
1393 $bugs = $prog->bugs;
1394 $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 # @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 # 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 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 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 interface NAME
1426 Choose the interface. The "get_set" interface is the
1427 default.
1428 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 iterator
1567 Behaves just like find but returns an iterator rather than
1568 an array or arrayref.
1569 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 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 • An object of type "class".
1581 • A reference to a hash containing method name/value
1583 pairs.
1584 • A single scalar primary key value.
1586 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 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 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 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 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 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 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 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 • An object of type "class".
1636 • A reference to a hash containing method name/value
1638 pairs.
1639 • A single scalar primary key value.
1641 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 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 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 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 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 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 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 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 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 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 • An object of type "class".
1703 • A reference to a hash containing method name/value
1705 pairs.
1706 • A single scalar primary key value.
1708 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 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 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 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 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 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 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 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 If passed an empty list, the method does nothing and the
1761 parent object's error attribute is set.
1762 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 The argument(s) must be a list or reference to an array
1770 containing items in one or more of the following formats:
1771 • An object of type "class".
1773 • A reference to a hash containing method name/value
1775 pairs.
1776 • A single scalar primary key value.
1778 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 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 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 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 If passed an empty list, the method does nothing and the
1805 parent object's error attribute is set.
1806 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 • An object of type "class".
1812 • A reference to a hash containing method name/value
1814 pairs.
1815 • A single scalar primary key value.
1817 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 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 For a complete example of this method type in action, see the
1832 Rose::DB::Object::Metadata::Relationship::ManyToMany documentation.
1833 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 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 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 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 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 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 interface NAME
1869 Choose the interface. The default is "get_set".
1870 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 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 This parameter conflicts with the "required" parameter.
1886 Only one of the two should be passed.
1887 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 This parameter conflicts with the "referential_integrity"
1896 parameter. Only one of the two should be passed.
1897 share_db BOOL
1899 If true, the db attribute of the current object is shared
1900 with the object loaded. Defaults to true.
1901 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 Any previously pending "get_set_on_save" action is
1916 discarded.
1917 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 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 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 Any previously pending "get_set_on_save" action is
1940 discarded.
1941 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 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 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 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 • An object of type "class"
1967 • A list of method name/value pairs.
1969 • A reference to a hash containing method name/value
1971 pairs.
1972 • A single scalar primary key value.
1974 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 The object is assigned to "hash_key" after having its
1983 "key_columns" set to their corresponding values in the
1984 current object.
1985 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 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 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 If the load succeeds, the object is returned.
2002 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 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 • An object of type "class"
2019 • A list of method name/value pairs.
2021 • A reference to a hash containing method name/value
2023 pairs.
2024 • A single scalar primary key value.
2026 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 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 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 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 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 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 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 If the load succeeds, the object is returned.
2065 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 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 • An object of type "class"
2081 • A list of method name/value pairs.
2083 • A reference to a hash containing method name/value
2085 pairs.
2086 • A single scalar primary key value.
2088 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 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 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 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 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 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 If the load succeeds, the object is returned.
2124 Example setup:
2126 # CLASS DB TABLE
2128 # ------- --------
2129 # Product products
2130 # Category categories
2131 package Product;
2133 our @ISA = qw(Rose::DB::Object);
2135 ...
2136 # 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 Example - get_set interface:
2159 $product = Product->new(id => 5, category_id => 99);
2161 # Read from the categories table
2163 $category = $product->category;
2164 # $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 # Does not write to the db
2175 $product->category(Category->new(...));
2176 $product->save; # writes to products table only
2178 Example - get_set_now interface:
2180 # Read from the products table
2182 $product = Product->new(id => 5)->load;
2183 # Read from the categories table
2185 $category = $product->category;
2186 # Write to the categories table:
2188 # (all possible argument formats show)
2189 # Object argument
2191 $product->category(Category->new(...));
2192 # Primary key value
2194 $product->category(123);
2195 # Method name/value pairs in a hashref
2197 $product->category(id => 123);
2198 # Method name/value pairs in a hashref
2200 $product->category({ id => 123 });
2201 # Write to the products table
2203 $product->save;
2204 Example - get_set_on_save interface:
2206 # Read from the products table
2208 $product = Product->new(id => 5)->load;
2209 # Read from the categories table
2211 $category = $product->category;
2212 # These do not write to the db:
2214 # Object argument
2216 $product->category(Category->new(...));
2217 # Primary key value
2219 $product->category(123);
2220 # Method name/value pairs in a hashref
2222 $product->category(id => 123);
2223 # Method name/value pairs in a hashref
2225 $product->category({ id => 123 });
2226 # Write to both the products and categories tables
2228 $product->save;
2229 Example - delete_now interface:
2231 # Read from the products table
2233 $product = Product->new(id => 5)->load;
2234 # Write to both the categories and products tables
2236 $product->delete_category();
2237 Example - delete_on_save interface:
2239 # Read from the products table
2241 $product = Product->new(id => 5)->load;
2242 # Does not write to the db
2244 $product->delete_category();
2245 # Write to both the products and categories tables
2247 $product->save;
2248 scalar
2250 Create get/set methods for scalar attributes.
2251 Options
2253 default VALUE
2254 Determines the default value of the attribute.
2255 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 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 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 interface NAME
2273 Choose the interface. The "get_set" interface is the
2274 default.
2275 length INT
2277 The maximum number of characters in the string.
2278 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 fatal
2285 Throw an exception.
2286 truncate
2288 Truncate the value to the correct length.
2289 warn
2291 Print a warning message.
2292 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 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 get Creates an accessor method for an object attribute that
2306 returns the current value of the attribute.
2307 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 Example:
2313 package MyDBObject;
2315 our @ISA = qw(Rose::DB::Object);
2317 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 sub init_type { 'C' }
2336 ...
2337 $o = MyDBObject->new(...);
2339 print $o->name; # Joe
2341 print $o->type; # C
2342 $o->name('Bob'); # set
2344 $o->type('AA'); # set
2345 eval { $o->type('foo') }; # fatal error: invalid value
2347 print $o->name, ' is ', $o->type; # get
2349 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 Options
2356 default ARRAYREF
2357 Determines the default value of the attribute. The value
2358 should be a reference to an array.
2359 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 interface NAME
2365 Choose the interface. The default is "get_set".
2366 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 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 When setting the attribute, the value is passed through the
2382 parse_set method of the object's db attribute.
2383 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 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 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 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 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 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 When setting the attribute, the value is passed through the
2417 parse_set method of the object's db attribute.
2418 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 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 Example:
2429 package Person;
2431 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 'parts' => { default => [ qw(arms legs) ] },
2442 ],
2443 );
2444 ...
2445 @parts = $person->parts; # ('arms', 'legs')
2447 $parts = $person->parts; # [ 'arms', 'legs' ]
2448 $person->nicknames('Jack', 'Gimpy'); # set with list
2450 $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
2451 $person->set_nicks('Jack', 'Gimpy'); # set with list
2453 $person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref
2454 varchar
2456 Create get/set methods for variable-length character string
2457 attributes.
2458 Options
2460 default VALUE
2461 Determines the default value of the attribute.
2462 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 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 interface NAME
2474 Choose the interface. The "get_set" interface is the
2475 default.
2476 length INT
2478 The maximum number of characters in the string.
2479 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 fatal
2486 Throw an exception.
2487 truncate
2489 Truncate the value to the correct length.
2490 warn
2492 Print a warning message.
2493 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 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 Example:
2508 package MyDBObject;
2510 our @ISA = qw(Rose::DB::Object);
2512 use Rose::DB::Object::MakeMethods::Generic
2514 (
2515 varchar =>
2516 [
2517 'name' => { length => 3 },
2518 ],
2519 );
2520 ...
2522 $o->name('John'); # truncates on set
2524 print $o->name; # 'Joh'
2525
2527 John C. Siracusa (siracusa@gmail.com)
2528
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.
2533perl v5.36.0 2023R-o0s1e-:2:0DB::Object::MakeMethods::Generic(3)