pursuit 0.4.3 → 1.0.1

data/README.md

@@ -1,6 +1,6 @@
 # Pursuit
 
-Advanced key-based searching for ActiveRecord objects.
+Search your ActiveRecord objects with ease!
 
 ## Installation
 
@@ -16,41 +16,224 @@ gem 'pursuit'
 
 ### Usage
 
-You can use the convenient DSL syntax to declare which attributes and relationships are searchable:
+Pursuit comes with three different strategies for interpreting queries:
+
+- Simple
+- Term
+- Predicate
+
+### Simple Search
+
+Simple takes the entire query and generates a SQL `LIKE` (or `ILIKE` for *PostgreSQL*) statement for each attribute
+added to the search instance. Here's an example of how you might use simple to search a hypothetical `Product` record:
+
+```ruby
+search = Pursuit::SimpleSearch.new(Product.all)
+search.search_attribute(:title)
+search.search_attribute(:subtitle)
+search.apply('Green Shirt')
+```
+
+Which results in the following SQL query:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+WHERE
+  "products"."title" LIKE '%Green Shirt%'
+  OR "products"."subtitle" LIKE '%Green Shirt%'
+```
+
+The initializer method also accepts a block, which is evaluated within the instance's context. This can make it cleaner
+when declaring the searchable attributes:
+
+```ruby
+search = Pursuit::SimpleSearch.new(Product.all) do
+  search_attribute :title
+  search_attribute :subtitle
+end
+
+search.apply('Green Shirt')
+```
+
+You can also pass custom `Arel::Attribute::Attribute` objects, which are especially useful when using joins:
+
+```ruby
+search = Pursuit::SimpleSearch.new(
+  Product.left_outer_joins(:variations).group(:id)
+) do
+  search_attribute :title
+  search_attribute ProductVariation.arel_table[:title]
+end
+
+search.apply('Green Shirt')
+```
+
+Which results in the following SQL query:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+  LEFT OUTER JOIN "product_variations" ON "product_variations"."product_id" = "products"."id"
+WHERE
+  "products"."title" LIKE '%Green Shirt%'
+  OR "product_variations"."title" LIKE '%Green Shirt%'
+GROUP BY
+  "products"."id"
+```
+
+### Term Search
+
+Term searches break a query into individual terms on spaces, while providing double and single quoted strings as a
+means to include spaces. Here's an example of using term searches on the same `Product` record from earlier:
 
 ```ruby
-class Product < ActiveRecord::Base
-  searchable do |o|
-    o.relation :variations, :title, :stock_status
-
-    # Attributes can be used for both keyed and unkeyed searching by default, but you can pass either `keyed: false` or
-    # `unkeyed: false` to restrict when the attribute is searched.
-    o.attribute :title
-    o.attribute :description
-    o.attribute :rating, unkeyed: false
-
-    # You can shorten the search keyword by passing the desired search term first, and then the real attribute name
-    # as the second argument.
-    #  => "category*=shirts"
-    o.attribute :category, :category_id
-
-    # It's also possible to query entirely custom Arel nodes by passing a block which returns the Arel node to query.
-    # You could use this to query a person's full name by concatenating their first and last name columns, for example.
-    o.attribute :title_length, unkeyed: false do
-      Arel::Nodes::NamedFunction.new('LENGTH', [
-        arel_table[:title]
-      ])
-    end
-  end
+search = Pursuit::TermSearch.new(Product.all) do
+  search_attribute :title
+  search_attribute :subtitle
 end
+
+search.apply('Green "Luxury Shirt"')
+```
+
+Which results in a SQL query similar to the following:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+WHERE
+  (
+    "products"."title" LIKE '%Green%'
+    OR "products"."subtitle" LIKE '%Green%'
+  ) AND (
+    "products"."title" LIKE '%Luxury Shirt%'
+    OR "products"."subtitle" LIKE '%Luxury Shirt%'
+  )
 ```
 
-This creates a ```.search``` method on your record class which accepts a single query argument:
+### Predicate Search
+
+Predicate searches use a parser (implemented with the `parslet` gem) to provide a minimal query language.
+This syntax is similar to the `WHERE` and `HAVING` clauses in SQL, but uses only symbols for operators and joins.
+
+Attributes can only be used in predicate searches when they have been added to the list of permitted attributes.
+You can also rename attributes, and add attributes for joined records.
+
+Here's a more complex example of using predicate-based searches with joins on the `Product` record from earlier:
 
 ```ruby
