muster 0.0.6 → 0.0.7

data/Authors

@@ -0,0 +1,2 @@
+- Chris Laco <claco@chrislaco.com?
+- Nikica Jokić (neektza@gmail.com)

data/Changes

@@ -1,3 +1,15 @@
+= 0.0.7
+
+* Added JoinsExpressions to ActiveRecord Strategy (neektza)
+
+= 0.0.6
+
+* Moved from OpenString to method_missing for dot notation on Results
+
+= 0.0.5
+
+* Added OpenStruct for dot notation on Results
+
 = 0.0.4
 
 * Rack middleware now returns Muster::Results

data/README.md

@@ -52,6 +52,12 @@ Returns options with support for dirctional indicators for use in sorting.
     ?order=name&order=age     #=>  { 'order' => ['name asc', 'age asc'] }
     ?order=name:asc&age:desc  #=>  { 'order' => ['name asc', 'age desc'] }
 
+### JoinsExpression
+
+Returns an ActiveRecord style array of 'joins' options.
+
+    ?joins=author.name,activity  #=>  { 'joins' => [{'author' => 'name'}, 'activity'] }
+
 ### Pagination
 
 Returns options to support pagination with logic for default page size, not-a-number checks and offset calculations.
@@ -64,12 +70,25 @@ Returns options to support pagination with logic for default page size, not-a-nu
 
 Combines many of the strategies above to output ActiveRecord Query interface compatible options.
 
-    ?select=id,name&where=status:new&order=name:desc&page=3&page_size=10
+    ?select=id,name&where=status:new&order=name:desc&joins=author.name,activity&page=3&page_size=10
     
-    { 'select' => ['id', 'name'], 'where' => {'status' => 'new'}, 'order' => 'name desc', 'limit' =>  10, 'offset' => 20, 'pagination' => {:page => 3, :per_page => 10} }
+    {
+      'select' => ['id', 'name'],
+      'where' => {'status' => 'new'},
+      'order' => 'name desc',
+      'limit' =>  10,
+      'offset' => 20,
+      'pagination' => {:page => 3, :per_page => 10},
+      'joins' => [{'author' => 'name'}, 'activity']
+    }
 
     query = env['muster.query']
-    Person.select( query[:select] ).where( query[:where] ).order( query[:order] ).offset( query[:offset] ).limit( query[:limit] )
+    Person.select( query[:select] )
+      .where( query[:where] )
+      .order( query[:order] )
+      .offset( query[:offset] )
+      .limit( query[:limit] )
+      .joins( query[:joins] )
 
 If you are using WillPaginate, you can also pass in :pagination:
 
@@ -127,7 +146,7 @@ You can combine multiple strategies, and their results will be merged
 
 1. Fork it from https://github.com/claco/muster
 2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Added some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request
-
+3. Added an entry in Changes/Authors
+4. Commit your changes (`git commit -am 'Added some feature'`)
+5. Push to the branch (`git push origin my-new-feature`)
+6. Create new Pull Request

data/lib/muster/strategies/active_record.rb

@@ -5,6 +5,7 @@ require 'muster/results'
 require 'muster/strategies/filter_expression'
 require 'muster/strategies/pagination'
 require 'muster/strategies/sort_expression'
+require 'muster/strategies/joins_expression'
 
 module Muster
   module Strategies
@@ -36,11 +37,12 @@ module Muster
         pagination = self.parse_pagination( query_string )
 
         parameters = Muster::Results.new(
-          :select => self.parse_select(query_string),
-          :order  => self.parse_order(query_string),
-          :limit  => pagination[:limit],
-          :offset => pagination[:offset],
-          :where  => self.parse_where(query_string)
+          :select   => self.parse_select(query_string),
+          :order    => self.parse_order(query_string),
+          :limit    => pagination[:limit],
+          :offset   => pagination[:offset],
+          :where    => self.parse_where(query_string),
+          :joins    => self.parse_joins(query_string)
         )
 
         parameters.regular_writer('pagination', pagination[:pagination].symbolize_keys)
@@ -114,6 +116,22 @@ module Muster
         return results[:where] || {}
       end
 
+      # Returns joins clauses for AR queries
+      #
+      # @param query_string [String] the original query string to parse join statements from
+      #
+      # @return [Hash]
+      #
+      # @example
+      #
+      #   value = self.parse_joins('joins=authors')  #=> {'joins' => 'authors'}
+      def parse_joins( query_string )
+        strategy = Muster::Strategies::JoinsExpression.new(:field => :joins)
+        results  = strategy.parse(query_string)
+
+        return results[:joins] || {}
+      end
+
     end
   end
 end

data/lib/muster/strategies/joins_expression.rb

