search_lingo 2.0.0.pre2 → 2.0.0.pre3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48dc212ce20b6ca6d502ad3776598375e9aadf5aba67448a0db0833ff9ae9b22
-  data.tar.gz: 9110f9d208a47032ded854d4541eb2d212359599f8b6ddc13bdb6add5c4ee6ab
+  metadata.gz: 3a72223dbfe08f7309fc060e7bb30afd3e4941810ba9f52fcf50340d6573db74
+  data.tar.gz: c560f79d14abbf7daa9a570ac0594184afb0aca4f69acf66ed86f4af15c6d5be
 SHA512:
-  metadata.gz: a9bfec6dad76471dedab609b8eef445c3b61bfb3eaded66d362849a1f42192de117485b7a9c4157aa8277a7a8a34df5f9c9f1aa15997d001751c92a3259172fe
-  data.tar.gz: 38a894d13baec1cb47a68bf805243fe238355dcf65cc35effae2d5c3d304082883fa73e60de07340d2f29c74ad15e89b5b1ca6d20235a63bfd6cd545b07d67af
+  metadata.gz: 343f682d46cf9ea34fafa75499790e0e0a0474e812c8c00cce81fe75b3f2f1b5de66975d0e2d975f4eca8e12deeedf2e9b927ebcce425fef9871d5405b686023
+  data.tar.gz: 725c8dca98f88dd630475c200e7b2ecb0347cb191df5d10e7e0dae9ac0c3e3d815e2830966f2bf18c6bd5448842a78a946a5ec6e60a6e58acaf83aa586adc6d8

data/.rubocop.yml

@@ -0,0 +1,14 @@
+AllCops:
+  TargetRubyVersion: 2.3.0
+Layout/AlignParameters:
+  Enabled: false
+Metrics/AbcSize:
+  Max: 25
+Style/AndOr:
+  EnforcedStyle: conditionals
+Style/TrailingCommaInArrayLiteral:
+  Enabled: false
+Style/TrailingCommaInHashLiteral:
+  Enabled: false
+Style/NumericPredicate:
+  Enabled: false

data/.travis.yml

@@ -1,4 +1,5 @@
 language: ruby
 rvm:
+  - 2.3.7
   - 2.4.4
   - 2.5.1

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in search_lingo.gemspec

data/Rakefile

@@ -1,9 +1,15 @@
-require "bundler/gem_tasks"
+# frozen-string-literal: true
+
+require 'bundler/gem_tasks'
 require 'rake/testtask'
 
 Rake::TestTask.new do |t|
   t.libs << 'test'
-  t.pattern = 'test/**/test_*.rb'
+  t.pattern = 'test/**/*_test.rb'
 end
 
 task default: :test
+
+task :rubocop do
+  system 'rubocop'
+end

data/bin/console

@@ -1,13 +1,14 @@
 #!/usr/bin/env ruby
+# frozen-string-literal: true
 
-require "bundler/setup"
-require "search_lingo"
+require 'bundler/setup'
+require 'search_lingo'
 
 # You can add fixtures and/or initialization code here to make experimenting
 # with your gem easier. You can also use a different console, if you like.
 
 # (If you use this, don't forget to add pry to your Gemfile!)
-require "pry"
+require 'pry'
 Pry.start
 
 # require "irb"

data/examples/complex.rb

@@ -1,9 +1,19 @@
+# frozen-string-literal: true
+
 class Job < ActiveRecord::Base # :nodoc:
-  # Assume this model has attributes: :id, :date, :name
+  # Attributes:
+  #   :id
+  #   :date
+  #   :name
 end
 
 class Receipt < ActiveRecord::Base # :nodoc:
-  # Assume this model has attributes: :id, :check_no, :check_date, :post_date, :amount
+  # Attributes:
+  #   :id
+  #   :check_no
+  #   :check_date
+  #   :post_date
+  #   :amount
 end
 
 module Parsers # :nodoc:
@@ -13,7 +23,7 @@ module Parsers # :nodoc:
     end
 
     def call(token, chain)
-      token.match /\Aid:\s*([[:digit:]]+)\z/ do |m|
+      token.match(/\Aid:\s*([[:digit:]]+)\z/) do |m|
         chain.where @table => { id: m[1] }
       end
     end

