periscope-activerecord 1.0.0

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2011 Steve Richert
+
+MIT License
+
+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.md

@@ -0,0 +1,132 @@
+# Periscope [![Build Status](https://secure.travis-ci.org/laserlemon/periscope.png)](http://travis-ci.org/laserlemon/periscope) [![Dependency Status](https://gemnasium.com/laserlemon/periscope.png)](https://gemnasium.com/laserlemon/periscope)
+
+Periscope provides a simple way to chain scopes on your models and to open those scopes up to your users.
+
+## The Problem
+
+More often than not, the index action in a RESTful Rails controller is expected to do a lot more than simply return all the records for a given model. We ask it to do all sorts of stuff like filtering, sorting and paginating results. Of course, this is typically done using _scopes_.
+
+But it can get ugly building long, complicated chains of scopes in the controller, especially when you try to give your users control over the scoping. Picture this:
+
+```ruby
+def index
+  @articles = Article.scoped
+  @articles = @articles.published_after(params[:published_after]) if params.key?(:published_after)
+  @articles = @articles.published_before(params[:published_before]) if params.key?(:published_before)
+end
+```
+
+You can imagine how bad this would get if more than two scopes were involved.
+
+## The Solution
+
+With Periscope, you can have this instead:
+
+```ruby
+def index
+  @articles = Article.periscope(request.query_parameters)
+end
+```
+
+The `periscope` method will find keys in your params matching your scope names and chain your scopes for you.
+
+**Note:** We're using `request.query_parameters` so that we can exclude our controller and action params. `request.query_parameters` will just return the params that appear in the query string.
+
+## But Wait!
+
+"What if I don't want to make all my scopes publicly accessible?"
+
+Within your model you can use the `scope_accessible` method to specify which scopes you want Periscope to honor.
+
+```ruby
+class User < ActiveRecord::Base
+  scope :gender, lambda{|g| where(gender: g) }
+  scope :makes, lambda{|s| where('salary >= ?', s) }
+
+  scope_accessible :gender
+end
+```
+
+And in your controller:
+
+```ruby
+class UsersController < ApplicationController
+  def index
+    @users = User.periscope(request.query_parameters)
+  end
+end
+```
+
+Requests to `/users?gender=male` will filter results to only male users. But a request to `/users?makes=1000000` will return all users, silently ignoring the protected scope.
+
+By default, all scopes are protected.
+
+## There's More!
+
+### Custom Parameter Parsing
+
+Sometimes the values you get from the query parameters aren't quite good enough. They may need to be massaged in order to work with your scopes and class methods. In those cases, you can provide a `:parser` option to your `scope_accessible` method.
+
+Parsers must respond to the `call` method, receiving the raw query parameter and returning an array of arguments to pass to the scope or class method.
+
+```ruby
+class User < ActiveRecord::Base
+  scope :gender, lambda{|g| where(gender: g) }
+
+  scope_accessible :gender, parser: lambda{|g| [g.downcase] }
+end
+```
+
+### On/Off Scopes
+
+But not all scopes accept arguments. For scopes that you want to toggle on or off, you can set a `:boolean => true` option. Whenever the received parameter is truthy, the scope will be applied. Otherwise, it will be skipped.
+
+```ruby
+class User < ActiveRecord::Base
+  scope :male, where(gender: 'male')
+  scope :female, where(gender: 'female')
+
+  scope_accessible :male, :female, boolean: true
+end
+```
+
+### Custom Method Names
+
+Sometimes the query parameters you want to open up to your users may collide with existing method names or reserved Ruby words. In order to avoid collision, you can set a `:method` option to specify what method to use for a query parameter.
+
+```ruby
+class Project < ActiveRecord::Base
+  scope_accessible :begin, method: :begins_after
+  scope_accessible :end, method: :ends_before
+
+  def self.begins_after(date)
+    where('begins_at >= ?', date)
+  end
+
+  def self.ends_before(date)
+    where('ends_at <= ?', date)
+  end
+end
+```
+
+Alternatively, you can set `:prefix` and/or `:suffix` options, which will be applied to the query parameter name to determine the corresponding method name.
+
+```ruby
+class Project < ActiveRecord::Base
+  scope_accessible :begin, :end, suffix: '_date'
+
+  def self.begin_date(date)
+    where('begins_at >= ?', date)
+  end
+
+  def self.end_date(date)
+    where('ends_at <= ?', date)
+  end
+end
+```
+
+## This sucks. How can I make it better?
+
+1. Fork it.
+2. Make it better.
+3. Send me a pull request.

data/lib/periscope-activerecord.rb

@@ -0,0 +1 @@
+require 'periscope/adapters/active_record'

data/lib/periscope/adapters/active_record.rb

@@ -0,0 +1,18 @@
+require 'periscope'
+require 'active_record'
+
+module Periscope
+  module Adapters
+    module ActiveRecord
+      include Periscope
+
+      private
+
+      def periscope_default_scope
+        scoped
+      end
+    end
+  end
+end
+
+ActiveRecord::Base.extend(Periscope::Adapters::ActiveRecord)

data/periscope-activerecord.gemspec

@@ -0,0 +1,29 @@
+# encoding: utf-8
+
+Gem::Specification.new do |gem|
+  gem.name    = 'periscope-activerecord'
+  gem.version = '1.0.0'
+
+  gem.authors     = ['Steve Richert']
+  gem.email       = ['steve.richert@gmail.com']
+  gem.description = %(Push your ActiveRecord models' scopes up to the surface)
+  gem.summary     = gem.description
+  gem.homepage    = 'https://github.com/laserlemon/periscope'
+
+  gem.add_dependency 'activerecord', '~> 3.0'
+  gem.add_dependency 'periscope', '~> 1.0'
+
+  gem.add_development_dependency 'database_cleaner', '~> 0.8'
+  gem.add_development_dependency 'factory_girl', '>= 2', '< 4'
+  gem.add_development_dependency 'rake', '~> 0.9'
+  gem.add_development_dependency 'rspec', '~> 2.0'
+  gem.add_development_dependency 'sqlite3'
+
+  gem.files = %w(
+    LICENSE
+    lib/periscope-activerecord.rb
+    lib/periscope/adapters/active_record.rb
+    periscope-activerecord.gemspec
+    README.md
+  )
+end

metadata

@@ -0,0 +1,174 @@
+--- !ruby/object:Gem::Specification
+name: periscope-activerecord
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+  prerelease: 
+platform: ruby
+authors:
+- Steve Richert
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2012-06-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: periscope
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: database_cleaner
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: factory_girl
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - <
+      - !ruby/object:Gem::Version
+        version: '4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - <
+      - !ruby/object:Gem::Version
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '0.9'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Push your ActiveRecord models' scopes up to the surface
+email:
+- steve.richert@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- lib/periscope-activerecord.rb
+- lib/periscope/adapters/active_record.rb
+- periscope-activerecord.gemspec
+- README.md
+homepage: https://github.com/laserlemon/periscope
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2923427527483607329
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+      segments:
+      - 0
+      hash: 2923427527483607329
+requirements: []
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Push your ActiveRecord models' scopes up to the surface
+test_files: []