bloodhound 0.1

data/.gitignore

@@ -0,0 +1 @@
+dist

data/README.markdown

@@ -0,0 +1,118 @@
+Bloodhound
+==========
+
+Simple key:value string conversion to hashes, with type casting.
+
+    require "bloodhound"
+
+    hound = Bloodhound.new
+    hound.add_search_field(:name,   :string)
+    hound.add_search_field(:age,    :integer)
+    hound.add_search_field(:active, :boolean)
+
+    attributes = hound.attributes_from('name:"John Doe" age:22 active:yes')
+    attributes #=> { "name" => "John Doe", "age" => 22, "active" => true }
+
+The available types are `:string` (the default), `:integer`, `:float`, `:date`,
+`:time`, and `:boolean`. Any other type is treated as a string.
+
+It matches several values as boolean values. 'yes', 'y', and 'true' are all
+mapped to `true`, while 'no', 'n', and 'false' are mapped to `false`.
+
+You can customize the hash key returned:
+
+    hound.add_search_field(:user, :string, "users.name")
+
+    attributes = hound.attributes_from('user:"John Doe"')
+    attributes #=> { "users.name" => "John Doe" }
+
+It can match dates and times, using [Chronic](http://github.com/mojombo/chronic),
+so this is valid:
+
+    hound.add_search_field(:added, :date, "added_on")
+
+    attributes = hound.attributes_from("added:today")
+    attributes #=> { "added_on" => Date.today }
+
+Finally, you can also provide processing rules for the parsed value, by passing
+a block:
+
+    hound.add_search_field(:inactive, :boolean, "active") {|value| not value }
+
+    attributes = hound.attributes_from("inactive:true")
+    attributes #=> { "active" => false }
+
+ActiveRecord integration
+------------------------
+
+    require "bloodhound/active_record"
+
+    class Video < ActiveRecord::Base
+      extend Bloodhound::Searchable
+      named_scope :search, lambda {|query| bloodhound.attributes_from(query) }
+    end
+
+The ActiveRecord implementation will automatically define search fields for all
+non-id, non-timestamp columns (ie, all except for `id` and `foo_id`).
+
+You can, of course, add those in manually if you need them.
+
+The syntax for defining attributes is a bit more rails-esque:
+
+    class Video < ActiveRecord::Base
+      extend Bloodhound::Searchable
+      search_field :user, :type => :string, :attribute => "users.login"
+    end
+
+The return value of `ActiveRecord::Bloodhound#attributes_from` changes a bit,
+and returns a hash directly compatible with ActiveRecord:
+
+    attributes = Video.bloodhound.attributes_from("user:foca")
+    attributes #=> { :conditions => { "users.login" => "foca" } }
+
+Any extra options you pass to `search_field` are added into the finder options:
+
+    class Video < ActiveRecord::Base
+      extend Bloodhound::Searchable
+      search_field :user, :attribute => "users.login", :joins => :user
+
+      belongs_to :user
+    end
+
+    attributes = Video.bloodhound.attributes_from("user:foca")
+    attributes #=> { :joins => :user,
+                     :conditions => { "users.login" => "foca" } }
+
+Known problems
+--------------
+
+* Chronic is a bit… weird matching some stuff, specially regarding time zones.
+* The ActiveRecord 'extra options' won't merge. So if you define two search
+  fields with ':joins => :an_association', only the latter will remain. This
+  will be fixed in a future release.
+
+License
+-------
+
+(The MIT License)
+
+Copyright (c) 2010 Nicolas Sanguinetti, http://nicolassanguinetti.info
+
+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/bloodhound.gemspec