data/examples/sequel_example.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 require 'sequel'
 require 'sqlite3'
 
@@ -17,12 +19,13 @@ require 'sqlite3'
 
 class CategoryParser # :nodoc:
   def call(token, chain)
-    if token.modifier == 'cat'
-      # This is kind of broken. The categories table will be joined once each
-      # time this parser matches a token.
-      chain.join(:categories, id: :category_id)
-        .where Sequel.qualify('categories', 'name') => token.term
-    end
+    return nil unless token.modifier == 'cat'
+
+    # This is not an ideal example. Sequel will join the categories table for
+    # each token that matches. I'm ignoring the problem since this is only an
+    # example.
+    category_name = Sequel.qualify :categories, :name
+    chain.join(:categories, id: :category_id).where category_name => token.term
   end
 end
 
@@ -57,7 +60,8 @@ class TaskSearch < SearchLingo::AbstractSearch # :nodoc:
         date = Date.parse "#{m[:y]}/#{m[:m]}/#{m[:d]}"
         chain.where due_date: date
       rescue ArgumentError
-        # Date.parse raised an ArgumentError
+        # Fail if Date.parse raises an ArgumentError
+        nil
       end
     end
   end

data/lib/search_lingo.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 require 'search_lingo/version'
 require 'search_lingo/abstract_search'
 require 'search_lingo/parsers'

data/lib/search_lingo/abstract_search.rb

@@ -1,6 +1,37 @@
+# frozen-string-literal: true
+
 require 'search_lingo/tokenizer'
 
 module SearchLingo
+  ##
+  # AbstractSearch is an abstract implementation from which search classes
+  # should inherit.
+  #
+  # Search classes are instantiated with a query string and a default scope on
+  # which to perform the search.
+  #
+  # Child classes must implement the #default_parse instance method, and they
+  # may optionally register one or more parsers.
+  #
+  #   class MySearch < SearchLingo::AbstractSearch
+  #     def default_parse(token, chain)
+  #       chain.where attribute: token.term
+  #     end
+  #   end
+  #
+  #   class MyOtherSearch < SearchLingo::AbstractSearch
+  #     parser SearchLingo::Parsers::DateParser.new Job.arel_table[:date]
+  #
+  #     parser do |token, chain|
+  #       token.match(/\Aid: [[:space:]]* (?<id>[[:digit:]]+)\z/x) do |m|
+  #         chain.where id: m[:id]
+  #       end
+  #     end
+  #
+  #     def default_parse(token, chain)
+  #       chain.where Job.arel_table[:name].matches "%#{token.term}%"
+  #     end
+  #   end
   class AbstractSearch
     attr_reader :query, :scope
 
@@ -8,7 +39,9 @@ module SearchLingo
     # Instantiates a new search object. +query+ is the string that is to be
     # parsed and compiled into an actual query. If +query+ is falsey, an empty
     # string will be used. +scope+ is the object to which the compiled query
-    # should be sent, e.g., an +ActiveRecord+ model.
+    # should be sent, e.g., an +ActiveRecord::Relation+.
+    #
+    #   MySearchClass.new 'foo bar: baz "froz quux"', Task.all
     def initialize(query, scope)
       @query = query || ''
       @scope = scope
@@ -46,6 +79,7 @@ module SearchLingo
       unless block_given? ^ parser.respond_to?(:call)
         raise ArgumentError, 'parse must be called with callable OR block'
       end
+
       parsers << (parser || block)
     end
 
@@ -115,7 +149,7 @@ module SearchLingo
     # This is a skeletal implementation that raises +NotImplementedError+.
     # Child classes should provide their own implementation. At a minimum, that
     # implementation should return +chain+. (Doing so would ignore +token+.)
-    def default_parse(token, chain)
+    def default_parse(_token, _chain)
       raise NotImplementedError,
         "#default_parse must be implemented by #{self.class}"
     end

data/lib/search_lingo/constants.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module SearchLingo
   ##
   # Pattern for matching modifiers within a token.

data/lib/search_lingo/parsers.rb

@@ -1 +1,3 @@
+# frozen-string-literal: true
+
 require 'search_lingo/parsers/date_parser'

data/lib/search_lingo/parsers/date_parser.rb

