i_am_i_can 4.0.0 → 4.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: bd4d579c7635be07c436c9d2f76913fdbaf14638
-  data.tar.gz: 4028733df55abde29ef7a4365e538211bf6192cb
+  metadata.gz: f5c54e75b43df8cbfb0e8acd30cb0fc40e0aeda0
+  data.tar.gz: 5a0a6c5198cdb76ca0a251b99d7320cc2a081854
 SHA512:
-  metadata.gz: 187dad10491e715a62224579b03906d75ae8716e399d4bc73f006eb3a1bf672693120f14b2d9221daab958a6c6aebdb05ec19dbc738a68f8ebafd1ef31ba6bd7
-  data.tar.gz: 8ad7aff9edb8342d472e08dfaf86e2dc63c26f2b5a90efcf491d637c69f9a60248cc1d730385a0c46a1aff1757cf709ee927ae4a252e8fcabc6a3ec795faac53
+  metadata.gz: 00ed26e8fe4e750241e92eda7d5acb084bc3a733f654af380e61f052c8723c62e5f8b82ef9e1907466caf02a8f7a2cc6c2d30fd44a20848b60965e53333e65f1
+  data.tar.gz: f6d4a8bbab40bfe9017f38a0f7acc63aa5784743e279a15c4b26611bab9ee8f39d1c58e572de1f48b9acfc36d464454869be057354329dad5119bc14d5bde1a3

data/README.md

