Role-ful

Roles for you and your objects.

Like it? Then please recommend me on Working with Rails.

Usage

In your class, after including Roleful, declare your roles. It’s up
to you to implement a role instance method for your objects that determines
what kind of permissions they receive.

If an object doesn’t have a role method, or if the role returns an invalid
role, the :null role will be used, which just returns false for all permissions.

Example Class:

class User
  include Roleful
  
  def initialize(name=nil)
    @role = name
  end
  
  def role
    @role
  end
end

Basic permissions

The role class method allows you to declare permissions for a given role:

class User
  
  role :admin do
    can :view_all_files
    can :view_all_pages
  end
  
  role :paid do
    can :view_all_pages
    can :view_invoice
  end
  
end

gets you:

User.new.null? # => true
User.new.can?(:view_invoice) # => false
User.new.can_view_all_pages? # => false
User.new.can_view_all_files? # => false

User.new(:paid).paid? # => true
User.new(:paid).can?(:view_invoice) # => true
User.new(:paid).can_view_all_pages? # => true
User.new(:paid).can_view_all_files? # => false

User.new(:admin).admin? # => true
User.new(:admin).can?(:view_invoice) # => false
User.new(:admin).can_view_all_pages? # => true
User.new(:admin).can_view_all_files? # => true

Super-users

If you pass role the :superuser option, then objects with that role
will be considered super-users, meaning every permission declared for that
class will be available:

class User
  
  role :super_admin, :superuser => true
  
end

User.new(:super_admin).can_view_all_pages? # => true
User.new(:super_admin).can_view_all_files # => true
User.new(:super_admin).can?(:view_invoice) # => true

Declaring permissions for more than one role

Sometimes you want to add the same permission to multiple roles. To
do this, simply pass multiple role names when calling role, and each
of the roles will be granted the permissions declared in the block.

Alternatively, you can just pass :all to role, and all of your roles
besides the :null role will be granted the permissions declared in
the block.

class User
  role :foo, :bar do
    can :be_both
  end
  
  role :all do
    can :pay_the_billz
  end
end

User.new(:foo).can_be_both? # => true
User.new(:bar).can_be_both? # => true
User.new(:admin).can_be_both? # => false

User.new(:foo).can_pay_the_billz? # => true
User.new(:bar).can_pay_the_billz? # => true
User.new(:admin).can_pay_the_billz? # => true

# The :null role still returns false
User.new(:null).can_pay_the_billz? # => false

Objects with more than one role

If an object’s role returns an Array, then the object will be
granted all of the roles in that Array.

class User
  role :foo do
    can :be_foo
  end
  
  role :bar do
    can :be_bar
  end
end

user = User.new([:foo, :bar])

user.foo? # => true
user.bar? # => true

user.can_be_foo? # => true
user.can_be_bar? # => true

Advanced Permissions

Sometimes a permission is contingent upon some other conditions being
met. You can handle these situations by passing the can call a block.
This block will be called in the context of your object:

class User
  role :thinker do
    can :be_self do |that|
      self == that
    end
  end
end

me  = User.new(:thinker)
you = User.new(:thinker)

me.can_be_self?(me) # => true
me.can_be_self?(you) # => false

Role contexts

If you want to temporarily give an object a role, you can use the with_role
method:

class User
  role :admin do
    can :do_anything
  end
end

user = User.new

user.admin? # => false
user.can_do_anything? # => false

user.with_role(:admin) do
  user.admin? # => true
  user.can_do_anything? # => true
end

user.admin? # => false
user.can_do_anything? # => false

Install

Install roleful like so:

gem install nakajima-roleful —source=http://gems.github.com

View the CI build

nakajima/roleful