ability_list 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 02257b2981224d6a1e1e43d60bb9721eba16420a
+  data.tar.gz: 7b586e6a4ba0bf248bfef3084310353a2ac89015
+SHA512:
+  metadata.gz: 1cea5050c2133f0bc47a4d266fb4a1bbbad62e2fff7c9a6533e4d873d4174515afb43437af66a674eecdf6e7a356ea97cc01d437e0acef0bb7d0994b44ba83f1
+  data.tar.gz: 14241716362b1380591ae3dbc59d847be38b9e8cb87d64b89892a35f4132967bf76ba1dee4f68673be0687f61aca57728025a6a6215d8837dbdc65d1c8182d40

data/.gitignore

@@ -0,0 +1 @@
+Gemfile.lock

data/Gemfile

@@ -0,0 +1 @@
+gemspec

data/README.md

@@ -0,0 +1,200 @@
+AbilityList
+===========
+
+Simple permissions system as plain old Ruby objects. No fancy integration with 
+ORMs or frameworks.
+
+All of this is just a single Ruby file with less than 50 lines of significant 
+code. [Read it now][ability_list.rb].
+
+## Defining abilities
+
+Define the list of abilities a user has by subclassing `AbilityList`.
+
+Each ability is comprised of a **verb** (required) and an **object** (optional).
+A *verb* is any symbol, while the *object* can be a symbol or a class.
+
+``` ruby
+class Abilities < AbilityList
+  def initialize(user)
+    can :view, Video
+
+    if user.admin?
+      can :delete, Video
+      can :upload, Video
+    end
+
+    can :login
+
+    can :view, :admin
+  end
+end
+```
+
+Then hook it to user by defining an `abilities` method.
+
+``` ruby
+class User < OpenStruct
+  include AbilityList::Helpers
+
+  def abilities
+    @abilities ||= Abilities.new(self)
+  end
+end
+```
+
+## Checking for abilities
+
+Now you may use `can?`:
+
+``` ruby
+user = User.new
+user.can?(:view, Video)
+user.can?(:view, Video.find(20))
+
+user.can?(:login)
+user.can?(:view, :admin)
+```
+
+The inverse `cannot?` is also available.
+
+## Raising errors
+
+Or you can use `authorize!`, which is exactly like `can?` except it raises
+an `AbilityList::Error` exception. Perfect for controllers.
+
+``` ruby
+user.authorize! :view, Video.find(20)
+```
+
+## Custom criteria
+
+You can pass a block to `can` for custom criteria:
+
+``` ruby
+can :view, Video do |video|
+  !video.restricted? or user.age > 18
+end
+```
+
+You can even use Ruby's `&:sym` syntax:
+
+``` ruby
+cannot :edit, Article, &:published?
+
+# Equivalent to cannot(:edit, Article) { |article| article.published? }
+```
+
+## Object types
+
+The method `can` always accepts at least 2 arguments: a *verb* and an *object*.
+
+You can define your permissions by passing a class as the object:
+
+``` ruby
+can :view, Video
+```
+
+which makes it possible to check for instances or classes:
+
+``` ruby
+user.can?(:view, Video)                 #-> passing a class
+user.can?(:view, Video.find(1008))      #-> passing an instance
+```
+
+But this doesn't have to be classes. Just pass anything else, like a symbol:
+
+``` ruby
+can :login, :mobile_site
+
+# user.can?(:login, :mobile_site)
+```
+
+## Overriding criteria
+
+Criteria are evaluated on a top-down basis, and the ones at the bottom will 
+override the ones on top.
+
+The method `cannot` is provided to make exceptions to rules.
+
+For example:
+
+``` ruby
+# Everyone can edit comments.
+can :edit, Comment
+
+# ...but unconfirmed users can't edit their comments.
+if user.unconfirmed?
+  cannot :edit, Comment
+end
+
+# ...but if the comments are really new, they can be edited, even if the user
+# hasn't confirmed.
+can :edit, Comment { |c| c.created_at < 3.minutes.ago }
+```
+
+## The `:manage` keyword
+
+You can use `:manage` as the verb to allow any verb.
+
+``` ruby
+can :manage, Group
+```
+
+This allows the user to do anything to `Group` its instances.
+
+``` ruby
+user.can?(:delete, Group)       #=> true
+user.can?(:create, Group)       #=> true
+user.can?(:eviscerate, Group)   #=> true
+```
+
+## The `:all` keyword
+
+You can use `:all` as the object for any permission. This allows a verb to work 
+on anything.
+
+Don't know why you'll want this, but cancan has it, so:
+
+``` ruby
+can :delete, :all
+```
+
+So you can:
+
+``` ruby
+user.can?(:delete, Video)     #=> true
+user.can?(:delete, Article)   #=> true
+user.can?(:delete, Recipe)    #=> true
+```
+
+More examples
+-------------
+
+See [RECIPES.md] for some practical examples.
+
+Limitations
+-----------
+
+AbilityList aims to be extremely lean, and to be as framework- and ORM-agnostic 
+as possible. As such, it doesn't:
+
+ * No explicit integration with Rails controllers.
+
+ * No explicit integration with ActiveRecord (or any other ORM).
+
+ * No explicit provisions for roles.
+ 
+See [RECIPES.md] on how to do these things.
+
+Acknowledgements
+----------------
+
+Heavily inspired by [cancan]. AbilityList is generally a stripped-down version 
+of cancan with a lot less features (see    Limitations) above.
+
+(c) 2013 MIT License.
+
+[cancan]: https://github.com/ryanb/cancan
+[RECIPES.md]: https://github.com/rstacruz/ability_list/blob/master/RECIPES.md
+[ability_list.rb]:https://github.com/rstacruz/ability_list/blob/master/lib/ability_list.rb

