search_lingo 1.0.0.beta2 → 1.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3dfc725892e1b65db47327257cd8c082536dd74b
-  data.tar.gz: 78e4297906559efcb5cedc54b003cf2abfaf4ac1
+  metadata.gz: 5f1e9e130f36eb2a7481db8481a510606e0f250d
+  data.tar.gz: 9add0798376d6e52412102eb0ba76c542f43ca88
 SHA512:
-  metadata.gz: 5359eff62098245796f55f5abe4d3e663e0e56677b7925ba1267bf0e00dda71cfefa84d87c416a57a6b7f21699ca7b2b9914d96b74f37b02fa0597a35c32b931
-  data.tar.gz: aaa8f3414ebf996194ce415e0270fa2321290900ac98092ea34d2dcb43608e3f6df4e62146fea960814063f753ca7b05fd9fb8a3637399dd1459fe786c7700aa
+  metadata.gz: d299c1e7b9fac6aeb2d17ccaaeb4ecacf3afcb42e71b009c9b2da5b9f6fd1b42238e4d33c3338ed1efddea1d776f92df352ad620e68dcbafa96f83fc630305ef
+  data.tar.gz: 8851f6d29a00c39bdce63e8381603a6b2970e8b0804b9549d22d2510203caaef71b04530d04deab7b799da9d240ebb4235429cdedda0e1beca53346eb3ea6bb5

data/.gitignore

@@ -1,4 +1,5 @@
 /.bundle/
+/.bundle-*/
 /.yardoc
 /Gemfile.lock
 /_yardoc/

data/README.md

@@ -13,6 +13,9 @@ project. Although originally designed to work with basic searching with
 ActiveRecord models, it should be usable with other data stores provided they
 let you chain queries together onto a single object.
 
+Be advised this software is still in beta release, and some of the internals
+are still subject to significant change.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -31,6 +34,51 @@ Or install it yourself as:
 
 ## Usage
 
+Here is a simple example.
+
+    class Task < ActiveRecord::Base
+    end
+
+    class TaskSearch < SearchLingo::AbstractSearch
+      def default_parse(token)
+        [:where, 'tasks.name LIKE ?', "%#{token}%"]
+      end
+    end
+
+    TaskSearch.new('foo bar', Task).results
+    # => Task.where('tasks.name LIKE ?', '%foo%').where('tasks.name LIKE ?', '%bar%')
+    TaskSearch.new('"foo bar"', Task).results
+    # => Task.where('tasks.name LIKE ?', '%foo bar%')
+
+And here is a more complex example.
+
+    class Category < ActiveRecord::Base
+      has_many :tasks
+    end
+
+    class Task < ActiveRecord::Base
+      belongs_to :category
+    end
+
+    class TaskSearch < SearchLingo::AbstractSearch
+      parser do |token|
+        token.match /\Acategory:\s*"?(.*?)"?\z/ do |m}
+          [:where, { categories: { name: m[1] } }]
+        end
+      end
+
+      def default_parse(token)
+        [:where, 'tasks.name LIKE ?', "%#{token}%"]
+      end
+
+      def scope
+        @scope.includes(:category).references(:category)
+      end
+    end
+
+    TaskSearch.new('category: "foo bar" baz', Task).results
+    # => Task.includes(:category).references(:category).where(categories: { name: 'foo bar' }).where('tasks.name LIKE ?', '%baz%')
+
 Create a class which inherits from SearchLingo::AbstractSearch. Provide an
 implementation of <code>#default_parse</code> in that class. Register parsers
 for specific types of search tokens using the <code>parser</code> class method.
@@ -57,13 +105,46 @@ succeeds.)
 
 ## Search Classes
 
