view release on metacpan or  search on metacpan

lib/Role.pm  view on Meta::CPAN

        'Role::B';

Composes roles into a class. Can be called as a class method.

=head3 apply_role

    Role::apply_role('My::Class', 'Role::Printable');
    Role::apply_role($object, 'Role::Serialisable');

Applies a role to a class or object at runtime. Returns true on success.

=head2 Query Methods

=head3 does

    if ($object->does('Role::Printable')) {
        $object->print;
    }

Checks if a class or object consumes a specific role.

=head3 get_applied_roles

    my @roles = Role::get_applied_roles('My::Class');
    my @roles = Role::get_applied_roles($object);

Returns the list of roles applied to a class.

=head3 is_role

    if (Role::is_role('Role::Printable')) {
        # It's a role
    }

Checks if a package is a role.

=head1 EXAMPLES

=head2 Basic Role with Requirements

    package Role::Validator;
    use Role;

    requires 'validate', 'get_errors';

    sub is_valid {
        my $self = shift;
        return $self->validate && !@{$self->get_errors};
    }

    1;

=head2 Role with Simple Attributes

    package Role::Timestamped;
    use Role;

    has 'created_at' => ( default => sub { time } );
    has 'updated_at' => ( default => sub { time } );

    sub update_timestamp {
        my $self = shift;
        $self->updated_at(time);
    }

    1;

    # Usage in class:
    package My::Class;
    use Class;
    with qw/Role::Timestamped/;

    sub new {
        my ($class, %args) = @_;
        my $self = bless \%args, $class;
        $self->created_at(time) unless $self->created_at;
        return $self;
    }

    1;

=head2 Role with Aliasing

    package My::Class;
    use Class;

    # Avoid conflict by aliasing
    with
        { role => 'Role::Logger', alias => { log => 'file_log' } },
        { role => 'Role::Debug', alias => { log => 'debug_log' } };

    sub log {
        my ($self, $message) = @_;
        $self->file_log($message);
        $self->debug_log($message);
    }

    1;

=head2 Runtime Role Application

    package PluginSystem;
    use Role;

    sub load_plugin {
        my ($self, $plugin_role) = @_;

        unless (Role::is_role($plugin_role)) {
            die "$plugin_role is not a role";
        }

        # Apply the plugin role to this instance's class
        Role::apply_role($self, $plugin_role);

        return $self;
    }

    1;

=head1 ATTRIBUTE SUPPORT