NAME¶
Rose::Class::MakeMethods::Generic - Create simple class methods.
SYNOPSIS¶
package MyClass;
use Rose::Class::MakeMethods::Generic
(
scalar =>
[
'error',
'type' => { interface => 'get_set_init' },
],
inheritable_scalar => 'name',
);
sub init_type { 'special' }
...
package MySubClass;
our @ISA = qw(MyClass);
...
MyClass->error(123);
print MyClass->type; # 'special'
MyClass->name('Fred');
print MySubClass->name; # 'Fred'
MyClass->name('Wilma');
print MySubClass->name; # 'Wilma'
MySubClass->name('Bam');
print MyClass->name; # 'Wilma'
print MySubClass->name; # 'Bam'
DESCRIPTION¶
Rose::Class::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 methods work only with classes, not objects.
METHODS TYPES¶
- scalar
- Create get/set methods for scalar class attributes.
- Options
- "init_method"
- The name of the class method to call when initializing the
value of an undefined attribute. This option is only applicable when using
the "get_set_init" interface. Defaults to the method name with
the prefix "init_" added.
- "interface"
- Choose one of the two possible interfaces. Defaults to
"get_set".
- Interfaces
- "get_set"
- Creates a simple get/set accessor method for a class
attribute. When called with an argument, the value of the attribute is
set. The current value of the attribute is returned.
- "get_set_init"
- Behaves like the "get_set" interface unless the
value of the attribute is undefined. In that case, the class method
specified by the "init_method" option is called and the
attribute is set to the return value of that method.
Example:
package MyClass;
use Rose::Class::MakeMethods::Generic
(
scalar => 'power',
'scalar --get_set_init' => 'name',
);
sub init_name { 'Fred' }
...
MyClass->power(99); # returns 99
MyClass->name; # returns "Fred"
MyClass->name('Bill'); # returns "Bill"
- inheritable_boolean
- Create get/set methods for boolean class attributes that
are inherited by subclasses until/unless their values are changed.
- Options
- "interface"
- Choose the interface. This is kind of pointless since there
is only one interface right now. Defaults to "get_set",
obviously.
- Interfaces
- "get_set"
- Creates a get/set accessor method for a class attribute.
When called with an argument, the value of the attribute is set to 1 if
that argument is true or 0 if it is false. The value of the attribute is
then returned.
If called with no arguments, and if the attribute was never set for this
class, then a left-most, breadth-first search of the parent classes is
initiated. The value returned is taken from first parent class encountered
that has ever had this attribute set.
Example:
package MyClass;
use Rose::Class::MakeMethods::Generic
(
inheritable_boolean => 'enabled',
);
...
package MySubClass;
our @ISA = qw(MyClass);
...
package MySubSubClass;
our @ISA = qw(MySubClass);
...
$x = MyClass->enabled; # undef
$y = MySubClass->enabled; # undef
$z = MySubSubClass->enabled; # undef
MyClass->enabled(1);
$x = MyClass->enabled; # 1
$y = MySubClass->enabled; # 1
$z = MySubSubClass->enabled; # 1
MyClass->enabled(0);
$x = MyClass->enabled; # 0
$y = MySubClass->enabled; # 0
$z = MySubSubClass->enabled; # 0
MySubClass->enabled(1);
$x = MyClass->enabled; # 0
$y = MySubClass->enabled; # 1
$z = MySubSubClass->enabled; # 1
MyClass->enabled(1);
MySubClass->enabled(undef);
$x = MyClass->enabled; # 1
$y = MySubClass->enabled; # 0
$z = MySubSubClass->enabled; # 0
MySubSubClass->enabled(1);
$x = MyClass->enabled; # 1
$y = MySubClass->enabled; # 0
$z = MySubSubClass->enabled; # 0
- inheritable_scalar
- Create get/set methods for scalar class attributes that are
inherited by subclasses until/unless their values are changed.
- Options
- "interface"
- Choose the interface. This is kind of pointless since there
is only one interface right now. Defaults to "get_set",
obviously.
- Interfaces
- "get_set"
- Creates a get/set accessor method for a class attribute.
When called with an argument, the value of the attribute is set and then
returned.
If called with no arguments, and if the attribute was never set for this
class, then a left-most, breadth-first search of the parent classes is
initiated. The value returned is taken from first parent class encountered
that has ever had this attribute set.
Example:
package MyClass;
use Rose::Class::MakeMethods::Generic
(
inheritable_scalar => 'name',
);
...
package MySubClass;
our @ISA = qw(MyClass);
...
package MySubSubClass;
our @ISA = qw(MySubClass);
...
$x = MyClass->name; # undef
$y = MySubClass->name; # undef
$z = MySubSubClass->name; # undef
MyClass->name('Fred');
$x = MyClass->name; # 'Fred'
$y = MySubClass->name; # 'Fred'
$z = MySubSubClass->name; # 'Fred'
MyClass->name('Wilma');
$x = MyClass->name; # 'Wilma'
$y = MySubClass->name; # 'Wilma'
$z = MySubSubClass->name; # 'Wilma'
MySubClass->name('Bam');
$x = MyClass->name; # 'Wilma'
$y = MySubClass->name; # 'Bam'
$z = MySubSubClass->name; # 'Bam'
MyClass->name('Koop');
MySubClass->name(undef);
$x = MyClass->name; # 'Koop'
$y = MySubClass->name; # undef
$z = MySubSubClass->name; # undef
MySubSubClass->name('Sam');
$x = MyClass->name; # 'Koop'
$y = MySubClass->name; # undef
$z = MySubSubClass->name; # 'Sam'
- hash
- Create methods to manipulate a hash of class
attributes.
- Options
- "hash_key"
- The key to use for the storage of this attribute. Defaults
to the name of the method.
- "interface"
- Choose which interface to use. Defaults to
"get_set".
- Interfaces
- "get_set"
- If called with no arguments, returns a list of key/value
pairs in list context or a reference to the actual hash used to store
values in scalar context.
If called with one argument, and that argument is a reference to a hash,
that hash reference is used as the new value for the attribute. Returns a
list of key/value pairs in list context or a reference to the actual hash
used to store values in scalar context.
If called with one argument, and that argument is a reference to an array,
then a list of the hash values for each key in the array is returned.
If called with one argument, and it is not a reference to a hash or an
array, then the hash value for that key is returned.
If called with an even number of arguments, they are taken as name/value
pairs and are added to the hash. It then returns a list of key/value pairs
in list context or a reference to the actual hash used to store values in
scalar context.
Passing an odd number of arguments greater than 1 causes a fatal error.
- "get_set_all"
- If called with no arguments, returns a list of key/value
pairs in list context or a reference to the actual hash used to store
values in scalar context.
If called with one argument, and that argument is a reference to a hash,
that hash reference is used as the new value for the attribute. Returns a
list of key/value pairs in list context or a reference to the actual hash
used to store values in scalar context.
Otherwise, the hash is emptied and the arguments are taken as name/value
pairs that are then added to the hash. It then returns a list of key/value
pairs in list context or a reference to the actual hash used to store
values in scalar context.
- "clear"
- Sets the attribute to an empty hash.
- "reset"
- Sets the attribute to undef.
- "delete"
- Deletes the key(s) passed as arguments. Failure to pass any
arguments causes a fatal error.
- "exists"
- Returns true of the argument exists in the hash, false
otherwise. Failure to pass an argument or passing more than one argument
causes a fatal error.
- "keys"
- Returns the keys of the hash in list context, or a
reference to an array of the keys of the hash in scalar context. The keys
are not sorted.
- "names"
- An alias for the "keys" interface.
- "values"
- Returns the values of the hash in list context, or a
reference to an array of the values of the hash in scalar context. The
values are not sorted.
Example:
package MyClass;
use Rose::Class::MakeMethods::Generic
(
hash =>
[
param => { hash_key =>'params' },
params => { interface=>'get_set_all' },
param_names => { interface=>'keys', hash_key=>'params' },
param_values => { interface=>'values', hash_key=>'params' },
param_exists => { interface=>'exists', hash_key=>'params' },
delete_param => { interface=>'delete', hash_key=>'params' },
clear_params => { interface=>'clear', hash_key=>'params' },
reset_params => { interface=>'reset', hash_key=>'params' },
],
);
...
MyClass->params; # undef
MyClass->params(a => 1, b => 2); # add pairs
$val = MyClass->param('b'); # 2
%params = MyClass->params; # copy hash keys and values
$params = MyClass->params; # get hash ref
MyClass->params({ c => 3, d => 4 }); # replace contents
MyClass->param_exists('a'); # false
$keys = join(',', sort MyClass->param_names); # 'c,d'
$vals = join(',', sort MyClass->param_values); # '3,4'
MyClass->delete_param('c');
MyClass->param(f => 7, g => 8);
$vals = join(',', sort MyClass->param_values); # '4,7,8'
MyClass->clear_params;
$params = MyClass->params; # empty hash
MyClass->reset_params;
$params = MyClass->params; # undef
- inheritable_hash
- Create methods to manipulate a hash of class attributes
that can be inherited by subclasses.
The hash of attributes is inherited by subclasses using a one-time copy. Any
subclass that accesses or manipulates the hash in any way will immediately
get its own private copy of the hash as it exists in the superclass at
the time of the access or manipulation.
The superclass from which the hash is copied is the closest ("least
super") class that has ever accessed or manipulated this hash. The
copy is a "shallow" copy, duplicating only the keys and values.
Reference values are not recursively copied.
Setting to hash to undef (using the 'reset' interface) will cause it to be
re-copied from a superclass the next time it is accessed.
- Options
- "hash_key"
- The key to use for the storage of this attribute. Defaults
to the name of the method.
- "interface"
- Choose which interface to use. Defaults to
"get_set".
- Interfaces
- "get_set"
- If called with no arguments, returns a list of key/value
pairs in list context or a reference to the actual hash used to store
values in scalar context.
If called with one argument, and that argument is a reference to a hash,
that hash reference is used as the new value for the attribute. Returns a
list of key/value pairs in list context or a reference to the actual hash
used to store values in scalar context.
If called with one argument, and that argument is a reference to an array,
then a list of the hash values for each key in the array is returned.
If called with one argument, and it is not a reference to a hash or an
array, then the hash value for that key is returned.
If called with an even number of arguments, they are taken as name/value
pairs and are added to the hash. It then returns a list of key/value pairs
in list context or a reference to the actual hash used to store values in
scalar context.
Passing an odd number of arguments greater than 1 causes a fatal error.
- "get_set_all"
- If called with no arguments, returns a list of key/value
pairs in list context or a reference to the actual hash used to store
values in scalar context.
If called with one argument, and that argument is a reference to a hash,
that hash reference is used as the new value for the attribute. Returns a
list of key/value pairs in list context or a reference to the actual hash
used to store values in scalar context.
Otherwise, the hash is emptied and the arguments are taken as name/value
pairs that are then added to the hash. It then returns a list of key/value
pairs in list context or a reference to the actual hash used to store
values in scalar context.
- "clear"
- Sets the attribute to an empty hash.
- "reset"
- Sets the attribute to undef.
- "delete"
- Deletes the key(s) passed as arguments. Failure to pass any
arguments causes a fatal error.
- "exists"
- Returns true of the argument exists in the hash, false
otherwise. Failure to pass an argument or passing more than one argument
causes a fatal error.
- "keys"
- Returns the keys of the hash in list context, or a
reference to an array of the keys of the hash in scalar context. The keys
are not sorted.
- "names"
- An alias for the "keys" interface.
- "values"
- Returns the values of the hash in list context, or a
reference to an array of the values of the hash in scalar context. The
values are not sorted.
Example:
package MyClass;
use Rose::Class::MakeMethods::Generic
(
inheritable_hash =>
[
param => { hash_key =>'params' },
params => { interface=>'get_set_all' },
param_names => { interface=>'keys', hash_key=>'params' },
param_values => { interface=>'values', hash_key=>'params' },
param_exists => { interface=>'exists', hash_key=>'params' },
delete_param => { interface=>'delete', hash_key=>'params' },
clear_params => { interface=>'clear', hash_key=>'params' },
reset_params => { interface=>'reset', hash_key=>'params' },
],
);
...
package MySubClass;
our @ISA = qw(MyClass);
...
MyClass->params; # undef
MyClass->params(a => 1, b => 2); # add pairs
$val = MyClass->param('b'); # 2
%params = MyClass->params; # copy hash keys and values
$params = MyClass->params; # get hash ref
# Inherit a copy of params from MyClass
$params = MySubClass->params; # { a => 1, b => 2 }
MyClass->params({ c => 3, d => 4 }); # replace contents
# MySubClass params are still as the existed at the time
# they were originally copied from MyClass
$params = MySubClass->params; # { a => 1, b => 2 }
# MySubClass can manipulate its own params as it wishes
MySubClass->param(z => 9);
$params = MySubClass->params; # { a => 1, b => 2, z => 9 }
MyClass->param_exists('a'); # false
$keys = join(',', sort MyClass->param_names); # 'c,d'
$vals = join(',', sort MyClass->param_values); # '3,4'
# Reset params (set to undef) so that they will be re-copied
# from MyClass the next time they're accessed
MySubClass->reset_params;
MyClass->delete_param('c');
MyClass->param(f => 7, g => 8);
$vals = join(',', sort MyClass->param_values); # '4,7,8'
# Inherit a copy of params from MyClass
$params = MySubClass->params; # { d => 4, f => 7, g => 8 }
- inherited_hash
- Create a family of class methods for managing an inherited
hash.
An inherited hash is made up of the union of the hashes of all superclasses,
minus any keys that are explicitly deleted in the current class.
- Options
- "add_implies"
- A method name, or reference to a list of method names, to
call when a key is added to the hash. Each added name/value pair is passed
to each method in the "add_implies" list, one pair at a
time.
- "add_method"
- The name of the class method used to add a single
name/value pair to the hash. Defaults to the method name with the prefix
"add_" added.
- "adds_method"
- The name of the class method used to add one or more
name/value pairs to the hash. Defaults to "plural_name" with the
prefix "add_" added.
- "cache_method"
- The name of the class method used to retrieve (or generate,
if it doesn't exist) the internal cache for the hash. This should be
considered a private method, but it is listed here because it does take up
a spot in the method namespace. Defaults to "plural_name" with
"_cache" added to the end.
- "clear_method"
- The name of the class method used to clear the contents of
the hash. Defaults to "plural_name" with a "clear_"
prefix added.
- "delete_implies"
- A method name, or reference to a list of method names, to
call when a key is removed from the hash. Each deleted key is passed as an
argument to each method in the "delete_implies" list, one key
per call.
- "delete_method"
- The name of the class method used to remove a single key
from the hash. Defaults to the method name with the prefix
"delete_" added.
- "deletes_method"
- The name of the class method used to remove one or more
keys from the hash. Defaults to "plural_name" with a
"delete_" prefix added.
- "exists_method"
- The name of the class method that tests for the existence
of a key in the hash. Defaults to the method name with the suffix
"_exists" added.
- "get_set_all_method"
- The name of the class method use to set or fetch the entire
hash. The hash may be passed as a reference to a hash or as a list of
name/value pairs. Returns the hash (in list context) or a reference to a
hash (in scalar context). Defaults to "plural_name".
- "hash_method"
- This is an alias for the "get_set_all_method"
parameter.
- "inherit_method"
- The name of the class method used to indicate that an
inherited key that was previously deleted from the hash should return to
being inherited. Defaults to the method name with the prefix
"inherit_" added.
- "inherits_method"
- The name of the class method used to indicate that one or
more inherited keys that were previously deleted from the hash should
return to being inherited. Defaults to the "plural_name" with
the prefix "inherit_" added.
- "interface"
- Choose the interface. This is kind of pointless since there
is only one interface right now. Defaults to "all",
obviously.
- "keys_method"
- The name of the class method that returns a reference to a
list of keys in scalar context, or a list of keys in list context.
Defaults to to "plural_name" with "_keys" added to the
end.
- "plural_name"
- The plural version of the method name, used to construct
the default names for some other methods. Defaults to the method name with
"s" added.
- Interfaces
- "all"
- Creates the entire family of methods described above. The
example below illustrates their use.
Example:
package MyClass;
use Rose::Class::MakeMethods::Generic
(
inherited_hash =>
[
pet_color =>
{
keys_method => 'pets',
delete_implies => 'delete_special_pet_color',
inherit_implies => 'inherit_special_pet_color',
},
special_pet_color =>
{
keys_method => 'special_pets',
add_implies => 'add_pet_color',
},
],
);
...
package MySubClass;
our @ISA = qw(MyClass);
...
MyClass->pet_colors(Fido => 'white',
Max => 'black',
Spot => 'yellow');
MyClass->special_pet_color(Toby => 'tan');
MyClass->pets; # Fido, Max, Spot, Toby
MyClass->special_pets; # Toby
MySubClass->pets; # Fido, Max, Spot, Toby
MyClass->pet_color('Toby'); # tan
MySubClass->special_pet_color(Toby => 'gold');
MyClass->pet_color('Toby'); # tan
MyClass->special_pet_color('Toby'); # tan
MySubClass->pet_color('Toby'); # gold
MySubClass->special_pet_color('Toby'); # gold
MySubClass->inherit_pet_color('Toby');
MySubClass->pet_color('Toby'); # tan
MySubClass->special_pet_color('Toby'); # tan
MyClass->delete_pet_color('Max');
MyClass->pets; # Fido, Spot, Toby
MySubClass->pets; # Fido, Spot, Toby
MyClass->special_pet_color(Max => 'mauve');
MyClass->pets; # Fido, Max, Spot, Toby
MySubClass->pets; # Fido, Max, Spot, Toby
MyClass->special_pets; # Max, Toby
MySubClass->special_pets; # Max, Toby
MySubClass->delete_special_pet_color('Max');
MyClass->pets; # Fido, Max, Spot, Toby
MySubClass->pets; # Fido, Max, Spot, Toby
MyClass->special_pets; # Max, Toby
MySubClass->special_pets; # Toby
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.