@@ -58,8 +58,9 @@ Resource.that_allow(user, to: :manage) # => ActiveRecord_Relation[]
     - [About role group](#about-role-group)
     - [Three steps to use this gem](#three-steps-to-use-this-gem)
     - [Two Concepts of this gem](#two-concepts-of-this-gem)
+    - [How it work?](#how-it-work)
 
-2. [Installation And Setup](#installation-and-setup)
+2. [Installation and Setup](#installation-and-setup)
 
 3. [Usage](#usage)
     - [Config Options](#config-options)
@@ -133,9 +134,20 @@ Resource.that_allow(user, to: :manage) # => ActiveRecord_Relation[]
 1. Stored (save in database) TODO
 2. Temporary (save in instance variable) TODO
 
+### How it work?
+
+Very simple. Really simple. Sooooo Simple.
+
+1. To define something, you actually `create` records.
+    [see here](https://github.com/zhandao/i_am_i_can/blob/master/lib/i_am_i_can/helpers/dynamic.rb#L92)
+2. To assign something, you actually call one of the activerecord association methods.
+    [see here](https://github.com/zhandao/i_am_i_can/blob/master/lib/i_am_i_can/helpers/dynamic.rb#L67)
+2. To query  something, you actually call the querying interfaces of activerecord.
+    [see here](https://github.com/zhandao/i_am_i_can/tree/master/lib/i_am_i_can/subject)
+
 [Feature List: needs you](https://github.com/zhandao/i_am_i_can/issues/2)
 
-## Installation And Setup
+## Installation and Setup
 
 1. Add this line to your application's Gemfile and then `bundle`:
 
@@ -251,7 +263,13 @@ UserRoleGroup.which(name: :vip).members.names # => %i[vip1 vip2 vip3]
         3. `is_not_a` / `has_not_role` / `has_not_roles`
         4. `will_not_be`
     2. `is_not_a_temporary`
-4. helpers:
+4. replacement assignment by calling: `is_only_a`, alias `currently_is`.
+    (makes the role collection contain only the supplied roles, by adding and deleting as appropriate)
+5. callbacks - before / after / around:
+    1. `role_assign`: assignment
+    2. `cancel_role_assign`: cancel assignment
+    3. `role_update`: 
+6. helpers:
     1. relation with stored role, defaults to `stored_roles`.
     2. `temporary_roles` and `valid_temporary_roles`
     3. `roles`
@@ -287,6 +305,12 @@ is_not_a_temporary *roles
 he.falls_from :admin         # => 'Role Assignment Done' or error message
 he.is_not_a_temporary :coder # => 'Role Assignment Done' or error message
 he.roles # => []
+
+# === Replacement Assignment ===
+# method signature
+is_only_a *roles
+# examples
+he.is_only_a :role1, :role2
 ```
 
 #### D. [Role / Group Querying](https://github.com/zhandao/i_am_i_can/blob/master/lib/i_am_i_can/subject/role_querying.rb)
@@ -347,6 +371,12 @@ UserPermission.count # => 1 + 2
 1. caller: role / role group instance, like `UserRole.which(name: :admin)`
 2. assignment by calling `can`. alias `has_permission`
 3. cancel assignment by calling `cannot`. alias `is_not_allowed_to`
+4. replacement assignment by calling: `can_only`,.
+    (makes the permission collection contain only the supplied permissions, by adding and deleting as appropriate)
+5. callbacks - before / after / around:
+    1. `permission_assign`: assignment
+    2. `cancel_permission_assign`: cancel assignment
+    3. `permission_update`: replacement assignment
 4. helpers:
     1. relation with stored permission, defaults to `permissions`.
 
@@ -359,11 +389,23 @@ UserRole.have_permission :fly
 
 # === Assignment ===
 # method signature
-can *actions, resource: nil, obj: resource,
+can *actions, resource: nil, obj: resource, # you can use `resource` or `obj` 
     _d: config.auto_definition, auto_definition: _d
 # examples
 role.can :fly # => 'Permission Assignment Done' or error message
 role.permissions # => [<#UserPermission id: ..>]
+
+# === Cancel Assignment ===
+# method signature
+cannot *actions, resource: nil, obj: resource
+# examples
+role.cannot :fly
+
+# === Replacement Assignment ===
+# method signature
+can_only *actions, resource: nil, obj: resource
+# examples
+role.can_only :run
 ```
 
 #### G. [Permission Querying](https://github.com/zhandao/i_am_i_can/blob/master/lib/i_am_i_can/subject/role_querying.rb)
@@ -397,8 +439,8 @@ he.can?    :perform, obj: :magic
 he.cannot? :perform, :magic
 he.can!    :perform, :magic
 
-he.can_each?   %i[fly jump] # return false if he can not `fly` or `jump`
-he.can_one_of! %i[fly jump] # return true if he can `fly` or `jump`
+he.can_each?   %i[ fly jump ] # return false if he can not `fly` or `jump`
+he.can_one_of! %i[ fly jump ] # return true if he can `fly` or `jump`
 ```
 
 #### H. Shortcut Combinations - which_can

data/lib/generators/i_am_i_can/templates/models/permission.erb

@@ -5,7 +5,7 @@ class <%= permission_c %> < ActiveRecord::Base
   has_and_belongs_to_many :related_role_groups,
                           join_table: '<%= group_pms_tb %>', foreign_key: :<%= group_u %>_id, class_name: '<%= group_c %>', association_foreign_key: :<%= permission_u %>_id
 <% end %>
-  belongs_to :obj, polymorphic: true
+  belongs_to :resource, polymorphic: true
 
   acts_as_permission
 end

data/lib/generators/i_am_i_can/templates/models/role.erb

@@ -2,17 +2,15 @@ class <%= role_c %> < ActiveRecord::Base
   has_and_belongs_to_many :related_users,
                           join_table: '<%= subj_role_tb %>', foreign_key: :<%= name_u %>_id, class_name: '<%= name_c %>', association_foreign_key: :<%= role_u %>_id
 <% unless @ii_opts[:without_group] %>
-  has_and_belongs_to_many :related_stored_groups,
+  has_and_belongs_to_many :related_groups,
                           join_table: '<%= group_role_tb %>', foreign_key: :<%= group_u %>_id, class_name: '<%= group_c %>', association_foreign_key: :<%= role_u %>_id
 <% end %>
   has_and_belongs_to_many :permissions,
                           join_table: '<%= role_pms_tb %>', foreign_key: :<%= permission_u %>_id, class_name: '<%= permission_c %>', association_foreign_key: :<%= role_u %>_id
 
-  has_many_temporary_permissions
-
   acts_as_role
 
-  # default_scope { with_stored_permissions }
+  # default_scope { with_permissions }
 end
 
 __END__

data/lib/generators/i_am_i_can/templates/models/role_group.erb

@@ -5,11 +5,11 @@ class RoleGroup < ActiveRecord::Base
   has_and_belongs_to_many :members,
                           join_table: '<%= group_role_tb %>', foreign_key: :<%= role_u %>_id, class_name: '<%= role_c %>', association_foreign_key: :<%= group_u %>_id
 
-  has_many_temporary_permissions
-
   acts_as_role_group
 
-  # default_scope { with_members.with_stored_permissions) }
+  # default_scope { with_members) }
+
+  # default_scope { with_permissions) }
 end
 
 __END__

data/lib/i_am_i_can/helpers/dynamic.rb

@@ -53,23 +53,21 @@ module IAmICan
       # You call the proc below by given contents [:role], then:
       #
       proc { |contents| contents.each do |content|
-        content_cls = i_am_i_can.send("#{content}_class")
+        content_cls = i_am_i_can.send("#{content}_class") rescue next
         _plural = '_' + content.to_s.pluralize
+        __plural = send("_#{_plural}")
 
         # _stored_roles_exec
         #   Add / Remove (by passing action :cancel) roles to a user instance
-        define_method "_#{_reflect_of(content)}_exec" do |action = :assignment, instances = [ ], **conditions|
-          collection = send(_plural)
-          if conditions.present? && action == :assignment
-            # Role.where(name: [...]).where.not(id: roles.ids)
-            query_result = content_cls.constantize.where(conditions).where.not(id: collection.ids)
-          elsif conditions.present? && action == :cancel
-            # Role.where(id: roles.ids, name: [...])
-            query_result = content_cls.constantize.where(id: collection.ids, **conditions)
-          end
+        define_method "_#{_reflect_of(content)}_exec" do |action = :assign, instances = [ ], **conditions|
+          collection, objects = send(_plural), [ ]
+          records = conditions.present? ? content_cls.constantize.where(conditions) : [ ]
 
-          objects = [*(query_result || [ ]), *(instances - collection)].uniq
-          action == :assignment ? collection << objects : collection.destroy(objects)
+          case action
+          when :assign  then collection << objects = (records + instances).uniq - collection
+          when :cancel  then collection.destroy objects = (records + instances).uniq & collection
+          when :replace then send("#{__plural}=", objects = (records + instances).uniq) # collection=
+          end
           objects
         end
         #
@@ -86,7 +84,7 @@ module IAmICan
       # You call the proc below by given contents [:role], then:
       #
       proc { |contents| contents.each do |content|
-        content_cls = i_am_i_can.send("#{content}_class")
+        content_cls = i_am_i_can.send("#{content}_class") rescue next
         _plural = '_' + content.to_s.pluralize
 
         # _create_roles

data/lib/i_am_i_can/permission/assignment.rb

@@ -1,22 +1,31 @@
 module IAmICan
   module Permission
     module Assignment
-      def can *actions,
-              resource: nil, obj: resource,
+      def can *actions, resource: nil, obj: resource,
               _d: i_am_i_can.auto_definition, auto_definition: _d
         self.class.have_permissions *actions, obj: obj if auto_definition
-        _permissions_assignment(actions, obj)
+        run_callbacks(:permission_assign) do
+          _permissions_assignment(actions, obj)
+        end
       end
 
       alias has_permission can
 
-      def cannot *actions, obj: nil
-        _permissions_assignment(:cancel, actions, obj)
+      def cannot *actions, resource: nil, obj: resource
+        run_callbacks(:cancel_permission_assign) do
+          _permissions_assignment(:cancel, actions, obj)
+        end
       end
 
       alias is_not_allowed_to cannot
 
-      def _permissions_assignment(action = :assignment, actions, obj)
+      def can_only *actions, resource: nil, obj: resource
+        run_callbacks(:permission_update) do
+          _permissions_assignment(:replace, actions, obj)
+        end
+      end
+
+      def _permissions_assignment(action = :assign, actions, obj)
         permissions = actions.product(Array[obj]).map { |(p, o)| { action: p, **deconstruct_obj(o) } }
         assignment = _stored_permissions_exec(action,
                                               permissions.reduce({ }) { |a, b| a.merge(b) { |_, x, y| [x, y] } })

data/lib/i_am_i_can/role/assignment.rb

@@ -6,26 +6,36 @@ module IAmICan
                     auto_definition: _d || which_can.present?,
                     save: true
         self.class.have_roles *roles, which_can: which_can, obj: obj if auto_definition
-        _roles_assignment(roles, save)
+        run_callbacks(:role_assign) do
+          _roles_assignment(roles, save)
+        end
       end
 
-      %i[ is is_a is_a_role is_roles has_role has_roles role_is role_are ].each { |aname| alias_method aname, :becomes_a }
-
       def is_a_temporary *roles, **options
         becomes_a *roles, save: false, **options
       end
 
       def falls_from *roles, saved: true
-        _roles_assignment(:cancel, roles, saved)
+        run_callbacks(:cancel_role_assign) do
+          _roles_assignment(:cancel, roles, saved)
+        end
       end
 
-      %i[ is_not_a will_not_be removes_role leaves has_not_role has_not_roles ].each { |aname| alias_method aname, :falls_from }
-
       def is_not_a_temporary *roles
         falls_from *roles, saved: false
       end
 
-      def _roles_assignment(action = :assignment, roles, save)
+      def is_only_a *roles
+        run_callbacks(:role_update) do
+          _roles_assignment(:replace, roles, true)
+        end
+      end
+
+      %i[ is is_a is_a_role is_roles has_role has_roles role_is role_are ].each { |aname| alias_method aname, :becomes_a }
+      %i[ is_not_a will_not_be removes_role leaves has_not_role has_not_roles ].each { |aname| alias_method aname, :falls_from }
+      %i[ currently_is_a ].each { |aname| alias_method aname, :is_only_a }
+
+      def _roles_assignment(action = :assign, roles, save)
         instances, names = Role.extract(roles, i_am_i_can)
         if save
           assignment = _stored_roles_exec(action, instances, name: names)

data/lib/i_am_i_can/role/grouping.rb

@@ -0,0 +1,6 @@
+module IAmICan
+  module Role
+    module Grouping
+    end
+  end
+end

data/lib/i_am_i_can/role.rb

@@ -1,7 +1,7 @@
 require 'i_am_i_can/role/definition'
 require 'i_am_i_can/role/assignment'
+require 'i_am_i_can/role/grouping'
 require 'i_am_i_can/role_group/definition'
-require 'i_am_i_can/role_group/assignment'
 
 module IAmICan
   module Role
@@ -18,9 +18,7 @@ module IAmICan
     end
 
     included do
-      # def attributes
-      #   super.symbolize_keys
-      # end
+      define_model_callbacks :permission_assign, :cancel_permission_assign, :permission_update
 
       # `can? :manage, User` / `can? :manage, obj: User`
       def can? action, o = nil, obj: o

data/lib/i_am_i_can/role_group/definition.rb

@@ -4,7 +4,7 @@ module IAmICan
       def group_roles *members, by_name:, which_can: [ ], obj: nil
         group = (i = i_am_i_can).role_group_model.where(name: by_name).first_or_create
         instances, names = Role.extract(members, i)
-        assignment = group._members_exec(:assignment, instances, name: names)
+        assignment = group._members_exec(:assign, instances, name: names)
         ResultOf.members assignment, i, given: [instances, names]
       end
 

data/lib/i_am_i_can/subject.rb

@@ -9,6 +9,7 @@ module IAmICan
     end
 
     included do
+      define_model_callbacks :role_assign, :cancel_role_assign, :role_update
     end
   end
 end

data/lib/i_am_i_can/support/association_class_methods.rb

@@ -35,8 +35,8 @@ module IAmICan
         end
       end
 
-      define_method :_temporary_roles_exec do |action = :assignment, names|
-        send('_temporary_roles_' + (action == :assignment ? 'add' : 'rmv'), names)
+      define_method :_temporary_roles_exec do |action = :assign, names|
+        send('_temporary_roles_' + (action == :assign ? 'add' : 'rmv'), names)
       end
     end
   end

data/lib/i_am_i_can/support/reflection.rb

@@ -4,7 +4,7 @@ module IAmICan
 
     class_methods do
       def _reflect_of(key)
-        _name = i_am_i_can.send("#{key}_class")
+        _name = i_am_i_can&.send("#{key}_class")
         reflections.each do |name, reflection|
           return name if reflection.class_name == _name
         end; nil

data/lib/i_am_i_can/version.rb

@@ -1,3 +1,3 @@
 module IAmICan
-  VERSION = '4.0.0'
+  VERSION = '4.1.0'
 end

data/lib/i_am_i_can.rb

@@ -15,7 +15,7 @@ require 'i_am_i_can/resource'
 
 module IAmICan
   def acts_as_subject
-    i_am_i_can.act = :subject
+    i_am_i_can&.act = :subject
     include Subject
 
     extend  Role::Definition
@@ -32,7 +32,7 @@ module IAmICan
   end
 
   def acts_as_role
-    i_am_i_can.act = :role
+    i_am_i_can&.act = :role
     include Role
 
     extend  Permission::Definition
@@ -49,10 +49,11 @@ module IAmICan
   end
 
   def acts_as_role_group
-    i_am_i_can.act = :role_group
+    i_am_i_can&.act = :role_group
     include Role
     # include RoleGroup
 
+    include Role::Grouping
     extend  Permission::Definition
     include Permission::Assignment
 
@@ -67,7 +68,7 @@ module IAmICan
   end
 
   def acts_as_permission
-    i_am_i_can.act = :permission
+    i_am_i_can&.act = :permission
     include Permission
 
     include Reflection

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: i_am_i_can
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.1.0
 platform: ruby
 authors:
 - zhandao
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-11-30 00:00:00.000000000 Z
+date: 2018-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -204,7 +204,7 @@ files:
 - lib/i_am_i_can/role.rb
 - lib/i_am_i_can/role/assignment.rb
 - lib/i_am_i_can/role/definition.rb
-- lib/i_am_i_can/role_group/assignment.rb
+- lib/i_am_i_can/role/grouping.rb
 - lib/i_am_i_can/role_group/definition.rb
 - lib/i_am_i_can/subject.rb
 - lib/i_am_i_can/subject/permission_querying.rb

data/lib/i_am_i_can/role_group/assignment.rb

@@ -1,6 +0,0 @@
-module IAmICan
-  module RoleGroup
-    module Assignment
-    end
-  end
-end