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 => 
  [
    'name',
    'type' => 
    {
      with_init => 1,
      check_in  => [ qw(AA AAA C D) ],
    }
  ],

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

sub init_type { 'C' }
...

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

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

$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
(
  set => 
  [
    '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

...

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

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 only current interface is get_set, which is the default.

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

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

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

Interfaces

get_set

Creates a get/set accessor 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.

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 only current interface is get_set, which is the default.

Interfaces

get_set

Creates a simple get/set accessor method for a boolean attribute. When setting the attribute, if the value is "true" according to Perl's rules, 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.

Example:

package MyDBObject;

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

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

$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

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. If manager_class defaults to Rose::DB::Object::Manager, the following argument is added to the manager_args hash: object_class => CLASS, where CLASS is the value of the class option (see above).
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 to get_objects.
interface: Choose the interface. The only current interface is get_set, which is the default.
share_db: 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 a hash of arguments added to the value of the query parameter passed to the call to manager_class's manager_method class method. If one of the key_column arguments is overridden, a fatal error will occur when manager_method is called.

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.

If called with no arguments and the hash key used to store the list of objects is defined, a reference to that array 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 will be returned. If the call to manager_class's manager_method method returns false, that false value is returned.

If the fetch succeeds, a reference to the array of objects is returned. (If the fetch finds zero objects, the array 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');

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.
share_db: 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 type class and is assigned to hash_key after having its key_columns set to their corresponding values in the current object.

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

The load may fail for several reasons. The load will not even be attempted if any of the key attributes in the current object are undefined. Instead, undef will be returned. If the call to the newly created object's load method returns false, 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 implies with_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 the init_method option is called and the attribute is set to the return value of that method.

Interfaces

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

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) ],
    }
  ],
);

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.

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 only current interface is get_set, which is the default.

Interfaces

get_set

Creates a simple get/set 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 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',
    '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

AUTHOR

John C. Siracusa (siracusa@mindspring.com)

COPYRIGHT

To install Rose::DB::Object, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Rose::DB::Object

CPAN shell

perl -MCPAN -e shell
install Rose::DB::Object

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

METHODS TYPES

AUTHOR

COPYRIGHT

Module Install Instructions