muster 0.0.1

data/lib/muster/strategies/hash.rb

@@ -0,0 +1,93 @@
+require 'active_support/core_ext/object/blank'
+require 'active_support/core_ext/array/wrap'
+require 'muster/strategies/rack'
+
+module Muster
+  module Strategies
+
+    # Query string parsing strategy with additional value handling options for separating values and uniqueness
+    #
+    # @example
+    #
+    #   strategy = Muster::Strategies::Hash.new(:unique_values => true, :value_separator => ',')
+    #   results  = strategy.parse('name=value&choices=1,2,1')  #=>  { 'name' => 'value', 'choices' => ['1', '2'] }
+    class Hash < Muster::Strategies::Rack
+
+      # @attribute [r] value_separator
+      # @return [String,RegEx] when specified, each field value will be split into multiple values using the specified separator
+      attr_reader :value_separator
+
+      # @attribute [r] unique_values
+      # @return [Boolean] when specified, ensures a fields values do not contain duplicates
+      attr_reader :unique_values
+
+      # 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] :value_separator (/,\s*/) when specified, splits the field value into multiple 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::Hash.new(:fields => [:name, :state], :value_separator => '|')
+      #   strategy = Muster::Strategies::Hash.new(:unique_values => false)
+      def initialize( options={} )
+        super
+
+        @unique_values   = self.options.fetch(:unique_values, true)
+        @value_separator = self.options.fetch(:value_separator, /,\s*/)
+      end
+
+      # Processes a query string and returns a hash of its fields/values
+      #
+      # @param query_string [String] the query string to parse
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   
+      #   results = strategy.parse('name=value&choices=1,2')  #=>  { 'name' => 'value', 'choices' => ['1', '2'] }
+      def parse( query_string )
+        parameters = super
+
+        parameters.each do |key, value|
+          if self.value_separator.present?
+            parameters[key] = self.separate_values(value)
+          end
+
+          if self.unique_values == true && value.instance_of?(Array)
+            parameters[key].uniq!
+          end
+        end
+
+        return parameters
+      end
+
+      protected
+
+      # Separates values into an Array of values using :values_separator
+      #
+      # @param value [String,Array] the original query string field value to separate
+      #
+      # @return [String,Array] String if a single value exists, Array otherwise
+      #
+      # @example
+      #
+      #   value = self.separate_values('1')    #=> '1'
+      #   value = self.separate_values('1,2')  #=>  ['1', '2']
+      def separate_values( value )
+        values = Array.wrap(value)
+
+        values = values.map do |value|
+          value.split(self.value_separator)
+        end.flatten
+
+        return (values.size > 1) ? values : value
+      end
+
+    end
+  end
+end

data/lib/muster/strategies/pagination.rb

@@ -0,0 +1,111 @@
+require 'active_support/core_ext/hash/slice'
+require 'muster/strategies/hash'
+
+module Muster
+  module Strategies
+
+    # Query string parsing strategy with logic to handle pagination options
+    #
+    # @example
+    #
+    #   strategy = Muster::Strategies::Pagination.new
+    #   results  = strategy.parse('page=3&per_page=10')  #=>  { 'pagination' => {'page' => 3, 'per_page' => 10}, 'limit' => 10, 'offset' => 20 }
+    class Pagination < Muster::Strategies::Rack
+    
+      # @attribute [r] default_page_size
+      # @return [Fixnum] when specified, will override the default page size of 30 when no page_size is parsed
+      attr_accessor :default_page_size
+
+      # Create a new Pagination 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] :value_separator (/,\s*/) when specified, splits the field value into multiple 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
+      # @option options [options,Fixnum] :default_page_size (30) when specified, the default page size to use when no page size is parsed
+      #
+      # @example
+      #
+      #   strategy = Muster::Strategies::Pagination.new
+      #   strategy = Muster::Strategies::Pagination.new(:default_page_size => 10)
+      def initialize( options={} )
+        super
+
+        self.default_page_size = self.options[:default_page_size].to_i
+        if self.default_page_size < 1
+          self.default_page_size = 30
+        end
+      end
+
+      # Processes a query string and returns a hash of its fields/values
+      #
+      # @param query_string [String] the query string to parse
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   
+      #   results = strategy.parse('page=3&per_page=10')  #=>  { 'pagination' => {'page' => 3, 'per_page' => 10}, 'limit' => 10, 'offset' => 20 }
+      def parse( query_string )
+        parameters = self.parse_query_string(query_string)
+
+        page = self.parse_page(parameters)
+        page_size = self.parse_page_size(parameters)
+
+
+        offset = (page - 1) * page_size
+        offset = nil if offset < 1
+
+        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
+        end
+
+        parameters
+      end
+
+      protected
+
+      # Returns the current page for the current query string.
+      #
+      # If page is not specified, or is not a positive number, 1 will be returned instead.
+      #
+      # @param parameters [Hash] the parameters parsed from the query string
+      #
+      # @return [Fixnum]
+      #
+      # @example
+      #
+      #   page = self.parse_page(:page => 2)    #=>  2
+      #   page = self.parse_page(:page => nil)  #=>  1
+      def parse_page( parameters )
+        page = parameters.delete(:page).to_i
+        page = 1 unless page > 0
+        page
+      end
+
+      # Returns the page size for the current query string.
+      #
+      # If per_page or page_size is not specified, or is not a positive number, :default_page_size will be returned instead.
+      #
+      # @param parameters [Hash] the parameters parsed from the query string
+      #
+      # @return [Fixnum]
+      #
+      # @example
+      #
+      #   page_size = self.parse_page(:page_size => 10)  #=>  10
+      #   page_size = self.parse_page(:per_page  => 10)  #=>  10
+      #   page_size = self.parse_page(:per_page  => nil) #=>  30
+      def parse_page_size( parameters )
+        page_size = (parameters.delete(:page_size) || parameters.delete(:per_page)).to_i
+        page_size = self.default_page_size unless page_size > 0
+        page_size
+      end
+
+    end
+  end
+end