-Product.search('plain shirt rating>=3')
+search = Pursuit::PredicateSearch.new(
+  Product.left_outer_join(:category, :variations).group(:id)
+) do
+  # Product Attributes
+  permit_attribute :title
+
+  # Product Category Attributes
+  permit_attribute :category_name, ProductCategory.arel_table[:name]
+
+  # Product Variation Attributes
+  permit_attribute :variation_title, ProductVariation.arel_table[:title]
+  permit_attribute :variation_currency, ProductVariation.arel_table[:currency]
+  permit_attribute :variation_amount, ProductVariation.arel_table[:amount]
+end
+
+search.apply('title = "Luxury Shirt" & (variation_amount = 0 | variation_amount > 1000)')
+```
+
+This translates to "a product whose title is 'Luxury Shirt' and has at least one variation with either an amount of 0,
+or an amount greater than 1000", which could be expressed in SQL as:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+  LEFT OUTER JOIN "product_categories" ON "product_categories"."id" = "products"."category_id"
+  LEFT OUTER JOIN "product_variations" ON "product_variations"."product_id" = "products"."id"
+WHERE
+  "products"."title" = 'Luxury Shirt'
+  AND (
+    "product_variations"."amount" = 0
+    OR "product_variations"."amount" > 1000
+  )
+GROUP BY
+  "products"."id"
 ```
 
+You can use any of the following operators in comparisons:
+
+- `=` checks if the attribute is equal to the value.
+- `!=` checks if the attributes is not equal to the value.
+- `>` checks if the attribute is greater than the value.
+- `<` checks if the attribute is less than the value.
+- `>=` checks if the attribute is greater than or equal to the value.
+- `<=` checks if the attribute is less than or equal to the value.
+- `~` checks if the attribute matches the value (using `LIKE` or `ILIKE`).
+- `!~` checks if the attribute does not match the value (using `LIKE` or `ILIKE`).
+
+Predicate searches also support "aggregate modifiers" which enable the use of aggregate functions, however this feature
+must be explicitly enabled and requires you to use a `GROUP BY` clause:
+
+```ruby
+search = Pursuit::PredicateSearch.new(
+  Product.left_outer_join(:category, :variations).group(:id)
+) do
+  # Product Attributes
+  permit_attribute :title
+
+  # Product Category Attributes
+  permit_attribute :category, ProductCategory.arel_table[:id]
+  permit_attribute :category_name, ProductCategory.arel_table[:name]
+
+  # Product Variation Attributes
+  permit_attribute :variation, ProductVariation.arel_table[:id]
+  permit_attribute :variation_title, ProductVariation.arel_table[:title]
+  permit_attribute :variation_currency, ProductVariation.arel_table[:currency]
+  permit_attribute :variation_amount, ProductVariation.arel_table[:amount]
+end
+
+search.apply('title = "Luxury Shirt" & #variation > 5')
+```
+
+And the resulting SQL from this query:
+
+```sql
+SELECT
+  "products".*
+FROM
+  "products"
+  LEFT OUTER JOIN "product_categories" ON "product_categories"."id" = "products"."category_id"
+  LEFT OUTER JOIN "product_variations" ON "product_variations"."product_id" = "products"."id"
+WHERE
+  "products"."title" = 'Luxury Shirt'
+GROUP BY
+  "products"."id"
+HAVING
+  COUNT("product_variations"."id") > 5
+```
+
+There's no distinction between the `WHERE` and `HAVING` clause in the predicate syntax, as it's intended to be easy to
+use, but this does come with a caveat.
+
+The query must have all aggregate-modified comparisons before or after non-aggregate-modified comparisons, you can't
+mix both.
+
+For example, this query would result in a parsing error: `title ~ Shirt & #variation > 5 & category_name = Shirts`
+
+You can preceed any attribute with one of these aggregate modifier symbols:
+
+- `#` uses the `COUNT` aggregate function
+- `+` uses the `MAX` aggregate function
+- `-` uses the `MIN` aggregate function
+- `*` uses the `SUM` aggregate function
+- `~` uses the `AVG` aggregate function
+
 ## Development
 
 After checking out the repo, run `bundle exec rake spec` to run the tests.

