skimming 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d38d35c798f029c2f8331d2ff3f890ede872607567b65e2d4ae43dcbdc28d034
-  data.tar.gz: 6447c4b4c3d103c5b3458852d87216444a8bc9c985b1851ae45727678c375e38
+  metadata.gz: 5c31cbb40931809f9bed74b5d90a9c30058734f50a8818d2694e16630a70c493
+  data.tar.gz: 272a1af1759927b87add863af0112d8c1ac92ca7353eb040892c58afbfefb4b3
 SHA512:
-  metadata.gz: 715fdc5fa8d1cb0519ac9e7b6696e102f3f245ba57bf6d7d8e08e89025e0ec060691bdfdac941de84422df17cd643032e745a91c8ffec7dc83a329de212a6380
-  data.tar.gz: 1e6e3d3a21855d2917790f56c50bd82579ec798f1392288febea4cf94bfbf704536e9ad2c0577f498bb0a24a88e3cb8afe6f9837f7510d67e5dd809dff1d2d41
+  metadata.gz: 28cea3d3f6ae71f06598ddb1e35bbd6aff2a559199460af4893b9484a63ed67a59ffc24a247629a0c99a83e676f24f7cd3eab58847a61ec74c022f09140517ea
+  data.tar.gz: 71cd69780026514df89d0193a2060196d06def6f0710f253c378f96ae4c2dcf154c2f133b33b669cc2e0165bb8ccd019c612fb2083b5a9ee4ecfe75a0c7ebff1

data/README.md

@@ -0,0 +1,73 @@
+# Skimming
+Skimming is a gem for rails application that allows to filter a collection based on certain database-configurable rules. Every model can have its own rules towards every other model.
+For example you can apply the feature to your Role model, so that every Role has individual filter rules for an association. It's useful expecially when you have to respond to an api call with a collection of records and you need it to be filtered differently based on which roles the authenticated user has.
+
+## Installation
+Inside your Gemfile put
+
+    gem 'skimming'
+
+and then run
+
+    bundle install
+
+In each model you want to have the feature, just put the following.
+
+    include Skimming::Model
+
+Create `config/skimming.yml` file in your project and compile it as follows for each of the models you included the code above into (let's say for instance you included Skimming::Model into Role model).
+
+    associations:
+      roles:
+        class_name: 'Role'
+
+Once this config file is created, you can launch the following command.
+
+    rails g skimming_migration
+
+The command above will generate a migration file in your project. Now you can migrate.
+
+    rails db:migrate
+
+### Use skimming filters of another model
+
+If you want, you can also allow a related model (for example User) to use Role's skimming rules. In that case the User model should have this instead.
+
+    include Skimming::ParasiteModel
+
+And the config file should have one more configuration.
+
+    associations:
+      roles:
+        class_name: 'Role'
+    options:
+      user:
+        skim_through:
+          - 'roles'
+
+## Usage
+
+Create one `Skimming::CollectionFilter` for each class your model needs to skim and assign a rule that has to be satisfied.
+
+    role.create_collection_filter(object_name: 'order', rule: '@order.complete?')
+    role.create_collection_filter(object_name: 'pet', rule: '@pet.nice?')
+    role.create_collection_filter(object_name: 'room', rule: '@room.clean?')
+
+You could also assign the same `Skimming::CollectionFilter` to multiple roles since they have a HABTM relation.
+
+If now you call `role.skim rooms_collection` only clean rooms will be returned.
+
+Also user can do that if it has the role assigned. By default the parasite model skims through all its associated models that have included `Skimming::Model` and sums all results, rejecting the records that all of the skimming models have rejected (if any of the skimming models have the record present in the filter, it will be present in the parasite model skimming result). However in some cases you may want to make the parasite model to skim only through one or some of these models. To do so, just pass one of the models or an array of those.
+
+    user.skim rooms_collection, through: :roles
+    user.skim rooms_collection, through: [:roles, :whatever]
+
+### Rules
+
+You can store in filters rules whatever conditions you like in plain ruby and the string will be evaulated. Inside the rules, object have to be called as instance variables. These instance variables indeed need to be present and can be declared in a few ways.
+
+1. The model name of the instance you called `skim` from, like the user, will be defined automatically based on model name, so if you call `user.skim rooms_collection` you will have `@user` variable defined.
+2. Based on the skimmed collection, instance variables are defined. In the case above, `@room` variable will be present for each of the rooms to be evaluated in. The collection name is calculated based on the class of the first object in the collection and will raise an error if is not the same for all collection elements. You can override this calculation specifying the `object_name` of the collection (the skimming will look for collection_filters with that `object_name`)
+3. You can pass as third argument an hash of objects like this `user.skim rooms_collection, time: Time.zone.now, whatever: @you_want` and you will have `@time` and `@whatever` variables defined for rule evaluation.
+
+WARNING: since the strings get evaluated, i recommend not to allow anyone except project developers to create collection_filters, in order to prevent malicious code from being executed.

data/lib/skimming/skimmer.rb

@@ -17,7 +17,7 @@ module Skimming
       return collection if filters_rules.empty?
 
       skimming_result = collection.select do |collection_object|
-        instance_variable_set("@#{collection_object.class.name.downcase}", collection_object)
+        instance_variable_set("@#{collection_name}", collection_object)
 
         filters_rules.all? { |rule| eval rule }
       end
@@ -29,6 +29,7 @@ module Skimming
       set_instance_variables
 
       skimming_associations = Skimming.configuration.options[subject.class.name.underscore][:skim_through] if skimming_associations.blank?
+      skimming_associations = [skimming_associations] unless skimming_associations.respond_to? :each
       skimming_result = []
 
       skimming_associations.each do |association_name|

data/skimming.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |s|
   s.name        = 'skimming'
-  s.version     = '0.0.1'
+  s.version     = '0.0.2'
   s.date        = '2020-04-18'
   s.summary     = "Collections skimming"
   s.description = "Filter your collections with database-configurable rules"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: skimming
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors:
 - Valerio Bellaveglia
@@ -17,6 +17,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- README.md
 - lib/generators/skimming_migration_generator.rb
 - lib/models/skimming/collection_filter.rb
 - lib/skimming.rb