refinuri 0.5.0 → 0.5.1

data/README.md

@@ -1,63 +1,42 @@
-# Refinuri
+# Refinuri #
+## ri-fahy-nuh-ree ##
 
-Refinuri provides two primary functions related to querying and filtering data:
+Refinuri has two primary functions related to querying and filtering data:
 
 + a simple way to produce pretty, meaningful URLs, even with complex query strings
 + a standardized, extensible interface to filtering metadata
 
-## Basics
+## The dime tour ##
 
-	@filters = Refinuri::Parser.parse_url('name:apple,banana,cherry;price:0-5;age:7-')
-	# sets up a new FilterSet based on the filter part of a URL
-	
-	Product.filtered(@filters)
-	# automatically applies all the filters to an ActiveRecord object just as though each were it's own #where()
-
-## In practice
-
-### Pretty URLs
-
-A 'traditional' style URL with standard query strings such as
+Refactor an ugly 'traditional' URL, such as
 	
 	craigslist.org/search/housing?cat=loft&minPrice=500&maxPrice=1000&cats=true&dogs=true&bedrooms=2
 
-Will become
-
-	craigslist.org/search/housing/type:loft;price:500-1000;pets:cats,dogs;bedrooms:2/
+to
 	
-### Internal interface to filters
+	craigslist.org/search/housing/type:loft;price:500-1000;pets:cats,dogs;bedrooms:2/
 
-Filters are stored within a FilterSet, a Hash-like object that allows for easy access to properly-typed data and merging in changes to the set of filters. Filters and changes are passed into FilterSet as hashes.
-	
-	>> base_filters = { :name => ['apple','banana','cherry'], :price => 0..5, :weight => '4..' }
-	>> set = FilterSet.new(base_filters)
-	
-The filters can be exposed through
+And parse it into a convenient set of filters
 
-	>> set[:name].value # => ['apple','banana','cherry']
-	>> set.to_url # => 'name:apple,banana,cherry;price:0-5;weight:4+'
-	>> set.to_h # => { :name => ['apple','banana','cherry'], :price => 0..5, :weight => '4..' }
-	
-Changes are merged into an existing filter set, either implicitly or explicitly as CRUD functions
+	@filters = Refinuri::Parser.parse_url(params[:filters])
+
+Now you can pass all that filtery goodness straight into your ActiveRecord object
 	
-	# implicit changes generally update existing values
-	>> changes = { :name => 'dewberry' }
-	>> set.merge!(changes)
-	>> set[:name].value # => ['apple','banana','cherry','dewberry']
+	Apartment.filtered(@filters)
 	
