Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Rose::DB::Object::MakeUseroContributedoPe::DB::Object::MakeMethods::Generic(3)

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

SYNOPSIS
	 package MyDBObject;

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

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

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

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

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

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

	 sub init_type { 'C' }
	 ...

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

	 print $obj->type; # C

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

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

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

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

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

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

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

	 $obj->is_happy;       # returns 1

	 ...

	 package Person;

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

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

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

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

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

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

	 package Program;

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

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

	 $bugs = $prog->bugs;

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

	 ...

	 package Product;

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

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

	 $category = $product->category;

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	   Example:

	       package Person;

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

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

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

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

       bitfield
	   Create get/set methods for bitfield attributes.

	   Options
	       default VALUE
		   Determines the default value	of the attribute.

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

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

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

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

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

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

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

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

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

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

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

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

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

	   Example:

	       package MyDBObject;

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

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

	       ...

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

	       $o->bits('101');

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

       boolean
	   Create get/set methods for boolean attributes.

	   Options
	       default VALUE
		   Determines the default value	of the attribute.

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

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

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

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

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

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

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

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

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

	   Example:

	       package MyDBObject;

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

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

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

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

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

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

	       default VALUE
		   Determines the default value	of the attribute.

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

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

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

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

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

		   fatal
		       Throw an	exception.

		   truncate
		       Truncate	the value to the correct length.

		   warn
		       Print a warning message.

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

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

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

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

	   Example:

	       package MyDBObject;

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

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

	       ...

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

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

       enum
	   Create get/set methods for enum attributes.

	   Options
	       default VALUE
		   Determines the default value	of the attribute.

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

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

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

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

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

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

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

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

	   Example:

	       package MyDBObject;

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

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

	       sub init_stage {	'new' }
	       ...

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

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

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

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

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

       integer
	   Create get/set methods for integer attributes.

	   Options
	       default VALUE
		   Determines the default value	of the attribute.

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

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

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

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

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

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

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

	   Example:

	       package MyDBObject;

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

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

	       sub init_type { 123 }
	       ...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

	   Example setup:

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

	       package Program;

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

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

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

	   Example - find interface:

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

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

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

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

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

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

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

	   Example - get_set interface:

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

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

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

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

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

	   Example - get_set_now interface:

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

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

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

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

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

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

	   Example - get_set_on_save interface:

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

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

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

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

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

	   Example - add_now interface:

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

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

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

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

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

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

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

	   Example - add_on_save interface:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

		   o   An object of type "class".

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

		   Any previously pending "get_set_on_save" action is
		   discarded.

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

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

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

		   Any previously pending "get_set_on_save" action is
		   discarded.

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

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

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

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

		   o   An object of type "class"

		   o   A list of method	name/value pairs.

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

		   o   A single	scalar primary key value.

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

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

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

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

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

		   If the load succeeds, the object is returned.

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

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

		   o   An object of type "class"

		   o   A list of method	name/value pairs.

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

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

		   If the load succeeds, the object is returned.

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

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

		   o   An object of type "class"

		   o   A list of method	name/value pairs.

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

		   o   A single	scalar primary key value.

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

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

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

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

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

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

		   If the load succeeds, the object is returned.

	   Example setup:

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

	       package Product;

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

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

	   Example - get_set interface:

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

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

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

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

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

	   Example - get_set_now interface:

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

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

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

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

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

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

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

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

	   Example - get_set_on_save interface:

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

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

	       # These do not write to the db:

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

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

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

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

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

	   Example - delete_now	interface:

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

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

	   Example - delete_on_save interface:

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

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

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

       scalar
	   Create get/set methods for scalar attributes.

	   Options
	       default VALUE
		   Determines the default value	of the attribute.

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

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

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

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

	       length INT
		   The maximum number of characters in the string.

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

		   fatal
		       Throw an	exception.

		   truncate
		       Truncate	the value to the correct length.

		   warn
		       Print a warning message.

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

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

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

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

	   Example:

	       package MyDBObject;

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

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

	       sub init_type { 'C' }
	       ...

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

	   Example:

	       package Person;

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

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

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

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

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

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

	   Options
	       default VALUE
		   Determines the default value	of the attribute.

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

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

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

	       length INT
		   The maximum number of characters in the string.

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

		   fatal
		       Throw an	exception.

		   truncate
		       Truncate	the value to the correct length.

		   warn
		       Print a warning message.

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

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

	   Example:

	       package MyDBObject;

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

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

	       ...

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

AUTHOR
       John C. Siracusa	(siracusa@gmail.com)

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

perl v5.24.1			  201Rose::DB::Object::MakeMethods::Generic(3)

NAME | SYNOPSIS | DESCRIPTION | METHODS TYPES | AUTHOR | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Rose::DB::Object::MakeMethods::Generic&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help