@@ -0,0 +1,27 @@
+Gem::Specification.new do |s|
+  s.name    = "bloodhound"
+  s.version = "0.1"
+  s.date    = "2010-01-15"
+
+  s.description = "Convert strings like 'user:foca age:23' to { 'user' => 'foca' => 'age' => 23 }"
+  s.summary = "Convert strings like 'user:foca age:23' to { 'user' => 'foca' => 'age' => 23 }"
+  s.homepage    = "http://github.com/foca/bloodhound"
+
+  s.authors = ["Nicolás Sanguinetti"]
+  s.email   = "contacto@nicolassanguinetti.info"
+
+  s.require_paths     = ["lib"]
+  s.has_rdoc          = false
+
+  s.files = %w[
+.gitignore
+README.markdown
+bloodhound.gemspec
+lib/bloodhound.rb
+lib/bloodhound/active_record.rb
+spec/spec_helper.rb
+spec/bloodhound_spec.rb
+spec/bloodhound/active_record_spec.rb
+]
+end
+

data/lib/bloodhound.rb

@@ -0,0 +1,63 @@
+require "chronic"
+
+class Bloodhound
+  VERSION = "0.1"
+  ATTRIBUTE_RE = /\s*(\S+):(?:"([^"]*)"|'([^']*)'|(\S+))\s*/.freeze
+
+  def initialize
+    @mappings = {}
+  end
+
+  def add_search_field(name, type=:string, attribute=name, &mapping)
+    @mappings[name.to_sym] = [attribute, type.to_sym, mapping]
+  end
+
+  def attributes_from(query)
+    parse_query(query).inject({}) do |conditions, (key,value)|
+      attribute, type, mapping = @mappings.fetch(key.to_sym, [])
+
+      if attribute && type
+        conditions[attribute.to_s] = (mapping || default_mapping).call(cast_value(value, type))
+      end
+
+      conditions
+    end
+  end
+
+  def default_mapping
+    lambda {|value| value }
+  end
+  private :default_mapping
+
+  def cast_value(value, type)
+    case type
+    when :boolean
+      { "true"  => true,
+        "yes"   => true,
+        "y"     => true,
+        "false" => false,
+        "no"    => false,
+        "n"     => false }.fetch(value.downcase, true)
+    when :integer
+      # Kernel#Float is a bit more lax about parsing numbers, like
+      # Integer(0.0) fails, when we just want it interpreted as a zero
+      Float(value).to_i
+    when :float, :decimal
+      Float(value)
+    when :date
+      Date.parse(Chronic.parse(value).to_s)
+    when :time, :datetime
+      Chronic.parse(value)
+    else
+      value
+    end
+  end
+  private :cast_value
+
+  def parse_query(query)
+    query.scan(ATTRIBUTE_RE).map do |(key,*value)|
+      [key, value.compact.first]
+    end
+  end
+  private :parse_query
+end

data/lib/bloodhound/active_record.rb

@@ -0,0 +1,43 @@
+require "bloodhound"
+
+module ActiveRecord
+  class Bloodhound < ::Bloodhound
+    def initialize
+      super()
+      @extra_options = {}
+    end
+
+    def add_search_field(name, type=:string, attribute=name, options={}, &mapping)
+      super(name, type, attribute, &mapping)
+      @extra_options[attribute.to_s] = options
+    end
+
+    def attributes_from(query)
+      super(query).inject({}) do |finder_options, (name, value)|
+        finder_options[:conditions] ||= {}
+        finder_options[:conditions].update(name => value)
+        finder_options.update(@extra_options.fetch(name, {}))
+        finder_options
+      end
+    end
+  end
+end
+
+module Bloodhound::Searchable
+  def bloodhound
+    @bloodhound ||= ActiveRecord::Bloodhound.new
+  end
+
+  def search_field(name, options={}, &mapping)
+    attribute = options.delete(:attribute) || name
+    type      = options.delete(:type) || :string
+    bloodhound.add_search_field(name, type, attribute, options, &mapping)
+  end
+
+  def self.extended(model)
+    model.columns.each do |column|
+      next if column.name.to_s =~ /_?id$/
+      model.search_field column.name, :type => column.type
+    end
+  end
+end

data/spec/bloodhound/active_record_spec.rb

