The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Entities-0.2
River stage zero No dependents
2 ++
/ Entities::Role

NAME

Entities::Role - A collection of possibly related actions granted to users.

VERSION

version 0.2

SYNOPSIS

        used internally, see L<Entities>

DESCRIPTION

A role is merely a collection of actions. Users are assigned to these roles to easily provide them with abilities they might need, probably to perform their 'roles' in a webapp (think of roles such as 'admins', 'members', 'vandal_fighters' or 'trolls'; probably not trolls though).

Roles can inherit all action of other roles, to allow for a structured authorization-system that is easier to apply and follow.

This entity class does the Abilities Moose role.

NOTE: you are not meant to create role objects directly, but only through the new_role() method in Entities.

METHODS

new( name => 'somerole', [ description => 'Just some role', is_super => 0, roles => [], actions => [], created => $dt_obj, modified => $other_dt_obj, parent => $entities_obj, id => 123 ] )

Creates a new instance of this module. Only 'name' is required.

id()

Returns the ID of the role, if set.

has_id()

Returns a true value if the role object has an ID attribute.

_set_id( $id )

Sets the ID of the role object to the provided value. Only to be used internally.

name()

Returns the name of the role.

description()

Returns the description text of this role.

set_description( $desc )

Changes the description text of the object to the provided text.

_roles( [\@roles] )

In scalar context, returns an array-ref of all role names this role inherits from. In list context returns an array. If an array-ref of role names is provided, it will replace the current list.

has_roles()

Returns a true value if the role inherits from any other roles.

roles()

Returns an array of all role objects this role inherits from.

_actions( [\@actions] )

In scalar context, returns an array-ref of all action names this role has. In list context returns an array. If an array-ref of action names is provided, it will replace the current list.

has_actions()

Returns a true value if the role has been granted any actions.

actions()

Returns an array of all action objects this role has been granted.

is_super()

Returns a true value if this role is considered a super-role. Super roles can do every possible action, in ANY SCOPE.

created()

Returns a DateTime object in the time the role object has been created.

modified( [$dt] )

Returns a DateTime object in the last time the object has been modified. If a DateTime object is provided, it is set as the new modified value.

parent()

Returns the Entities::Backend instance that stores this object.

has_direct_action( $action_name )

Returns a true value if the role has been explicitely grant the action named $action_named (i.e. not through inheritance).

grant_action( $action_name )

Grants the action named $action_name to the role. Croaks if the action does not exist, warns if the role has already been granted this action.

Returns the role object itself.

drop_action( $action_name )

Removes the action named $action_name from the list of actions the role has been explictely granted to perform. This doesn't necessarily mean the role will not be able to perform this action anymore, as it might be available to it via inherited roles. Warns if the role wasn't granted this action, does not croak if the action does not exist. Returns the role object itself.

inherit_from_role( $role_name )

Sets up an inheritance between the current role object and the role whose name is $role_name. Croaks if $role_name cannot be found, warns if such an inheritance already exists.

Returns the role object itself.

dont_inherit_from_role( $role_name )

This badly named method drops the inheritance from the role named $role_name. Warns if the role object doesn't inherit from the provided role, does not croak if the provided role does not even exist. Returns the role object itself.

METHODS CONSUMED FROM Abilities

The following methods are consumed by this class from the Abilities Moose role. See the documentation for that role for more information on these methods.

can_perform( $action_name | @action_names )

takes_from( $role_name | @role_names )

inherits_from_role( $role_name | @role_names )

all_abilities()

METHOD MODIFIERS

The following list documents any method modifications performed through the magic of Moose.

around qw/_roles _actions/

If the _roles() and _actions() methods are called with no arguments and in list context - will automatically dereference the array-ref into arrays.

after anything_that_changes_object

Automatically saves the object to the backend after any method that changed it was executed. Also updates the 'modified' attribute with the current time before saving. Note, however, that the roles() and action() methods are not here, since they are only meant to be used for writing internally.

SEE ALSO

Entities.

AUTHOR

Ido Perlmuter, <ido at ido50 dot net>

BUGS

Please report any bugs or feature requests to bug-entities at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Entities. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Entities

You can also look for information at:

LICENSE AND COPYRIGHT

Copyright 2010 Ido Perlmuter.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.