File Coverage

blib/lib/Articulate/Permission.pm

Criterion	Covered	Total	%
statement	26	34	76.4
branch			n/a
condition	2	2	100.0
subroutine	9	10	90.0
pod	3	3	100.0
total	40	49	81.6

package Articulate::Permission;
use strict;
use warnings;

use Moo;
use Devel::StackTrace;

use overload bool => sub { shift->granted }, '0+' => sub { shift->granted };

=head1 NAME

Articulate::Permission - represent a permission request/response

=cut

=head1 FUNCTIONS

=head3 permission

  my $permission = permission $user, verb => $location;

Creates a new request, using the verb and data supplied as the respective arguments.

=cut

use Exporter::Declare;
default_exports qw(permission);

sub permission {
  __PACKAGE__->new(
    {
      user_id => shift // '[guest]',
      verb => shift,
      location => shift
    }
  );
}

=head1 METHODS

=head3 new

An unremarkable Moo constructor.

=cut

=head3 grant

  $permission->grant('Anybody can do that!');

Declares that the user has that permission, for the reason given; sets C and C and populates the stack trace.

=cut

sub grant {
  my $self   = shift;
  my $reason = shift;

  # die if granted or denied are already set?
  $self->granted(1);
  $self->reason($reason);
  $self->stack_trace( Devel::StackTrace->new );
  return $self;
}

=head3 deny

  $permission->deny('Don\t touch that!');

Declares that the user does not have that permission, for the reason given; sets C and C and populates the stack trace.

=cut

sub deny {
  my $self   = shift;
  my $reason = shift;

  # die if granted or denied are already set?
  $self->granted(0);
  $self->denied(1);
  $self->reason($reason);
  $self->stack_trace( Devel::StackTrace->new );
  return $self;
}

=head1 ATTRIBUTES

=head3 user_id

The user_id requesting permission to access the resource.

=cut

has user_id => (
  is      => 'rw',
  default => sub { undef },
);

=head3 verb

The action being performed, e.g. C, C, etc. The verbs available are entirely dependant on the application.

A permission request will be granted or denied by an authorisation rule (see Articulate::Authorisation), who will typically implement verbs that bay be different from but are either a) broader than, or b) equally broad as, the verbs used by the Articulate::Service.

=cut

has verb => (
  is      => 'rw',
  default => sub { 'error' },
);

=head3 location

The location of the resource for which permission is requested.

=cut

has location => (
  is      => 'rw',
  default => sub { [] },
);

=head3 granted

Whether or not the permission has been explicitly granted. The value of this is used for overload behaviour.

Please do not explicitly set this. Use C instead.

=cut

has granted => (
  is      => 'rw',
  default => sub { 0 },
);

=head3 denied

Whether the permission has been explicitly denied.

Please do not explicitly set this. Use C instead.

=cut

has denied => (
  is      => 'rw',
  default => sub { 0 }
);

=head3 reason

The reason for the grant or denial of permission.

Please do not explicitly set this. Use C or C instead.

=cut

has reason => (
  is      => 'rw',
  default => sub { '' }
);

=head3 stack_trace

The stack trace at the point of grant or denial of permission.

Please do not explicitly set this. Use C or C instead.

=cut

has stack_trace => (
  is      => 'rw',
  default => sub { '' }
);

=head1 SEE ALSO

=over

=item * L

=item * L (which performs a similar function for L)

=back

=cut

1;