-Search classes should inherit from SearchLingo::AbstractSearch and they should
-override the <code>#default_parse</code> instance method. It is important that
-this method be defined in such a way that it always succeeds, as the results
-will be sent to the query object via <code>#public_send</code>. In addtion, the
-class method <code>parser</code> can be used to declare additional parsers that
-should be used by the search class. (See the section "Parsing" for more
-information on what makes a suitable parser.)
+Search classes should inherit from SearchLogic::AbstractSearch, and they must
+provide their own implementation of <code>#default_parse</code>. Optionally, a
+search class may also use the parse class method to add specialized parsers for
+handling tokens that match specific patterns. As each token is processed, the
+search class will first run through the specialized parsers. If none of them
+succeed, it will fall back on the <code>#default_parse</code> method. See the
+section "Parsing" for more information on how parsers work and how they should
+be structured.
+
+## Tokenization
+
+Queries are comprised of zero or more tokens separated by white space. A token
+has a term and an optional operator. (A simple token has no operator; a
+compound token does.) A term can be a single word or multiple words joined by
+spaces and contained within double quotes. For example <code>foo</code> and
+<code>"foo bar baz"</code> are both single terms. An operator is one or more
+alphanumeric characters followed by a colon and zero or more spaces.
+
+    QUERY    := TOKEN*
+    TOKEN    := (OPERATOR ':' [[:space:]]*)? TERM
+    OPERATOR := [[:alnum:]]+
+    TERM     := '"' [^"]* '"' | [[:graph:]]+
+
+The following are all examples of tokens:
+
+* <code>foo</code>
+* <code>"foo bar"</code>
+* <code>foo: bar</code>
+* <code>foo: "bar baz"</code>
+
+(If you need a term to equal something that might otherwise be interpreted as
+an operator, you can enclose the term in double quotes, e.g., while <code>foo:
+bar</code> would be interpreted a single compound token, <code>"foo:"
+bar</code> would be treated as two distinct simple tokens.)
+
+Tokens are passed to parsers as instances of the Token class. The Token class
+provides <code>#operator</code> and <code>#term</code> methods, but delegates
+all other behavior to the String class. Consequently, when writing parsers, you
+have the option of either interacting with the token as a raw String or making
+use of the extra functionality of Tokens.
 
 ## Parsers
 
@@ -71,7 +152,7 @@ Any object that can respond to the <code>#call</code> method can be used as a
 parser. If the parser succeeds, it should return an Array of arguments that can
 be sent to the query object using <code>#public_send</code>, e.g.,
 <code>[:where, { id: 42 }]</code>. If the parser fails, it should return a
-falsey value (typically nil).
+falsey value.
 
 For very simple parsers which need not be reusable, you can pass the
 parsing logic to the <code>parser</code> method as a block:
@@ -129,34 +210,6 @@ classes:
       parser Parsers::IdParser.new :categories
     end
 
-## Tokenization
-
-Queries are comprised of one or more tokens separated by spaces. A simple token
-is a term which can be a single word (or date, number, etc.) or multiple terms
-within a pair of double quotes. A compound token is a simple token preceded by
-an operator followed by zero or more spaces.
-
-    QUERY          := TOKEN*
-    TOKEN          := COMPOUND_TOKEN | TERM
-    COMPOUND_TOKEN := OPERATOR TERM
-    OPERATOR       := [[:graph:]]+:
-    TERM           := "[^"]*" | [[:graph:]]+
-
-Terms can be things like:
-
-* foo
-* "foo bar"
-* 6/14/15
-* 1000.00
-
-Operators can be things like:
-
-* foo:
-* bar_baz:
-
-(If you want to perform a query with a term that could potentially be parsed as
-an operator, you would place the term in quotes, i.e., "foo:".)
-
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/lib/search_lingo/abstract_search.rb

@@ -2,13 +2,12 @@ require 'search_lingo/tokenizer'
 
 module SearchLingo
   class AbstractSearch
-    def initialize(query, scope, tokenizer: Tokenizer)
+    def initialize(query, scope)
       @query = query || ''
       @scope = scope
-      @tokenizer = tokenizer.new @query
     end
 
-    attr_reader :query, :scope, :tokenizer
+    attr_reader :query, :scope
 
     def self.parsers
       @parsers ||= []
@@ -16,7 +15,7 @@ module SearchLingo
 
     def self.parser(callable = nil, &block)
       unless callable || block_given?
-        raise ArgumentError, '.parse must be called with callable or block'
+        raise ArgumentError, 'parse must be called with callable or block'
       end
       if callable && block_given?
         warn "WARNING: parse called with callable and block (#{caller.first}"
@@ -48,6 +47,10 @@ module SearchLingo
       end
     end
 
+    def tokenizer
+      @tokenizer ||= Tokenizer.new query
+    end
+
     def parse(token)
       parsers.each do |parser|
         result = parser.call token

data/lib/search_lingo/constants.rb

@@ -0,0 +1,4 @@
+module SearchLingo
+  OPERATOR  = /[[:alnum:]]+/
+  TERM      = /"[^"]+"|[[:graph:]]+/
+end

data/lib/search_lingo/parsers.rb