@@ -0,0 +1,84 @@
+require 'muster/strategies/hash'
+
+module Muster
+  module Strategies
+
+    # Query string parsing strategy with additional value handling options for separating filtering expressions
+    #
+    # @example
+    #
+    #   strategy = Muster::Strategies::JoinsExpression.new
+    #   results  = strategy.parse('joins=author.name,activity')  #=>  { 'joins' => [{'author' => 'name'}, 'activity'] }
+    class JoinsExpression < Muster::Strategies::Hash
+
+      # @attribute [r] expression_separator
+      # @return [String,RegEx] when specified, each field value will be split into multiple expressions using the specified separator
+      attr_reader :expression_separator
+
+      # @attribute [r] field_separator
+      # @return [String,RegEx] when specified, each expression will be split into multiple field/values using the specified separator
+      attr_reader :field_separator
+
+      # Create a new Hash parsing strategy
+      #
+      # @param [Hash] options the options available for this method
+      # @option options [optional,Array<Symbol>] :fields when specified, only parse the specified fields
+      #  You may also use :field if you only intend to pass one field
+      # @option options [optional,String,RegEx] :expression_separator (/,\s*/) when specified, splits the query string value into multiple expressions
+      #  You may pass the separator as a string or a regular expression
+      # @option options [optional,String,RegEx] :field_separator (.) when specified, splits the expression value into multiple field/values
+      #  You may pass the separator as a string or a regular expression
+      # @option options [optional,Boolean] :unique_values (true) when true, ensures field values do not contain duplicates
+      #
+      # @example
+      #
+      #   strategy = Muster::Strategies::FilterExpression.new
+      #   strategy = Muster::Strategies::FilterExpression.new(:unique_values => true)
+      def initialize( options={} )
+        super
+
+        @expression_separator = self.options.fetch(:expression_separator, /,\s*/)
+        @field_separator      = self.options.fetch(:field_separator, '.')
+        @unique_values        = self.options.fetch(:unique_values, true)
+      end
+
+      # Processes a query string and returns an array of hashes that represent an ActiveRecord joins expression
+      #
+      # @param query_string [String] the query string to parse
+      #
+      # @return [Muster::Results]
+      #
+      # @example
+      #   
+      #   results = strategy.parse('joins=author.name,activity')  #=>  { 'joins' => [{'author' => 'name'}, 'activity'] }
+      def parse( query_string )
+        parameters = Muster::Results.new( self.fields_to_parse(query_string) )
+
+        parameters.each do |key, value|
+          value = value.uniq.first if self.unique_values == true && value.instance_of?(Array)
+          parameters[key] = self.make_nested_hash(value)
+        end
+      end
+
+      protected
+      # Converts the array that represents the value to a nested hash
+      #
+      # @param value [Array] the value to convert
+      #
+      # @return [String,Array] An array of nested a Hash / Hashes
+      #
+      # @example
+      #
+      #   value = self.make_nested_hash('activity,author.country.name')  #=> ['activity', {'author' => {'country' => 'name'}}]
+      def make_nested_hash( value )
+        expressions = value.split(expression_separator)
+        expressions.map do |e| 
+          fields = e.split(field_separator)
+          fields[0..-2].reverse.reduce(fields.last) { |a, n| { n => a } }
+        end
+      end
+
+    end
+  end
+end
+

data/lib/muster/version.rb

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

data/spec/muster/strategies/active_record_spec.rb

@@ -6,7 +6,7 @@ describe Muster::Strategies::ActiveRecord do
 
   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 == {"select"=>[], "order"=>[], "limit"=>30, "offset"=>nil, "where"=>{}, "joins"=>{}, "pagination"=>{:page=>1, :per_page=>30}}
       subject.parse('').should be_an_instance_of(Muster::Results)
     end
 
@@ -49,6 +49,24 @@ describe Muster::Strategies::ActiveRecord do
       end
     end
 
+    context 'joins' do
+      it 'returns single value in Array' do
+        subject.parse('joins=author')[:joins].should eq ['author']
+      end
+      
+      it 'returns multiple values in Array' do
+        subject.parse('joins=author,voter')[:joins].should eq ['author', 'voter']
+      end
+
+      it 'returns a nested hash of separated values' do
+        subject.parse('joins=author.country.name')[:joins].should eq [{'author' => { 'country' => 'name'}}]
+      end
+      
+      it 'returns an array of nested hashes' do
+        subject.parse('joins=author.country.name,activity.rule')[:joins].should eq [{'author' => { 'country' => 'name'}}, {'activity' => 'rule'}]
+      end
+    end
+
     context 'pagination' do
       it 'returns default will paginate compatible pagination' do
         subject.parse('')[:pagination].should == {:page => 1, :per_page => 30}

data/spec/muster/strategies/joins_expression_spec.rb

