has_scope 0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2009 Plataforma Tecnologia. http://blog.plataformatec.com.br
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,51 @@
+== HasScope
+
+Has scope allows you to easily create controller filters based on your resources named scopes.
+Imagine the following model called graduations:
+
+  class Graduation < ActiveRecord::Base
+    named_scope :featured, :conditions => { :featured => true }
+    named_scope :by_degree, proc {|degree| { :conditions => { :degree => degree } } }
+  end
+
+You can use those named scopes as filters by declaring them on your controller:
+
+  class GraduationsController < ApplicationController
+    has_scope :featured, :boolean => true
+    has_scope :by_degree
+  end
+
+Now, if you want to apply them to an specific resource, you just need to call <tt>apply_scopes</tt>:
+
+  class GraduationsController < ApplicationController
+    has_scope :featured, :boolean => true
+    has_scope :by_degree
+
+    def index
+      @graduations = apply_scopes(Graduations).all
+    end
+  end
+
+Then for each request:
+
+  /graduations
+  #=> acts like a normal request
+
+  /graduations?featured=true
+  #=> calls the named scope and bring featured graduations
+
+  /graduations?featured=true&by_degree=phd
+  #=> brings featured graduations with phd degree
+
+You can retrieve all the scopes applied in one action with <tt>current_scopes</tt> method.
+In the last case, it would return: { :featured => true, :by_degree => "phd" }.
+
+Please check <tt>has_scope</tt> method for all the supported options.
+
+== Bugs and Feedback
+
+If you discover any bugs or want to drop a line, feel free to create an issue on GitHub.
+
+http://github.com/plataformatec/has_scope/issues
+
+MIT License. Copyright 2009 Plataforma Tecnologia. http://blog.plataformatec.com.br

data/Rakefile

@@ -0,0 +1,42 @@
+# encoding: UTF-8
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test HasScope'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Generate documentation for HasScope'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'HasScope'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "has_scope"
+    s.version = "0.1"
+    s.summary = "Maps controller filters to your resource scopes"
+    s.email = "contact@plataformatec.com.br"
+    s.homepage = "http://github.com/plataformatec/has_scope"
+    s.description = "Maps controller filters to your resource scopes"
+    s.authors = ['José Valim']
+    s.files =  FileList["[A-Z]*", "lib/**/*", "init.rb"]
+  end
+
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler, or one of its dependencies, is not available. Install it with: sudo gem install jeweler"
+end

data/lib/has_scope.rb