data/RECIPES.md

@@ -0,0 +1,101 @@
+How to implement roles
+----------------------
+
+AbilityList has no explicit support for roles because they're pretty easy to do 
+in the plain ol' Ruby way.
+
+``` ruby
+class Abilities < AbilityList
+  def initialize(user)
+    # Assume this returns an array of strings like ['admin', 'editor'].
+    roles = user.roles
+
+    # Now simply call the respective methods of each role.
+    roles.each { |role| send role }
+  end
+
+  def admin
+    can :manage, User
+    can :manage, Group
+  end
+
+  def editor
+    can :edit, Article
+  end
+
+  def publisher
+    can :publish, Article
+  end
+
+  def writer
+    can :create, Article
+  end
+end
+```
+
+How to integrate with Rails controllers
+---------------------------------------
+
+This Rails example raises an error when the logged in user is not allowed of a 
+certain permission.
+
+``` ruby
+class ArticleController
+  before_filter :authorize_viewing
+
+private
+
+  def authorize_viewing
+    current_user.authorize! :view, Article
+  end
+end
+```
+
+How to implement user levels
+----------------------------
+
+If your `User` model has a numeric field `level`, where more permissions are 
+available to users with higher levels, you can implement it like so:
+
+``` ruby
+class Abilities < AbilityList
+  def initialize(user)
+    if user.level > 50
+      can :launch, Rocket
+      can :command, Army
+    end
+
+    if user.level > 30
+      can :view_status, Rocket
+    end
+
+    if user.level > 1
+      can :login, :site
+    end
+  end
+end
+```
+
+Defining Rails helpers
+----------------------
+
+The `Helpers` module used in Users can be used as Rails helpers too.
+
+``` ruby
+module PermissionsHelper
+  # Provides `can?` and `cannot?`... as long as you have `#abilities` defined.
+  include AbilityList::Helpers
+
+  def abilities
+    current_user.try :abilities
+  end
+end
+```
+
+So that you may:
+
+``` erb
+<% if can?(:edit, @post) %>
+  <a href="#edit">Edit</a>
+<% end %>
+```

data/Rakefile

@@ -0,0 +1,6 @@
+desc "Run tests."
+task :test do
+  Dir['./test/*_test.rb'].each { |f| load f }
+end
+
+task :default => :test

data/ability_list.gemspec

@@ -0,0 +1,15 @@
+require './lib/ability_list/version'
+
+Gem::Specification.new do |s|
+  s.name = "ability_list"
+  s.version = AbilityList::VERSION
+  s.summary = %[Simple user permissions management.]
+  s.description = %[A very simple way to manage permissions. Works with any ORM.]
+  s.authors = ["Rico Sta. Cruz", 'CJ Lazell']
+  s.email = ["hi@ricostacruz.com"]
+  s.homepage = "http://github.com/cj/ability_list"
+  s.files = `git ls-files`.strip.split("\n")
+
+  s.add_development_dependency "minitest"
+  s.add_development_dependency "rake"
+end

data/lib/ability_list.rb

@@ -0,0 +1,90 @@
+class AbilityList
+  Error = Class.new(StandardError)
+
+  # Returns a list of rules. These are populated by `can` and `cannot`.
+  # (Rules are tuples)
+  def rules
+    @rules ||= []
+  end
+
+  # ---
+
+  # Declares that the owner can perform `verb` on `class`.
+  def can(verb, klass=nil, columns=[], &block)
+    columns = [columns] unless columns.is_a? Array
+    rules << [true, verb, get_class(klass), columns, block]
+  end
+
+  # Inverse of `can`.
+  def cannot(verb, klass=nil, columns=[], &block)
+    columns = [columns] unless columns.is_a? Array
+    rules << [false, verb, get_class(klass), columns, block]
+  end
+
+  # ---
+
+  # Checks if the owner can perform `verb` on the given `object` (or class).
+  def can?(verb, object=nil, columns=[])
+    columns = [columns] unless columns.is_a? Array
+    rules = rules_for(verb, get_class(object))
+    rules.inject(false) do |bool, (sign, _, _, cols, proc)|
+      sign ?
+        ((bool || !proc ||  proc.call(object)) && ((columns & cols) == columns)) :  # can
+        (bool &&  proc && !proc.call(object) && (columns.empty? || (columns & cols) != columns))    # cannot
+    end
+  end
+
+  # Inverse of `can?`.
+  def cannot?(verb, object=nil, columns)
+    ! can?(verb, object, columns)
+  end
+
+  # ---
+
+  # Ensures that the owner can perform `verb` on `object/class` -- raises an
+  # error otherwise.
+  def authorize!(verb, object=nil)
+    can?(verb, object) or raise Error.new("Access denied (#{verb})")
+  end
+
+  # Inverse of `authorize!`.
+  def unauthorize!(verb, object=nil)
+    cannot?(verb, object) or raise Error.new("Access denied (#{verb})")
+  end
+
+  # ---
+
+  # Returns a subset of `rules` that match the given `verb` and `class`.
+  def rules_for(verb, klass)
+    rules.select do |(sign, _verb, _klass, cols, block)|
+      (_verb  == :manage || _verb  == verb) &&
+      (_klass == :all    || _klass == klass)
+    end
+  end
+
+private
+
+  def get_class(object)
+    [NilClass, Symbol, Class].include?(object.class) ? object : object.class
+  end
+end
+
+# Provides `#can?` and `#cannot?` and other helpers.
+# Assumes that you have an `#ability` method defined.
+module AbilityList::Helpers
+  def can?(*a)
+    abilities && abilities.can?(*a)
+  end
+
+  def cannot?(*a)
+    !abilities || abilities.cannot?(*a)
+  end
+
+  def authorize!(*a)
+    raise AbilityList::Error.new("No 'ability' defined") unless abilities
+    abilities.authorize!(*a)
+  end
+end
+
+require 'ability_list/version'
+

