guise 0.6.0 → 0.6.1

data/.travis.yml

@@ -1,13 +1,33 @@
+sudo: false
+cache: bundler
 rvm:
-  - 1.9.3
   - 2.0.0
-  - 2.1.0
-  - jruby-19mode
+  - 2.1.8
+  - 2.2.4
+  - 2.3.0
 gemfile:
   - gemfiles/3.1.gemfile
   - gemfiles/3.2.gemfile
   - gemfiles/4.0.gemfile
-install: 'travis_retry bundle install -j 4'
+  - gemfiles/4.1.gemfile
+  - gemfiles/4.2.gemfile
+  - gemfiles/5.0.gemfile
 script: 'bundle exec rake'
 env:
-  secure: "I0cDQLpPt8NlOswL5Vomim4gb+NHvLW+0mPf2iimP1gTE5C+3PnoomCRx//0CyI/NSMhjrHg8DbrkvtBCfAYinrgzCi3cUkofi0zn5T6GaGUfYQz4Bmh7fmvppRVpVDCSXMOzOSYYEXBnie5b865BYTDrt1U3aM8qvq7pd/XOXg="
+  global:
+    # Code Climate coverage reporting
+    - secure: "I0cDQLpPt8NlOswL5Vomim4gb+NHvLW+0mPf2iimP1gTE5C+3PnoomCRx//0CyI/NSMhjrHg8DbrkvtBCfAYinrgzCi3cUkofi0zn5T6GaGUfYQz4Bmh7fmvppRVpVDCSXMOzOSYYEXBnie5b865BYTDrt1U3aM8qvq7pd/XOXg="
+matrix:
+  exclude:
+    - rvm: 2.2.4
+      gemfile: gemfiles/3.1.gemfile
+    - rvm: 2.3.0
+      gemfile: gemfiles/3.1.gemfile
+    - rvm: 2.2.4
+      gemfile: gemfiles/3.2.gemfile
+    - rvm: 2.0.0
+      gemfile: gemfiles/5.0.gemfile
+    - rvm: 2.1.8
+      gemfile: gemfiles/5.0.gemfile
+  allow_failures:
+    - gemfile: gemfiles/5.0.gemfile

data/.yardopts

@@ -0,0 +1 @@
+--markup markdown --title "paraphrase Documentation" --protected -M github-markup -M redcarpet

data/Appraisals

@@ -22,3 +22,8 @@ appraise '4.2' do
   gem 'activerecord', '~> 4.2.0'
   gem 'activesupport', '~> 4.2.0'
 end
+
+appraise '5.0' do
+  gem 'activerecord', '~> 5.0.0.beta'
+  gem 'activesupport', '~> 5.0.0.beta'
+end

data/README.md

