moulin_rouge 0.0.1.beta1 → 0.0.1.beta2

data/CHANGELOG.md

@@ -1,6 +1,11 @@
 CHANGELOG
 =========
 
+0.0.1.beta2 (Mar 28, 2011)
+
+*   Instead of declarate the authorization in plain ruby file, that could break spec and other things, manage the scope to the MoulinRouge::Authorization class
+*   Changing the name of the generator to match the name changes
+
 0.0.1.beta (Mar 16, 2011)
 
 *   Implementing the generators

data/MIT-LICENSE

@@ -1,4 +1,4 @@
-Copyright 2012 YOURNAME
+Copyright 2012 Edson Hilios
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,9 +1,9 @@
 Moulin Rouge
 ============
 
-**Moulin Rouge** is a DSL to manage your permissions and groups of access outside the [CanCan](https://github.com/ryanb/cancan) Ability class. It will help you organize and declare your permissions with has much ruby files you judge necessary, that are automatically pushed to CanCan authorization system. It is also decoupled from the role system.
+**Moulin Rouge** offers a custom and easy DSL to manage your authorizations and groups of access with [CanCan](https://github.com/ryanb/cancan). The main feature is the ability to split your authorizations in many ruby files, that are automatically pushed to CanCan authorization system. It is also decoupled from any role system giving you flexibility.
 
-There are a bunch of examples bellow to show you how to implement.
+There are a bunch of examples bellow to show you how to get started and explaining all features.
 
 Installation
 ------------
@@ -22,13 +22,15 @@ Run the generator to install the roles and permissions structure:
   
 Generate a permission file:
 
-    rails g moulin_rouge:permission <name>
+    rails g moulin_rouge:auth <name>
     
 Add your permissions to newly created file:
   
 ```ruby
-role :name do
-  can :read, :something
+class UserAuthorization < MoulinRouge::Authorization
+  role :name do
+    can :read, :something
+  end
 end
 ```
 
@@ -41,33 +43,35 @@ First of all, you have to accept that the role registering belongs to the ruby c
 
 When you run:
 
-      bundle g moulinrouge:install
+      bundle g moulin_rouge:install
     
 This will create the following folder structure:
 
       root
       | app/
-      | | permissions/
+      | | authorizations/
       | config/
       | | initalizers
       | | | moulin_rouge.rb
     
 ### Defining roles ###
     
-All your permission files will be stored inside the `app/permissions` folder. Just create a ruby file inside and the definitions will be automatically defined.
+All your authorization files will be stored inside the `app/authorizations` folder. Just create a ruby file inside and the definitions will be automatically defined.
   
 ```ruby
-role :superuser do
-  can :manage, :all
-end
+class UserAuthorization < MoulinRouge::Authorization
+  role :superuser do
+    can :manage, :all
+  end
 
-role :editors do
-  can :manage, Articles
-end
+  role :editors do
+    can :manage, Articles
+  end
 
-role :authors do
-  can :manage, Article do |article|
-    article.user_id == current_user.id
+  role :authors do
+    can :manage, Article do |article|
+      article.user_id == current_user.id
+    end
   end
 end
 ```
@@ -78,20 +82,22 @@ Also, the others CanCan methods are avaliable (`cannot`, `can?`, `cannot?`) and
   
 ### Groups ###
   
-A group is an easy way to organize your permissions, no matter where file the definition is. All groups with the same name, will have their abilities and permissions nested together.
+A group is an easy way to organize your authorization. All groups with the same name, will have their abilities and authorizations nested together.
 
-The group will delegate all abilities defined into, to their childrens, so any children role or group  will have the abilities defined in the parent. Also the group is not an avaliable role, they only serve has namespaces.
+The group will delegate all abilities defined inside of it, to their childrens, so any role or group  will have the same abilities defined in the parent. Also the group is not an avaliable role, they only serve has namespaces.
 
 ```ruby
-group :marketing do
-  can :read, Dashboard
+class UserAuthorization < MoulinRouge::Authorization
+  group :marketing do
+    can :read, Dashboard
 
-  role :manager do
-    can :manage, Proposal
-  end
+    role :manager do
+      can :manage, Proposal
+    end
 
-  role :salesman do
-    can :manage, Proposal, :user_id => current_user.id
+    role :salesman do
+      can :manage, Proposal, :user_id => current_user.id
+    end
   end
 end
 ```
@@ -101,7 +107,7 @@ To avoid name conflicts, whenever you have a nested roles or groups, their name
 Following the example above, will generate two roles:
 
 ```ruby
-MoulinRouge::Permission.list  
+MoulinRouge::Authorization.defined_roles
 # => [:marketing_manager, :marketing_salesman]
 # => :marketing_manager   => can :read, Dashboard, can :manage, Proposal
 # => :marketing_salesman  => can :read, Dashboard, can :manage, Proposal, :user_id => current_user.id
@@ -112,11 +118,13 @@ MoulinRouge::Permission.list
 When you have nested rules, they will act has namespaces, no ability will be shared unless is explicited with the `include` method.
   
 ```ruby
-role :marketing do
-  can :manage, Proposal
+class UserAuthorization < MoulinRouge::Authorization
+  role :marketing do
+    can :manage, Proposal
 
-  role :salesman do
-    can :read, Proposal
+    role :salesman do
+      can :read, Proposal
+    end
   end
 end
 ```
@@ -124,7 +132,7 @@ end
 Following the example above, this will generate two roles with the abilities:
 
 ```ruby
-MoulinRouge::Permission.list  
+MoulinRouge::Authorization.defined_roles
 # => [:marketing, :marketing_salesman]
 # => :marketing            => can :manage, Proposal
 # => :marketing_salesman   => can :read, Proposal
@@ -132,19 +140,21 @@ MoulinRouge::Permission.list
 
 ### Extending ###
 
-Many times you want to extend a role from another one, **MoulinRouge** let you `include` the abilities from one role to another, all the abilities from the target will be appended to the caller. 
+If you want extend the abilities from a role to another, **MoulinRouge** let you `include` them automatically. All the abilities from the target will be appended to the caller.
 
-Only roles can be included, and if you provide a name that isn't defined, a `RoleNotFound` will be raised. Notice by the example bellow, that you should provide the full name of the role in order to find the correct one.
+Only roles can be included, and if you provide a name that is not defined, a `RoleNotFound` will be raised. *Notice* by the example bellow, that you should provide the full name of the role in order to find them.
 
 ```ruby
-group :marketing do
-  role :admin do
-    can :do, :something
+class UserAuthorization < MoulinRouge::Authorization
+  group :marketing do
+    role :admin do
+      can :do, :something
+    end
   end
-end
 
-role :super do
-  include :marketing_admin
+  role :super do
+    include :marketing_admin
+  end
 end
 ```
 
@@ -153,15 +163,15 @@ Configuration
 
 ```ruby
 MoulinRouge.configure do |config|
-  # Cache permissions
+  # Cache authorizations
   config.cache = Rails.env.production?
-  # The search path for permissions
-  config.path = 'app/permissions/**/*.rb'
-  # The method that will test the permission
+  # Path for search the authorizations files
+  config.path = 'app/authorizations/**/*.rb'
+  # Method name that will send to the user to test if the role is assigned to him
   config.test_method = :is?
-  # The class of the model
+  # Your user model
   config.model = User
-  # How you like to call the active user model
+  # The method name that will access the current user information
   config.model_instance = :current_user
 end
 ```
@@ -169,7 +179,7 @@ end
 Goodies
 -------
 
-For those who like I dislikes the `load_and_authorize_resource` method from CanCan, here is provided a cleaner and more flexible solution through `ActionController::Responder`, the `MoulinRouge::CanCan::Responder` bellow there are instruction to activate them.
+For those who does not like the `load_and_authorize_resource` method from CanCan, here is provided a cleaner and more flexible solution through `ActionController::Responder`, the `MoulinRouge::CanCan::Responder` bellow there are instruction to activate them.
 
 Create the file `lib/application_responder.rb` with the following:
 
@@ -198,8 +208,17 @@ More about the `Responder` class:
 *   http://blog.plataformatec.com.br/2009/08/embracing-rest-with-mind-body-and-soul/
 *   http://archives.ryandaigle.com/articles/2009/8/6/what-s-new-in-edge-rails-cleaner-restful-controllers-w-respond_with/
 
+Testing
+-------
+
+This gem uses the [RSpec-2](https://www.relishapp.com/rspec) lib for BDD testing, with the help of [Guard](https://github.com/guard/guard) to autotest. For development just execute the following line:
+
+    bundle exec guard
+
+And it will perform all tests, and reload every time you implement something new. Also you can follow the test coverage by [simplecov](https://github.com/colszowka/simplecov).
+
 Thanks
-=======
+------
 
 *   [Troles](https://github.com/kristianmandrup/trole)
 *   [CanTango](https://github.com/kristianmandrup/cantango)
@@ -209,7 +228,9 @@ Thanks
 
 Mouling Rouge is a cabaret in Paris best know as the birthplace on modern [CanCan](https://github.com/ryanb/cancan) second to [Wikipedia](http://en.wikipedia.org/wiki/Moulin_Rouge).
 
-Credits
-=======
+Copyrights
+----------
+
+Copyrights 2012 [**Edson Hilios**](http://edson.hilios.com.br) edson (at) hilios (dot) com (dot) br
 
-**Edson Hilios** <edson (at) hilios (dot) com (dot) br>
+This software is licensed under [MIT-LICENSE](https://github.com/hilios/moulin_rouge/blob/master/MIT-LICENSE)

data/lib/generators/moulin_rouge/auth_generator.rb

@@ -0,0 +1,18 @@
+require 'rails/generators'
+
+module MoulinRouge
+  module Generators
+    class AuthGenerator < ::Rails::Generators::Base
+
+      source_root File.expand_path('../templates', __FILE__)
+
+      desc "Creates a new authorization file"
+
+      argument :name
+
+      def creates_an_authorization_file
+        copy_file("authorization.rb", "app/authorizations/#{name}_authorization.rb")
+      end
+    end
+  end
+end

data/lib/generators/moulin_rouge/install_generator.rb

@@ -6,11 +6,11 @@ module MoulinRouge
 
       source_root File.expand_path('../templates', __FILE__)
 
-      desc "Installs the gem folder structure for the app"
+      desc "Installs the gem folder structure"
 
       def generate_folder_structure
-        directory("install", "./")
-        generate("moulin_rouge:permission", "admin")
+        initializer("moulin_rouge.rb", "initializer.rb")
+        generate("moulin_rouge:permission", "user")
       end
     end
   end

data/lib/generators/moulin_rouge/templates/authorization.rb

@@ -0,0 +1,21 @@
+class <%= name.camelize %>Authorization < MoulinRouge::Authorization
+  # can :read, Post
+  # can :read, Comment
+  # can :manage, Comment do |comment|
+  #   comment.user_id == current_user.id
+  # end
+  # 
+  # role :admin do
+  #   can :manage, :all
+  # end
+  # 
+  # group :main do
+  #   role :editor do
+  #     can :manage, Post
+  #   end
+  # 
+  #   role :author do
+  #     can :manage, Post, :user_id => current_user.id
+  #   end
+  # end
+end

data/lib/generators/moulin_rouge/templates/initializer.rb

@@ -0,0 +1,14 @@
+MoulinRouge.configure do |config|
+  # Cache authorizations
+  config.cache = Rails.env.production?
+  # Path for search the authorizations files
+  config.path = 'app/authorizations/**/*.rb'
+  # Method name that will send to the user to test if the role is assigned to him
+  config.test_method = :is?
+  # Your user model
+  config.model = User
+  # The method name that will access the current user information
+  config.model_instance = :current_user
+end
+
+MoulinRouge.run! # Creates the Ability class

data/lib/moulin_rouge.rb

@@ -23,7 +23,7 @@ module MoulinRouge
 
     # Import all permission files in the configuration
     def self.load!
-      MoulinRouge::Permission.main.import(MoulinRouge.configuration.path)
+      MoulinRouge::Authorization.compile!
     end
 
     # Returns true if the run! method was called and false oterwise
@@ -39,6 +39,6 @@ module MoulinRouge
 
     # Reset all constants
     def self.reset! #:nodoc:
-      MoulinRouge::Permission.reset!
+      MoulinRouge::Authorization.reset!
     end
 end

data/lib/moulin_rouge/{permission.rb → ability.rb}

@@ -1,7 +1,7 @@
 module MoulinRouge
   class RoleNotFound < Exception; end
-  # A wrapper to catch and store the DSL methods
-  class Permission
+  # The CanCan wrapper with the custom DSL methods
+  class Ability
     CANCAN_METHODS = [:can, :cannot, :can?, :cannot?]
     # Returns a string with the given name
     attr_reader :singular_name
@@ -22,11 +22,12 @@ module MoulinRouge
       @is_group       = options.delete(:group)
       abilities.concat(parent.abilities) if not parent.nil? and parent.group?
       instance_eval(&block) if block_given?
-      # Store this permission
-      self.class.add(self) unless parent.nil? or @is_group
+      # Register this ability
+      MoulinRouge::Authorization.register(self) unless parent.nil? or group?
     end
 
-    def method_missing(name, *args, &block)
+    # Stores the CanCan methods and current_user method to later evaluation
+    def method_missing(name, *args, &block) #:nodoc:
       return store_method(name, *args, &block) if CANCAN_METHODS.include?(name)
       return MoulinRouge::ModelDouble.new if MoulinRouge.configuration.model_instance == name
       super(name, *args, &block)
@@ -34,7 +35,7 @@ module MoulinRouge
     
     # Define a new role inside this scope. If exists a role with the 
     # same name evaluate the block inside them instead of create a new one
-    def role(name, options = {}, &block)
+    def role(name = :main, options = {}, &block)
       if children = find(name)
         children.instance_eval(&block)
         children
@@ -50,11 +51,37 @@ module MoulinRouge
       role(name, options, &block)
     end
 
+    # Appends all childrens and abilities from one object to another,
+    # raises an error if could not found a match.
+    def include(name)
+      unless from = MoulinRouge::Authorization.abilities[name]
+        raise RoleNotFound
+      end
+      from.childrens.each { |children| childrens << children.dup }
+      from.abilities.each { |ability|  abilities << ability.dup  }
+    end
+
+    # Returns a symbol with the name appended with the parents separeted by a underscore
+    def name
+      unless @name
+        @name  = []
+        @name << self.parent.name.to_s if not self.parent.nil? and not self.parent.parent.nil?
+        @name << self.singular_name.to_s
+        @name  = @name.join('_')
+      end
+      @name.to_sym
+    end
+
     # Returns true if is a group
     def group?
       @is_group
     end
 
+    # Returns true if is a role
+    def role?
+      !group?
+    end
+
     # Add the given parameters to the authorizations list
     def store_method(name, *args, &block)
       abilities << MoulinRouge::CanCan::Method.new(name, *args, &block)
@@ -71,70 +98,16 @@ module MoulinRouge
       @abilities ||= []
     end
 
-    # Returns all abilities for this permission.
-    # If this is a group, grab the abilities from parent.
+    # Returns an array with the abilities collected from this node and from
+    # their childrens.
     def inherithed_abilities
       abilities.concat(childrens.map(&:inherithed_abilities).flatten).uniq
     end
     
-    # Execute all files in the given path in the class scope
-    def import(path)
-      Dir[path].each { |file| instance_eval(File.open(file).read) }
-    end
-    
     # Returns the instance of the children with the given name if exists and nil otherwise
     def find(name)
       childrens.each { |children| return children if children.name == name or children.singular_name == name }
      return nil
     end
-
-    # Appends all childrens and abilities from one object to another,
-    # raises an error if could not found a match.
-    def include(name)
-      unless from = self.class.all[name]
-        raise RoleNotFound
-      end
-      from.childrens.each { |children| childrens << children.dup }
-      from.abilities.each { |ability|  abilities << ability.dup  }
-    end
-    
-    # Returns a symbol with the name appended with the parents separeted by a underscore
-    def name
-      unless @name
-        @name  = []
-        @name << self.parent.name.to_s if not self.parent.nil? and not self.parent.parent.nil?
-        @name << self.singular_name.to_s
-        @name  = @name.join('_')
-      end
-      @name.to_sym
-    end
-    
-    class << self
-      # The instance of the main container, if don't exist create one
-      def main
-        @main ||= self.new(:main)
-      end
-      # Returns an array with the name of all roles created
-      def list
-        @list ||= []
-      end
-
-      # Returns an hash with all permissions defined
-      def all
-        @all ||= {}
-      end
-
-      # Stores the instance on the all hash and add the name to the list
-      def add(instance)
-        name = instance.name
-        self.all[name] = instance
-        self.list << name unless self.list.include?(name)
-      end
-
-      # Reset all constants
-      def reset! #:nodoc:
-        @main, @list, @all = nil
-      end
-    end
   end
 end