Permalink
Browse files

Finished preliminary yard docs

  • Loading branch information...
1 parent b106200 commit 6deb17225217f5b87e592633b9cdd6fb38bfe0ff @airhorns committed Jan 24, 2011
Showing with 55 additions and 22 deletions.
  1. +1 −1 .gitignore
  2. +20 −7 lib/thwart/role.rb
  3. +34 −14 lib/thwart/role_registry.rb
View
@@ -19,8 +19,8 @@ tmtags
## PROJECT::GENERAL
coverage
rdoc
+doc
pkg
.bundle
.yardoc
-
## PROJECT::SPECIFIC
View
@@ -1,5 +1,5 @@
module Thwart
-
+ # Internal module encapsulating the various permissions an actor may play. Fields queries.
module Role
attr_accessor :name, :default_response, :responses
@@ -18,6 +18,11 @@ def parents=(p)
@parents
end
+ # Queries this role to see if it has any rules that govern the actor trying to perform the action on the resource.
+ # @param {Thwart::Actor} actor The actor trying to perform the action on the resource
+ # @param {Thwart::Resource|Class|Symbol} resource The resource to which the actor might act upon
+ # @param {Symbol} action The name of the action being attempted
+ # @return {true|false|nil} Returns a boolean if this role has a rule that applies, or nil if no rules apply. The action can be performed if the query returns true.
def query(actor, resource, action)
@query_result_found = false
resp = nil
@@ -35,7 +40,9 @@ def query(actor, resource, action)
resp
end
-
+
+ # Traverses the rule tree to see if a rule exists governing the class of resources the queried resource belongs to.
+ # @private
def resource_response(resources, name)
# Return the resource scoped response if it exists
if resources.respond_to?(:[]) && resources.respond_to?(:include?)
@@ -48,6 +55,8 @@ def resource_response(resources, name)
nil
end
+ # Traverses the rule tree to see if a rule exists governing the class of action the actor is trying to perform
+ # @private
def action_response(action)
# Return the action level boolean, proc, or nil if it exists is the responses array
response = self.responses[action]
@@ -57,6 +66,8 @@ def action_response(action)
nil
end
+ # Normalizes the name of the resource being queried as might be found in the rule tree
+ # @param {Symbol|Thwart::Resource|Class|Object} resource An object which may be a Thwart::Resource, a string/symbol resource name, or a class/object.
def find_resource_name(resource)
return resource if resource.is_a?(Symbol)
r ||= resource.thwart_name if resource.respond_to?(:thwart_name)
@@ -69,23 +80,25 @@ def find_resource_name(resource)
end
private
-
+
+ # Internal tracking method for tracking if an applicable rule has been discovered.
def found!(response)
@query_result_found = true
response
end
-
+
+ # Internal tracking method for tracking if an applicable rule has been discovered.
def found?
@query_result_found ||= false
@query_result_found == true
end
end
-
+
+ # Internal class adopted by actors as the default response.
class DefaultRole
include Thwart::Role
def query(*args)
return Thwart.default_query_response
end
end
-
-end
+end
@@ -1,18 +1,39 @@
module Thwart
class DuplicateRoleError < StandardError; end
class MissingRoleError < StandardError; end
-
+
+ # Internal class for handling the storage, adoption, and traversal of roles and role trees.
class RoleRegistry
+
+ def initialize(role_creator = nil)
+ self.monitor_builder(role_creator) if !role_creator.nil?
+ self
+ end
+
def roles
@roles ||= []
@roles
end
-
+
+ # Adds a uniquely named role to the registry.
+ # @param {Thwart::Role} role The role to be added. Must have a unique name.
def add(role)
raise DuplicateRoleError, "Role #{role} already exists in the role registry!" if self.has_role?(role)
@roles << role
end
+ # Boolean describing if a role exists in the registry.
+ # @param {Thwart::Role} the role to search for.
+ def has_role?(role)
+ self.roles.include?(role)
+ end
+
+ # Queries the tree of roles to see if any have applicable rules and returns their result if they do.
+ # Optionally logs the query path.
+ # @param {Thwart::Actor} actor The actor trying to perform the action on the resource
+ # @param {Thwart::Resource|Class|Symbol} resource The resource to which the actor might act upon
+ # @param {Symbol} action The name of the action being attempted
+ # @return {true|false} A boolean describing weather or not the actor can preform the action on the resource.
def query(actor, resource, action)
role = self.find_actor_role(actor)
# logging setup
@@ -27,6 +48,7 @@ def query(actor, resource, action)
if role.nil? || !self.has_role?(role)
raise MissingRoleError, "Role #{role} could not be found in the registry!" if Thwart.actor_must_play_role
else
+ # Start DFS
q = [role]
while r = q.shift
resp = r.query(actor, resource, action)
@@ -51,23 +73,19 @@ def query(actor, resource, action)
Thwart.default_query_response # return was not called above, return the default
end
-
- def has_role?(role)
- self.roles.include?(role)
- end
-
+
+ # Method to get the `Thwart::Role` class played by an actor.
+ # @param {Thwart::Actor} actor The actor in question
+ # @return {Thwart::Role} The role class the actor plays.
def find_actor_role(actor)
r = actor.thwart_role if actor.respond_to?(:thwart_role)
r = r.to_sym if r.respond_to?(:to_sym)
r = find_role(r) if r.is_a?(Symbol)
r
end
-
- def initialize(role_creator = nil)
- self.monitor_builder(role_creator) if !role_creator.nil?
- self
- end
-
+
+ # Adds callback hooks to add all built roles to the registry.
+ # @private
def monitor_builder(role_creator)
registry = self
unless role_creator.nil?
@@ -80,8 +98,10 @@ def monitor_builder(role_creator)
@role_creator = role_creator
end
+ # Finds a role based on a name
+ # @private
def find_role(name)
self.roles.find {|a| a.name == name}
end
end
-end
+end

0 comments on commit 6deb172

Please sign in to comment.