@@ -0,0 +1,44 @@
+require "spec_helper"
+require "bloodhound/active_record"
+
+describe ActiveRecord::Bloodhound do
+  it "returns a hash with { :conditions => {keys matched} } instead of just the keys" do
+    subject.add_search_field(:foo)
+    subject.attributes_from("foo:bar").should == { :conditions => { "foo" => "bar" } }
+  end
+
+  it "allows for extra options, that get merged into the return hash" do
+    subject.add_search_field(:user, :string, "users.name", :joins => :users)
+    subject.attributes_from("user:'John Doe'").should == {
+      :joins => :users,
+      :conditions => { "users.name" => "John Doe" }
+    }
+  end
+end
+
+describe Bloodhound::Searchable do
+  Column = Struct.new(:name, :type)
+
+  class MockModel
+    def self.columns
+      [Column.new(:id, :integer), Column.new(:name, :string), Column.new(:user_id, :integer)]
+    end
+
+    extend Bloodhound::Searchable
+  end
+
+  it "allows accessing the bloodhound object in the model by calling Model.bloodhound" do
+    MockModel.bloodhound.should be_an(ActiveRecord::Bloodhound)
+  end
+
+  it "adds search fields for the non-id fields in the model" do
+    conditions = MockModel.bloodhound.attributes_from("name:John id:3 user_id:5").fetch(:conditions)
+    conditions.should_not have_key("id")
+    conditions.should_not have_key("user_id")
+  end
+
+  it "allows you to add search fields with a more ActiveRecord-ish syntax" do
+    MockModel.search_field :user, :type => :string, :attribute => "users.name"
+    MockModel.bloodhound.attributes_from("user:John").should == { :conditions => { "users.name" => "John" } }
+  end
+end

data/spec/bloodhound_spec.rb

