cando 0.2.0 → 0.2.1

data/README.md

@@ -68,6 +68,54 @@ to use those edit (or create) the `Rakefile` and include
      rake cando:users    # List users and their roles
 
 ### Using CanDo in your project's code
+
+#### Api
+Please see [the api documentation](http://rubydoc.info/gems/cando/CanDo) up to date documentation.
+
+ connect to db (usually called within init block):
+
+    CanDo.connect "mysql://user:passwd@host:port/database"
+
+ create a role; capabilities will be created if they don't exist yet:
+
+    define_role("role_name", ["capability1","capability2", "capability3", ...])
+
+ assign role(s) to a user: if no user with that id exist, a new one will
+ be created; if a role does not exist, an exception is raised. You can pass
+ in a role object or just role names; pass in empty array to remove all roles:
+
+    role3 = CanDo::Role.first
+    assign_roles("user1", ["role1", "role2", role3])
+
+ get user's capabilities; returns an array of strings:
+
+    capabilities("user1")
+
+ get user's roles; returns an array of strings:
+
+    roles("user1")
+
+ set default handler if `can("u","c"){ ... }` fails (usually called within init block):
+
+    CanDo.cannot_block { |user_urn, capability| raise "#{user_urn} is missing #{capability}" }
+
+ guard block by `can` function; will execute `cannot_block` if user is missing
+ this capability (see example below):
+
+    can("user1", :capability1) do
+      puts "woohoo"
+    end
+
+ use `can` function as an expression -- `cannot_block` will not be executed if
+ expressions resolves to `false`:
+
+    if can("user1", :capability1)
+       puts "woohoo"
+    else
+       puts ":("
+    end
+
+#### Usage example
 Using the CanDo in your code (working code with an empty database):
 
     require 'cando'

data/Rakefile

@@ -51,6 +51,7 @@ Rake::RDocTask.new do |rdoc|
 
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "cando #{version}"
+  rdoc.rdoc_files.include('lib')
   rdoc.rdoc_files.include('README*')
   rdoc.rdoc_files.include('lib/**/*.rb')
   rdoc.rdoc_files.include('contrib/**/*.rb')

data/VERSION

@@ -1 +1 @@
-0.2.0
+0.2.1

data/cando.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = "cando"
-  s.version = "0.2.0"
+  s.version = "0.2.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Daniel Bornkessel"]
-  s.date = "2014-05-21"
+  s.date = "2014-05-27"
   s.description = "CanDo is a small gem to implement a simple user access system based on users, roles & capabilites, where:\n\n    each user can have 0, 1 or many roles\n    each role can have 0, 1 or many capabilites\n\nUsers have capabilities by getting roles assigned (role == collection of capabilities). Within the code, the can helper method can be used to test whether a user has a certain capability or not (see below for a working code example)."
   s.email = "daniel@soundcloud.com"
   s.extra_rdoc_files = [

data/lib/cando.rb

@@ -6,15 +6,41 @@ if File.basename($0) == "rake"    # we are in a rake call: export our rake stuff
 end
 
 module CanDo
+  # The provided cannot_block is not as expected
   class ConfigCannotBlockError < RuntimeError; end
-  class ConfigMysqlDBError < RuntimeError; end
-  class ConfigMysqlConnectionError < RuntimeError; end
+
+  # CanDo.connect received an invalid or unsupported connection string
+  class ConfigDBError < RuntimeError; end
+
+  # Error while trying to connect to the database
+  class ConfigConnectionError < RuntimeError; end
+
+  # CanDo is not connected to a database but connection is needed
   class DBNotConnected < RuntimeError; end
 
+  # Return current database connection
+  #
+  # raises DBNotConnected exception if CanDo is not connected to a db
   def self.db
     @db or raise DBNotConnected.new("CanDo is not connected to a database")
   end
 
+  # Initializes CanDo
+  #
+  # This method should be called during boot up to configure CanDo with the db
+  # connection and the cannot_block:
+  #
+  #    CanDo.init do
+  #      # this will be executed if the user does not have the
+  #      # asked-for capability (only applies if 'can' is passed a block)
+  #      cannot_block do |user_urn, capability|
+  #        raise "#{user_urn} can not #{capability} .. user capabilities are: #{capabilities(user_urn)}"
+  #      end
+  #
+  #      connect "mysql://cando_user:cando_passwd@host:port/database"
+  #    end
+  #
+  # ...
   def self.init(&block)
     CanDo.instance_eval &block
 
@@ -32,8 +58,11 @@ module CanDo
   end
 
 
-  # will be executed if `can(user_urn, :capability) { }` will not be executed
-  # due to missing capabilities
+  # Block to be executed if <tt>can("user", :cap) { }</tt> will not be executed due to missing capability
+  #
+  # - the block needs to accept two arguments <tt>|user_urn, capability|</tt>
+  # - this function should be called in the init method (see there for an example).
+  # - if this block gets executed, it'll have the context of the <tt>can(...){ }</tt> call
   def self.cannot_block(&block)
     if !block
       raise ConfigCannotBlockError.new("CanDo#cannot_block expects block")
@@ -45,9 +74,16 @@ module CanDo
     @@cannot_block_proc = block
   end
 
+  # Connect to database
+  #
+  # Pass in a connection string of the form
+  #
+  #     mysql://user:passwd@host:port/database
+  #
+  # Raises CanDo::ConfigConnectionError or CanDo::ConfigDBError when problems occur
   def self.connect(connection)
     if connection =~ /sqlite/
-      raise ConfigMysqlDBError.new("sqlite is not supported as it misses certain constraints")
+      raise ConfigDBError.new("sqlite is not supported as it misses certain constraints")
     end
 
     begin
@@ -55,7 +91,7 @@ module CanDo
       @db.test_connection
       @db
     rescue => e
-      raise ConfigMysqlConnectionError.new(<<-EOF
+      raise ConfigConnectionError.new(<<-EOF
 Error connecting to database. Be sure to pass in a databse config like 'mysql://user:passwd@host/database':
 #{e.message}
 EOF
@@ -63,6 +99,26 @@ EOF
     end
   end
 
+  # Method to check whether a user has a certain capability
+  #
+  # It can be used in two manners:
+  #
+  # * pass it a block which is only executed if the user has the capability:
+  #
+  #     can("user_urn", :capability) do
+  #       puts "woohoo"
+  #     end
+  #
+  # this will execute cannot_block if user is missing this capability.
+  #
+  # * use as an expression that return true or false/nil
+  #
+  #    if can("user_urn", :capability) do
+  #       puts "woohoo"
+  #    else
+  #       puts "epic fail"
+  #    end
+  #
   def can(user_urn, capability)
     user = CanDo::User.find(:id => user_urn)
     has_permission = user && user.can(capability)
@@ -78,14 +134,28 @@ EOF
     has_permission
   end
 
+  # Define or redefine a role
+  #
+  # Capabilities will be created if they don't exist yet
   def define_role(role, capabilities)
     CanDo::Role.define_role(role, capabilities)
   end
 
+  # Assign role(s) to a user
+  #
+  #     assign_roles("user_urn", ["role_name", role_object])
+  #
+  # - if no user with that id exist, a new one will be created
+  # - if a role does not exist, an CanDo::Role::UndefinedRole is raised
+  # - you can pass in a role object or just role names (see example above)
+  # - pass in an empty array to remove all roles from user
   def assign_roles(user, roles)
     CanDo::User.find_or_create(:id => user).assign_roles(roles)
   end
 
+  # Get user's roles
+  #
+  # returns an array of strings
   def roles(user)
     user = CanDo::User.first(:id => user)
     return [] unless user
@@ -93,6 +163,9 @@ EOF
     user.roles.map(&:id)
   end
 
+  # Get user's capabilities
+  #
+  # returns an array of strings
   def capabilities(user)
     user = CanDo::User.first(:id => user)
     return [] unless user

data/lib/models/role.rb

@@ -1,5 +1,8 @@
 module CanDo
   class Role < Sequel::Model(:cando_roles)
+    # This role does not exist
+    class UndefinedRole < Exception; end
+
     many_to_many :users, :join_table => :cando_roles_users
     many_to_many :capabilities, :join_table => :cando_capabilities_roles
     unrestrict_primary_key

data/lib/models/user.rb

@@ -1,6 +1,6 @@
 module CanDo
-  class UndefinedRole < Exception; end
   class User < Sequel::Model(:cando_users)
+
     many_to_many :roles, :join_table => :cando_roles_users
     unrestrict_primary_key
 
@@ -22,7 +22,7 @@ module CanDo
           rescue Sequel::UniqueConstraintViolation => e
             puts "user already has role '#{r}'"
           rescue Sequel::NoMatchingRow
-            raise UndefinedRole.new("Role '#{r}' does not exist")
+            raise Role::UndefinedRole.new("Role '#{r}' does not exist")
           end
         end
       end

data/spec/cando_spec.rb

@@ -1,11 +1,5 @@
 require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
 
-#describe "Cando" do
-#  it "fails" do
-#    fail "hey buddy, you should probably rename this file and start specing for real"
-#  end
-#end
-#
 describe "CanDo module methods" do
   context "CanDo.cannot_block expects block accepting two parameters" do
     it { expect{ CanDo.cannot_block }.to              raise_error(CanDo::ConfigCannotBlockError) }
@@ -39,8 +33,8 @@ describe "CanDo module methods" do
   end
 
   context "CanDo.connect" do
-    it { expect{ CanDo.connect(nil) }.to raise_error(CanDo::ConfigMysqlConnectionError) }
-    it { expect{ CanDo.connect("sqlite::memory:") }.to raise_error(CanDo::ConfigMysqlDBError) }
+    it { expect{ CanDo.connect(nil) }.to raise_error(CanDo::ConfigConnectionError) }
+    it { expect{ CanDo.connect("sqlite::memory:") }.to raise_error(CanDo::ConfigDBError) }
     it { CanDo.connect(ENV['CANDO_TEST_DB']).test_connection be_true }
   end
 
@@ -90,8 +84,8 @@ describe "CanDo module methods" do
       end
 
       context "invalid roles" do
-        it { expect{ assign_roles("user", ["non-existant-role"]) }.to raise_error(CanDo::UndefinedRole) }
-        it { expect{ assign_roles("user", [nil]) }.to raise_error(CanDo::UndefinedRole) }
+        it { expect{ assign_roles("user", ["non-existant-role"]) }.to raise_error(CanDo::Role::UndefinedRole) }
+        it { expect{ assign_roles("user", [nil]) }.to raise_error(CanDo::Role::UndefinedRole) }
       end
 
       context "standard situation" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cando
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-05-21 00:00:00.000000000 Z
+date: 2014-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: sequel
@@ -169,7 +169,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: 1474018739418741316
+      hash: -614063614560370007
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: