pursuit 0.4.5 → 1.1.0

data/lib/pursuit/predicate_parser.rb

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Parser for predicate queries.
+  #
+  # Predicate queries take an attribute, an operator (such as the equal sign), and a 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 might use:
+  #
+  # => "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,86 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Provides an interface for declaring which attributes can be used in a predicate query, and a method for applying
+  # a predicate query to an `ActiveRecord::Relation` instance.
+  #
+  # @see Pursuit::PredicateParser
+  # @see Pursuit::PredicateTransform
+  #
+  class PredicateSearch
+    # @return [Arel::Table] The default table to retrieve attributes from.
+    #
+    attr_accessor :default_table
+
+    # @return [Boolean] `true` when aggregate modifiers can be used, `false` otherwise.
+    #
+    attr_accessor :permit_aggregate_modifiers
+
+    # @return [Hash<Symbol, Arel::Attributes::Attribute>] The attributes permitted for use in queries.
+    #
+    attr_accessor :permitted_attributes
+
+    # Creates a new predicate search instance.
+    #
+    # @param default_table              [Arel::Table] The default table to retrieve attributes from.
+    # @param permit_aggregate_modifiers [Boolean]     `true` when aggregate modifiers can be used, `false` otherwise.
+    # @param block                      [Proc]        The proc to invoke in the search instance (optional).
+    #
+    def initialize(default_table: nil, permit_aggregate_modifiers: false, &block)
+      @default_table = default_table
+      @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 = default_table[attribute] if attribute.is_a?(Symbol)
+      permitted_attributes[name] = attribute || default_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)
+      transform.apply(
+        parser.parse(query),
+        permit_aggregate_modifiers: permit_aggregate_modifiers,
+        permitted_attributes: permitted_attributes
+      )
+    end
+
+    # Applies the predicate clauses derived from `query` to `relation`.
+    #
+    # @param  query    [String]                 The predicate query.
+    # @param  relation [ActiveRecord::Relation] The base relation to apply the predicate clauses to.
+    # @return          [ActiveRecord::Relation] The base relation with the predicate clauses applied.
+    #
+    def apply(query, relation)
+      nodes = parse(query)
+      relation = relation.where(nodes[:where]) if nodes[:where]
+      relation = relation.having(nodes[:having]) if nodes[:having]
+      relation
+    end
+  end
+end

data/lib/pursuit/predicate_transform.rb