@@ -1,36 +1,57 @@
+# frozen-string-literal: true
+
 require 'search_lingo/parsers/mdy'
 
 module SearchLingo
   module Parsers # :nodoc:
+    ##
+    # DateParser is an example parser which handles dates that adhere to the
+    # MDY format used in the US. It uses `SearchLingo::Parsers::MDY.parse` to
+    # parse the date. It handles simple dates as well as closed and open-ended
+    # date ranges.
+    #
+    # Examples of single dates are 7/14, 7/14/17, and 7/14/2017.
+    # Examples of closed date ranges are 1/1-6/30 and 7/1/16-6/30/18.
+    # Examples of open date ranges are -6/30 and 7/1/17-.
     class DateParser
       include MDY
 
+      attr_reader :column, :prefix, :append
+
       ##
       # Instantiates a new DateParser object.
       #
       # The required argument +column+ should be an Arel attribute.
       #
       # If present, the optional argument +modifier+ will be used as the
-      # operator which precedes the date term.
+      # token operator which precedes the date term.
+      #
+      # If a block is provided, it will be used to append additional methods to
+      # the filter chain. (This is useful for static methods that must be
+      # appended to the filter chain independent of the content of the token,
+      # for example, if you need to join another table.)
       #
-      # DateParser.new Booking.arel_table[:date]
-      # DateParser.new Contract.arel_table[:date], modifier: 'contract'
-      def initialize(column, modifier: nil)
+      # DateParser.new Model.arel_table[:date]
+      # DateParser.new Model.arel_table[:date], modifier: 'contract'
+      # DateParser.new Model.arel_table[:date] do |chain|
+      #   chain.joins(:relation)
+      # end
+      def initialize(column, modifier: nil, &block)
         @column = column
