dusen 0.1.0 → 0.2.0

data/.gitignore

@@ -4,5 +4,6 @@ pkg
 .idea
 app_root/log/*
 Gemfile.lock
+spec/shared/app_root/db/*.db
 
 

data/README.md

@@ -1,4 +1,162 @@
-Dusen - Maps Google-like queries to ActiveRecord scope chains
-=============================================================
+Dusen - Maps Google-like queries to ActiveRecord scopes
+=======================================================
 
-TODO
+
+Dusen gives your ActiveRecord models a DSL to process Google-like queries like:
+
+    some words
+    "a phrase of words"
+    filetype:pdf
+    a mix of words "and phrases" and qualified:fields
+
+Dusen tokenizes these queries for you and feeds them through simple mappers that
+convert a token to an ActiveRecord scope chain.
+This process is packaged in a class method `.search`:
+
+    Contact.search('makandra software "Ruby on Rails" city:augsburg')
+
+
+Installation
+------------
+
+In your `Gemfile` say:
+
+    gem 'dusen'
+
+Now run `bundle install` and restart your server.
+
+
+
+Processing text queries
+-----------------------
+
+This describes how to define a search syntax that processes queries
+of words and phrases:
+
+    coworking fooville "market ave"
+
+
+Our example will be a simple address book:
+
+    class Contact < ActiveRecord::Base
+
+      validates_presence_of :name, :street, :city, :name
+
+    end
+
+
+We will now teach `Contact` to process a text query like this:
+
+    class Contact < ActiveRecord::Base
+
+      ...
+
+      search_syntax do
+
+        search_by :text do |scope, phrase|
+          columns = [:name, :street, :city, :email]
+          scope.where_like(columns => phrase)
+        end
+
+      end
+
+    end
+
+
+Note how you will only ever need to deal with a single token (word or phrase) and return a scope that matches the token.
+Dusen will take care how these scopes will be chained together.
+
+If we now call `Contact.search('coworking fooville "market ave"')`
+the block supplied to `search_by` is called once per token:
+
+1. `|Contact, 'coworking'|`
+2. `|Contact.where_like(columns => 'coworking'), 'fooville'|`
+3. `|Contact.where_like(columns => 'coworking').where_like(columns => 'fooville'), 'market ave'|`
+
+
+The resulting scope chain is your `Contact` model filtered by
+the given query:
+
+     > Contact.search('coworking fooville "market ave"')
+    => Contact.where_like(columns => 'coworking').where_like(columns => 'fooville').where_like(columns => 'market ave')
+
+
+Note that `where_like` is an utility method that comes with the Dusen gem.
+It takes one or more column names and a phrase and generates an SQL fragment
+like this:
+
+    contacts.name LIKE "%coworking%" OR contacts.street LIKE "%coworking%" OR contacts.email LIKE "%coworking%" OR contacts.email LIKE "%coworking%"
+
+
+Processing queries for qualified fields
+---------------------------------------
+
+Let's give `Contact` a way to explictely search for a contact's email address, without
+going through a full text search. We do this by adding additional `search_by` instructions
+to our model:
+
+    search_syntax do
+
+      search_by :text do |scope, phrase|
+        ...
+      end
+
+     search_by :email do |scope, email|
+       scope.where(:email => email)
+     end
+
+   end
+
+
+The result is this:
+
+     > Contact.search('email:foo@bar.com')
+    => Contact.where(:email => 'foo@bar.com')
+
+
+Feel free to combine text tokens and field tokens:
+
+     > Contact.search('fooville email:foo@bar.com')
+    => Contact.where_like(columns => 'fooville').where(:email => 'foo@bar.com')
+
+
+
+Programmatic access without DSL
+-------------------------------
+
+You can use Dusen's functionality without using the ActiveRecord DSL or the search scope. Here are some method calls to get you started:
+
+    Contact.search_syntax # => #<Dusen::Syntax>
+
+    syntax = Dusen::Syntax.new
+    syntax.learn_field :email do |scope, email|
+      scope.where(:email => email)
+    end
+
+    query = Dusen::Parser.parse('fooville email:foo@bar.com') # => #<Dusen::Query>
+    query.tokens # => [#<Dusen::Token field: 'text', value: 'fooville'>, #<Dusen::Token field: 'email', value: 'foo@bar.com'>]
+    query.to_s # => "fooville + foo@bar.com"
+
+    syntax.search(Contact, query) # => #<ActiveRecord::Relation>
+
+
+Development
+-----------
+
+Test applications for various Rails versions lives in `spec`. You can run specs from the project root by saying:
+
+  bundle exec rake all:spec
+
+If you would like to contribute:
+
+- Fork the repository.
+- Push your changes **with specs**.
+- Send me a pull request.
+
+I'm very eager to keep this gem leightweight and on topic. If you're unsure whether a change would make it into the gem, [talk to me beforehand](mailto:henning.koch@makandra.de).
+
+
+Credits
+-------
+
+Henning Koch from [makandra](http://makandra.com/)

data/lib/dusen/active_record_ext.rb

@@ -2,9 +2,13 @@ module Dusen
   module ActiveRecord
 
     def search_syntax(&dsl)
-      @dusen_syntax = Dusen::Description.read_syntax(&dsl)
-      singleton_class.send(:define_method, :search) do |query_string|
-        @dusen_syntax.search(self, query_string)
+      if dsl
+        @search_syntax = Dusen::Description.read_syntax(&dsl)
+        singleton_class.send(:define_method, :search) do |query_string|
+          @search_syntax.search(self, query_string)
+        end
+      else
+        @search_syntax
       end
     end
 

data/lib/dusen/parser.rb

@@ -8,23 +8,23 @@ module Dusen
     def self.parse(query_string)
       query_string = query_string.dup # we are going to delete substrings in-place
       query = Query.new
-      extract_field_query_atoms(query_string, query)
-      extract_text_query_atoms(query_string, query)
+      extract_field_query_tokens(query_string, query)
+      extract_text_query_tokens(query_string, query)
       query
     end
 
-    def self.extract_text_query_atoms(query_string, query)
+    def self.extract_text_query_tokens(query_string, query)
       while query_string.sub!(TEXT_QUERY, '')
         value = "#{$1}#{$2}"
-        query << Atom.new(value)
+        query << Token.new(value)
       end
     end
 
-    def self.extract_field_query_atoms(query_string, query)
+    def self.extract_field_query_tokens(query_string, query)
       while query_string.sub!(FIELD_QUERY, '')
         field = $1
         value = "#{$2}#{$3}"
-        query << Atom.new(field, value)
+        query << Token.new(field, value)
       end
     end
 

data/lib/dusen/query.rb

@@ -4,11 +4,11 @@ module Dusen
     include Enumerable
 
     def initialize
-      @atoms = []
+      @tokens = []
     end
 
-    def <<(atom)
-      @atoms << atom
+    def <<(token)
+      @tokens << token
     end
 
     def to_s
@@ -16,7 +16,7 @@ module Dusen
     end
 
     def each(&block)
-      @atoms.each(&block)
+      @tokens.each(&block)
     end
 
   end

data/lib/dusen/syntax.rb

@@ -17,9 +17,9 @@ module Dusen
     def search(root_scope, query)
       scope = root_scope
       query = parse(query) if query.is_a?(String)
-      query.each do |atom|
-        scoper = @scopers[atom.field] || unknown_scoper
-        scope = scoper.call(scope, atom.value)
+      query.each do |token|
+        scoper = @scopers[token.field] || unknown_scoper
+        scope = scoper.call(scope, token.value)
       end
       scope
     end

data/lib/dusen/{atom.rb → token.rb}

@@ -1,5 +1,5 @@
 module Dusen
-  class Atom
+  class Token
 
     attr_reader :field, :value
 

data/lib/dusen/version.rb

@@ -1,3 +1,3 @@
 module Dusen
-  VERSION = '0.1.0'
-end
+  VERSION = '0.2.0'
+end

data/lib/dusen.rb

@@ -1,5 +1,5 @@
 require 'dusen/util'
-require 'dusen/atom'
+require 'dusen/token'
 require 'dusen/description'
 require 'dusen/parser'
 require 'dusen/query'

data/spec/shared/dusen/active_record_spec.rb

@@ -34,7 +34,7 @@ describe Dusen::ActiveRecord do
       User.search('city:"Foo Bar"').to_a.should == [match]
     end
 
-    it 'should allow to mix multiple types of atoms in a single query' do
+    it 'should allow to mix multiple types of tokens in a single query' do
       match = User.create!(:name => 'Foo', :city => 'Foohausen')
       no_match = User.create!(:name => 'Foo', :city => 'Barhausen')
       User.search('Foo city:Foohausen').to_a.should == [match]
@@ -42,4 +42,12 @@ describe Dusen::ActiveRecord do
 
   end
 
+  describe '.search_syntax' do
+
+    it "should return the model's syntax definition when called without a block" do
+      User.search_syntax.should be_a(Dusen::Syntax)
+    end
+
+  end
+
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: dusen
 version: !ruby/object:Gem::Version 
-  hash: 27
+  hash: 23
   prerelease: 
   segments: 
   - 0
-  - 1
+  - 2
   - 0
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors: 
 - Henning Koch
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-11-20 00:00:00 +01:00
+date: 2012-11-23 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -47,11 +47,11 @@ files:
 - dusen.gemspec
 - lib/dusen.rb
 - lib/dusen/active_record_ext.rb
-- lib/dusen/atom.rb
 - lib/dusen/description.rb
 - lib/dusen/parser.rb
 - lib/dusen/query.rb
 - lib/dusen/syntax.rb
+- lib/dusen/token.rb
 - lib/dusen/util.rb
 - lib/dusen/version.rb
 - spec/rails-2.3/Gemfile
@@ -110,7 +110,6 @@ files:
 - spec/rails-3.2/spec_helper.rb
 - spec/shared/app_root/app/controllers/application_controller.rb
 - spec/shared/app_root/app/models/user.rb
-- spec/shared/app_root/db/gem_test.db
 - spec/shared/app_root/db/migrate/001_create_users.rb
 - spec/shared/dusen/active_record_spec.rb
 has_rdoc: true