data/lib/ability_list/version.rb

@@ -0,0 +1,3 @@
+class AbilityList
+  VERSION = "0.0.2"
+end

data/test/basic_test.rb

@@ -0,0 +1,73 @@
+require File.expand_path('../helper.rb', __FILE__)
+
+module BasicTest
+  Video = Class.new(OpenStruct)
+
+  # ---
+
+  class User < OpenStruct
+    include AbilityList::Helpers
+
+    def abilities
+      @abilities ||= Abilities.new(self)
+    end
+  end
+
+  # ---
+
+  class Abilities < AbilityList
+    def initialize(user)
+      # Every can view videos.
+      can :view, Video
+
+      # ...except restricted ones.
+      cannot :view, Video, &:restricted
+
+      # ...but for those that are restricted, it's okay if the user is old enough.
+      can :view, Video do |vid|
+        vid.restricted && user.age > 18
+      end
+    end
+  end
+
+  # ---
+
+  describe "Basic tests" do
+    it "#can? 1" do
+      user  = User.new :age => 22
+      video = Video.new :restricted => false
+
+      user.can?(:view, video).must_equal true
+    end
+
+    it "#can? 2" do
+      user  = User.new :age => 10
+      video = Video.new :restricted => true
+
+      user.can?(:view, video).must_equal false
+    end
+
+    it "#can? 3" do
+      user  = User.new :age => 42
+      video = Video.new :restricted => true
+
+      user.can?(:view, video).must_equal true
+    end
+
+    it "#cannot?" do
+      user  = User.new :age => 10
+      video = Video.new :restricted => true
+
+      user.cannot?(:view, video).must_equal true
+    end
+
+    it "#authorize!" do
+      user  = User.new :age => 10
+      video = Video.new :restricted => true
+
+      assert_raises AbilityList::Error do
+        user.authorize! :view, video
+      end
+    end
+  end
+end

