Provided by: librose-object-perl_0.860-1_all 
NAME
Rose::Class::MakeMethods::Set - Create class methods to manage sets.
SYNOPSIS
package MyClass;
use Rose::Class::MakeMethods::Set
(
inheritable_set =>
[
required_name =>
{
add_implies => 'add_valid_name',
test_method => 'name_is_required',
},
],
inherited_set =>
[
valid_name =>
{
test_method => 'name_is_valid',
},
],
);
...
package MySubClass;
our @ISA = qw(MyClass);
...
MyClass->add_valid_names('A', 'B', 'C');
MyClass->add_required_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
$r1 = join(',', MyClass->required_names); # 'D'
$v2 = join(',', MySubClass->valid_names); # 'A,B,C,D';
$r2 = join(',', MySubClass->required_names); # 'D'
MySubClass->add_required_names('X', 'Y');
$v2 = join(',', MySubClass->valid_names); # 'A,B,C,D,X,Y';
$r2 = join(',', MySubClass->required_names); # 'D,X,Y'
MySubClass->delete_valid_names('B', 'X');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
$r1 = join(',', MyClass->required_names); # 'D'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'D,X,Y'
MySubClass->delete_required_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
$r1 = join(',', MyClass->required_names); # 'D'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'X,Y'
DESCRIPTION
Rose::Class::MakeMethods::Set 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
inheritable_set
Create a family of class methods for managing an inheritable set of items, each with
an optional associated value. Each item must be a string, or must stringify to a
unique string value, since a hash is used internally to store the set.
The set is inherited by subclasses, but any subclass that accesses or manipulates the
set in any way will immediately get its own private copy of the set as it exists in
the superclass at the time of the access or manipulation. The superclass from which
the set is copied is the closest ("least super") class that has ever accessed or
manipulated this set.
These may sound like wacky rules, but it may help to know that this family of methods
was created for use in the Rose::HTML::Objects family of modules to manage the set of
required HTML attributes (and their optional default values) for various HTML tags.
Options
"add_implies"
A method name, or reference to a list of method names, to call when an item is
added to the set. Each added attribute is passed as an argument to each
method in the "add_implies" list.
"add_method"
The name of the class method used to add a single item to the set. Defaults to
the method name with the prefix "add_" added.
"adds_method"
The name of the class method used to add one or more items to the set.
Defaults to "add_method" with "s" added to the end.
"clear_method"
The name of the class method used to clear the contents of the set. 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 an item is
removed from the set. Each deleted attribute is passed as an argument to each
method in the "delete_implies" list.
"delete_method"
The name of the class method used to remove a single item from the set.
Defaults to the method name with the prefix "delete_" added.
"deletes_method"
The name of the class method used to remove one or more items from the set.
Defaults to "plural_name" with a "delete_" prefix added.
"hash_method"
The name of the class method that returns a reference to the actual hash that
contains the set of items in scalar context, and a shallow copy of the hash in
list context. Defaults to "plural_name" with "_hash" added to the end.
"interface"
Choose the interface. This is kind of pointless since there is only one
interface right now. Defaults to "all", obviously.
"list_method"
The name of the class method that returns a reference to a sorted list of
items in scalar context, or a sorted list in list context. If called with any
arguments, the set is cleared with a call to "clear_method", then the set is
repopulated by passing all of the arguments to a call to "adds_method". The
method name defaults to "plural_name".
"plural_name"
The plural name of the items, used to construct the default names for some
other methods. Defaults to the method name with "s" added.
"test_method"
The name of the class method that tests for the existence of an item in the
set. Defaults to the method name with the prefix "is_" added.
"value_method"
The name of the class method used to get and set the (optional) value
associated with each item in the set. Defaults to the method name with
"_value" added to the end.
Interfaces
"all"
Creates the entire family of methods described above. The example below
illustrates their use.
Example:
package MyClass;
use Rose::Class::MakeMethods::Set
(
inheritable_set =>
[
valid_name =>
{
test_method => 'name_is_valid',
delete_implies => 'delete_required_name',
},
required_name =>
{
add_implies => 'add_valid_name',
test_method => 'name_is_required',
},
],
);
package MySubClass;
our @ISA = qw(MyClass);
...
MyClass->add_valid_names('A', 'B', 'C');
MyClass->add_required_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
$r1 = join(',', MyClass->required_names); # 'D'
$v2 = join(',', MySubClass->valid_names); # 'A,B,C,D';
$r2 = join(',', MySubClass->required_names); # 'D'
MySubClass->add_required_names('X', 'Y');
$v2 = join(',', MySubClass->valid_names); # 'A,B,C,D,X,Y';
$r2 = join(',', MySubClass->required_names); # 'D,X,Y'
MySubClass->delete_valid_names('B', 'X');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
$r1 = join(',', MyClass->required_names); # 'D'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'D,Y'
MySubClass->delete_required_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
$r1 = join(',', MyClass->required_names); # 'D'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'Y'
MyClass->name_is_required('D'); # true
MySubClass->name_is_required('D'); # false
$h = MyClass->valid_names_hash;
# Careful! This is the actual hash used for set storage!
# You should use delete_valid_name() instead!
delete $h->{'C'};
MySubClass->required_name_value(Y => 'xval');
print MySubClass->required_name_value('Y'); # 'xval'
%r = MySubClass->required_names_hash;
print $r{'Y'}; # 'xval'
# Okay: %r is a (shallow) copy, not the actual hash
delete $r{'Y'};
inherited_set
Create a family of class methods for managing an inherited set of items. Each item
must be a string, or must stringify to a unique string value, since a hash is used
internally to store the set.
An inherited set is made up of the union of the sets of all superclasses, minus any
items 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 an item is
added to the set. Each added attribute is passed as an argument to each
method in the "add_implies" list.
"add_method"
The name of the class method used to add a single item to the set. Defaults to
the method name with the prefix "add_" added.
"adds_method"
The name of the class method used to add one or more items to the set.
Defaults to "add_method" with "s" added to the end.
"cache_method"
The name of the class method used to retrieve (or generate, if it doesn't
exist) the internal cache for the set. 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 set. 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 an item is
removed from the set. Each deleted attribute is passed as an argument to each
method in the "delete_implies" list.
"delete_method"
The name of the class method used to remove a single item from the set.
Defaults to the method name with the prefix "delete_" added.
"deletes_method"
The name of the class method used to remove one or more items from the set.
Defaults to "plural_name" with a "delete_" prefix added.
"hash_method"
The name of the class method that returns a hash (in list context) or a
reference to a hash (in scalar context) that contains the set of items. The
existence of a key in the hash indicates its existence in the set. Defaults to
"plural_name" with "_hash" added to the end.
"inherit_method"
The name of the class method used to indicate that an inherited value that was
previously deleted from the set 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
values that were previously deleted from the set should return to being
inherited. Defaults to the "inherit_method" name with "s" added to the end.
"interface"
Choose the interface. This is kind of pointless since there is only one
interface right now. Defaults to "all", obviously.
"list_method"
The name of the class method that returns a reference to a sorted list of
items in scalar context, or a sorted list in list context. If called with any
arguments, the set is cleared with a call to "clear_method", then the set is
repopulated by passing all of the arguments to a call to "adds_method". The
method name defaults to "plural_name".
"plural_name"
The plural name of the items, used to construct the default names for some
other methods. Defaults to the method name with "s" added.
"test_method"
The name of the class method that tests for the existence of an item in the
set. Defaults to the method name with the prefix "is_" added.
Interfaces
"all"
Creates the entire family of methods described above. The example below
illustrates their use.
Example:
package MyClass;
use Rose::Class::MakeMethods::Set
(
inherited_set =>
[
valid_name =>
{
test_method => 'name_is_valid',
delete_implies => 'delete_required_name',
inherit_implies => 'inherit_required_name',
},
required_name =>
{
add_implies => 'add_valid_name',
test_method => 'name_is_required',
},
],
);
...
package MySubClass;
our @ISA = qw(MyClass);
...
MyClass->add_valid_names('A', 'B', 'C');
MyClass->add_required_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D';
$r1 = join(',', MyClass->required_names); # 'D'
$v2 = join(',', MySubClass->valid_names); # 'A,B,C,D';
$r2 = join(',', MySubClass->required_names); # 'D'
MyClass->add_required_names('X', 'Y');
$v2 = join(',', MySubClass->valid_names); # 'A,B,C,D,X,Y';
$r2 = join(',', MySubClass->required_names); # 'D,X,Y'
MySubClass->delete_valid_names('B', 'X');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
$r1 = join(',', MyClass->required_names); # 'D,X,Y'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'D,Y'
MySubClass->delete_required_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
$r1 = join(',', MyClass->required_names); # 'D,X,Y'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'Y'
MySubClass->inherit_required_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
$r1 = join(',', MyClass->required_names); # 'D,X,Y'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'D,Y'
MySubClass->delete_valid_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
$r1 = join(',', MyClass->required_names); # 'D,X,Y'
$v2 = join(',', MySubClass->valid_names); # 'A,C,Y';
$r2 = join(',', MySubClass->required_names); # 'Y'
MySubClass->inherit_valid_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,D,X,Y';
$r1 = join(',', MyClass->required_names); # 'D,X,Y'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'D,Y'
MyClass->delete_valid_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,X,Y';
$r1 = join(',', MyClass->required_names); # 'X,Y'
$v2 = join(',', MySubClass->valid_names); # 'A,C,Y';
$r2 = join(',', MySubClass->required_names); # 'Y'
MySubClass->add_required_name('D');
$v1 = join(',', MyClass->valid_names); # 'A,B,C,X,Y';
$r1 = join(',', MyClass->required_names); # 'X,Y'
$v2 = join(',', MySubClass->valid_names); # 'A,C,D,Y';
$r2 = join(',', MySubClass->required_names); # 'D,Y'
$h = MyClass->valid_names_hash;
# This has no affect on the set. $h is not a reference to the
# actual hash used for set storage.
delete $h->{'C'};
$v1 = join(',', MyClass->valid_names); # 'A,B,C,X,Y';
$r1 = join(',', MyClass->required_names); # 'X,Y'
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.