@@ -0,0 +1,118 @@
+require 'spec_helper'
+
+describe Muster::Strategies::JoinsExpression do
+  let(:options) { {} }
+  subject { Muster::Strategies::JoinsExpression.new(options) }
+
+  describe '#parse' 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
+        subject.parse('joins=author,author.foop').should eq({ "joins" => ["author", {"author" => "foop"}] })
+      end
+
+      it 'hash supports indifferent key access' do
+        hash = subject.parse('joins=author,activity')
+        hash[:joins][0].should eq('author')
+        hash[:joins][1].should eq('activity')
+      end
+
+      it 'combines multiple expressions into an array' do
+        subject.parse('joins=author,activity').should == { 'joins' => ['author', 'activity'] }
+      end
+
+      it 'discards non unique values' do
+        subject.parse('joins=author&joins=author').should == { 'joins' => ['author'] }
+      end
+    end
+
+    context 'with :expression_separator option' do
+      context 'as regex' do
+        before do
+          options[:expression_separator] = /\|\s*/
+        end
+
+        it 'converts comma separated value into Array' do
+          subject.parse('joins=author|activity').should == { 'joins' => ['author', 'activity'] }
+        end
+
+        it 'ignores spaces after a separator' do
+          subject.parse('joins=author|%20  activity').should == { 'joins' => ['author', 'activity'] }
+        end
+      end
+
+      context 'as string' do
+        before do
+          options[:expression_separator] = '|'
+        end
+
+        it 'converts comma separated value into Array' do
+          subject.parse('joins=author|activity|rule').should == { 'joins' => ['author', 'activity', 'rule'] }
+        end
+      end
+    end
+
+    context 'with :field_separator option' do
+      context 'as regex' do
+        before { options[:field_separator] = /\s*:\s*/ }
+
+        it 'splits field from values' do
+          subject.parse('joins=author:country:name').should == { 'joins' => [{'author' => {'country' => 'name'}}] }
+        end
+
+        it 'ignores spaces after field' do
+          subject.parse('joins=author : country').should == { 'joins' => [{'author' => 'country'}] }
+        end
+      end
+
+      context 'as string' do
+        before { options[:field_separator] = ':' }
+
+        it 'converts comma separated value into Array' do
+          subject.parse('joins=author:country').should == { 'joins' => [{'author' => 'country'}] }
+        end
+      end
+    end
+
+    context 'with :fields option' do
+      context 'as symbol' do
+        before { options[:field] = :includes }
+
+        it 'fields returns expressions for the key specified' do
+          subject.parse('includes=author').should == { 'includes' => ['author'] }
+        end
+      end
+
+      context 'as Array of symbols' do
+        before { options[:fields] = [:includes, :joins] }
+
+        it 'fields returns expressions for the keys specified' do
+          subject.parse('joins=author&includes=activity').should == { 'joins' => ['author'], 'includes' => ['activity'] }
+        end
+      end
+
+      context 'as string' do
+        before { options[:field] = 'includes' }
+
+        it 'fields returns expressions for the key specified' do
+          subject.parse('includes=author').should == { 'includes' => ['author'] }
+        end
+      end
+
+      context 'as Array of strings' do
+        before { options[:fields] = ['includes', 'joins'] }
+
+        it 'fields returns expressions for the keys specified' do
+          subject.parse('includes=author&joins=activity').should == { 'includes' => ['author'], 'joins' => ['activity'] }
+        end
+      end
+    end
+
+  end
+end
+

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: muster
 version: !ruby/object:Gem::Version
-  version: 0.0.6
+  version: 0.0.7
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-31 00:00:00.000000000 Z
+date: 2013-03-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -134,6 +134,7 @@ files:
 - .gitignore
 - .rspec
 - .yardopts
+- Authors
 - Changes
 - Gemfile
 - LICENSE
@@ -146,6 +147,7 @@ files:
 - lib/muster/strategies/active_record.rb
 - lib/muster/strategies/filter_expression.rb
 - lib/muster/strategies/hash.rb
+- lib/muster/strategies/joins_expression.rb
 - lib/muster/strategies/pagination.rb
 - lib/muster/strategies/rack.rb
 - lib/muster/strategies/sort_expression.rb
@@ -156,6 +158,7 @@ files:
 - spec/muster/strategies/active_record_spec.rb
 - spec/muster/strategies/filter_expression_spec.rb
 - spec/muster/strategies/hash_spec.rb
+- spec/muster/strategies/joins_expression_spec.rb
 - spec/muster/strategies/pagination_spec.rb
 - spec/muster/strategies/sort_expression_spec.rb
 - spec/spec_helper.rb
@@ -189,6 +192,7 @@ test_files:
 - spec/muster/strategies/active_record_spec.rb
 - spec/muster/strategies/filter_expression_spec.rb
 - spec/muster/strategies/hash_spec.rb
+- spec/muster/strategies/joins_expression_spec.rb
 - spec/muster/strategies/pagination_spec.rb
 - spec/muster/strategies/sort_expression_spec.rb
 - spec/spec_helper.rb