@@ -0,0 +1,107 @@
+require "spec_helper"
+
+describe Bloodhound do
+  context "adding fields" do
+    it "can specify a type of :string" do
+      subject.add_search_field(:some_string, :string)
+      { "some_string" => "falafel" }.should be_included_in_extracted_attributes_from("some_string:falafel")
+    end
+
+    it "can specify a type of :integer" do
+      subject.add_search_field(:some_number, :integer)
+      { "some_number" => 1 }.should be_included_in_extracted_attributes_from("some_number:1")
+    end
+
+    it "can specify a type of :float" do
+      subject.add_search_field(:some_number, :float)
+      { "some_number" => 1.5 }.should be_included_in_extracted_attributes_from("some_number:1.5")
+    end
+
+    it "can specify a type of :boolean" do
+      subject.add_search_field(:some_boolean, :boolean)
+      { "some_boolean" => true }.should be_included_in_extracted_attributes_from("some_boolean:true")
+    end
+
+    it "can specify a type of :date" do
+      subject.add_search_field(:some_date, :date)
+      { "some_date" => Date.parse('2010-01-05') }.should be_included_in_extracted_attributes_from("some_date:2010-01-05")
+    end
+
+    it "can specifiy a type of :time" do
+      subject.add_search_field(:some_time, :time)
+      { "some_time" => Time.mktime(2010, 1, 5, 12, 0, 0) }.should be_included_in_extracted_attributes_from("some_time:'2010-01-05 12:00:00'")
+    end
+
+    it "can specify a type of :text" do
+      subject.add_search_field(:some_text, :text)
+      { "some_text" => "Hello world" }.should be_included_in_extracted_attributes_from("some_text:'Hello world'")
+    end
+
+    it "defaults to a :string field" do
+      subject.add_search_field(:some_string)
+      { "some_string" => "falafel" }.should be_included_in_extracted_attributes_from("some_string:falafel")
+    end
+  end
+
+  context "matching quoted values" do
+    before { subject.add_search_field(:foo) }
+
+    it "matches unquoted values" do
+      { "foo" => "bar" }.should be_included_in_extracted_attributes_from("foo:bar")
+      { "foo" => "b'a'r" }.should be_included_in_extracted_attributes_from("foo:b'a'r")
+      { "foo" => "ba'r" }.should be_included_in_extracted_attributes_from("foo:ba'r")
+    end
+
+    it "matches values within double quotes" do
+      { "foo" => "this is awesome" }.should be_included_in_extracted_attributes_from(%Q(foo:"this is awesome"))
+      { "foo" => "this is 'tricky'" }.should be_included_in_extracted_attributes_from(%Q(foo:"this is 'tricky'"))
+      { "foo" => "'this is even trickier'" }.should be_included_in_extracted_attributes_from(%Q(foo:"'this is even trickier'"))
+    end
+
+    it "matches values within single quotes" do
+      { "foo" => 'this is awesome' }.should be_included_in_extracted_attributes_from(%Q(foo:'this is awesome'))
+      { "foo" => 'this is "tricky"' }.should be_included_in_extracted_attributes_from(%Q(foo:'this is "tricky"'))
+      { "foo" => '"this is even trickier"' }.should be_included_in_extracted_attributes_from(%Q(foo:'"this is even trickier"'))
+    end
+  end
+
+  context "casting values" do
+    it "matches 'yes', 'true', 'y', 'no', 'false', and 'n' as boolean values" do
+      subject.add_search_field(:foo, :boolean)
+      { "foo" => true }.should be_included_in_extracted_attributes_from("foo:yes")
+      { "foo" => true }.should be_included_in_extracted_attributes_from("foo:y")
+      { "foo" => true }.should be_included_in_extracted_attributes_from("foo:true")
+      { "foo" => false }.should be_included_in_extracted_attributes_from("foo:no")
+      { "foo" => false }.should be_included_in_extracted_attributes_from("foo:n")
+      { "foo" => false }.should be_included_in_extracted_attributes_from("foo:false")
+    end
+
+    it "parses integers as Integer objects" do
+      subject.add_search_field(:foo, :integer)
+      subject.add_search_field(:bar, :integer)
+      { "foo" => 1, "bar" => 2 }.should be_included_in_extracted_attributes_from("foo:1 bar:2.8")
+    end
+
+    it "parses decimal values as Float objects" do
+      subject.add_search_field(:foo, :float)
+      { "foo" => 1.5 }.should be_included_in_extracted_attributes_from("foo:1.5")
+    end
+
+    it "parses dates as instances of Date" do
+      subject.add_search_field(:foo, :date)
+      { "foo" => Date.today }.should be_included_in_extracted_attributes_from("foo:today")
+    end
+
+    it "parses times as instances of Time" do
+      subject.add_search_field(:foo, :time)
+      { "foo" => Time.mktime(2010, 1, 5, 12, 0, 0) }.should be_included_in_extracted_attributes_from("foo:2010-01-05 12:00:00")
+    end
+  end
+
+  context "processing matched values with user-defined lambdas" do
+    it "lets you convert matched values according to your business rules" do
+      subject.add_search_field(:incomplete, :boolean, "complete") {|value| not value }
+      { "complete" => false }.should be_included_in_extracted_attributes_from("incomplete:yes")
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,18 @@
+require "spec"
+require "ostruct"
+require "bloodhound"
+
+Spec::Runner.configure do |config|
+  module CustomMatchers
+    def be_included_in_extracted_attributes_from(attribute_string)
+      simple_matcher :other_set_of_attributes do |given|
+        expected = subject.attributes_from(attribute_string)
+        given.each do |key, value|
+          expected.fetch(key).should == value
+        end
+      end
+    end
+  end
+
+  config.include CustomMatchers
+end

metadata

@@ -0,0 +1,62 @@
+--- !ruby/object:Gem::Specification 
+name: bloodhound
+version: !ruby/object:Gem::Version 
+  version: "0.1"
+platform: ruby
+authors: 
+- "Nicol\xC3\xA1s Sanguinetti"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-01-15 00:00:00 -02:00
+default_executable: 
+dependencies: []
+
+description: Convert strings like 'user:foca age:23' to { 'user' => 'foca' => 'age' => 23 }
+email: contacto@nicolassanguinetti.info
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- .gitignore
+- README.markdown
+- bloodhound.gemspec
+- lib/bloodhound.rb
+- lib/bloodhound/active_record.rb
+- spec/spec_helper.rb
+- spec/bloodhound_spec.rb
+- spec/bloodhound/active_record_spec.rb
+has_rdoc: false
+homepage: http://github.com/foca/bloodhound
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Convert strings like 'user:foca age:23' to { 'user' => 'foca' => 'age' => 23 }
+test_files: []
+