data/bin/console

@@ -1,7 +1,17 @@
 #!/usr/bin/env ruby
 
+# frozen_string_literal: true
+
 require 'bundler/setup'
 require 'pursuit'
 require 'pry'
 
+if ENV['AR'] == 'true'
+  require 'combustion'
+  Combustion.initialize!(:active_record)
+
+  require 'bundler'
+  Bundler.require(:default, :development)
+end
+
 Pry.start

data/config.ru

@@ -3,7 +3,6 @@
 require 'rubygems'
 require 'bundler'
 
-Bundler.require :default, :development
-
-Combustion.initialize! :all
+Bundler.require(:default, :development)
+Combustion.initialize!(:all)
 run Combustion::Application

data/lib/pursuit/aggregate_modifier_not_found.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Raised when an aggregate modifier cannot be found.
+  #
+  class AggregateModifierNotFound < QueryError
+    # @return [String] The aggregate modifier which does not map to an aggregate function.
+    #
+    attr_reader :aggregate_modifier
+
+    # Creates a new error instance.
+    #
+    # @param aggregate_modifier [Symbol] The aggregate modifier which does not map to an aggregate function.
+    #
+    def initialize(aggregate_modifier)
+      @aggregate_modifier = aggregate_modifier
+      super("#{aggregate_modifier} is not a valid aggregate modifier")
+    end
+  end
+end

data/lib/pursuit/aggregate_modifier_required.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Raised when an attribute that must be used with an aggregate modifier is used without one.
+  #
+  class AggregateModifierRequired < QueryError
+    # @return [Symbol] The name of the attribute which must be used with an aggregate modifier.
+    #
+    attr_reader :attribute
+
+    # Creates a new error instance.
+    #
+    # @param attribute [Symbol] The name of the attribute which must be used with an aggregate modifier.
+    #
+    def initialize(attribute)
+      @attribute = attribute
+      super("'#{attribute}' must be used with an aggregate modifier")
+    end
+  end
+end

data/lib/pursuit/aggregate_modifiers_not_available.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Raised when an aggregate modifier is used in a query, but aggregate modifiers are not available.
+  #
+  class AggregateModifiersNotAvailable < QueryError
+    # Creates a new error instance.
+    #
+    def initialize
+      super('Aggregate modifiers cannot be used in this query')
+    end
+  end
+end

data/lib/pursuit/attribute_not_found.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Raised when an attribute cannot be found.
+  #
+  class AttributeNotFound < QueryError
+    # @return [Symbol] The name of the attribute which could not be found.
+    #
+    attr_reader :attribute
+
+    # Creates a new error instance.
+    #
+    # @param attribute [Symbol] The name of the attribute which could not be found.
+    #
+    def initialize(attribute)
+      @attribute = attribute
+      super("'#{attribute}' is not a valid attribute")
+    end
+  end
+end

data/lib/pursuit/constants.rb

@@ -3,5 +3,5 @@
 module Pursuit
   # @return [String] The gem's semantic version number.
   #
-  VERSION = '0.4.3'
+  VERSION = '1.0.1'
 end

data/lib/pursuit/error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Base error class for all pursuit errors.
+  #
+  class Error < StandardError; end
+end

