In an if_attribute statement, contains says that the value has to be part of the collection specified by the if_attribute attribute. For the block, see if_attribute.

[Source]

     # File lib/reader.rb, line 271
271:       def contains (&block)
272:         [:contains, block]
273:       end

Allows the definition of privileges to be allowed for the current role, either in a has_permission_on block or directly in one call.

  role :admin
    has_permission_on :employees, :to => :read
    has_permission_on :employees do
      to :create
      if_attribute ...
    end
    has_permission_on :employees, :to => :delete do
      if_attribute ...
    end
  end

The block form allows to describe restrictions on the permissions using if_attribute. Multiple has_permission_on statements are OR‘ed when evaluating the permissions. Also, multiple if_attribute statements in one block are OR‘ed.

Available options

:to

A symbol or an array of symbols representing the privileges that should be granted in this statement.

[Source]

     # File lib/reader.rb, line 200
200:       def has_permission_on (context, options = {}, &block)
201:         raise DSLError, "has_permission_on only allowed in role blocks" if @current_role.nil?
202:         options = {:to => []}.merge(options)
203:         
204:         privs = options[:to] 
205:         privs = [privs] unless privs.is_a?(Array)
206:         raise DSLError, "has_permission_on either needs a block or :to option" if !block_given? and privs.empty?
207:         
208:         rule = AuthorizationRule.new(@current_role, privs, context)
209:         @auth_rules << rule
210:         if block_given?
211:           @current_rule = rule
212:           yield
213:           # TODO ensure?
214:           @current_rule = nil
215:         end
216:       end

In a has_permission_on block, if_attribute specifies conditions of dynamic parameters that have to be met for the user to meet the privileges in this block. Conditions are evaluated on the context object. Thus, the following allows CRUD for branch admins only on employees that belong to the same branch as the current user.

  role :branch_admin
    has_permission_on :employees do
      to :create, :read, :update, :delete
      if_attribute :branch => is { user.branch }
    end
  end

In this case, is is the operator for evaluating the condition. Another operator is contains for collections. In the block supplied to the operator, user specifies the current user for whom the condition is evaluated.

Conditions may be nested:

  role :company_admin
    has_permission_on :employees do
      to :create, :read, :update, :delete
      if_attribute :branch => { :company => is {user.branch.company} }
    end
  end

Multiple if_attribute statements are OR‘ed.

[Source]

     # File lib/reader.rb, line 256
256:       def if_attribute (attr_conditions_hash)
257:         raise DSLError, "if_attribute only in has_permission blocks" if @current_rule.nil?
258:         parse_attribute_conditions_hash!(attr_conditions_hash)
259:         @current_rule.append_attribute Attribute.new(attr_conditions_hash)
260:       end

Roles may inherit all the rights from subroles. The given roles become subroles of the current block‘s role.

  role :admin do
    includes :user
    has_permission_on :employees, :to => [:update, :create]
  end
  role :user do
    has_permission_on :employees, :to => :read
  end

[Source]

     # File lib/reader.rb, line 172
172:       def includes (*roles)
173:         raise DSLError, "includes only in role blocks" if @current_role.nil?
174:         @role_hierarchy[@current_role] ||= []
175:         @role_hierarchy[@current_role] += roles.flatten
176:       end

In an if_attribute statement, is says that the value has to be exactly met by the if_attribute attribute. For the block, see if_attribute.

[Source]

     # File lib/reader.rb, line 264
264:       def is (&block)
265:         [:is, block]
266:       end

Defines the authorization rules for the given role in the following block.

  role :admin do
    has_permissions_on ...
  end

[Source]

     # File lib/reader.rb, line 154
154:       def role (role, &block)
155:         append_role role
156:         @current_role = role
157:         yield
158:       ensure
159:         @current_role = nil
160:       end

Used in a has_permission_on block, to may be used to specify privileges to be assigned to the current role under the conditions specified in the current block.

  role :admin
    has_permission_on :employees do
      to :create, :read, :update, :delete
    end
  end

[Source]

     # File lib/reader.rb, line 226
226:       def to (*privs)
227:         raise DSLError, "to only allowed in has_permission_on blocks" if @current_rule.nil?
228:         @current_rule.append_privileges(privs)
229:       end