NAME

Mars::Role - Role Declaration

ABSTRACT

Role Declaration for Perl 5

SYNOPSIS

  package Person;

  use Mars::Class;

  attr 'fname';
  attr 'lname';

  package Identity;

  use Mars::Role;

  attr 'id';
  attr 'login';
  attr 'password';

  sub EXPORT {
    # explicitly declare routines to be consumed
    return ['id', 'login', 'password'];
  }

  package Authenticable;

  use Mars::Role;

  sub authenticate {
    return true;
  }

  sub AUDIT {
    my ($self, $from) = @_;
    die "${from} missing Identity role" if !$from->does('Identity');
  }

  sub EXPORT {
    # explicitly declare routines to be consumed
    return ['authenticate'];
  }

  package User;

  use Mars::Class;

  base 'Person';
  with 'Identity';

  attr 'email';

  test 'Authenticable';

  sub valid {
    my ($self) = @_;
    return $self->login && $self->password ? true : false;
  }

  package main;

  my $user = User->new(
    fname => 'Elliot',
    lname => 'Alderson',
  );

  # bless({fname => 'Elliot', lname => 'Alderson'}, 'User')

DESCRIPTION

This package provides a role builder which when used causes the consumer to inherit from Mars::Kind::Role which provides role construction and lifecycle hooks. A role differs from a "class" in that it can't be instantiated using the new method. A role can act as an interface by defining the an "audit" hook, which is invoked automatically by the "test" function. The role composition semantics are as follows: Routines to be consumed must be explicitly declared via the "export" hook. Routines will be copied to the consumer unless they already exist (excluding routines from base classes, which will be overridden). If multiple roles are consumed having routines with the same name (i.e. naming collisions) the first routine copied wins.

FUNCTIONS

This package provides the following functions:

attr

  attr(Str $name) (Str)

The attr function creates attribute accessors for the calling package. This function is always exported unless a routine of the same name already exists.

Since 0.01

attr example 1

  package Example;

  use Mars::Class;

  attr 'name';

  # "Example"

base

  base(Str $name) (Str)

The base function registers one or more base classes for the calling package. This function is always exported unless a routine of the same name already exists.

Since 0.01

base example 1

  package Entity;

  use Mars::Class;

  sub output {
    return;
  }

  package Example;

  use Mars::Class;

  base 'Entity';

  # "Example"

false

  false() (Bool)

The false function returns a falsy boolean value which is designed to be practically indistinguishable from the conventional numerical 0 value. This function is always exported unless a routine of the same name already exists.

Since 0.01

false example 1

  package Example;

  use Mars::Class;

  my $false = false;

  # 0

false example 2

  package Example;

  use Mars::Class;

  my $true = !false;

  # 1

role

  role(Str $name) (Str)

The role function registers and consumes roles for the calling package. This function is always exported unless a routine of the same name already exists.

Since 0.01

role example 1

  package Ability;

  use Mars::Role;

  sub action {
    return;
  }

  package Example;

  use Mars::Class;

  role 'Ability';

  # "Example"

role example 2

  package Ability;

  use Mars::Role;

  sub action {
    return;
  }

  sub EXPORT {
    return ['action'];
  }

  package Example;

  use Mars::Class;

  role 'Ability';

  # "Example"

test

  test(Str $name) (Str)

The test function registers and consumes roles for the calling package and performs an "audit", effectively allowing a role to act as an interface. This function is always exported unless a routine of the same name already exists.

Since 0.01

test example 1

  package Actual;

  use Mars::Role;

  package Example;

  use Mars::Class;

  test 'Actual';

  # "Example"

test example 2

  package Actual;

  use Mars::Role;

  sub AUDIT {
    die "Example is not an 'actual' thing" if $_[1]->isa('Example');
  }

  package Example;

  use Mars::Class;

  test 'Actual';

  # "Example"

true

  true() (Bool)

The true function returns a truthy boolean value which is designed to be practically indistinguishable from the conventional numerical 1 value. This function is always exported unless a routine of the same name already exists.

Since 0.01

true example 1

  package Example;

  use Mars::Class;

  my $true = true;

  # 1

true example 2

  package Example;

  use Mars::Class;

  my $false = !true;

  # 0

with

  with(Str $name) (Str)

The with function registers and consumes roles for the calling package. This function is an alias of the "role" function. This function is always exported unless a routine of the same name already exists.

Since 0.01

with example 1

  package Understanding;

  use Mars::Role;

  sub knowledge {
    return;
  }

  package Example;

  use Mars::Class;

  with 'Understanding';

  # "Example"

with example 2

  package Understanding;

  use Mars::Role;

  sub knowledge {
    return;
  }

  sub EXPORT {
    return ['knowledge'];
  }

  package Example;

  use Mars::Class;

  with 'Understanding';

  # "Example"

AUTHORS

Awncorp, awncorp@cpan.org

cpanm Mars

perl -MCPAN -e shell
install Mars