data/lib/pursuit/predicate_parser.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Parser for predicate-based queries.
+  #
+  # Predicate-based queries take an attribute to compare the value of, an operator (such as the equal sign), and the
+  # value to compare with.
+  #
+  # For example, to search for records where the `first_name` attribute is equal to "John" and the `last_name`
+  # attribute contains either "Doe" or "Smith", you would enter:
+  # => "first_name = John & (last_name ~ Doe | last_name ~ Smith)"
+  #
+  class PredicateParser < Parslet::Parser
+    # Whitespace
+
+    rule(:space)  { match('\s').repeat(1) }
+    rule(:space?) { match('\s').repeat(0) }
+
+    # Boolean Types
+
+    rule(:boolean_true)  { stri('true').as(:truthy) }
+    rule(:boolean_false) { stri('false').as(:falsey) }
+    rule(:boolean)       { boolean_true | boolean_false }
+
+    # Numeric Types
+
+    rule(:numeric_prefix) do
+      str('+') | str('-')
+    end
+
+    rule(:integer) do
+      (numeric_prefix.maybe >> match('[0-9]').repeat(1)).as(:integer)
+    end
+
+    rule(:decimal) do
+      (numeric_prefix.maybe >> match('[0-9]').repeat(0) >> str('.') >> match('[0-9]').repeat(1)).as(:decimal)
+    end
+
+    rule(:number) do
+      decimal | integer
+    end
+
+    # Character Types
+
+    rule(:escaped_character) do
+      str('\\') >> match('.')
+    end
+
+    # String Types
+
+    rule(:string_double_quotes) do
+      str('"') >> (escaped_character | match('[^"]')).repeat(0).as(:string_double_quotes) >> str('"')
+    end
+
+    rule(:string_single_quotes) do
+      str("'") >> (escaped_character | match("[^']")).repeat(0).as(:string_single_quotes) >> str("'")
+    end
+
+    rule(:string_no_quotes) do
+      match("[\\w\\!\\'\\+\\,\\-\\.\\/\\:\\?\\@]").repeat(1).as(:string_no_quotes)
+    end
+
+    rule(:string) do
+      string_double_quotes | string_single_quotes | string_no_quotes
+    end
+
+    # Operators
+
+    rule(:operator_equal)                    { str('=') }
+    rule(:operator_not_equal)                { str('!=') }
+    rule(:operator_contains)                 { str('~') }
+    rule(:operator_not_contains)             { str('!~') }
+    rule(:operator_less_than)                { str('<') }
+    rule(:operator_greater_than)             { str('>') }
+    rule(:operator_less_than_or_equal_to)    { str('<=') }
+    rule(:operator_greater_than_or_equal_to) { str('>=') }
+    rule(:operator_and)                      { str('&') }
+    rule(:operator_or)                       { str('|') }
+
+    rule(:comparator) do
+      (
+        operator_greater_than_or_equal_to |
+        operator_less_than_or_equal_to |
+        operator_greater_than |
+        operator_less_than |
+        operator_not_contains |
+        operator_contains |
+        operator_not_equal |
+        operator_equal
+      ).as(:comparator)
+    end
+
+    rule(:joiner) do
+      (
+        operator_and |
+        operator_or
+      ).as(:joiner)
+    end
+
+    # Comparison Operands
+
+    rule(:aggregate_modifier) do
+      match('[\#\*\+\-\~]').as(:aggregate_modifier)
+    end
+
+    rule(:attribute) do
+      string.as(:attribute)
+    end
+
+    rule(:value) do
+      (boolean | number | string).as(:value)
+    end
+
+    # Comparison
+
+    rule(:comparison) do
+      attribute >> space? >> comparator >> space? >> value
+    end
+
+    rule(:comparison_group) do
+      str('(') >> space? >> comparison_node >> space? >> str(')')
+    end
+
+    rule(:comparison_join) do
+      (comparison_group | comparison).as(:left) >> space? >> joiner >> space? >> comparison_node.as(:right)
+    end
+
+    rule(:comparison_node) do
+      comparison_join | comparison_group | comparison
+    end
+
+    # Aggregate Comparison
+
+    rule(:aggregate_comparison) do
+      aggregate_modifier >> attribute >> space? >> comparator >> space? >> value
+    end
+
+    rule(:aggregate_comparison_group) do
+      str('(') >> space? >> aggregate_comparison_node >> space? >> str(')')
+    end
+
+    rule(:aggregate_comparison_join) do
+      (aggregate_comparison_group | aggregate_comparison).as(:left) >>
+        space? >> joiner >> space? >> aggregate_comparison_node.as(:right)
+    end
+
+    rule(:aggregate_comparison_node) do
+      aggregate_comparison_join | aggregate_comparison_group | aggregate_comparison
+    end
+
+    # Predicate
+
+    rule(:predicate_where) do
+      comparison_node.as(:where)
+    end
+
+    rule(:predicate_having) do
+      aggregate_comparison_node.as(:having)
+    end
+
+    rule(:predicate) do
+      space? >> (
+        (predicate_where >> space? >> operator_and >> space? >> predicate_having) |
+        (predicate_having >> space? >> operator_and >> space? >> predicate_where) |
+        predicate_where |
+        predicate_having
+      ) >> space?
+    end
+
+    root(:predicate)
+
+    # Helpers
+
+    def stri(string)
+      string
+        .each_char
+        .map { |c| match("[#{c.upcase}#{c.downcase}]") }
+        .reduce(:>>)
+    end
+  end
+end