@@ -0,0 +1,127 @@
+module HasScope
+  TRUE_VALUES = ["true", true, "1", 1]
+
+  def self.included(base)
+    base.class_eval do
+      extend ClassMethods
+      helper_method :current_scopes
+
+      class_inheritable_accessor :scopes_configuration, :instance_writer => false
+      self.scopes_configuration ||= {}
+    end
+  end
+
+  module ClassMethods
+    # Detects params from url and apply as scopes to your classes.
+    #
+    # == Options
+    #
+    # * <tt>:boolean</tt> - When set to true, call the scope only when the param is true or 1,
+    #                       and does not send the value as argument.
+    #
+    # * <tt>:only</tt> - In which actions the scope is applied. By default is :all.
+    #
+    # * <tt>:except</tt> - In which actions the scope is not applied. By default is :none.
+    #
+    # * <tt>:as</tt> - The key in the params hash expected to find the scope.
+    #                  Defaults to the scope name.
+    #
+    # * <tt>:if</tt> - Specifies a method, proc or string to call to determine
+    #                  if the scope should apply
+    #
+    # * <tt>:unless</tt> - Specifies a method, proc or string to call to determine
+    #                      if the scope should NOT apply.
+    #
+    # * <tt>:default</tt> - Default value for the scope. Whenever supplied the scope
+    #                       is always called. This is useful to add easy pagination.
+    #
+    def has_scope(*scopes)
+      options = scopes.extract_options!
+      options.symbolize_keys!
+      options.assert_valid_keys(:boolean, :only, :except, :if, :unless, :default, :as)
+
+      scopes.each do |scope|
+        self.scopes_configuration[scope]         ||= {}
+        self.scopes_configuration[scope][:as]      = options[:as] || scope
+        self.scopes_configuration[scope][:only]    = Array(options[:only])
+        self.scopes_configuration[scope][:except]  = Array(options[:except])
+
+        [:if, :unless, :boolean, :default].each do |opt|
+          self.scopes_configuration[scope][opt] = options[opt] if options.key?(opt)
+        end
+      end
+    end
+  end
+
+  protected
+
+  # Receives an object where scopes will be applied to.
+  #
+  #   class GraduationsController < InheritedResources::Base
+  #     has_scope :featured, :boolean => true, :only => :index
+  #     has_scope :by_degree, :only => :index
+  #
+  #     def index
+  #       @graduations = apply_scopes(Graduation).all
+  #     end
+  #   end
+  #
+  def apply_scopes(target_object)
+    self.scopes_configuration.each do |scope, options|
+      next unless apply_scope_to_action?(options)
+      key = options[:as]
+
+      if params.key?(key)
+        value, call_scope = params[key], true
+      elsif options.key?(:default)
+        value, call_scope = options[:default], true
+        value = value.call(self) if value.is_a?(Proc)
+      end
+
+      if call_scope
+        if options[:boolean]
+          target_object = target_object.send(scope) if current_scopes[key] = TRUE_VALUES.include?(value)
+        else
+          current_scopes[key] = value
+          target_object = target_object.send(scope, value)
+        end
+      end
+    end
+
+    target_object
+  end
+
+  # Given an options with :only and :except arrays, check if the scope
+  # can be performed in the current action.
+  def apply_scope_to_action?(options) #:nodoc:
+    return false unless applicable?(options[:if], true) && applicable?(options[:unless], false)
+
+    if options[:only].empty?
+      options[:except].empty? || !options[:except].include?(action_name.to_sym)
+    else
+      options[:only].include?(action_name.to_sym)
+    end
+  end
+
+  # Evaluates the scope options :if or :unless. Returns true if the proc
+  # method, or string evals to the expected value.
+  def applicable?(string_proc_or_symbol, expected) #:nodoc:
+    case string_proc_or_symbol
+      when String
+        eval(string_proc_or_symbol) == expected
+      when Proc
+        string_proc_or_symbol.call(self) == expected
+      when Symbol
+        send(string_proc_or_symbol) == expected
+      else
+        true
+    end
+  end
+
+  # Returns the scopes used in this action.
+  def current_scopes
+    @current_scopes ||= {}
+  end
+end
+
+ApplicationController.send :include, HasScope

data/test/has_scope_test.rb