data/lib/muster/strategies/rack.rb

@@ -0,0 +1,89 @@
+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'
+
+module Muster
+  module Strategies
+
+    # Query string parsing strategy based on Rack::Utils#parse_query
+    #
+    # @example
+    #
+    #   strategy = Muster::Strategies::Rack.new
+    #   results  = strategy.parse('name=value&choices=1&choices=2')  #=>  { 'name' => 'value', 'choices' => ['1', '2'] }
+    class Rack
+
+      # @attribute [r] options
+      # @return [Hash] options specified during initialization
+      attr_reader :options
+
+      # @attribute [r] fields
+      # @return [Hash] list of fields to parse, ignoring all others
+      attr_reader :fields
+
+      # Create a new Rack 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
+      #
+      # @example
+      #
+      #   strategy = Muster::Strategies::Rack.new(:fields => [:name, :state])
+      #   strategy = Muster::Strategies::Rack.new(:field  => :name)
+      def initialize( options={} )
+        @options = options.with_indifferent_access
+
+        @fields  = Array.wrap(@options[:field] || @options[:fields])
+        @fields.map!{ |field| field.to_sym }
+      end
+
+      # Processes a query string and returns a hash of its fields/values
+      #
+      # @param query_string [String] the query string to parse
+      #
+      # @return [Hash]
+      #
+      # @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)
+      end
+
+      protected
+
+      # Converts the query string into a hash for processing
+      #
+      # @param query_string [String] the query string being parsed
+      #
+      # @return [Hash]
+      #
+      # @example
+      #
+      #   fields = self.parse_query_string('name=value&choices=1&choices=1')  #=>  { 'name' => 'value', 'choices' => ['1', '2'] }
+      def parse_query_string( query_string )
+        ::Rack::Utils.parse_query(query_string).with_indifferent_access
+      end
+
+      # Returns the list of fields to be parsed
+      #
+      # @param query_string [String] the query string to parse
+      #
+      # If the :fields option was specified, only those fields will be returned. Otherwise, all fields will be returned.
+      #
+      # @return [Hash]
+      def fields_to_parse( query_string )
+        fields = self.parse_query_string(query_string)
+
+        if self.fields.present?
+          fields = fields.select{ |key, value| self.fields.include?(key.to_sym) }
+        end
+
+        return fields.with_indifferent_access
+      end
+
+    end
+  end
+end

data/lib/muster/strategies/sort_expression.rb