data/lib/pursuit/predicate_search.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # :nodoc:
+  #
+  class PredicateSearch
+    # @return [Boolean] `true` when aggregate modifiers can be used in queries, `false` otherwise.
+    #
+    attr_accessor :permit_aggregate_modifiers
+
+    # @return [Hash<Symbol, Arel::Attributes::Attribute>] The attributes permitted for use in queries.
+    #
+    attr_reader :permitted_attributes
+
+    # @return [ActiveRecord::Relation] The relation to which the predicate clauses are added.
+    #
+    attr_reader :relation
+
+    # Creates a new predicate search instance.
+    #
+    # @param relation                   [ActiveRecord::Relation] The relation to which the predicate clauses are added.
+    # @param permit_aggregate_modifiers [Boolean]                Whether aggregate modifiers can be used or not.
+    # @param block                      [Proc]                   The proc to invoke in the search instance (optional).
+    #
+    def initialize(relation, permit_aggregate_modifiers: false, &block)
+      @relation = relation
+      @permit_aggregate_modifiers = permit_aggregate_modifiers
+      @permitted_attributes = HashWithIndifferentAccess.new
+
+      instance_eval(&block) if block
+    end
+
+    # @return [Pursuit::PredicateParser] The parser which converts queries into trees.
+    #
+    def parser
+      @parser ||= PredicateParser.new
+    end
+
+    # @return [Pursuit::PredicateTransform] The transform which converts trees into ARel nodes.
+    #
+    def transform
+      @transform ||= PredicateTransform.new
+    end
+
+    # Permits use of the specified attribute in predicate queries.
+    #
+    # @param  name      [Symbol]                              The name used in the query.
+    # @param  attribute [Arel::Attributes::Attribute, Symbol] The underlying attribute to query.
+    # @return           [Arel::Attributes::Attribute]         The underlying attribute to query.
+    #
+    def permit_attribute(name, attribute = nil)
+      attribute = relation.klass.arel_table[attribute] if attribute.is_a?(Symbol)
+      permitted_attributes[name] = attribute || relation.klass.arel_table[name]
+    end
+
+    # Parse a predicate query into ARel nodes.
+    #
+    # @param  query [String]                          The predicate query.
+    # @return       [Hash<Symbol, Arel::Nodes::Node>] The ARel nodes representing the predicate query.
+    #
+    def parse(query)
+      tree = parser.parse(query)
+      transform.apply(
+        tree,
+        permitted_attributes: permitted_attributes,
+        permit_aggregate_modifiers: permit_aggregate_modifiers
+      )
+    end
+
+    # Returns #relation filtered by the predicate query.
+    #
+    # @param  query [String]                 The predicate query.
+    # @return       [ActiveRecord::Relation] The updated relation with the predicate clauses added.
+    #
+    def apply(query)
+      nodes = parse(query)
+      relation = self.relation
+      relation = relation.where(nodes[:where]) if nodes[:where]
+      relation = relation.having(nodes[:having]) if nodes[:having]
+      relation
+    end
+  end
+end