@@ -3,14 +3,106 @@
 [![Build Status](https://travis-ci.org/ecbypi/guise.png?branch=master)](https://travis-ci.org/ecbypi/guise)
 [![Code Climate](https://codeclimate.com/github/ecbypi/guise.png)](https://codeclimate.com/github/ecbypi/guise)
 
+A typical, quick-and-easy role management system involves `users` and `roles`
+tables with a join table between them to determine membership to a role:
 
-An alternative to storing role resources in the database.
+```ruby
+class User < ActiveRecord::Base
+  has_many :user_roles
+  has_many :roles, through: :user_roles
+end
+
+class UserRole < ActiveRecord::Bae
+  belongs_to :user
+  belongs_to :role
+end
+
+class Role < ActiveRecord::Base
+  has_many :user_roles
+  has_many :users, through: :user_roles
+end
+```
+
+A problem with this is that in simple setups, application behavior tends to be
+hard-coded to rely on the existence of a database record representing the role
+object in the `roles` table.
+
+`guise` de-normalizes the above setup by storing the name of the role as a
+column in what would be the join table between `users` and `roles`. The allowed
+values are limited to the values defined in a declaration on the model that is
+meant to have different roles.
+
+Given `User` and `Role` models where the `Role` model has a `value` column.
+
+```ruby
+class User < ActiveRecord::Base
+end
+
+class Role < ActiveRecord::Base
+end
+```
+
+By adding the following method call to `has_guises` to `User` and `guise_for` to
+`Role`:
+
+```ruby
+class User < ActiveRecord::Base
+  has_guises :DeskWorker, :MailForwarder, association: :roles, attribute: :value
+end
+
+class Role < ActiveRecord::Base
+  guise_for :User
+end
+```
 
-`guise` uses a `has_many` association to store type information instead of
-using `has_many :through` or `has_and_belongs_to_many.` The `has_many` association
-stores the role or type information as a string representing the class name.
+The equivalent associations, model scopes and validations are configured:
 
-If effect, `guise` enables 'multi-table-inheritance'.
+```ruby
+class User < ActiveRecord::Base
+  has_many :roles
+
+  scope :desk_workers, -> { joins(:roles).where(roles: { value: "DeskWorker" }) }
+  scope :mail_forwarders, -> { joins(:roles).where(roles: { value: "MailForwarder" }) }
+
+  def has_role?(value)
+    roles.detect { |role| role.value == value }
+  end
+
+  def has_roles?(*values)
+    values.all? { |value| has_role?(value)
+  end
+
+  def has_any_roles?(*values)
+    values.any? { |value| has_role?(value)
+  end
+
+  def desk_worker?
+    has_role?("DeskWorker")
+  end
+
+  def mail_forwarder?
+    has_role?("MailForwarder")
+  end
+end
+
+class Role < ActiveRecord::Base
+  belongs_to :user
+
+  scope :desk_workers, -> { where(value: "DeskWorker") }
+  scope :mail_forwarders, -> { where(value: "MailForwarder") }
+
+  validates(
+    :value,
+    presence: true,
+    uniqueness: { scope: :user_id },
+    inclusion: { in: %w( DeskWorker MailForwarder ) }
+  )
+end
+```
+
+This allows filtering users by role / type and assigning records a role without
+requiring an existing record in the database. The predicate methods can be used
+for permissions / authorization.
 
 ## Installation
 
@@ -20,7 +112,7 @@ Add this line to your application's Gemfile:
 gem 'guise'
 ```
 
-And then execute:
+Then execute:
 
 ```
 $ bundle
@@ -32,23 +124,25 @@ Or install it yourself as:
 $ gem install guise
 ```
 
-
 ## Usage
 
 Create a table to store your type information:
 
 ```
-rails generate model user_role user:references title:string:uniq
+rails generate model role user:references value:string:uniq
 rake db:migrate
 ```
 
+It is recommended to add an index on the foreign key and guise attribute. In
+this case the columns are `user_id` and `value`.
+
 Then add `has_guises` to your model. This will setup the `has_many` association
 for you. It requires the name of the association and name of the column that
-the sublcass name will be stored in.
+the subclass name will be stored in.
 
 ```ruby
 class User < ActiveRecord::Base
-  has_guises :DeskWorker, :MailForwarder, association: :user_roles, attribute: :title
+  has_guises :DeskWorker, :MailForwarder, association: :roles, attribute: :value
 end
 ```
 
@@ -72,7 +166,11 @@ This method does the following:
 * Validates the column storing the name of the guise in the list supplied is
   unique to the resource it belongs to and is one of the provided names.
 
-To add a class for each guise, call `:guise_of` in a subclass:
+### Role Subclasses
+
+If using `User.<guise_scope>` is too tedious, it is possible to setup
+subclasses to represent each value referenced in `has_guises` using the
+`guise_of` method:
 
 ```ruby
 class DeskWorker < User
@@ -80,25 +178,21 @@ class DeskWorker < User
 end
 ```
 
-This adds the following to the `DeskWorker` class:
+This is equivalent to the following:
 
 ```ruby
 class DeskWorker < User
-  default_scope -> { joins(:user_roles).where(user_roles: { title: 'DeskWorker'}) }
+  default_scope -> { joins(:roles).where(roles: { value: 'DeskWorker'}) }
 
   after_initialize do
-    self.guises.build(title: 'DeskWorker')
-  end
-
-  after_create do
-    self.guises.create(title: 'DeskWorker')
+    self.guises.build(value: 'DeskWorker')
   end
 end
 ```
 
 To scope the association class to a guise, use `scoped_guise_for`. The name of
-the class must be the guise it represents combined with the name of the parent
-class.
+the class must be `<guise_value><association_class_name>` (i.e. the guise it
+represents combined with the name of the parent class.
 
 ```ruby
 class DeskWorkerUserRole < UserRole
@@ -110,23 +204,20 @@ This sets up the class as follows:
 
 ```ruby
 class DeskWorkerUserRole < UserRole
-  default_scope -> { where(title: 'DeskWorker') }
+  default_scope -> { where(value: "DeskWorker") }
 
   after_initialize do
-    self.title = 'DeskWorker'
-  end
-
-  before_create do
-    self.title = 'DeskWorker'
+    self.value = "DeskWorker"
   end
 end
 ```
 
 ### Customization
 
-If the association doesn't standard association assumptions, you can pass in
-the options for `has_many` into `has_guises`. The same applies to `guise_for`
-with the addition that you can specify not to validate attributes.
+If the association doesn't standard association assumptions made by
+`activerecord`, you can pass in the options for `has_many` into `has_guises`.
+The same applies to `guise_for` with the addition that you can specify not to
+validate attributes.
 
 ```ruby
 class Person < ActiveRecord::Base

data/gemfiles/3.1.gemfile

@@ -5,4 +5,4 @@ source "https://rubygems.org"
 gem "activerecord", "~> 3.1.0"
 gem "activesupport", "~> 3.1.0"
 
-gemspec :path=>"../"
+gemspec :path => "../"

data/gemfiles/3.1.gemfile.lock

@@ -19,48 +19,53 @@ GEM
       tzinfo (~> 0.3.29)
     activesupport (3.1.12)
       multi_json (~> 1.0)
-    appraisal (0.5.2)
+    appraisal (2.1.0)
       bundler
       rake
+      thor (>= 0.14.0)
     arel (2.2.3)
     builder (3.0.4)
-    codeclimate-test-reporter (0.4.0)
+    byebug (5.0.0)
+      columnize (= 0.9.0)
+    codeclimate-test-reporter (0.4.8)
       simplecov (>= 0.7.1, < 1.0.0)
     coderay (1.1.0)
+    columnize (0.9.0)
     diff-lcs (1.2.5)
     docile (1.1.5)
-    factory_girl (4.4.0)
-      activesupport (>= 3.0.0)
-    i18n (0.6.11)
+    i18n (0.7.0)
+    json (1.8.3)
     method_source (0.8.2)
-    multi_json (1.10.1)
-    pry (0.10.1)
+    multi_json (1.11.2)
+    pry (0.10.3)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
-    rake (10.3.2)
-    rspec (3.0.0)
-      rspec-core (~> 3.0.0)
-      rspec-expectations (~> 3.0.0)
-      rspec-mocks (~> 3.0.0)
-    rspec-core (3.0.4)
-      rspec-support (~> 3.0.0)
-    rspec-expectations (3.0.4)
+    rake (10.4.2)
+    redcarpet (3.3.3)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.0)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.0.0)
-    rspec-mocks (3.0.4)
-      rspec-support (~> 3.0.0)
-    rspec-support (3.0.4)
-    shoulda-matchers (2.6.2)
-      activesupport (>= 3.0.0)
-    simplecov (0.9.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.0)
+    simplecov (0.10.0)
       docile (~> 1.1.0)
-      multi_json
-      simplecov-html (~> 0.8.0)
-    simplecov-html (0.8.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
     slop (3.6.0)
-    sqlite3 (1.3.9)
-    tzinfo (0.3.41)
+    sqlite3 (1.3.11)
+    thor (0.19.1)
+    tzinfo (0.3.45)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
@@ -68,12 +73,16 @@ PLATFORMS
 DEPENDENCIES
   activerecord (~> 3.1.0)
   activesupport (~> 3.1.0)
-  appraisal (~> 0.5)
+  appraisal (>= 1.0)
+  byebug (~> 5.0)
   codeclimate-test-reporter (~> 0.3)
-  factory_girl (~> 4.4)
   guise!
   pry (~> 0.9)
   rake (~> 10.1)
+  redcarpet (~> 3.2)
   rspec (~> 3.0)
-  shoulda-matchers (~> 2.5)
   sqlite3 (~> 1.3)
+  yard (~> 0.8)
+
+BUNDLED WITH
+   1.10.6

data/gemfiles/3.2.gemfile

@@ -5,4 +5,4 @@ source "https://rubygems.org"
 gem "activerecord", "~> 3.2.0"
 gem "activesupport", "~> 3.2.0"
 
-gemspec :path=>"../"
+gemspec :path => "../"

data/gemfiles/3.2.gemfile.lock

@@ -8,59 +8,64 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    activemodel (3.2.13)
-      activesupport (= 3.2.13)
+    activemodel (3.2.22)
+      activesupport (= 3.2.22)
       builder (~> 3.0.0)
-    activerecord (3.2.13)
-      activemodel (= 3.2.13)
-      activesupport (= 3.2.13)
+    activerecord (3.2.22)
+      activemodel (= 3.2.22)
+      activesupport (= 3.2.22)
       arel (~> 3.0.2)
       tzinfo (~> 0.3.29)
-    activesupport (3.2.13)
-      i18n (= 0.6.1)
+    activesupport (3.2.22)
+      i18n (~> 0.6, >= 0.6.4)
       multi_json (~> 1.0)
-    appraisal (0.5.2)
+    appraisal (2.1.0)
       bundler
       rake
-    arel (3.0.2)
+      thor (>= 0.14.0)
+    arel (3.0.3)
     builder (3.0.4)
-    codeclimate-test-reporter (0.4.0)
+    byebug (5.0.0)
+      columnize (= 0.9.0)
+    codeclimate-test-reporter (0.4.8)
       simplecov (>= 0.7.1, < 1.0.0)
     coderay (1.1.0)
+    columnize (0.9.0)
     diff-lcs (1.2.5)
     docile (1.1.5)
-    factory_girl (4.4.0)
-      activesupport (>= 3.0.0)
-    i18n (0.6.1)
+    i18n (0.7.0)
+    json (1.8.3)
     method_source (0.8.2)
-    multi_json (1.10.1)
-    pry (0.10.1)
+    multi_json (1.11.2)
+    pry (0.10.3)
       coderay (~> 1.1.0)
       method_source (~> 0.8.1)
       slop (~> 3.4)
-    rake (10.3.2)
-    rspec (3.0.0)
-      rspec-core (~> 3.0.0)
-      rspec-expectations (~> 3.0.0)
-      rspec-mocks (~> 3.0.0)
-    rspec-core (3.0.4)
-      rspec-support (~> 3.0.0)
-    rspec-expectations (3.0.4)
+    rake (10.4.2)
+    redcarpet (3.3.3)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.0)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.0.0)
-    rspec-mocks (3.0.4)
-      rspec-support (~> 3.0.0)
-    rspec-support (3.0.4)
-    shoulda-matchers (2.6.2)
-      activesupport (>= 3.0.0)
-    simplecov (0.9.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.0)
+    simplecov (0.10.0)
       docile (~> 1.1.0)
-      multi_json
-      simplecov-html (~> 0.8.0)
-    simplecov-html (0.8.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
     slop (3.6.0)
-    sqlite3 (1.3.9)
-    tzinfo (0.3.41)
+    sqlite3 (1.3.11)
+    thor (0.19.1)
+    tzinfo (0.3.45)
+    yard (0.8.7.6)
 
 PLATFORMS
   ruby
@@ -68,12 +73,16 @@ PLATFORMS
 DEPENDENCIES
   activerecord (~> 3.2.0)
   activesupport (~> 3.2.0)
-  appraisal (~> 0.5)
+  appraisal (>= 1.0)
+  byebug (~> 5.0)
   codeclimate-test-reporter (~> 0.3)
-  factory_girl (~> 4.4)
   guise!
   pry (~> 0.9)
   rake (~> 10.1)
+  redcarpet (~> 3.2)
   rspec (~> 3.0)
-  shoulda-matchers (~> 2.5)
   sqlite3 (~> 1.3)
+  yard (~> 0.8)
+
+BUNDLED WITH
+   1.10.6