@@ -0,0 +1,75 @@
+require 'active_support/core_ext/array/wrap'
+require 'muster/strategies/hash'
+
+module Muster
+  module Strategies
+
+    # Query string parsing strategy with additional value handling for sort orders
+    #
+    # @example
+    #
+    #   strategy = Muster::Strategies::SortExpression.new
+    #   results  = strategy.parse('sort=name:desc')  #=>  { 'sort' => 'name desc' }
+    class SortExpression < Muster::Strategies::Hash
+
+      # Processes a query string and returns a hash of its fields/values
+      #
+      # @param query_string [String] the query string to parse
+      #
+      # @return [Hash]
+      #
+      # @example
+      #   
+      #   results = strategy.parse('order=name')            #=>  { 'order' => 'name asc' }
+      #   results = strategy.parse('order=name:desc')       #=>  { 'order' => 'name desc' }
+      #   results = strategy.parse('order=name,date:desc')  #=>  { 'order' => ['name asc', 'date desc'] }
+      def parse( query_string )
+        parameters  = super
+
+        parameters.each do |key, value|
+          parameters[key] = self.parse_sort_expression(value)
+        end
+      end
+
+      protected
+
+      # Separates the values into their field and direction
+      #
+      # @param value [String] the value being parsed
+      #
+      # @return [String,Arrary] String if a single value, Array otherwise
+      #
+      # @example
+      #
+      #    value = self.parse_sort_expression('name:asc')  #=>  'name asc'
+      #    value = self.parse_sort_expression(['name:asc', 'date'])  #=>  ['name asc', 'date asc']
+      def parse_sort_expression( value )
+        values = Array.wrap(value)
+
+        values = values.map do |value|
+          name, direction = value.split(':', 2)
+          direction = self.parse_direction(direction)
+
+          "#{name} #{direction}"
+        end.flatten
+
+        return (values.size > 1) ? values : values.first
+      end
+
+      # Parse and normalize the sot expression direction
+      #
+      # @param direction [String] the direction to normalize
+      #
+      # @return [String]
+      #
+      # @example
+      #
+      #   direction = self.parse_direction('ascending')   #=> 'asc'
+      #   direction = self.parse_direction('descending')  #=> 'desc'
+      def parse_direction( direction )
+        direction.to_s.match(/^desc/i) ? 'desc' : 'asc'
+      end
+
+    end
+  end
+end

data/lib/muster/version.rb

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

data/muster.gemspec

@@ -0,0 +1,24 @@
+# -*- encoding: utf-8 -*-
+require File.expand_path('../lib/muster/version', __FILE__)
+
+Gem::Specification.new do |gem|
+  gem.authors       = ["Christopher H. Laco"]
+  gem.email         = ["claco@chrislaco.com"]
+  gem.description   = %q{Muster is a gem that turns query string options in varying formats into data structures suitable for use in AR scopes and queryies.}
+  gem.summary       = %q{Muster various query string options into AR query compatable options.}
+  gem.homepage      = "https://github.com/claco/muster"
+
+  gem.files         = `git ls-files`.split($\)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.name          = "muster"
+  gem.require_paths = ["lib"]
+  gem.version       = Muster::VERSION
+
+  gem.add_dependency 'activesupport', '~> 3.0'
+  gem.add_dependency 'rack',          '~> 1.4'
+
+  gem.add_development_dependency 'rspec',     '~> 2.10.0'
+  gem.add_development_dependency 'redcarpet', '~> 2.1'
+  gem.add_development_dependency 'yard',      '~> 0.8.2'
+end

data/spec/muster/rack_spec.rb

@@ -0,0 +1,37 @@
+require 'spec_helper'
+
+describe Muster::Rack do
+  let(:application) { lambda{|env| [200, {'Content-Type' => 'text/plain'}, '']} }
+  let(:environment) { Rack::MockRequest.env_for('/?name=value&order=name') }
+  let(:options)     { {} }
+  let(:middleware)  { Muster::Rack.new(application, Muster::Strategies::Hash, options) }
+
+  it 'parse query string with strategy' do
+    middleware.call(environment)
+
+    environment[Muster::Rack::QUERY].should == {'name' => 'value', 'order' => 'name'}
+  end
+
+  it 'accepts options for middlewhere' do
+    options[:field] = :name
+
+    middleware.call(environment)
+
+    environment[Muster::Rack::QUERY].should == {'name' => 'value'}
+  end
+
+  it 'accepts a strategy instance' do
+    strategy = Muster::Strategies::Hash.new(:field => :name)
+    Muster::Rack.new(application, strategy).call(environment)
+
+    environment[Muster::Rack::QUERY].should == {'name' => 'value'}
+  end
+
+  it 'merges multiple strategies into one result' do
+    Muster::Rack.new(application, Muster::Strategies::Hash, :field => :name).call(environment)
+    environment[Muster::Rack::QUERY].should == {'name' => 'value'}
+
+    Muster::Rack.new(application, Muster::Strategies::Hash, :field => :order).call(environment)
+    environment[Muster::Rack::QUERY].should == {'name' => 'value', 'order' => 'name'}
+  end
+end

data/spec/muster/strategies/active_record_spec.rb

@@ -0,0 +1,137 @@
+require 'spec_helper'
+
+describe Muster::Strategies::ActiveRecord do
+  let(:options) { {} }
+  subject { Muster::Strategies::ActiveRecord.new(options) }
+
+  describe '#parse' do
+    context 'selects' do
+      it 'returns single value as Array' do
+        subject.parse('select=id')[:select].should == ['id']
+      end
+
+      it 'returns values in Array' do
+        subject.parse('select=id&select=name')[:select].should == ['id', 'name']
+      end
+
+      it 'supports comma separated values' do
+        subject.parse('select=id&select=guid,name')[:select].should == ['id', 'guid', 'name']
+
+      end
+    end
+
+    context 'orders' do
+      it 'returns single value as Array' do
+        subject.parse('order=id')[:order].should == ['id asc']
+      end
+
+      context 'with direction' do
+        it 'supports asc' do
+          subject.parse('order=id:asc')[:order].should == ['id asc']
+        end
+
+        it 'supports desc' do
+          subject.parse('order=id:desc')[:order].should == ['id desc']
+        end
+
+        it 'supports ascending' do
+          subject.parse('order=id:ascending')[:order].should == ['id asc']
+        end
+
+        it 'supports desc' do
+          subject.parse('order=id:descending')[:order].should == ['id desc']
+        end
+      end
+    end
+
+    context 'pagination' do
+      it 'returns default will paginate compatible pagination' do
+        subject.parse('')[:pagination].should == {:page => 1, :per_page => 30}
+      end
+
+      it 'returns default limit options' do
+        subject.parse('')[:limit].should eq 30
+      end
+
+      it 'returns default offset options' do
+        subject.parse('')[:offset].should eq nil
+      end
+
+      it 'accepts per_page option' do
+        results = subject.parse('per_page=10')
+        results[:pagination].should == {:page => 1, :per_page => 10}
+        results[:limit].should eq 10
+        results[:offset].should eq nil
+      end
+
+      it 'ensures per_page is positive integer' do
+        results = subject.parse('per_page=-10')
+        results[:pagination].should == {:page => 1, :per_page => 30}
+        results[:limit].should eq 30
+        results[:offset].should eq nil
+      end
+
+      it 'accepts page_size option' do
+        results = subject.parse('page_size=10')
+        results[:pagination].should == {:page => 1, :per_page => 10}
+        results[:limit].should eq 10
+        results[:offset].should eq nil
+      end
+
+      it 'accepts page option' do
+        results = subject.parse('page=2')
+        results[:pagination].should == {:page => 2, :per_page => 30}
+        results[:limit].should eq 30
+        results[:offset].should eq 30
+      end
+
+      it 'ensures page is positive integer' do
+        results = subject.parse('page=a')
+        results[:pagination].should == {:page => 1, :per_page => 30}
+        results[:limit].should eq 30
+        results[:offset].should eq nil
+      end
+    end
+
+    context 'wheres' do
+      it 'returns a single value as a string in a hash' do
+        subject.parse('where=id:1')[:where].should == {'id' => '1'}
+      end
+
+      it 'returns values as an Array in a hash' do
+        subject.parse('where=id:1&where=id:2')[:where].should == {'id' => ['1', '2']}
+      end
+
+      it 'supports pipe for multiple values' do
+        subject.parse('where=id:1|2')[:where].should == {'id' => ['1', '2']}
+      end
+    end
+
+    context 'the full monty' do
+      it 'returns a hash of all options' do
+        query_string = 'select=id,guid,name&where=name:foop&order=id:desc&order=name&page=3&page_size=5'
+        results = subject.parse(query_string)
+
+        results[:select].should == ['id', 'guid', 'name']
+        results[:where].should  == {'name' => 'foop'}
+        results[:order].should  == ['id desc', 'name asc']
+        results[:pagination].should == {:page => 3, :per_page => 5}
+        results[:offset].should == 10
+        results[:limit].should == 5
+      end
+
+      it 'supports indifferent access' do
+        query_string = 'select=id,guid,name&where=name:foop&order=id:desc&order=name&page=3&page_size=5'
+        results = subject.parse(query_string)
+
+        results['select'].should == ['id', 'guid', 'name']
+        results['where'].should  == {'name' => 'foop'}
+        results['order'].should  == ['id desc', 'name asc']
+        results['pagination'].should == {:page => 3, :per_page => 5}
+        results['offset'].should == 10
+        results['limit'].should == 5
+
+      end
+    end
+  end
+end