-	# explicilty stated CRUD functions
-	>> more_changes = { :update => { :name => ['eggplant','fig] }, :destroy => { :price => nil } }
-	>> set.merge!(more_changes)
-	>> set[:name].value # => ['apple','banana','cherry','dewberry','eggplant','fig']
-	>> set[:price] # => nil
+And easily add links to your views to create, update, or delete the filters
 	
-## Benefits
+	filter_with_link("Allow Ferrets", { :pets => 'ferrets' })
+	filter_with_link("Only cats", { :create => { :pets => 'cats' } })
+	filter_with_link("Any Price", { :delete => { :price => nil } })
+
+## Benefits ##
 
-Not only does Refinuri improve the readability and length of URLs, but behind the scenes each piece of filtering data is being handled as the appropriate data type automatically. A range of prices is an actual Range, a list of brands is an Array, etc.
+Not only does Refinuri improve the readability and length of URLs, but behind the scenes each piece of filtering data is being handled as the appropriate datatype automatically. A range of prices is an actual Range, a list of items is actually an Array, etc.
 
-This is useful both because it allows you to hand the queries off to ActiveRecord very easily, and also because the data can change very freely. A filter can change from an Integer to a Range with very little overhear need to change things on the backend.
+This is useful both because it allows you to hand the queries off to ActiveRecord very easily, and also because the data can be changed very easily. Individuals filters can accept arbitrary numbers of items, numeric filters and go from Integers to Ranges with no effort, etc.
 
-The hope is that with most of the heavy lifting being done automatically and in a consistent way, it will be much easier to actually implement a user-facing interface that allows for these more advanced controls than are generally being offered.
+The hope is that, with most of the heavy lifting being done automatically and in a consistent way, it will be much easier to actually implement a user-facing interface that allows for more advanced and useful controls to be implemented.
 
 ## Usage
 
@@ -65,122 +44,180 @@ The hope is that with most of the heavy lifting being done automatically and in
 	
 	$ sudo gem install refinuri
 
-### Common API aspects
+### Example Application ###
 
-#### URL parsing
-	
-	>> Refinuri::Parser.parse_url('name:apple,banana,cherry')
-	=> #<Refinuri::Base::FilterSet:0x1003ad300>
+#### routes.rb ####
+
+	match 'products/:id/:filters' => 'products#index'
+
+#### application_controller.rb ####
+
+	before_filter :refine_filters
 	
-#### Generating URL string
+	private
+	def refine_filters
+		@filters = Refinuri::Parser.parse_url(params[:filters]) if params[:filters]
+	end
+
+#### products_controller.rb ####
+
+	@products = Product.filtered(@filters)
 	
-	>> @filter_set.to_url
-	=> 'name:apple,banana,cherry'
+#### products/index.html.erb ####
+
+	<%= filter_with_link("Price less than $50", { :price => '..50' }) %>
+	<% @products.each do |product| %>
+		<%= product.name %>
+	<% end %>
 	
-#### Available data types
+## API ##
 
-Currently supported datatypes include:
+### Defining filters ###
 
-##### Arrays
+Filters are initially defined as a Hash, where each key represents an attribute upon which a resource can be filtered, and the value represents the values that will pass the filter.
 
-	# in URLs an array is represented as
-	key:item1,item2,item3
+The following hash creates three filters:
+
+	{ :name => ['apple','banana','cherry'], :price => 0..5, :weight => '4..' }
 	
-	# which are parsed as standard Ruby arrays, available through the FilterSet
-	@set[:key] => ['item1','item2','item3']
+The Hash is used to create a new FilterSet, the class responsible for handling changes to the filters and outputting the filter values appropriately when necessary.
 
-##### Bounded ranges
+	Refinuri::Base::FilterSet.new({ :name => ['apple','banana','cherry'], :price => 0..5, :weight => '4..' })
 
-	# in URLs a range is represented as
-	key:10-20
-	
-	# which are parsed as standard Ruby ranges, available through the FilterSet
-	@set[:key] => 10..20
+### Modifying filters ###
 
-(Support for both inclusive and exclusive ranges is not yet included)
+The FilterSet uses #merge! to accept changes to an existing set of filters. #merge! also accepts a hash, but allows for defining how the filters should be merged into the set.
 
-##### Unbounded ranges
+By incorporating the various CRUD functions into the Hash, the new filters and values will be merged into the existing set.
 
-Unbounded ranges are a non-standard datatype, which allows for a convenient way of defining only an upper- or lower-bound on a range.
+	@filters.merge!({ :create => { :color => 'orange' }, :update => { :name => 'dewberry', :price => 0..10 }, :delete => { :weight => nil } })
+	
+Any filters being merged that aren't explicitly stated as one of the CRUD functions is assumed to be an :update.
 
-Lower-bound ranges
+### Returning values ###
 
-	# represented in URLs as
-	key:10+
+#### Values of entire filter sets: ####
+
+\#to_h returns the entire set as a hash, similar to the one used to initialize the filter, but with any changes that have been made
 	
-	# are parsed into strings in the format
-	@set[:key] => '10..'
+	@filters.to_h
+	=> { :name => ['apple','banana','cherry','dewberry'], :color => ['orange'], :price => 0..10, :weight => '4..' }
+
+\#to\_url returns the entire set as a URL-friendly string, which could be included as an option in a link_to() helper
 	
-	# and provides a convenience method for use in an ActiveRecord #where
-	@set[:key].to_db => 'key >= 10'
+	@fitlers.to_url
+	=> "name:apple,banana,cherry,dewberry;color:orange;price:0-10;weight:4+"
 
-Upper-bound ranges
+#### Values of individual filters within a set: ####
 
-	# represented in URLs as
-	key:10-
+\#value returns the filter value as it was defined
+
+	@filters[:name].value
+	=> ['apple','banana','cherry']
+
+\#to_db returns a value suitable for passing to a #where chain of an ActiveRecord object
 	
-	# are parsed into strings in the format
-	@set[:key] => '..10'
+	@filters[:name].to_db
+	=> { :name => ['apple','banana','cherry'] }
+	
+\#to_s returns a value suitable for use in a URL
 	
-	# and provides a convenience method for use in an ActiveRecord #where
-	@set[:key].to_db => 'key <= 10'
+	@filters[:name].to_s
+	=> "apple,banana,cherry"
 	
-#### Creating and modifying FilterSets
+### Parsing filter strings ###
 
-New filters a populated with a hash
+Filters defined within strings, such as those contained in a URL, can be parsed into a FilterSet using:
+	
+	Refinuri::Parser.parse_url()
+	
+### ActiveRecord integration ###
+
+There are two ways of using FilterSets and filters with ActiveRecord.
 
-	>> Refinuri::Base::FilterSet.new({ :name => ['apple','banana','cherry'] })
+#### Individually ####
+
+The first is to utilize an individual filter manually along side the #where method, which is part of the Rails 3 query interface. The #to_db method returns values for filters specifically designed for use as a #where argument.
+	
+	Product.where(@filters[:price].to_db) # => like Product.where(:price => 0..10)
+	Product.where(@filters[:name].to_db) # => like Product.where(:name => ['apple','banana','cherry'])
+	Product.where(@filters[:weight].to_db) # => like Product.where('weight <= 10')
 
-Filters are modified with #merge! by passing in a hash of changes.
+#### En masse ####
 
-Changes that are not explicitly stated as a CRUD function are assumed to be UPDATEs. UPDATEs will create a new filter if it does not already exist, or will add unique values to an array, or replace a range. CREATE will either create a new filter or completely replace an existing filter.
+The second is to pass the entire FilterSet off to ActiveRecord, and filter the object using all currently defined filters. The #filtered method is provided to ActiveRecord::Base for this purpose.
 
-	# implicit changes, treated as UPDATE
-	>> @filter.merge!({ :name => ['dewberry','eggplant'] })
-	# @filter[:name].value => ['apple','banana','cherry','dewberry','eggplant']
+	Product.filtered(@filters)
 	
-	# explicit UPDATE
-	>> @filter.merge!({ :update => { :name => ['dewberry','eggplant'] } })
-	# @filter[:name].value => ['apple','banana','cherry','dewberry','eggplant']
+This is like doing
 	
-	# explicit CREATE
-	>> @filter.merge!({ :creaet => { :name => ['dewberry','eggplant'] } })
-	# @filter[:name].value => ['dewberry','eggplant']
+	Product.where(@filters[:price].to_db).where(@filters[:name].to_db).where(@filters[:weight].to_db)
+
+### ActionView helpers ###
+
+There are several link helpers included to serve common needs of creating and updating filters through the UI.
+
+The first is a simple interface for passing a set of changes to the current set of filters, and returning the appropriate link.
 	
-	# explicit DELETE
-	>> @filter.merge!({ :delete => { :name => nil } })
-	# @filter[:name] => nil
+	filter_with_link("+ apple", { :name => 'apple' })
+	filter_with_link("- apple", { :delete => { :name => 'apple' } })
 
-#### Using filters with ActiveRecord
+The next acts as a toggle for values within array-based filters, and will toggle individual values (not the entire filter, per se)
+	
+	toggle_filter_with_link("+/- apple", { :name => 'apple' })
 
-Each data type has a #to_db method which returns a value suitable for use as the argument for ActiveRecord's #where method
+## Data types ##
 
-	@set = Refinuri::Base::FilterSet.new({ :price => 10..20, :age => '10..' })
+### Arrays
+
+In URLs an array is represented as
+
+	key:item1,item2,item3
 	
-	Product.where(@set[:price].to_db)
-	# is equivalent to
-	Product.where(:price => 10..20)
+Which are parsed as standard Ruby arrays, available through the FilterSet
+
+	@set[:key] => ['item1','item2','item3']
+
+### Ranges
+
+In URLs a range is represented as
+
+	key:10-20
 	
-and
-	Product.where(@set[:age].to_db)
-	# is equivalent to
-	Product.where('age >= 10')
+Which are parsed as standard Ruby ranges, available through the FilterSet
+
+	@set[:key] => 10..20
+
+(Support for both inclusive and exclusive ranges is not yet included, but coming soon)
+
+### Unbounded ranges
+
+Unbounded ranges are a non-ruby-standard datatype, which allows for a convenient way of defining only an upper- or lower-bound on a range.
+
+### Lower-bound ranges
+
+Represented in URLs as
+
+	key:10+
 	
-If you would like to simply query an ActiveRecord object against all the filters in a FilterSet, the #filtered() method comes in handy
+Parsed into the filter as strings in the format
 
-	Product.filtered(@set)
-	# is equivalent to
-	Product.where(:price => 10..20).where('age >= 10')	
+	@set[:key] => '10..'
 	
-#### Helpers
+And provides a convenience method for use in an ActiveRecord #where
+
+	@set[:key].to_db => 'key >= 10'
+
+### Upper-bound ranges
+
+Represented in URLs as
+
+	key:10-
 	
-	# creates a link to the current view, adding 'apple' the the :name filter, 
-	# or returning an unchanged link if 'apple' is already in the :name filter
-	>> filter_with_link("Apple", { :name => 'apple' })
+Are parsed into strings in the format
+
+	@set[:key] => '..10'
 	
-	# toggles the value 'apple' within the name filter, adding it if is not
-	# in the set, or removing it if it is
-	>> toggle_filter_with_link("Apple", { :name => 'apple' })
+And provides a convenience method for use in an ActiveRecord #where
 
-### Example Application
-*coming soon...*
+	@set[:key].to_db => 'key <= 10'

data/VERSION

@@ -1 +1 @@
-0.5.0
+0.5.1

data/refinuri.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{refinuri}
-  s.version = "0.5.0"
+  s.version = "0.5.1"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Chris Kalafarski"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: refinuri
 version: !ruby/object:Gem::Version 
-  version: 0.5.0
+  version: 0.5.1
 platform: ruby
 authors: 
 - Chris Kalafarski