@@ -0,0 +1,231 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Transform for the tree produced by `Pursuit::PredicateParser`.
+  #
+  # @see Pursuit::PredicateParser
+  #
+  class PredicateTransform < Parslet::Transform
+    # @return [Hash<String, Symbol>] The list of supported aggregate modifiers, and the method name to invoke on the
+    #                                attribute node in order to obtain the function node.
+    #
+    AGGREGATE_MODIFIERS = {
+      '#' => :count,
+      '*' => :sum,
+      '+' => :maximum,
+      '-' => :minimum,
+      '~' => :average
+    }.freeze
+
+    # Boolean Types
+
+    rule(truthy: simple(:_)) { true }
+    rule(falsey: simple(:_)) { false }
+
+    # Numeric Types
+
+    rule(integer: simple(:value)) { Integer(value) }
+    rule(decimal: simple(:value)) { BigDecimal(value) }
+
+    # String Types
+
+    rule(string_double_quotes: [])             { '' }
+    rule(string_double_quotes: simple(:value)) { value.to_s.gsub(/\\(.)/, '\1') }
+
+    rule(string_single_quotes: [])             { '' }
+    rule(string_single_quotes: simple(:value)) { value.to_s.gsub(/\\(.)/, '\1') }
+
+    rule(string_no_quotes: simple(:value)) { value.to_s }
+
+    # Comparisons
+
+    rule(attribute: simple(:attribute), comparator: '=', value: simple(:value)) do |context|
+      eq_node(attribute(context), context[:value])
+    end
+
+    rule(attribute: simple(:attribute), comparator: '!=', value: simple(:value)) do |context|
+      not_eq_node(attribute(context), context[:value])
+    end
+
+    rule(attribute: simple(:attribute), comparator: '<', value: simple(:value)) do |context|
+      lt_node(attribute(context), context[:value])
+    end
+
+    rule(attribute: simple(:attribute), comparator: '>', value: simple(:value)) do |context|
+      gt_node(attribute(context), context[:value])
+    end
+
+    rule(attribute: simple(:attribute), comparator: '<=', value: simple(:value)) do |context|
+      lteq_node(attribute(context), context[:value])
+    end
+
+    rule(attribute: simple(:attribute), comparator: '>=', value: simple(:value)) do |context|
+      gteq_node(attribute(context), context[:value])
+    end
+
+    rule(attribute: simple(:attribute), comparator: '~', value: simple(:value)) do |context|
+      match_node(attribute(context), context[:value])
+    end
+
+    rule(attribute: simple(:attribute), comparator: '!~', value: simple(:value)) do |context|
+      does_not_match_node(attribute(context), context[:value])
+    end
+
+    # Aggregate Comparisons
+
+    rule(
+      aggregate_modifier: simple(:aggregate_modifier),
+      attribute: simple(:attribute),
+      comparator: '=',
+      value: simple(:value)
+    ) do |context|
+      eq_node(aggregate_attribute(context), context[:value])
+    end
+
+    rule(
+      aggregate_modifier: simple(:aggregate_modifier),
+      attribute: simple(:attribute),
+      comparator: '!=',
+      value: simple(:value)
+    ) do |context|
+      not_eq_node(aggregate_attribute(context), context[:value])
+    end
+
+    rule(
+      aggregate_modifier: simple(:aggregate_modifier),
+      attribute: simple(:attribute),
+      comparator: '<',
+      value: simple(:value)
+    ) do |context|
+      lt_node(aggregate_attribute(context), context[:value])
+    end
+
+    rule(
+      aggregate_modifier: simple(:aggregate_modifier),
+      attribute: simple(:attribute),
+      comparator: '>',
+      value: simple(:value)
+    ) do |context|
+      gt_node(aggregate_attribute(context), context[:value])
+    end
+
+    rule(
+      aggregate_modifier: simple(:aggregate_modifier),
+      attribute: simple(:attribute),
+      comparator: '<=',
+      value: simple(:value)
+    ) do |context|
+      lteq_node(aggregate_attribute(context), context[:value])
+    end
+
+    rule(
+      aggregate_modifier: simple(:aggregate_modifier),
+      attribute: simple(:attribute),
+      comparator: '>=',
+      value: simple(:value)
+    ) do |context|
+      gteq_node(aggregate_attribute(context), context[:value])
+    end
+
+    rule(
+      aggregate_modifier: simple(:aggregate_modifier),
+      attribute: simple(:attribute),
+      comparator: '~',
+      value: simple(:value)
+    ) do |context|
+      match_node(aggregate_attribute(context), context[:value])
+    end
+
+    rule(
+      aggregate_modifier: simple(:aggregate_modifier),
+      attribute: simple(:attribute),
+      comparator: '!~',
+      value: simple(:value)
+    ) do |context|
+      does_not_match_node(aggregate_attribute(context), context[:value])
+    end
+
+    # Joins
+
+    rule(left: simple(:left), joiner: '&', right: simple(:right)) do
+      left.and(right)
+    end
+
+    rule(left: simple(:left), joiner: '|', right: simple(:right)) do
+      left.or(right)
+    end
+
+    # Helpers
+
+    class << self
+      def attribute(context)
+        attribute_name = context[:attribute].to_sym
+        attribute = context.dig(:permitted_attributes, attribute_name)
+        raise AttributeNotFound, attribute_name if attribute.blank?
+        raise AggregateModifierRequired, attribute_name if attribute.name == Arel.star
+
+        attribute
+      end
+
+      def aggregate_attribute(context)
+        raise AggregateModifiersNotAvailable unless context[:permit_aggregate_modifiers]
+
+        attribute_name = context[:attribute].to_sym
+        attribute = context.dig(:permitted_attributes, attribute_name)
+        raise AttributeNotFound, attribute_name if attribute.blank?
+
+        aggregate_modifier_name = context[:aggregate_modifier].to_s
+        aggregate_modifier = AGGREGATE_MODIFIERS[aggregate_modifier_name]
+        raise AggregateModifierNotFound, aggregate_modifier_name unless aggregate_modifier
+
+        attribute.public_send(aggregate_modifier)
+      end
+
+      def eq_node(attribute, value)
+        value = ActiveRecord::Base.sanitize_sql(value) if value.is_a?(String)
+        return attribute.eq(value) if value.present?
+
+        attribute.eq(nil).or(attribute.matches_regexp('^\s*$'))
+      end
+
+      def not_eq_node(attribute, value)
+        value = ActiveRecord::Base.sanitize_sql(value) if value.is_a?(String)
+        return attribute.not_eq(value) if value.present?
+
+        attribute.not_eq(nil).and(attribute.does_not_match_regexp('^\s*$'))
+      end
+
+      def gt_node(attribute, value)
+        value = ActiveRecord::Base.sanitize_sql(value) if value.is_a?(String)
+        attribute.gt(value)
+      end
+
+      def gteq_node(attribute, value)
+        value = ActiveRecord::Base.sanitize_sql(value) if value.is_a?(String)
+        attribute.gteq(value)
+      end
+
+      def lt_node(attribute, value)
+        value = ActiveRecord::Base.sanitize_sql(value) if value.is_a?(String)
+        attribute.lt(value)
+      end
+
+      def lteq_node(attribute, value)
+        value = ActiveRecord::Base.sanitize_sql(value) if value.is_a?(String)
+        attribute.lteq(value)
+      end
+
+      def match_node(attribute, value)
+        value = ActiveRecord::Base.sanitize_sql_like(value) if value.is_a?(String)
+        value = value.blank? ? '%' : "%#{value}%"
+        attribute.matches(value)
+      end
+
+      def does_not_match_node(attribute, value)
+        value = ActiveRecord::Base.sanitize_sql_like(value) if value.is_a?(String)
+        value = value.blank? ? '%' : "%#{value}%"
+        attribute.does_not_match(value)
+      end
+    end
+  end
+end

data/lib/pursuit/query_error.rb

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

data/lib/pursuit/simple_search.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Provides an interface for declaring which attributes should be searched in a simple query, and a method for applying
+  # a simple query to an `ActiveRecord::Relation` instance.
+  #
+  class SimpleSearch
+    # @return [Set<Arel::Attributes::Attribute>] The attributes to match against.
+    #
+    attr_accessor :attributes
+
+    # @return [Arel::Table] The default table to retrieve attributes from.
+    #
+    attr_accessor :default_table
+
+    # Creates a new simple search instance.
+    #
+    # @param default_table [Arel::Table] The default table to retrieve attributes from.
+    # @param block         [Proc]        The proc to invoke in the search instance (optional).
+    #
+    def initialize(default_table: nil, &block)
+      @attributes = Set.new
+      @default_table = default_table
+
+      instance_eval(&block) if block
+    end
+
+    # Adds an attribute to match against in queries.
+    #
+    # @param  attribute [Arel::Attributes::Attribute, Symbol] The underlying attribute to query.
+    # @return           [Arel::Attributes::Attribute]         The underlying attribute to query.
+    #
+    def search_attribute(attribute)
+      attribute = default_table[attribute] if attribute.is_a?(Symbol)
+      attributes.add(attribute)
+    end
+
+    # Parse a simple query into an ARel node.
+    #
+    # @param  query [String]            The simple query.
+    # @return       [Arel::Nodes::Node] The ARel node representing the simple query.
+    #
+    def parse(query)
+      value = ActiveRecord::Base.sanitize_sql_like(query)
+      value = "%#{value}%"
+
+      attributes.inject(nil) do |previous_node, attribute|
+        node = attribute.matches(value)
+        next node unless previous_node
+
+        previous_node.or(node)
+      end
+    end
+
+    # Applies the simple clauses derived from `query` to `relation`.
+    #
+    # @param  query    [String]                 The simple query.
+    # @param  relation [ActiveRecord::Relation] The base relation to apply the simple clauses to.
+    # @return          [ActiveRecord::Relation] The base relation with the simple clauses applied.
+    #
+    def apply(query, relation)
+      node = parse(query)
+      node ? relation.where(node) : relation.none
+    end
+  end
+end

