muster 0.0.2 → 0.0.3

data/Changes

@@ -1,3 +1,7 @@
+= 0.0.3
+
+* Added Muster::Results to help filter strategy results values
+
 = 0.0.2
 
 * rack env['muster.query'] now supports indifferent access

data/lib/muster.rb

@@ -1,3 +1,4 @@
 require 'muster/version'
 require 'muster/strategies'
+require 'muster/results'
 require 'muster/rack'

data/lib/muster/results.rb

@@ -0,0 +1,177 @@
+require 'active_support/core_ext/array/wrap'
+require 'active_support/core_ext/object/blank'
+require 'active_support/hash_with_indifferent_access'
+
+module Muster
+
+  # Query parsed results helper class
+  #
+  # As with most Muster classes, all hashes returned and options specified support with indifferent access.
+  #
+  # @param data [Hash] the hash of query string results after parsing to load
+  #
+  # @example
+  #
+  #   data = { :select => [:id, :name, :created_at] }
+  #   results = Muster::Results.new(data)
+  #
+  #   # Filter values one at a time
+  #   results.data                                     #=> { 'select' => [:id, :name, :created_at] }
+  #   results.filter(:select, :only => [:id, :name])   #=> [:id, :name]
+  #   results.filter(:select, :except => :created_at)  #=> [:id, :name]
+  #   results.filter(:page, 1)                         #=> 1
+  #   results.filter(:page)                            #=> KeyError: :page does not exist
+  #
+  #   # Filter values in one pass
+  #   results.add_filter(:select, :only => [:id, :name])
+  #   results.add_filter(:page, 1)
+  #   results.filtered                                 #=> { 'select' => [:id, :name], 'page' => 1 }
+  class Results < ActiveSupport::HashWithIndifferentAccess
+
+    # @attribute [r] data
+    # @return [Hash] raw data specified during initialization
+    attr_reader :data
+
+    # @attribute [r] filters
+    # @return [Hash] filters specified using {#add_filter}
+    attr_reader :filters
+
+    # Create a new results instance
+    #
+    # @param data [Hash] the raw parsed query string data
+    # @param [Hash] options the options available for this method
+    #  They'e aren't any options yet. :-)
+    #
+    # @example
+    #
+    #   data = { :select => [:id, :name, :created_at] }
+    #   results = Muster::Results.new(data)
+    def initialize( data, options={} )
+      super(data)
+
+      @data = data
+      @filters = {}
+    end
+
+    # Add a filter to be applied to the data in {#filtered} results
+    #
+    # @param key [String,Symbol] the key of the values in {#data} to filter
+    # @param [optional, Hash] options the options available for this filter
+    # @option options [optional] :only when specified, only return the matching values
+    #   If you specify a single value, a single value will be returned
+    #   If you specify an Array of values, an Array will be returned, even if only one value matches
+    # @option options [optional] :except return all values except the ones given here
+    #   If the raw data value is a single value, a single value will be returned
+    #   If the raw data value is an Array, and array will be returned, even if all values are excluded
+    #   If nothing was excluded, the raw value is returned as-is
+    #
+    # If you pass a scalar value instead of a Hash into options, it will be treated as the default, just like
+    # Hash#fetch does.
+    #
+    # If you pass nothing into the options argument, it will return all values if the key exists or raise
+    # a KeyError like Hash#fetch.
+    #
+    # @return [void]
+    #
+    # @example
+    #
+    #   results.add_filter(:select, :only => [:id, :name]
+    #   results.add_filter(:select, :except => [:id]
+    #   results.add_filter(:page, 1)
+    def add_filter( key, *options )
+      self.filters[key] = options
+    end
+
+    # Returns the raw data with all of the filters applied
+    #
+    # If no filters were added, this method simply returns self.
+    #
+    # @return [Muster::Results]
+    #
+    # @example
+    #
+    #   results.add_filter(:select, :only => [:id, :name]
+    #   results.add_dilter(:page, 1)
+    #   results.filtered   #=> { 'select' => [:id, :name], 'page' => 1 }
+    def filtered
+      return self if self.filters.empty?
+
+      filtered_results = self.filters.inject( {} ) do |results, (key, options)|
+        results[key] = self.filter( key, *options )
+
+        results
+      end
+
+      return self.class.new(filtered_results)
+    end
+
+    # Filters and returns the raw data values for the specifid key and options
+    #
+    # @param key [String,Symbol] the key of the values in {#data} to filter
+    # @param [optional, Hash] options the options available for this filter
+    # @option options [optional] :only when specified, only return the matching values
+    #   If you specify a single value, a single value will be returned
+    #   If you specify an Array of values, an Array will be returned, even if only one value matches
+    # @option options [optional] :except return all values except the ones given here
+    #   If the raw data value is a single value, a single value will be returned
+    #   If the raw data value is an Array, and array will be returned, even if all values are excluded
+    #   If nothing was excluded, the raw value is returned as-is
+    #
+    # If you pass a scalar value instead of a Hash into options, it will be treated as the default, just like
+    # Hash#fetch does.
+    #
+    # If you pass nothing into the options argument, it will return all values if the key exists or raise
+    # a KeyError like Hash#fetch.
+    #
+    # @return [void]
+    #
+    # @example
+    #
+    #   data = { :select => [:id, :name, :created_at]
+    #   results = Muster::Results.new(data)
+    #   results.filter(:select)                           #=> [:id, :name, :created_at]
+    #   results.filter(:select, :only => :name)           #=> :name
+    #   results.filter(:select, :only => [:other, :name]  #=> [:name]
+    #   results.filter(:other, :default)                  #=> :default
+    #   results.filter(:other)                            #=> KeyError
+    def filter( key, *options )
+      if options.present? && options.first.instance_of?(Hash)
+        options = options.first.with_indifferent_access
+
+        if options.has_key?(:only)
+          return filter_only_values( key, options[:only] )
+        elsif options.has_key?(:except)
+          return filter_excluded_values( key, options[:except] )
+        end
+      else
+        return self.fetch(key, *options)
+      end
+    end
+
+    private
+
+    def filter_excluded_values( key, excluded )
+      value = self[key]
+      excluded = Array.wrap(excluded)
+
+      if value.instance_of?(Array)
+        return value - excluded
+      elsif excluded.include?(value)
+        return nil
+      else
+        return value
+      end
+    end
+
+    def filter_only_values( key, allowed )
+      values = Array.wrap( self[key] )
+
+      if allowed.instance_of?(Array)
+        return values & allowed
+      elsif values.include?(allowed)
+        return allowed
+      end
+    end
+
+  end
+end