@@ -0,0 +1,4 @@
+require 'search_lingo/parsers/date_parser'
+require 'search_lingo/parsers/date_range_parser'
+require 'search_lingo/parsers/gte_date_parser'
+require 'search_lingo/parsers/lte_date_parser'

data/lib/search_lingo/token.rb

@@ -1,15 +1,16 @@
 require 'delegate'
+require 'search_lingo/constants'
 
 module SearchLingo
   class Token < DelegateClass(String)
-    FORMAT = %r{\A(?:(\S+):\s*)?"?(.+?)"?\z}
+    STRUCTURE = /\A(?:(#{OPERATOR}):[[:space:]]*)?"?(.+?)"?\z/
 
     def operator
-      self[FORMAT, 1]
+      self[STRUCTURE, 1]
     end
 
     def term
-      self[FORMAT, 2]
+      self[STRUCTURE, 2]
     end
 
     def compound?
@@ -17,7 +18,8 @@ module SearchLingo
     end
 
     def inspect
-      '#<%s %s operator=%s term=%s>' % [self.class, super, operator.inspect, term.inspect]
+      '#<%s String(%s) operator=%s term=%s>' %
+        [self.class, super, operator.inspect, term.inspect]
     end
   end
 end

data/lib/search_lingo/tokenizer.rb

@@ -1,5 +1,6 @@
 require 'forwardable'
 require 'strscan'
+require 'search_lingo/constants'
 require 'search_lingo/token'
 
 module SearchLingo
@@ -7,34 +8,34 @@ module SearchLingo
     include Enumerable
     extend Forwardable
 
-    SIMPLE    = %r{"[^"]*"|[[:graph:]]+}
-    COMPOUND  = %r{(?:[[:graph:]]+:[[:space:]]*)?#{SIMPLE}}
-    DELIMITER = %r{[[:space:]]*}
+    SIMPLE_TOKEN   = /#{TERM}/
+    COMPOUND_TOKEN = /(?:#{OPERATOR}:[[:space:]]*)?#{TERM}/
+    DELIMITER      = /[[:space:]]*/
 
     def initialize(query)
       @scanner = StringScanner.new query.strip
     end
 
-    def enum
-      Enumerator.new do |yielder|
-        until scanner.eos?
-          token = scanner.scan COMPOUND
-          if token
-            yielder << Token.new(token)
-          end
-          scanner.skip DELIMITER
-        end
+    def each
+      return to_enum(__callee__) unless block_given?
+
+      until scanner.eos?
+        yield self.next
       end
     end
 
+    def next
+      scanner.skip DELIMITER
+      token = scanner.scan COMPOUND_TOKEN
+      raise StopIteration unless token
+      Token.new token
+    end
+
     def_delegator :scanner, :reset
-    def_delegators :enum, :each, :next
 
     def simplify
       scanner.unscan
-      Token.new(scanner.scan(SIMPLE)).tap do
-        scanner.skip DELIMITER
-      end
+      Token.new scanner.scan SIMPLE_TOKEN
     end
 
     private

data/lib/search_lingo/version.rb

@@ -1,3 +1,3 @@
 module SearchLingo
-  VERSION = '1.0.0.beta2'
+  VERSION = '1.0.0.beta3'
 end

data/lib/search_lingo.rb

@@ -1,7 +1,3 @@
 require 'search_lingo/version'
 require 'search_lingo/abstract_search'
-
-require 'search_lingo/parsers/date_parser'
-require 'search_lingo/parsers/date_range_parser'
-require 'search_lingo/parsers/gte_date_parser'
-require 'search_lingo/parsers/lte_date_parser'
+require 'search_lingo/parsers'

data/search_lingo.gemspec

@@ -19,6 +19,8 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.required_ruby_version = '>= 2.1'
+
   spec.add_development_dependency "bundler", "~> 1.9"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency 'minitest'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: search_lingo
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta2
+  version: 1.0.0.beta3
 platform: ruby
 authors:
 - John Parker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2015-06-04 00:00:00.000000000 Z
+date: 2015-06-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -100,6 +100,8 @@ files:
 - examples/simple.rb
 - lib/search_lingo.rb
 - lib/search_lingo/abstract_search.rb
+- lib/search_lingo/constants.rb
+- lib/search_lingo/parsers.rb
 - lib/search_lingo/parsers/date_parser.rb
 - lib/search_lingo/parsers/date_range_parser.rb
 - lib/search_lingo/parsers/gte_date_parser.rb
@@ -121,7 +123,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"