data/lib/pursuit/term_parser.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Parser for a list of terms.
+  #
+  class TermParser < Parslet::Parser
+    # Whitespace
+
+    rule(:space)  { match('\s').repeat(1) }
+    rule(:space?) { match('\s').repeat(0) }
+
+    # 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('[^\s]').repeat(1).as(:string_no_quotes)
+    end
+
+    rule(:string) do
+      string_double_quotes | string_single_quotes | string_no_quotes
+    end
+
+    # Terms
+
+    rule(:term)      { string.as(:term) }
+    rule(:term_pair) { term.as(:left) >> space >> term_node.as(:right) }
+    rule(:term_node) { term_pair | term }
+    rule(:terms)     { space? >> term_node >> space? }
+    root(:terms)
+  end
+end

data/lib/pursuit/term_search.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+module Pursuit
+  # Provides an interface for declaring which attributes should be searched in a term query, and a method for applying
+  # a term query to an `ActiveRecord::Relation` instance.
+  #
+  # @see Pursuit::TermParser
+  # @see Pursuit::TermTransform
+  #
+  class TermSearch
+    # @return [Set<Arel::Attributes::Attribute>] The attributes to match against.
+    #
+    attr_accessor :attributes
+
+    # @return [Arel::Table] The default table to retrieve attributes from.
+    #
+    attr_accessor :default_table
+
+    # Creates a new term search instance.
+    #
+    # @param default_table [Arel::Table] The default table to retrieve attributes from.
+    # @param block         [Proc]        The proc to invoke in the search instance (optional).
+    #
+    def initialize(default_table: nil, &block)
+      @attributes = Set.new
+      @default_table = default_table
+
+      instance_eval(&block) if block
+    end
+
+    # @return [Pursuit::TermParser] The parser which converts queries into trees.
+    #
+    def parser
+      @parser ||= TermParser.new
+    end
+
+    # @return [Pursuit::TermTransform] The transform which converts trees into ARel nodes.
+    #
+    def transform
+      @transform ||= TermTransform.new
+    end
+
+    # Adds an attribute to match against in term queries.
+    #
+    # @param  attribute [Arel::Attributes::Attribute, Symbol] The underlying attribute to query.
+    # @return           [Arel::Attributes::Attribute]         The underlying attribute to query.
+    #
+    def search_attribute(attribute)
+      attribute = default_table[attribute] if attribute.is_a?(Symbol)
+      attributes.add(attribute)
+    end
+
+    # Parse a term query into an ARel node.
+    #
+    # @param  query [String]            The term query.
+    # @return       [Arel::Nodes::Node] The ARel node representing the term query.
+    #
+    def parse(query)
+      tree = parser.parse(query)
+      transform.apply(tree, attributes: attributes)
+    end
+
+    # Applies the term clauses derived from `query` to `relation`.
+    #
+    # @param  query    [String]                 The term query.
+    # @param  relation [ActiveRecord::Relation] The base relation to apply the term clauses to.
+    # @return          [ActiveRecord::Relation] The base relation with the term clauses applied.
+    #
+    def apply(query, relation)
+      node = parse(query)
+      node ? relation.where(node) : relation.none
+    end
+  end
+end