data/lib/muster/strategies/active_record.rb

@@ -1,6 +1,7 @@
 require 'active_support/core_ext/array/wrap'
 require 'active_support/hash_with_indifferent_access'
 require 'muster/strategies/hash'
+require 'muster/results'
 require 'muster/strategies/filter_expression'
 require 'muster/strategies/pagination'
 require 'muster/strategies/sort_expression'
@@ -24,7 +25,7 @@ module Muster
       #
       # @param query_string [String] the query string to parse
       #
-      # @return [Hash]
+      # @return [Muster::Results]
       #
       # @example
       #   
@@ -34,7 +35,7 @@ module Muster
       def parse( query_string )
         pagination = self.parse_pagination( query_string )
 
-        parameters = ActiveSupport::HashWithIndifferentAccess.new(
+        parameters = Muster::Results.new(
           :select => self.parse_select(query_string),
           :order  => self.parse_order(query_string),
           :limit  => pagination[:limit],

data/lib/muster/strategies/filter_expression.rb

@@ -1,4 +1,5 @@
 require 'active_support/core_ext/array/wrap'
+require 'muster/results'
 require 'muster/strategies/hash'
 
 module Muster
@@ -49,18 +50,20 @@ module Muster
       #
       # @param query_string [String] the query string to parse
       #
-      # @return [Hash]
+      # @return [Muster::Results]
       #
       # @example
       #   
       #   results = strategy.parse('where=id:1&name:Bob')  #=>  { 'where' => {'id' => '1', 'name' => 'Bob'} }
       def parse( query_string )
-        parameters  = self.fields_to_parse(query_string)
+        parameters = Muster::Results.new( self.fields_to_parse(query_string) )
 
         parameters.each do |key, value|
           parameters[key] = self.separate_expressions(value)
           parameters[key] = self.separate_fields(parameters[key])
         end
+
+        return parameters
       end
 
       protected

data/lib/muster/strategies/hash.rb

@@ -45,7 +45,7 @@ module Muster
       #
       # @param query_string [String] the query string to parse
       #
-      # @return [Hash]
+      # @return [Muster::Results]
       #
       # @example
       #   

data/lib/muster/strategies/pagination.rb

@@ -1,4 +1,5 @@
 require 'active_support/core_ext/hash/slice'
+require 'muster/results'
 require 'muster/strategies/hash'
 
 module Muster
@@ -43,7 +44,7 @@ module Muster
       #
       # @param query_string [String] the query string to parse
       #
-      # @return [Hash]
+      # @return [Muster::Results]
       #
       # @example
       #   
@@ -61,10 +62,10 @@ module Muster
         parameters = parameters.merge(:pagination => {:page => page, :per_page => page_size}, :limit => page_size, :offset => offset)
         
         if self.fields.present?
-          parameters = parameters.slice(*self.fields).with_indifferent_access
+          parameters = parameters.slice(*self.fields)
         end
 
-        parameters
+        return Muster::Results.new(parameters)
       end
 
       protected

data/lib/muster/strategies/rack.rb

@@ -2,6 +2,7 @@ require 'active_support/core_ext/object/blank'
 require 'active_support/core_ext/hash/indifferent_access'
 require 'active_support/core_ext/array/wrap'
 require 'rack/utils'
+require 'muster/results'
 
 module Muster
   module Strategies
@@ -43,13 +44,13 @@ module Muster
       #
       # @param query_string [String] the query string to parse
       #
-      # @return [Hash]
+      # @return [Muster::Results]
       #
       # @example
       #   
       #   results = strategy.parse('name=value&choices=1&choices=1')  #=>  { 'name' => 'value', 'choices' => ['1', '2'] }
       def parse( query_string )
-        self.fields_to_parse(query_string)
+        Muster::Results.new( self.fields_to_parse(query_string) )
       end
 
       protected

data/lib/muster/version.rb

@@ -1,4 +1,4 @@
 module Muster
   # Current version of Muster
-  VERSION = "0.0.2"
+  VERSION = "0.0.3"
 end

data/spec/muster/results_spec.rb

@@ -0,0 +1,87 @@
+require 'spec_helper'
+
+describe Muster::Results do
+  let(:data)        { {:name => [1, 2, 3]} }
+  let(:options)     { {} }
+  subject(:results) { Muster::Results.new(data, options) }
+
+  its(:data) { should eq data }
+
+  describe '#filter' do
+    context 'without options hash' do
+      it 'returns the same as fetch' do
+        results.filter(:name).should eq [1,2,3]
+      end
+
+      it 'supports a default value' do
+        results.filter(:bogons, :default).should eq :default
+      end
+
+      it 'throws exception without default' do
+        expect{ results.filter(:bogons) }.to raise_error(KeyError)
+      end
+    end
+
+    context 'with options hash' do
+      context 'with :except option' do
+        context 'with data value as Array' do
+          before { data[:name] = [1,2,3] }
+
+          it 'returns values not listed in :except as array' do
+            results.filter(:name, :except => [2]).should eq [1,3]
+          end
+
+          it 'returns values not listed in :except as scalar' do
+            results.filter(:name, :except => 2).should eq [1,3]
+          end
+        end
+
+        context 'with data value as scalar' do
+          before { data[:name] = 1 }
+
+          it 'returns value not listed in :except as scalar' do
+            results.filter(:name, :except => 2).should eq 1
+          end
+
+          it 'returns value not listed in :except as scalar' do
+            results.filter(:name, :except => 1).should be_nil
+          end
+        end
+      end
+
+      context 'with :only option' do
+        it 'returns value listed in :only as scalar' do
+          results.filter(:name, :only => 1).should eq 1
+        end
+
+        it 'returns values listed in :only as array' do
+          results.filter(:name, :only => [1,3]).should eq [1,3]
+        end
+      end
+    end
+  end
+
+  describe '#filtered' do
+    context 'without filters' do
+      it 'returns self' do
+        results.filtered.object_id.should == results.object_id
+      end
+
+      its(:filters) { should be_an_instance_of(Hash) }
+      its(:filters) { should be_empty }
+    end
+
+    context 'with filters' do
+      it 'applies filters to data' do
+        results.add_filter(:name, :only => [2, 3])
+        results.add_filter(:page, 1)
+        results.add_filter(:order, :only => [:first])
+        results.add_filter(:where, :only => :second)
+
+        filtered_results = results.filtered
+        filtered_results.should be_an_instance_of(Muster::Results)
+        filtered_results.should == {"name"=>[2, 3], "page"=>1, "order"=>[], "where"=>nil}
+      end
+    end
+  end
+end

data/spec/muster/strategies/active_record_spec.rb

@@ -5,6 +5,11 @@ describe Muster::Strategies::ActiveRecord do
   subject { Muster::Strategies::ActiveRecord.new(options) }
 
   describe '#parse' do
+    it 'returns a Muster::Results instance' do
+      subject.parse('').should == {"select"=>[], "order"=>[], "limit"=>30, "offset"=>nil, "where"=>{}, "pagination"=>{:page=>1, :per_page=>30}}
+      subject.parse('').should be_an_instance_of(Muster::Results)
+    end
+
     context 'selects' do
       it 'returns single value as Array' do
         subject.parse('select=id')[:select].should == ['id']

data/spec/muster/strategies/filter_expression_spec.rb

@@ -9,6 +9,7 @@ describe Muster::Strategies::FilterExpression do
     context 'by default' do
       it 'returns empty hash for empty query string' do
         subject.parse('').should == {}
+        subject.parse('').should be_an_instance_of(Muster::Results)
       end
 
       it 'returns hash of all key/value pairs' do

data/spec/muster/strategies/hash_spec.rb

@@ -9,6 +9,7 @@ describe Muster::Strategies::Hash do
     context 'by default' do
       it 'returns empty hash for empty query string' do
         subject.parse('').should == {}
+        subject.parse('').should be_an_instance_of(Muster::Results)
       end
 
       it 'returns hash of all key/value pairs' do

data/spec/muster/strategies/pagination_spec.rb

@@ -5,6 +5,11 @@ describe Muster::Strategies::Pagination do
   subject { Muster::Strategies::Pagination.new(options) }
 
   describe '#parse' do
+    it 'returns a Muster::Results instance' do
+      subject.parse('').should == {"pagination"=>{"page"=>1, "per_page"=>30}, "limit"=>30, "offset"=>nil}
+      subject.parse('').should be_an_instance_of(Muster::Results)
+    end
+
     context 'by default' do
       it 'returns default hash for empty query string' do
         subject.parse('').should == {'pagination' => {'page' => 1, 'per_page' => 30}, 'offset' => nil, 'limit' => 30}

data/spec/muster/strategies/sort_expression_spec.rb

@@ -9,6 +9,7 @@ describe Muster::Strategies::SortExpression do
     context 'by default' do
       it 'returns empty hash for empty query string' do
         subject.parse('').should == {}
+        subject.parse('').should be_an_instance_of(Muster::Results)
       end
 
       it 'returns hash of all key/value pairs' do

data/spec/spec_helper.rb

@@ -1,5 +1,7 @@
-require 'simplecov'
-SimpleCov.start
+if ENV['COVERAGE']
+  require 'simplecov'
+  SimpleCov.start
+end
 
 require 'rack/mock'
 require 'muster'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: muster
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
   prerelease: 
 platform: ruby
 authors:
@@ -9,11 +9,11 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-10-05 00:00:00.000000000 Z
+date: 2012-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
-  requirement: &70144206747920 !ruby/object:Gem::Requirement
+  requirement: &70287572649780 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -21,10 +21,10 @@ dependencies:
         version: '3.0'
   type: :runtime
   prerelease: false
-  version_requirements: *70144206747920
+  version_requirements: *70287572649780
 - !ruby/object:Gem::Dependency
   name: rack
-  requirement: &70144206744660 !ruby/object:Gem::Requirement
+  requirement: &70287572649080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '1.4'
   type: :runtime
   prerelease: false
-  version_requirements: *70144206744660
+  version_requirements: *70287572649080
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &70144206743960 !ruby/object:Gem::Requirement
+  requirement: &70287572648560 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -43,10 +43,10 @@ dependencies:
         version: 2.11.0
   type: :development
   prerelease: false
-  version_requirements: *70144206743960
+  version_requirements: *70287572648560
 - !ruby/object:Gem::Dependency
   name: redcarpet
-  requirement: &70144206743440 !ruby/object:Gem::Requirement
+  requirement: &70287572648080 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '2.1'
   type: :development
   prerelease: false
-  version_requirements: *70144206743440
+  version_requirements: *70287572648080
 - !ruby/object:Gem::Dependency
   name: simplecov
-  requirement: &70144206742920 !ruby/object:Gem::Requirement
+  requirement: &70287572647660 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *70144206742920
+  version_requirements: *70287572647660
 - !ruby/object:Gem::Dependency
   name: yard
-  requirement: &70144206601360 !ruby/object:Gem::Requirement
+  requirement: &70287572647100 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -76,7 +76,7 @@ dependencies:
         version: 0.8.2
   type: :development
   prerelease: false
-  version_requirements: *70144206601360
+  version_requirements: *70287572647100
 description: Muster is a gem that turns query strings of varying formats into data
   structures suitable for easier consumption in AR/DataMapper scopes and queries.
 email:
@@ -95,6 +95,7 @@ files:
 - Rakefile
 - lib/muster.rb
 - lib/muster/rack.rb
+- lib/muster/results.rb
 - lib/muster/strategies.rb
 - lib/muster/strategies/active_record.rb
 - lib/muster/strategies/filter_expression.rb
@@ -105,6 +106,7 @@ files:
 - lib/muster/version.rb
 - muster.gemspec
 - spec/muster/rack_spec.rb
+- spec/muster/results_spec.rb
 - spec/muster/strategies/active_record_spec.rb
 - spec/muster/strategies/filter_expression_spec.rb
 - spec/muster/strategies/hash_spec.rb
@@ -137,6 +139,7 @@ specification_version: 3
 summary: Muster various query string formats into a more reusable data structure.
 test_files:
 - spec/muster/rack_spec.rb
+- spec/muster/results_spec.rb
 - spec/muster/strategies/active_record_spec.rb
 - spec/muster/strategies/filter_expression_spec.rb
 - spec/muster/strategies/hash_spec.rb