NAME
Role::Subsystem - a parameterized role for object subsystems, helpers, and delegates
VERSION
version 0.101250
SYNOPSIS
You write this subsystem:
package Account::SettingsManager;
use Moose;
use Account;
with 'Role::Subsystem' => {
ident => 'acct-settings-mgr',
type => 'Account',
what => 'account',
getter => sub { Account->retrieve_by_id( $_[0] ) },
};
sub do_stuff {
my ($self) = @_;
$self->account->xyzzy;
}...and then you can say:
my $settings_mgr = Account::SettingsManager->for_account($account);
printf "We got the settings manager for account %s\n",
$settings_mgr->account_id;
$settings_mgr->do_stuff;DESCRIPTION
Role::Subsystem is a parameterized role. It's meant to simplify creating classes that encapsulate specific parts of the business logic related to parent classes. As in the synopsis above, it can be used to write "helpers." The subsystems it creates must have a reference to a parent object, which might be referenced by id or with an actual object reference. Role::Subsystem tries to guarantee that no matter which kind of reference you have, the other kind can be obtained and stored for use.
PARAMETERS
These parameters can be given when including Role::Subsystem; these are in contrast to the attributes and methods below, which are added to the classe composing this role.
ident
This is a simple name for the role to use when describing itself in messages. It is required.
what
This is the name of the attribute that will hold the parent object, like the account in the synopsis above.
This attribute is required.
type
This is the type that the what must be. It may be a stringly Moose type or an MooseX::Types type. (Or anything else, right now, but anything else will probably cause runtime failures or worse.)
This attribute is required.
id_type
This parameter is like type, but is used to check the what's id, discussed more below. If not given, it defaults to Defined.
id_method
This is the name of a method to call on what to get its id. It defaults to id.
getter
This (optional) attribute supplied a callback that will produce the parent object from the what_id.
weak_ref
If true, when a subsytem object is created with a defined parent object (that is, a value for what), the reference to the object will be weakened. This allows the parent and the subsystem to store references to one another without creating a problematic circular reference.
If the parent object is subsequently garbage collected, a new value for what will be retreived and stored, and it will not be weakened. To allow this, setting weak_ref to true requires that getter be supplied.
weak_ref is true by default.
ATTRIBUTES
The following attributes are added classes composing Role::Subsystem.
$what
This will refer to the parent object of the subsystem. It will be a value of the type type defined when parameterizing Role::Subsystem. It may be lazily computed if it was not supplied during creation or if the initial value was weak and subsequently garbage collected.
If the value of what when parameterizing Role::Subsystem was account, that will be the name of this attribute, as well as the method used to read it.
$what_id
This method gets the id of the parent object. It will be a defined value of the id_type provided when parameterizing Role::Subsystem. It may be lazily computed by calling the id_method on what as needed.
METHODS
for_$what
my $settings_mgr = Account::SettingsManager->for_account($account);This is a convenience constructor, returning a subsystem object for the given what.
for_$what_id
my $settings_mgr = Account::SettingsManager->for_account_id($account_id);This is a convenience constructor, returning a subsystem object for the given what_id.
AUTHOR
Ricardo Signes <rjbs@cpan.org>COPYRIGHT AND LICENSE
This software is copyright (c) 2010 by Ricardo Signes.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.