data/test/column_test.rb

@@ -0,0 +1,43 @@
+require File.expand_path('../helper.rb', __FILE__)
+
+module ColumnTest
+  Video  = Class.new(OpenStruct)
+  Player = Class.new(OpenStruct)
+
+  # ---
+
+  class User < OpenStruct
+    include AbilityList::Helpers
+
+    def abilities
+      @abilities ||= Abilities.new(self)
+    end
+  end
+
+  # ---
+
+  class Abilities < AbilityList
+    def initialize(user)
+      # Every can view videos.
+      can :view, Video, [:title, :description]
+      can :view, Player, :name
+    end
+  end
+
+  # ---
+
+  describe 'Column tests' do
+    it '#can? 1' do
+      user   = User.new
+      video  = Video.new title: 'moo', description: 'cow', about: 'grass'
+      player = Player.new name: 'Bob', age: 100
+
+      user.can?(:view, video, :title).must_equal true
+      user.can?(:view, video, [:title, :description]).must_equal true
+      user.can?(:view, video, :about).must_equal false
+      user.can?(:view, player, :name).must_equal true
+      user.cannot?(:view, player, :age).must_equal true
+      user.cannot?(:view, player, :name).must_equal false
+    end
+  end
+end

data/test/helper.rb

@@ -0,0 +1,9 @@
+$:.unshift File.expand_path('../../lib', __FILE__)
+
+require 'minitest/autorun'
+require 'ability_list'
+require 'ostruct'
+
+class TestCase < MiniTest::Unit::TestCase
+
+end

data/test/helpers_test.rb

@@ -0,0 +1,34 @@
+require File.expand_path('../helper.rb', __FILE__)
+
+module HelpersTest
+  Video = Class.new(OpenStruct)
+
+  # ---
+
+  class User < OpenStruct
+    include AbilityList::Helpers
+
+    def abilities
+    end
+  end
+
+  # ---
+
+  describe "Helper tests" do
+    let(:user) { User.new }
+
+    it '#can? fail' do
+      (!! user.can?(:cook, :spam)).must_equal false
+    end
+
+    it '#cannot? fail' do
+      (!! user.cannot?(:cook, :spam)).must_equal true
+    end
+
+    it '#authorize! fail' do
+      assert_raises AbilityList::Error do
+        user.authorize! :cook, :spam
+      end
+    end
+  end
+end

data/test/nil_test.rb

@@ -0,0 +1,36 @@
+require File.expand_path('../helper.rb', __FILE__)
+
+module NilTest
+  class User < OpenStruct
+    include AbilityList::Helpers
+
+    def abilities
+      @abilities ||= Abilities.new(self)
+    end
+  end
+
+  # ---
+
+  class Abilities < AbilityList
+    def initialize(user)
+      can :make, :fire
+      can :make
+    end
+  end
+
+  # ---
+
+  describe "Nil tests" do
+    let(:user) { User.new }
+
+    it "#can? 1" do
+      user.can?(:make, :fire).must_equal true
+    end
+    it "#can? 2" do
+      user.can?(:make).must_equal true
+    end
+    it "#can? 3" do
+      user.can?(:make, :lasagna).must_equal false
+    end
+  end
+end

metadata

@@ -0,0 +1,86 @@
+--- !ruby/object:Gem::Specification
+name: ability_list
+version: !ruby/object:Gem::Version
+  version: 0.0.2
+platform: ruby
+authors:
+- Rico Sta. Cruz
+- CJ Lazell
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: A very simple way to manage permissions. Works with any ORM.
+email:
+- hi@ricostacruz.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- README.md
+- RECIPES.md
+- Rakefile
+- ability_list.gemspec
+- lib/ability_list.rb
+- lib/ability_list/version.rb
+- test/basic_test.rb
+- test/column_test.rb
+- test/helper.rb
+- test/helpers_test.rb
+- test/nil_test.rb
+homepage: http://github.com/cj/ability_list
+licenses: []
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Simple user permissions management.
+test_files: []
+has_rdoc: