muster 0.0.1

data/.gitignore

@@ -0,0 +1,18 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+.rvmrc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

@@ -0,0 +1,2 @@
+--color
+--format progress

data/.yardopts

@@ -0,0 +1 @@
+--protected

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in muster.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Christopher H. Laco
+
+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 @@
+# Muster
+
+Muster is a gem that turns query string options of varying formats into data structures suitable for
+easier consumption in things like AR and DataMapper scopes and queries, making API development just a little bit easier.
+
+    require 'muster'
+
+    use Muster::Rack, Muster::Strategies::ActiveRecord, :fields => [:select, :order]
+
+    # GET /people?select=id,name&order=name:desc
+    # in your routes/controllers
+    query = env['muster.query']
+
+    @people = Person.select( query[:select] ).order( query[:order] )
+
+## Strategies
+
+The following types of strategies are supported. You can combine them in Rack any way you see fit to match the query string options
+you want to support.
+
+### Rack
+
+Returns the query as parsed by Rack::Utils#parse_query.
+
+    ?name=value1&name=value2&choice=1&choice=1
+    
+    { 'name' => ['value1', 'value2'], 'choice' => ['1', '1'] }
+
+### Hash
+
+Same as Rack but with support for delimited value separation and unique value detection.
+
+    ?name=value1,value2&choice=1&choice=1
+
+    { 'name' => ['value1', 'value2'], 'choice' => '1' }
+
+### FilterExpression
+
+Allows name value pairs to be specified in the query string values for use in filtering methods that take Hashes.
+Include delimited value and unique value support from above.
+
+    ?filter=id:1&filter=name:food  #=>  { 'filter' => {'id' => '1', 'name' => 'food'} }
+    ?filter=id:1&filter=id:2       #=>  { 'filter' => {'id' => ['1', '2']} }     
+    ?filter=id:1|2                 #=>  { 'filter' => {'id' => ['1', '2']} }
+    ?filter=id:1,name:food         #=>  { 'filter' => {'id' => '1', 'name' => 'food'} }
+
+### SortExpression
+
+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'] }
+
+### Pagination
+
+Returns options to support pagination with logic for default page size, not-a-number checks and offset calculations.
+
+    ?page=2&per_page=5    #=>  { 'pagination' => {'page' => 2, 'per_page' => 5}, 'limit' => 5, 'offset' => 5 }
+    ?page=a&page_size=-2  #=>  { 'pagination' => {'page' => 1, 'per_page' => 30}, 'limit' => 30, 'offset' => nil}
+
+
+### ActiveRecord
+
+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', 'limit' =>  10, 'offset' => 20, 'pagination' => {:page => 3, :per_page => 10} }
+
+    query = env['muster.query']
+    Person.select( query[:select] ).where( query[:where] ).order( query[:order] ).offset( query[:offset] ).limit( query[:limit] )
+
+If you are using WillPaginate, you can also pass in :pagination:
+
+    Person.paginate( query[:paginate] )
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'muster'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install muster
+
+## Usage
+
+### In any Rack application:
+
+    require 'muster'
+
+    use Muster::Rack, Muster::Strategies::ActiveRecord, :fields => [:select, :order]
+    
+    # GET /people?select=id,name&order=name:desc
+    # in your routes/controllers
+    query = env['muster.query']
+    
+    @people = Person.select( query[:select] ).order( query[:order] )
+
+You can combine multiple strategies, and their results will be merged
+
+    use Muster::Rack, Muster::Strategies::Hash, :field => :select
+    use Muster::Rack, Muster::Strategies::ActiveRecord, :field => :order
+    
+    # GET /people?select=id,name&order=name:desc
+    # in your routes/controllers
+    query = env['muster.query']
+    
+    @people = Person.select( query[:select] ).order( query[:order] )
+
+
+### In any code:
+
+    require 'muster'
+
+    strategy = Muster::Strategies::Hash.new
+    query    = strategy.parse(request.query_string)
+    people   = Person.select( query[:select] ).order( query[:order] )
+
+## Contributing
+
+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
+

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+require 'rspec/core/rake_task'
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+YARD::Rake::YardocTask.new(:yard)

data/lib/muster.rb

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

data/lib/muster/rack.rb

@@ -0,0 +1,72 @@
+require 'rack'
+
+module Muster
+
+  # Rack middleware plugin for Muster query string parsing
+  #
+  # @example
+  #
+  #   app = Rack::Builder.new do
+  #     use Rack::Muster, Muster::Strategies::Hash, :fields => [:name, :choices]
+  #   end
+  #   
+  #   # GET /?name=bob&choices=1&choices=2
+  #   match '/' do
+  #     env['muster.query']  #=> {'name' => 'bob', 'choices' => ['1', '2']}
+  #   end
+  class Rack
+
+    # @attribute [r] app
+    # @return [Object] Rack application middleware is running under
+    attr_reader :app
+    
+    # @attribute [r] strategy
+    # @return [Muster::Strategies::Rack] Muster Strategy to run
+    attr_reader :strategy
+      
+    # @attribute [r] options
+    # @return [Hash] options to pass to strategy 
+    attr_reader :options
+
+    # Key in ENV where processed query string are stored
+    QUERY = 'muster.query'.freeze
+
+    # Key in ENV where the query string that was processed is stored
+    QUERY_STRING = 'muster.query_string'.freeze
+
+    # Creates a new Rack::Muster middleware instance
+    #
+    # @param app [String] Rack application
+    # @param strategy [Muster::Strategies::Rack] Muster query string parsing strategy to run
+    # @param options [Hash] options to pass to the specified strategy
+    #
+    # @example
+    #
+    #   middleware = Muster::Rack.new(app, Muster::Strategies::Hash, :fields => [:name, :choices])
+    #   
+    #   strategy = Muster::Strategies::Hash.new(:fields => [:name, :choices])
+    #   middleware = Muster::Rack.new(app, strategy)
+    def initialize( app, strategy, options={} )
+      @app = app
+      @strategy = strategy
+      @options = options
+    end
+
+    # Handle Rack request
+    #
+    # @param env [Hash] Rack environment
+    #
+    # @return [Array]
+    def call( env )
+      request  = ::Rack::Request.new(env)
+      parser   = self.strategy.kind_of?(Class) ? self.strategy.new(options) : self.strategy
+
+      env[QUERY] ||= {}
+      env[QUERY].merge! parser.parse(request.query_string)
+      env[QUERY_STRING] = request.query_string
+
+      @app.call(env)
+    end
+
+  end
+end

data/lib/muster/strategies.rb

@@ -0,0 +1,6 @@
+require 'muster/strategies/rack.rb'
+require 'muster/strategies/active_record'
+require 'muster/strategies/filter_expression'
+require 'muster/strategies/hash'
+require 'muster/strategies/pagination'
+require 'muster/strategies/sort_expression'

data/lib/muster/strategies/active_record.rb

@@ -0,0 +1,118 @@
+require 'active_support/core_ext/array/wrap'
+require 'active_support/hash_with_indifferent_access'
+require 'muster/strategies/hash'
+require 'muster/strategies/filter_expression'
+require 'muster/strategies/pagination'
+require 'muster/strategies/sort_expression'
+
+module Muster
+  module Strategies
+
+    # Query string parsing strategy that outputs ActiveRecord Query compatible options
+    #
+    # @example
+    #
+    #   strategy = Muster::Strategies::ActiveRecord.new
+    #   results  = strategy.parse('select=id,name&where=status:new&order=name:desc')
+    #
+    #   # { 'select' => ['id', 'name'], :where => {'status' => 'new}, :order => 'name desc' }
+    #   #
+    #   # Person.select( results[:select] ).where( results[:where] ).order( results[:order] )
+    class ActiveRecord < Muster::Strategies::Rack
+
+      # 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('select=id,name&where=status:new&order=name:desc')
+      #
+      #   # { 'select' => ['id', 'name'], :where => {'status' => 'new}, :order => 'name desc' }
+      def parse( query_string )
+        pagination = self.parse_pagination( query_string )
+
+        parameters = ActiveSupport::HashWithIndifferentAccess.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)
+        )
+
+        parameters.regular_writer('pagination', pagination[:pagination].symbolize_keys)
+
+        return parameters
+      end
+
+      protected
+
+      # Returns select clauses for AR queries
+      #
+      # @param query_string [String] the original query string to parse select clauses from
+      #
+      # @return [Array]
+      #
+      # @example
+      #
+      #   value = self.parse_select('select=id,name')  #=> ['id', 'name']
+      def parse_select( query_string )
+        strategy = Muster::Strategies::Hash.new(:field => :select)
+        results  = strategy.parse(query_string)
+
+        return Array.wrap( results[:select] )
+      end
+
+      # Returns order by clauses for AR queries
+      #
+      # @param query_string [String] the original query string to parse order clauses from
+      #
+      # @return [Array]
+      #
+      # @example
+      #
+      #   value = self.parse_order('order=name:desc')  #=> ['name asc']
+      def parse_order( query_string )
+        strategy = Muster::Strategies::SortExpression.new(:field => :order)
+        results  = strategy.parse(query_string)
+
+        return Array.wrap( results[:order] )
+      end
+
+      # Returns pagination information for AR queries
+      #
+      # @param query_string [String] the original query string to parse pagination from
+      #
+      # @return [Hash]
+      #
+      # @example
+      #
+      #   value = self.parse_pagination('page=2&page_size=10')  #=> { 'pagination' => {:page => 2, :per_page => 10}, 'limit' => 10, 'offset' => 10 }
+      def parse_pagination( query_string )
+        strategy = Muster::Strategies::Pagination.new(:fields => [:pagination, :limit, :offset])
+        results  = strategy.parse(query_string)
+        
+        return results
+      end
+
+      # Returns where clauses for AR queries
+      #
+      # @param query_string [String] the original query string to parse where statements from
+      #
+      # @return [Hash]
+      #
+      # @example
+      #
+      #   value = self.parse_where('where=id:1')  #=> {'id' => '1'}
+      def parse_where( query_string )
+        strategy = Muster::Strategies::FilterExpression.new(:field => :where)
+        results  = strategy.parse(query_string)
+
+        return results[:where] || {}
+      end
+
+    end
+  end
+end

data/lib/muster/strategies/filter_expression.rb

@@ -0,0 +1,142 @@
+require 'active_support/core_ext/array/wrap'
+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::FilterExpression.new
+    #   results  = strategy.parse('where=id:1&name:Bob')  #=>  { 'where' => {'id' => '1', 'name' => 'Bob'} }
+    class FilterExpression < 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,String,RegEx] :value_separator (|) 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::FilterExpression.new
+      #   strategy = Muster::Strategies::FilterExpression.new(:unique_values => false)
+      def initialize( options={} )
+        super
+
+        @expression_separator = self.options.fetch(:expression_separator, /,\s*/)
+        @field_separator = self.options.fetch(:field_separator, ':')
+        @value_separator = self.options.fetch(:value_separator, '|')
+      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('where=id:1&name:Bob')  #=>  { 'where' => {'id' => '1', 'name' => 'Bob'} }
+      def parse( query_string )
+        parameters  = 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
+      end
+
+      protected
+
+      # Separates values into an Array of expressions using :expression_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('where=id:1')       #=> {'where' => 'id:1'}
+      #   value = self.separate_values('where=id:1,id:2')  #=> {'where' => ['id:1', 'id:2']}
+      def separate_expressions( value )
+        values = Array.wrap(value)
+
+        values = values.map do |value|
+          value.split(self.expression_separator)
+        end.flatten
+
+        return (values.size > 1) ? values : values.first
+      end
+
+      # Separates expression field values into an Hash of expression filters using :field_separator
+      #
+      # @param value [String,Array] the expressions field value to separate
+      #
+      # @return [Hash]
+      #
+      # @example
+      #
+      #   value = self.separate_fields('id:1')    #=> {'id' => '1'}
+      #   value = self.separate_values('id:1|2')  #=> {'id' => '1|2'}
+      def separate_fields( value )
+        values = Array.wrap(value)
+        
+        filters = {}
+
+        values.each do |value|
+          name, value = value.split(self.field_separator, 2)
+
+          if self.value_separator.present?
+            value = self.separate_values(value)
+          end
+
+          filters[name] = filters.has_key?(name) ? [filters[name], value].flatten : value
+
+          if self.unique_values == true && filters[name].instance_of?(Array)
+            filters[name].uniq!
+          end
+        end
+
+        return filters
+      end
+
+      # Separates expression filter values into an Array of expression filter values using :value_separator
+      #
+      # @param value [String,Array] the expressions filter 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