-        @prefix = %r{#{modifier}:[[:space:]]*} if modifier
+        @prefix = /#{modifier}:[[:space:]]*/ if modifier
+        @append = if block_given?
+                    block
+                  else
+                    ->(chain) { chain }
+                  end
       end
 
-      attr_reader :column, :prefix
-
       ##
-      # Attempts to parse the token as a date, closed date range, or open date
-      # range.
-      #
-      # Examples of single dates are 7/14, 7/14/17, and 7/14/2017.
-      # Examples of closed date ranges are 1/1-6/30 and 7/1/16-6/30/18.
-      # Examples of open date ranges are -6/30 and 7/1/17-.
+      # Attempts to parse +token+ as a single date, closed date range, or open
+      # date range. If parsing succeeds, the parser sends #where to +chain+
+      # with the appropriate Arel node and returns the result.
       def call(token, chain)
-        catch :stop do
+        catch :halt do
           parse_single_date token, chain
           parse_date_range  token, chain
           parse_lte_date    token, chain
@@ -39,38 +60,40 @@ module SearchLingo
       end
 
       def inspect # :nodoc:
-        '#<%s:0x%x @prefix=%s @column=%s>' %
-          [self.class, object_id << 1, prefix.inspect, column.inspect]
+        format '#<%<cls>s @prefix=%<prefix>s @column=%<column>s>',
+          cls: self.class,
+          prefix: prefix.inspect,
+          column: column.inspect
       end
 
       private
 
-      def parse_single_date(token, chain)
+      def parse_single_date(token, chain) # :nodoc:
         token.match(/\A#{prefix}(?<date>#{US_DATE})\z/) do |m|
           date = parse(m[:date]) or return nil
-          throw :stop, chain.where(column.eq(date))
+          throw :halt, append.call(chain).where(column.eq(date))
         end
       end
 
-      def parse_date_range(token, chain)
+      def parse_date_range(token, chain) # :nodoc:
         token.match(/\A#{prefix}(?<min>#{US_DATE})-(?<max>#{US_DATE})\z/) do |m|
           min = parse(m[:min]) or return nil
           max = parse(m[:max], relative_to: min.next_year) or return nil
-          throw :stop, chain.where(column.in(min..max))
+          throw :halt, append.call(chain).where(column.in(min..max))
         end
       end
 
-      def parse_lte_date(token, chain)
+      def parse_lte_date(token, chain) # :nodoc:
         token.match(/\A#{prefix}-(?<date>#{US_DATE})\z/) do |m|
           date = parse(m[:date]) or return nil
-          throw :stop, chain.where(column.lteq(date))
+          throw :halt, append.call(chain).where(column.lteq(date))
         end
       end
 
-      def parse_gte_date(token, chain)
+      def parse_gte_date(token, chain) # :nodoc:
         token.match(/\A#{prefix}(?<date>#{US_DATE})-\z/) do |m|
           date = parse(m[:date]) or return nil
-          throw :stop, chain.where(column.gteq(date))
+          throw :halt, append.call(chain).where(column.gteq(date))
         end
       end
     end

data/lib/search_lingo/parsers/mdy.rb

@@ -1,7 +1,12 @@
+# frozen-string-literal: true
+
 require 'date'
 
 module SearchLingo
   module Parsers # :nodoc:
+    ##
+    # MDY provides a parser for dates that adhere to the MDY format used in the
+    # US.
     module MDY
       ##
       # Pattern for matching US-formatted date strings.
@@ -22,25 +27,30 @@ module SearchLingo
       # defaults to today's date.
       #
       # Available as both a class method and an instance method.
+      # rubocop:disable Metrics/MethodLength
       def parse(term, relative_to: Date.today)
-        term.match /\A#{US_DATE}\z/ do |m|
+        term.match(/\A#{US_DATE}\z/) do |m|
           return Date.parse "#{m[:y]}/#{m[:m]}/#{m[:d]}" if m[:y]
 
           ref   = relative_to
-          day   = Integer(m[:d])
-          month = Integer(m[:m])
+          month = Integer m[:m]
+          day   = Integer m[:d]
           year  = if month < ref.month || month == ref.month && day <= ref.day
                     ref.year
                   else
                     ref.year - 1
                   end
-
           Date.new year, month, day
         end
       rescue ArgumentError
+        # Fail if Date.parse or Date.new raise ArgumentError.
+        nil
       end
+      # rubocop:enable Metrics/MethodLength
 
+      # rubocop:disable Style/AccessModifierDeclarations:
       module_function :parse
+      # rubocop:enable Style/AccessModifierDeclarations:
     end
   end
 end

data/lib/search_lingo/token.rb

@@ -1,7 +1,22 @@
+# frozen-string-literal: true
+
 require 'delegate'
 require 'search_lingo/constants'
 
 module SearchLingo
+  ##
+  # Single token from a query string. A token consists of a term an an optional
+  # modifier. The term may be a word or multiple words contained within double
+  # quotes. The modifier is one or more alphanumeric characters. The modifier
+  # and term and separated by a colon followed by zero or more whitespace
+  # characters.
+  #
+  # The following are examples of tokens:
+  #
+  #   Token.new('foo')
+  #   Token.new('"foo bar"')
+  #   Token.new('foo: bar')
+  #   Token.new('foo: "bar baz"')
   class Token < DelegateClass(String)
     ##
     # Pattern for decomposing a token into a modifier and a term.
@@ -17,7 +32,7 @@ module SearchLingo
       self[STRUCTURE, 1]
     end
 
-    alias_method :operator, :modifier
+    alias operator modifier
 
     ##
     # Returns the term portion of the token. If the term is wrapped in quotes,
@@ -36,12 +51,15 @@ module SearchLingo
     #   Token.new('foo: bar').compound? # => true
     #   Token.new('bar').compound?      # => false
     def compound?
-      !!modifier
+      !modifier.nil? && !modifier.empty?
     end
 
     def inspect # :nodoc:
-      '#<%s String(%s) modifier=%s term=%s>' %
-        [self.class, super, modifier.inspect, term.inspect]
+      format '#<%<cls>s String(%<str>s) modifier=%<mod>s term=%<term>s>',
+        cls: self.class,
+        str: super,
+        mod: modifier.inspect,
+        term: term.inspect
     end
   end
 end

data/lib/search_lingo/tokenizer.rb

@@ -1,9 +1,17 @@
+# frozen-string-literal: true
+
 require 'forwardable'
 require 'strscan'
 require 'search_lingo/constants'
 require 'search_lingo/token'
 
 module SearchLingo
+  ##
+  # Tokenizer breaks down a query string into individual tokens.
+  #
+  #   Tokenizer.new 'foo'
+  #   Tokenizer.foo 'foo "bar baz"'
+  #   Tokenizer.foo 'foo "bar baz" froz: quux'
   class Tokenizer
     include Enumerable
     extend Forwardable
@@ -30,9 +38,7 @@ module SearchLingo
     def each
       return to_enum(__callee__) unless block_given?
 
-      until scanner.eos?
-        yield self.next
-      end
+      yield self.next until scanner.eos?
     end
 
     ##
@@ -42,6 +48,7 @@ module SearchLingo
       scanner.skip DELIMITER
       token = scanner.scan COMPOUND_TOKEN
       raise StopIteration unless token
+
       Token.new token
     end
 

data/lib/search_lingo/version.rb

@@ -1,3 +1,5 @@
+# frozen-string-literal: true
+
 module SearchLingo
-  VERSION = '2.0.0.pre2'
+  VERSION = '2.0.0.pre3'
 end

data/search_lingo.gemspec

@@ -1,34 +1,43 @@
-# coding: utf-8
-lib = File.expand_path('../lib', __FILE__)
+# frozen-string-literal: true
+
+lib = File.expand_path('lib', __dir__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'search_lingo/version'
 
+# rubocop:disable Metrics/BlockLength
 Gem::Specification.new do |spec|
-  spec.name          = "search_lingo"
+  spec.name          = 'search_lingo'
   spec.version       = SearchLingo::VERSION
-  spec.authors       = ["John Parker"]
-  spec.email         = ["jparker@urgetopunt.com"]
+  spec.authors       = ['John Parker']
+  spec.email         = ['jparker@urgetopunt.com']
 
-  spec.summary       = %q{Framework for defining and parsing search queries.}
-  spec.description   = %q{SearchLingo is a simple framework for defining simple query languages and translating them into application-specific queries.}
-  spec.homepage      = "https://github.com/jparker/search_lingo"
-  spec.license       = "MIT"
+  spec.summary       = 'Framework for defining and parsing search queries.'
+  spec.description   = <<~DESCRIPTION
+    SearchLingo is a simple framework for defining simple query languages and
+    translating them into application-specific queries.
+  DESCRIPTION
+  spec.homepage      = 'https://github.com/jparker/search_lingo'
+  spec.license       = 'MIT'
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
-  spec.bindir        = "exe"
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f|
+    f.match(%r{^(test|spec|features)/})
+  }
+  spec.bindir        = 'exe'
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ["lib"]
+  spec.require_paths = ['lib']
 
   spec.rdoc_options += ['-x', 'examples/', '-x', 'test/']
 
-  spec.required_ruby_version = '>= 2.1'
+  spec.required_ruby_version = '>= 2.3'
 
-  spec.add_development_dependency "bundler", "~> 1.9"
-  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency 'bundler', '~> 1.9'
   spec.add_development_dependency 'minitest'
   spec.add_development_dependency 'minitest-focus'
   spec.add_development_dependency 'mocha'
   spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rake', '~> 10.0'
+  spec.add_development_dependency 'rubocop'
   spec.add_development_dependency 'sequel', '~> 5.0'
   spec.add_development_dependency 'sqlite3'
 end
+# rubocop:enable Metrics/BlockLength

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: search_lingo
 version: !ruby/object:Gem::Version
-  version: 2.0.0.pre2
+  version: 2.0.0.pre3
 platform: ruby
 authors:
 - John Parker
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-10-02 00:00:00.000000000 Z
+date: 2018-10-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -25,21 +25,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '1.9'
 - !ruby/object:Gem::Dependency
-  name: rake
+  name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '10.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest
+  name: minitest-focus
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -53,7 +53,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: minitest-focus
+  name: mocha
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -67,7 +67,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: mocha
+  name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -81,7 +81,21 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: pry
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -122,8 +136,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: SearchLingo is a simple framework for defining simple query languages
-  and translating them into application-specific queries.
+description: |
+  SearchLingo is a simple framework for defining simple query languages and
+  translating them into application-specific queries.
 email:
 - jparker@urgetopunt.com
 executables: []
@@ -131,6 +146,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".gitignore"
+- ".rubocop.yml"
 - ".travis.yml"
 - Gemfile
 - LICENSE.txt
@@ -166,7 +182,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.1'
+      version: '2.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">"