@@ -0,0 +1,153 @@
+require File.dirname(__FILE__) + '/test_helper'
+
+class Tree
+end
+
+class TreesController < ApplicationController
+  has_scope :color, :unless => :show_all_colors?
+  has_scope :only_tall, :boolean => true, :only => :index, :if => :restrict_to_only_tall_trees?
+  has_scope :shadown_range, :default => 10, :except => [ :index, :show, :destroy, :new ]
+  has_scope :root_type, :as => :root
+  has_scope :calculate_height, :default => proc {|c| c.session[:height] || 20 }, :only => :new
+
+  def index
+    @trees = apply_scopes(Tree).all
+  end
+
+  def new
+    @tree = apply_scopes(Tree).new
+  end
+
+  def show
+    @tree = apply_scopes(Tree).find(params[:id])
+  end
+  alias :edit :show
+
+  protected
+    def restrict_to_only_tall_trees?
+      true
+    end
+
+    def show_all_colors?
+      false
+    end
+    
+    def default_render
+      render :text => action_name
+    end
+end
+
+class HasScopeTest < ActionController::TestCase
+  tests TreesController
+
+  def test_boolean_scope_is_called_when_boolean_param_is_true
+    Tree.expects(:only_tall).with().returns(Tree).in_sequence
+    Tree.expects(:all).returns([mock_tree]).in_sequence
+    get :index, :only_tall => 'true'
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ :only_tall => true }, current_scopes)
+  end
+
+  def test_boolean_scope_is_called_when_boolean_param_is_false
+    Tree.expects(:only_tall).never
+    Tree.expects(:all).returns([mock_tree])
+    get :index, :only_tall => 'false'
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ :only_tall => false }, current_scopes)
+  end
+
+  def test_scope_is_called_only_on_index
+    Tree.expects(:only_tall).never
+    Tree.expects(:find).with('42').returns(mock_tree)
+    get :show, :only_tall => 'true', :id => '42'
+    assert_equal(mock_tree, assigns(:tree))
+    assert_equal({ }, current_scopes)
+  end
+
+  def test_scope_is_skipped_when_if_option_is_false
+    @controller.stubs(:restrict_to_only_tall_trees?).returns(false)
+    Tree.expects(:only_tall).never
+    Tree.expects(:all).returns([mock_tree])
+    get :index, :only_tall => 'true'
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ }, current_scopes)
+  end
+
+  def test_scope_is_skipped_when_unless_option_is_true
+    @controller.stubs(:show_all_colors?).returns(true)
+    Tree.expects(:color).never
+    Tree.expects(:all).returns([mock_tree])
+    get :index, :color => 'blue'
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ }, current_scopes)
+  end
+
+  def test_scope_is_called_except_on_index
+    Tree.expects(:shadown_range).with().never
+    Tree.expects(:all).returns([mock_tree])
+    get :index, :shadown_range => 20
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ }, current_scopes)
+  end
+
+  def test_scope_is_called_with_arguments
+    Tree.expects(:color).with('blue').returns(Tree).in_sequence
+    Tree.expects(:all).returns([mock_tree]).in_sequence
+    get :index, :color => 'blue'
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ :color => 'blue' }, current_scopes)
+  end
+
+  def test_multiple_scopes_are_called
+    Tree.expects(:only_tall).with().returns(Tree)
+    Tree.expects(:color).with('blue').returns(Tree)
+    Tree.expects(:all).returns([mock_tree])
+    get :index, :color => 'blue', :only_tall => 'true'
+    assert_equal([mock_tree], assigns(:trees))
+    assert_equal({ :color => 'blue', :only_tall => true }, current_scopes)
+  end
+
+  def test_scope_is_called_with_default_value
+    Tree.expects(:shadown_range).with(10).returns(Tree).in_sequence
+    Tree.expects(:find).with('42').returns(mock_tree).in_sequence
+    get :edit, :id => '42'
+    assert_equal(mock_tree, assigns(:tree))
+    assert_equal({ :shadown_range => 10 }, current_scopes)
+  end
+
+  def test_default_scope_value_can_be_overwritten
+    Tree.expects(:shadown_range).with('20').returns(Tree).in_sequence
+    Tree.expects(:find).with('42').returns(mock_tree).in_sequence
+    get :edit, :id => '42', :shadown_range => '20'
+    assert_equal(mock_tree, assigns(:tree))
+    assert_equal({ :shadown_range => '20' }, current_scopes)
+  end
+
+  def test_scope_with_different_key
+    Tree.expects(:root_type).with('outside').returns(Tree).in_sequence
+    Tree.expects(:find).with('42').returns(mock_tree).in_sequence
+    get :show, :id => '42', :root => 'outside'
+    assert_equal(mock_tree, assigns(:tree))
+    assert_equal({ :root => 'outside' }, current_scopes)
+  end
+
+  def test_scope_with_default_value_as_proc
+    session[:height] = 100
+    Tree.expects(:calculate_height).with(100).returns(Tree).in_sequence
+    Tree.expects(:new).returns(mock_tree).in_sequence
+    get :new
+    assert_equal(mock_tree, assigns(:tree))
+    assert_equal({ :calculate_height => 100 }, current_scopes)
+   end
+
+  protected
+
+    def mock_tree(stubs={})
+      @mock_tree ||= mock(stubs)
+    end
+
+    def current_scopes
+      @controller.send :current_scopes
+    end
+end
+

data/test/test_helper.rb

@@ -0,0 +1,32 @@
+require 'rubygems'
+
+begin
+  gem "test-unit"
+rescue LoadError
+end
+
+begin
+  gem "ruby-debug"
+  require 'ruby-debug'
+rescue LoadError
+end
+
+require 'test/unit'
+require 'mocha'
+
+ENV["RAILS_ENV"] = "test"
+RAILS_ROOT = "anywhere"
+
+require 'active_support'
+require 'action_controller'
+require 'action_controller/test_case'
+require 'action_controller/test_process'
+
+class ApplicationController < ActionController::Base; end
+
+$:.unshift File.expand_path(File.dirname(__FILE__) + '/../lib')
+require 'has_scope'
+
+ActionController::Routing::Routes.draw do |map|
+  map.connect ':controller/:action/:id'
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+name: has_scope
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- "Jos\xC3\xA9 Valim"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-04 00:00:00 -02:00
+default_executable: 
+dependencies: []
+
+description: Maps controller filters to your resource scopes
+email: contact@plataformatec.com.br
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- CHANGELOG.rdoc
+- MIT-LICENSE
+- README.rdoc
+- Rakefile
+- lib/has_scope.rb
+has_rdoc: true
+homepage: http://github.com/plataformatec/has_scope
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Maps controller filters to your resource scopes
+test_files: 
+- test/has_scope_test.rb
+- test/test_helper.rb