NAME
Rose::DB::Object::MakeMethods::Generic - Create generic object methods for Rose::DB::Object-derived objects.
SYNOPSIS
package MyDBObject;
our @ISA = qw(Rose::DB::Object);
use Rose::DB::Object::MakeMethods::Generic
(
scalar =>
[
'type' =>
{
with_init => 1,
check_in => [ qw(AA AAA C D) ],
},
'set_type' => { hash_key => 'type' },
],
character =>
[
code => { length => 6 }
],
varchar =>
[
name => { length => 10 }
],
boolean =>
[
'is_red',
'is_happy' => { default => 1 },
],
);
sub init_type { 'C' }
...
$o = MyDBObject->new(...);
print $o->type; # C
$o->name('Bob'); # set
$o->set_type('C'); # set
$o->type('AA'); # set
$o->set_type; # Fatal error: no argument passed to "set" method
$o->name('C' x 40); # truncate on set
print $o->name; # 'CCCCCCCCCC'
$o->code('ABC'); # pad on set
print $o->code; # 'ABC '
eval { $o->type('foo') }; # fatal error: invalid value
print $o->name, ' is ', $o->type; # get
$obj->is_red; # returns undef
$obj->is_red('true'); # returns 1 (assuming "true" a
# valid boolean literal according to
# $obj->db->parse_boolean('true'))
$obj->is_red(''); # returns 0
$obj->is_red; # returns 0
$obj->is_happy; # returns 1
...
package Person;
our @ISA = qw(Rose::DB::Object);
...
use Rose::DB::Object::MakeMethods::Generic
(
scalar => 'name',
set =>
[
'nicknames',
'parts' => { default => [ qw(arms legs) ] },
],
# See the Rose::DB::Object::Metadata::Relationship::ManyToMany
# documentation for a more complete example
objects_by_map =>
[
friends =>
{
map_class => 'FriendMap',
manager_args => { sort_by => 'name' },
},
],
);
...
@parts = $person->parts; # ('arms', 'legs')
$parts = $person->parts; # [ 'arms', 'legs' ]
$person->nicknames('Jack', 'Gimpy'); # set with list
$person->nicknames([ 'Slim', 'Gip' ]); # set with array ref
print join(', ', map { $_->name } $person->friends);
...
package Program;
our @ISA = qw(Rose::DB::Object);
...
use Rose::DB::Object::MakeMethods::Generic
(
objects_by_key =>
[
bugs =>
{
class => 'Bug',
key_columns =>
{
# Map Program column names to Bug column names
id => 'program_id',
version => 'version',
},
manager_args => { sort_by => 'date_submitted DESC' },
query_args => [ state => { ne => 'closed' } ],
},
]
);
...
$prog = Program->new(id => 5, version => '3.0', ...);
$bugs = $prog->bugs;
# Calls (essentially):
#
# Rose::DB::Object::Manager->get_objects(
# db => $prog->db, # share_db defaults to true
# object_class => 'Bug',
# query =>
# {
# program_id => 5, # value of $prog->id
# version => '3.0', # value of $prog->version
# state => { ne => 'closed' },
# },
# sort_by => 'date_submitted DESC');
...
package Product;
our @ISA = qw(Rose::DB::Object);
...
use Rose::DB::Object::MakeMethods::Generic
(
object_by_key =>
[
category =>
{
class => 'Category',
key_columns =>
{
# Map Product column names to Category column names
category_id => 'id',
},
},
]
);
...
$product = Product->new(id => 5, category_id => 99);
$category = $product->category;
# $product->category call is roughly equivalent to:
#
# $cat = Category->new(id => $product->category_id,
# db => $prog->db);
#
# $ret = $cat->load;
# return $ret unless($ret);
# return $cat;
DESCRIPTION
Rose::DB::Object::MakeMethods::Generic is a method maker that inherits from Rose::Object::MakeMethods. See the Rose::Object::MakeMethods documentation to learn about the interface. The method types provided by this module are described below.
All method types defined by this module are designed to work with objects that are subclasses of (or otherwise conform to the interface of) Rose::DB::Object. In particular, the object is expected to have a db method that returns a Rose::DB-derived object. See the Rose::DB::Object documentation for more details.
METHODS TYPES
- array
-
Create get/set methods for "array" attributes. A "array" column in a database table contains an ordered list of values. Not all databases support an "array" column type. Check the Rose::DB documentation for your database type.
- Options
-
default
-
Determines the default value of the attribute. The value should be a reference to an array.
hash_key
-
The key inside the hash-based object to use for the storage of this attribute. Defaults to the name of the method.
interface
-
Choose the interface. The default is
get_set
.
- Interfaces
-
get_set
-
Creates a get/set method for a "array" object attribute. A "array" column in a database table contains an ordered list of values.
When setting the attribute, the value is passed through the parse_array method of the object's db attribute.
When saving to the database, if the attribute value is defined, the method will pass the attribute value through the format_array method of the object's db attribute before returning it.
When not saving to the database, the method returns the array as a list in list context, or as a reference to the array in scalar context.
get
-
Creates an accessor method for a "array" object attribute. A "array" column in a database table contains an ordered list of values.
When saving to the database, if the attribute value is defined, the method will pass the attribute value through the format_array method of the object's db attribute before returning it.
When not saving to the database, the method returns the array as a list in list context, or as a reference to the array in scalar context.
set
-
Creates a mutator method for a "array" object attribute. A "array" column in a database table contains an ordered list of values.
When setting the attribute, the value is passed through the parse_array method of the object's db attribute.
When saving to the database, if the attribute value is defined, the method will pass the attribute value through the format_array method of the object's db attribute before returning it.
When not saving to the database, the method returns the array as a list in list context, or as a reference to the array in scalar context.
If called with no arguments, a fatal error will occur.
Example:
package Person; our @ISA = qw(Rose::DB::Object); ... use Rose::DB::Object::MakeMethods::Generic ( array => [ 'nicknames', 'set_nicks' => { interface => 'set', hash_key => 'nicknames' }, 'parts' => { default => [ qw(arms legs) ] }, ], ); ... @parts = $person->parts; # ('arms', 'legs') $parts = $person->parts; # [ 'arms', 'legs' ] $person->nicknames('Jack', 'Gimpy'); # set with list $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref $person->set_nicks('Jack', 'Gimpy'); # set with list $person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref
- bitfield
-
Create get/set methods for bitfield attributes.
- Options
-
default
-
Determines the default value of the attribute.
hash_key
-
The key inside the hash-based object to use for the storage of this attribute. Defaults to the name of the method.
interface
-
Choose the interface. The default is
get_set
. intersects
-
Set the name of the "intersects" method. (See
with_intersects
below.) Defaults to the bitfield attribute method name with "_intersects" appended. bits
-
The number of bits in the bitfield. Defaults to 32.
with_intersects
-
This option is only applicable with the
get_set
interface.If true, create an "intersects" helper method in addition to the
get_set
method. The intersection method name will be the attribute method name with "_intersects" appended, or the value of theintersects
option, if it is passed.The "intersects" method will return true if there is any intersection between its arguments and the value of the bitfield attribute (i.e., if Bit::Vector's Intersection method returns a value greater than zero), false (but defined) otherwise. Its argument is passed through the parse_bitfield method of the object's db attribute before being tested for intersection. Returns undef if the bitfield is not defined.
- Interfaces
-
get_set
-
Creates a get/set method for a bitfield attribute. When setting the attribute, the value is passed through the parse_bitfield method of the object's db attribute before being assigned.
When saving to the database, the method will pass the attribute value through the format_bitfield method of the object's db attribute before returning it. Otherwise, the value is returned as-is.
get
-
Creates an accessor method for a bitfield attribute. When saving to the database, the method will pass the attribute value through the format_bitfield method of the object's db attribute before returning it. Otherwise, the value is returned as-is.
set
-
Creates a mutator method for a bitfield attribute. When setting the attribute, the value is passed through the parse_bitfield method of the object's db attribute before being assigned.
When saving to the database, the method will pass the attribute value through the format_bitfield method of the object's db attribute before returning it. Otherwise, the value is returned as-is.
If called with no arguments, a fatal error will occur.
Example:
package MyDBObject; our @ISA = qw(Rose::DB::Object); use Rose::DB::Object::MakeMethods::Generic ( bitfield => [ 'flags' => { size => 32, default => 2 }, 'bits' => { size => 16, with_intersects => 1 }, ], ); ... print $o->flags->to_Bin; # 00000000000000000000000000000010 $o->bits('101'); $o->bits_intersects('100'); # true $o->bits_intersects('010'); # false
- boolean
-
Create get/set methods for boolean attributes.
- Options
-
default
-
Determines the default value of the attribute.
hash_key
-
The key inside the hash-based object to use for the storage of this attribute. Defaults to the name of the method.
interface
-
Choose the interface. The default is
get_set
.
- Interfaces
-
get_set
-
Creates a get/set method for a boolean attribute. When setting the attribute, if the value is "true" according to Perl's rules, it is compared to a list of "common" true and false values: 1, 0, 1.0 (with any number of zeros), 0.0 (with any number of zeros), t, true, f, false, yes, no. (All are case-insensitive.) If the value matches, then it is set to true (1) or false (0) accordingly.
If the value does not match any of those, then it is passed through the parse_boolean method of the object's db attribute. If parse_boolean returns true (1) or false (0), then the attribute is set accordingly. If parse_boolean returns undef, a fatal error will occur. If the value is "false" according to Perl's rules, the attribute is set to zero (0).
When saving to the database, the method will pass the attribute value through the format_boolean method of the object's db attribute before returning it. Otherwise, the value is returned as-is.
get
-
Creates an accessor method for a boolean attribute. When saving to the database, the method will pass the attribute value through the format_boolean method of the object's db attribute before returning it. Otherwise, the value is returned as-is.
set
-
Creates a mutator method for a boolean attribute. When setting the attribute, if the value is "true" according to Perl's rules, it is compared to a list of "common" true and false values: 1, 0, 1.0 (with any number of zeros), 0.0 (with any number of zeros), t, true, f, false, yes, no. (All are case-insensitive.) If the value matches, then it is set to true (1) or false (0) accordingly.
If the value does not match any of those, then it is passed through the parse_boolean method of the object's db attribute. If parse_boolean returns true (1) or false (0), then the attribute is set accordingly. If parse_boolean returns undef, a fatal error will occur. If the value is "false" according to Perl's rules, the attribute is set to zero (0).
If called with no arguments, a fatal error will occur.
Example:
package MyDBObject; our @ISA = qw(Rose::DB::Object); use Rose::DB::Object::MakeMethods::Generic ( boolean => [ 'is_red', 'is_happy' => { default => 1 }, 'set_happy' => { interface => 'set', hash_key => 'is_happy' }, ], ); $obj->is_red; # returns undef $obj->is_red('true'); # returns 1 (assuming "true" a # valid boolean literal according to # $obj->db->parse_boolean('true')) $obj->is_red(''); # returns 0 $obj->is_red; # returns 0 $obj->is_happy; # returns 1 $obj->set_happy(0); # returns 0 $obj->is_happy; # returns 0
- character
-
Create get/set methods for fixed-length character string attributes.
- Options
-
default
-
Determines the default value of the attribute.
hash_key
-
The key inside the hash-based object to use for the storage of this attribute. Defaults to the name of the method.
interface
-
Choose the interface. The default is
get_set
. length
-
The number of characters in the string. Any strings longer than this will be truncated, and any strings shorter will be padded with spaces to meet the length requirement. If length is omitted, the string will be left unmodified.
- Interfaces
-
get_set
-
Creates a get/set method for a fixed-length character string attribute. When setting, any strings longer than
length
will be truncated, and any strings shorter will be padded with spaces to meet the length requirement. Iflength
is omitted, the string will be left unmodified. get
-
Creates an accessor method for a fixed-length character string attribute.
set
-
Creates a mutator method for a fixed-length character string attribute. Any strings longer than
length
will be truncated, and any strings shorter will be padded with spaces to meet the length requirement. Iflength
is omitted, the string will be left unmodified.
Example:
package MyDBObject; our @ISA = qw(Rose::DB::Object); use Rose::DB::Object::MakeMethods::Generic ( character => [ 'name' => { length => 3 }, ], ); ... $o->name('John'); # truncates on set print $o->name; # 'Joh' $o->name('A'); # pads on set print $o->name; # 'A '
- objects_by_key
-
Create get/set methods for an array of Rose::DB::Object-derived objects fetched based on a key formed from attributes of the current object.
- Options
-
class
-
The name of the Rose::DB::Object-derived class of the objects to be fetched. This option is required.
hash_key
-
The key inside the hash-based object to use for the storage of the fetched objects. Defaults to the name of the method.
key_columns
-
A reference to a hash that maps column names in the current object to those in the objects to be fetched. This option is required.
manager_args
-
A reference to a hash of arguments passed to the
manager_class
when fetching objects. Ifmanager_class
defaults to Rose::DB::Object::Manager, the following argument is added to themanager_args
hash:object_class => CLASS
, where CLASS is the value of theclass
option (see above). manager_class
-
The name of the Rose::DB::Object::Manager-derived class used to fetch the objects. The
manager_method
class method is called on this class. Defaults to Rose::DB::Object::Manager. manager_method
-
The name of the class method to call on
manager_class
in order to fetch the objects. Defaults toget_objects
. interface
-
Choose the interface. The only current interface is
get_set
, which is the default. -
If true, the db attribute of the current object is shared with all of the objects fetched. Defaults to true.
query_args
-
A reference to an array of arguments added to the value of the
query
parameter passed to the call tomanager_class
'smanager_method
class method.
- Interfaces
-
get_set
-
Creates a method that will attempt to fetch Rose::DB::Object-derived objects based on a key formed from attributes of the current object.
If passed a single argument of undef, the list of objects is set to undef. If passed a reference to an array, the list of objects is set to point to that same array. (Note that these objects are not automatically added to the database.)
If called with no arguments and the hash key used to store the list of objects is defined, the list (in list context) or a reference to that array (in scalar context) of objects is returned. Otherwise, the objects are fetched.
The fetch may fail for several reasons. The fetch will not even be attempted if any of the key attributes in the current object are undefined. Instead, undef (in scalar context) or an empty list (in list context) will be returned. If the call to
manager_class
'smanager_method
method returns false, that false value (in scalar context) or an empty list (in list context) is returned.If the fetch succeeds, a list (in list context) or a reference to the array of objects (in scalar context) is returned. (If the fetch finds zero objects, the list or array reference will simply be empty. This is still considered success.)
Example:
package Program; our @ISA = qw(Rose::DB::Object); ... use Rose::DB::Object::MakeMethods::Generic ( objects_by_key => [ bugs => { class => 'Bug', key_columns => { # Map Program column names to Bug column names id => 'program_id', version => 'version', }, manager_args => { sort_by => 'date_submitted DESC' }, query_args => { state => { ne => 'closed' } }, }, ] ); ... $prog = Program->new(id => 5, version => '3.0', ...); $bugs = $prog->bugs; # Calls (essentially): # # Rose::DB::Object::Manager->get_objects( # db => $prog->db, # share_db defaults to true # object_class => 'Bug', # query => # { # program_id => 5, # value of $prog->id # version => '3.0', # value of $prog->version # state => { ne => 'closed' }, # }, # sort_by => 'date_submitted DESC');
- objects_by_map
-
Create methods that fetch Rose::DB::Object-derived objects via an intermediate Rose::DB::Object-derived class that maps between two other Rose::DB::Object-derived classes. See the Rose::DB::Object::Metadata::Relationship::ManyToMany documentation for a more complete example of this type of method in action.
- Options
-
hash_key
-
The key inside the hash-based object to use for the storage of the fetched objects. Defaults to the name of the method.
interface
-
Choose the interface. The only current interface is
get_set
, which is the default. manager_args
-
A reference to a hash of arguments passed to the
manager_class
when fetching objects. manager_class
-
The name of the Rose::DB::Object::Manager-derived class that the
map_class
will use to fetch records. Defaults to Rose::DB::Object::Manager. manager_method
-
The name of the class method to call on
manager_class
in order to fetch the objects. Defaults toget_objects
. map_class
-
The name of the Rose::DB::Object-derived class that maps between the other two Rose::DB::Object-derived classes. This class must have a foreign key and/or "one to one" relationship for each of the two tables that it maps between.
map_from
-
The name of the "one to one" relationship or foreign key in
map_class
that points to the object of the class that the method exists in. Setting this value is only necessary if themap_class
has more than one foreign key or "one to one" relationship that points to one of the classes that it maps between. map_to
-
The name of the "one to one" relationship or foreign key in
map_class
that points to the "foreign" object to be fetched. Setting this value is only necessary if themap_class
has more than one foreign key or "one to one" relationship that points to one of the classes that it maps between. -
If true, the db attribute of the current object is shared with all of the objects fetched. Defaults to true.
query_args
-
A reference to an array of arguments added to the value of the
query
parameter passed to the call tomanager_class
'smanager_method
class method.
- Interfaces
-
get_set
-
Creates a method that will attempt to fetch Rose::DB::Object-derived objects that are related to the current object through the
map_class
.If passed a single argument of undef, the list of objects is set to undef. If passed a reference to an array of objects, then the list or related objects is set to point to that same array. (Note that these objects are not automatically added to the database.)
If the call to
manager_class
'smanager_method
method returns false, that false value (in scalar context) or an empty list (in list context) is returned.If the fetch succeeds, a list (in list context) or a reference to the array of objects (in scalar context) is returned. (If the fetch finds zero objects, the list or array reference will simply be empty. This is still considered success.)
For a complete example of this method type in action, see the Rose::DB::Object::Metadata::Relationship::ManyToMany documentation.
- object_by_key
-
Create a get/set methods for a single Rose::DB::Object-derived object loaded based on a primary key formed from attributes of the current object.
- Options
-
class
-
The name of the Rose::DB::Object-derived class of the object to be loaded. This option is required.
hash_key
-
The key inside the hash-based object to use for the storage of the object. Defaults to the name of the method.
key_columns
-
A reference to a hash that maps column names in the current object to those of the primary key in the object to be loaded. This option is required.
interface
-
Choose the interface. The only current interface is
get_set
, which is the default. -
If true, the db attribute of the current object is shared with the object loaded. Defaults to true.
- Interfaces
-
get_set
-
Creates a method that will attempt to create and load a Rose::DB::Object-derived object based on a primary key formed from attributes of the current object.
If passed a single argument of undef, the
hash_key
used to store the object is set to undef. Otherwise, the argument is assumed to be an object of typeclass
and is assigned tohash_key
after having itskey_columns
set to their corresponding values in the current object.If called with no arguments and the
hash_key
used to store the object is defined, the object is returned. Otherwise, the object is created and loaded.The load may fail for several reasons. The load will not even be attempted if any of the key attributes in the current object are undefined. Instead, undef will be returned. If the call to the newly created object's
load
method returns false, that false value is returned.If the load succeeds, the object is returned.
Example:
package Product; our @ISA = qw(Rose::DB::Object); ... use Rose::DB::Object::MakeMethods::Generic ( object_by_key => [ category => { class => 'Category', key_columns => { # Map Product column names to Category column names category_id => 'id', }, }, ] ); ... $product = Product->new(id => 5, category_id => 99); $category = $product->category; # $product->category call is roughly equivalent to: # # $cat = Category->new(id => $product->category_id # db => $prog->db); # # $ret = $cat->load; # return $ret unless($ret); # return $cat;
- scalar
-
Create get/set methods for scalar attributes.
- Options
-
default
-
Determines the default value of the attribute. This option is only applicable when using the
get_set
interface. check_in
-
A reference to an array of valid values. When setting the attribute, if the new value is not equal (string comparison) to one of the valid values, a fatal error will occur.
hash_key
-
The key inside the hash-based object to use for the storage of this attribute. Defaults to the name of the method.
init_method
-
The name of the method to call when initializing the value of an undefined attribute. Defaults to the method name with the prefix
init_
added. This option implieswith_init
. interface
-
Choose the interface. The only current interface is
get_set
, which is the default. with_init
-
Modifies the behavior of the
get_set
interface. If the attribute is undefined, the method specified by theinit_method
option is called and the attribute is set to the return value of that method.
- Interfaces
-
get
get_set
-
Creates a get/set method for an object attribute. When called with an argument, the value of the attribute is set. The current value of the attribute is returned.
Creates an accessor method for an object attribute that returns the current value of the attribute.
set
-
Creates a mutator method for an object attribute. When called with an argument, the value of the attribute is set. If called with no arguments, a fatal error will occur.
Example:
package MyDBObject; our @ISA = qw(Rose::DB::Object); use Rose::DB::Object::MakeMethods::Generic ( scalar => [ name => { default => 'Joe' }, type => { with_init => 1, check_in => [ qw(AA AAA C D) ], } set_type => { check_in => [ qw(AA AAA C D) ], } ], ); sub init_type { 'C' } ... $o = MyDBObject->new(...); print $o->name; # Joe print $o->type; # C $o->name('Bob'); # set $o->type('AA'); # set eval { $o->type('foo') }; # fatal error: invalid value print $o->name, ' is ', $o->type; # get
- set
-
Create get/set methods for "set" attributes. A "set" column in a database table contains an unordered group of values. Not all databases support a "set" column type. Check the Rose::DB documentation for your database type.
- Options
-
default
-
Determines the default value of the attribute. The value should be a reference to an array.
hash_key
-
The key inside the hash-based object to use for the storage of this attribute. Defaults to the name of the method.
interface
-
Choose the interface. The default is
get_set
.
- Interfaces
-
get_set
-
Creates a get/set method for a "set" object attribute. A "set" column in a database table contains an unordered group of values. On the Perl side of the fence, an ordered list (an array) is used to store the values, but keep in mind that the order is not significant, nor is it guaranteed to be preserved.
When setting the attribute, the value is passed through the parse_set method of the object's db attribute.
When saving to the database, if the attribute value is defined, the method will pass the attribute value through the format_set method of the object's db attribute before returning it.
When not saving to the database, the method returns the set as a list in list context, or as a reference to the array in scalar context.
get
-
Creates an accessor method for a "set" object attribute. A "set" column in a database table contains an unordered group of values. On the Perl side of the fence, an ordered list (an array) is used to store the values, but keep in mind that the order is not significant, nor is it guaranteed to be preserved.
When saving to the database, if the attribute value is defined, the method will pass the attribute value through the format_set method of the object's db attribute before returning it.
When not saving to the database, the method returns the set as a list in list context, or as a reference to the array in scalar context.
set
-
Creates a mutator method for a "set" object attribute. A "set" column in a database table contains an unordered group of values. On the Perl side of the fence, an ordered list (an array) is used to store the values, but keep in mind that the order is not significant, nor is it guaranteed to be preserved.
When setting the attribute, the value is passed through the parse_set method of the object's db attribute.
When saving to the database, if the attribute value is defined, the method will pass the attribute value through the format_set method of the object's db attribute before returning it.
When not saving to the database, the method returns the set as a list in list context, or as a reference to the array in scalar context.
Example:
package Person; our @ISA = qw(Rose::DB::Object); ... use Rose::DB::Object::MakeMethods::Generic ( set => [ 'nicknames', 'set_nicks' => { interface => 'set', hash_key => 'nicknames' }, 'parts' => { default => [ qw(arms legs) ] }, ], ); ... @parts = $person->parts; # ('arms', 'legs') $parts = $person->parts; # [ 'arms', 'legs' ] $person->nicknames('Jack', 'Gimpy'); # set with list $person->nicknames([ 'Slim', 'Gip' ]); # set with array ref $person->set_nicks('Jack', 'Gimpy'); # set with list $person->set_nicks([ 'Slim', 'Gip' ]); # set with array ref
- varchar
-
Create get/set methods for variable-length character string attributes.
- Options
-
default
-
Determines the default value of the attribute.
hash_key
-
The key inside the hash-based object to use for the storage of this attribute. Defaults to the name of the method.
interface
-
Choose the interface. The only current interface is
get_set
, which is the default. length
-
The maximum number of characters in the string. Any strings longer than this will be truncated. If length is omitted, the string will be left unmodified.
- Interfaces
-
get_set
-
Creates a get/set accessor method for a fixed-length character string attribute. When setting, any strings longer than
length
will be truncated. Iflength
is omitted, the string will be left unmodified.
Example:
package MyDBObject; our @ISA = qw(Rose::DB::Object); use Rose::DB::Object::MakeMethods::Generic ( varchar => [ 'name' => { length => 3 }, ], ); ... $o->name('John'); # truncates on set print $o->name; # 'Joh'
AUTHOR
John C. Siracusa (siracusa@mindspring.com)
COPYRIGHT
Copyright (c) 2005 by John C. Siracusa. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.