clearly-query 0.3.1.pre

data/lib/clearly/query/compose/special.rb

@@ -0,0 +1,24 @@
+module Clearly
+  module Query
+    module Compose
+
+      # Methods for composing queries containing spacial comparisons.
+      module Special
+        include Clearly::Query::Validate
+
+        private
+
+        # Create null comparison node.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Boolean] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_null_node(node, value)
+          validate_node_or_attribute(node)
+          validate_boolean(value)
+          value ? node.eq(nil) : node.not_eq(nil)
+        end
+
+      end
+    end
+  end
+end

data/lib/clearly/query/compose/subset.rb

@@ -0,0 +1,115 @@
+module Clearly
+  module Query
+    module Compose
+
+      # Methods for composing subset queries.
+      module Subset
+        include Clearly::Query::Validate
+
+        private
+
+        # Create contains condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Object] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_contains_node(node, value)
+          validate_node_or_attribute(node)
+          node.matches(like_syntax(value, {start: true, end: true}))
+        end
+
+        # Create not contains condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Object] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_not_contains_node(node, value)
+          validate_node_or_attribute(node)
+          node.does_not_match(like_syntax(value, {start: true, end: true}))
+        end
+
+        # Create starts_with condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Object] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_starts_with_node(node, value)
+          validate_node_or_attribute(node)
+          node.matches(like_syntax(value, {start: false, end: true}))
+        end
+
+        # Create not starts_with condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Object] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_not_starts_with_node(node, value)
+          validate_node_or_attribute(node)
+          node.does_not_match(like_syntax(value, {start: false, end: true}))
+        end
+
+        # Create ends_with condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Object] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_ends_with_node(node, value)
+          validate_node_or_attribute(node)
+          node.matches(like_syntax(value, {start: true, end: false}))
+        end
+
+        # Create not ends_with condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Object] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_not_ends_with_node(node, value)
+          validate_node_or_attribute(node)
+          node.does_not_match(like_syntax(value, {start: true, end: false}))
+        end
+
+        # Create IN condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Array] values
+        # @return [Arel::Nodes::Node] condition
+        def compose_in_node(node, values)
+          validate_node_or_attribute(node)
+          values = [values].flatten
+          validate_not_blank(values)
+          validate_array(values)
+          validate_array_items(values)
+          node.in(values)
+        end
+
+        # Create NOT IN condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Array] values
+        # @return [Arel::Nodes::Node] condition
+        def compose_not_in_node(node, values)
+          validate_node_or_attribute(node)
+          values = [values].flatten
+          validate_not_blank(values)
+          validate_array(values)
+          validate_array_items(values)
+          node.not_in(values)
+        end
+
+        # Create regular expression condition.
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Object] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_regex_node(node, value)
+          validate_node_or_attribute(node)
+          sanitized_value = sanitize_similar_to_value(value)
+          Arel::Nodes::Regexp.new(node, Arel::Nodes.build_quoted(sanitized_value))
+        end
+
+        # Create negated regular expression condition.
+        # Not available just now, maybe in Arel 6?
+        # @param [Arel::Nodes::Node, Arel::Attributes::Attribute, String] node
+        # @param [Object] value
+        # @return [Arel::Nodes::Node] condition
+        def compose_not_regex_node(node, value)
+          validate_node_or_attribute(node)
+          sanitized_value = sanitize_similar_to_value(value)
+          Arel::Nodes::NotRegexp.new(node, Arel::Nodes.build_quoted(sanitized_value))
+        end
+
+      end
+    end
+  end
+end

data/lib/clearly/query/composer.rb

@@ -0,0 +1,269 @@
+module Clearly
+  module Query
+
+    # Class that composes a query from a filter hash.
+    class Composer
+      include Clearly::Query::Compose::Conditions
+      include Clearly::Query::Validate
+
+      # @return [Array<Clearly::Query::Definition>] available definitions
+      attr_reader :definitions
+
+      # Create an instance of Composer using a set of model query spec definitions.
+      # @param [Array<Clearly::Query::Definition>] definitions
+      # @return [Clearly::Query::Composer]
+      def initialize(definitions)
+        validate_not_blank(definitions)
+        validate_array(definitions)
+        validate_definition_instance(definitions[0])
+        validate_array_items(definitions)
+        @definitions = definitions
+        @table_names = definitions.map { |d| d.table.name }
+        self
+      end
+
+      # Create an instance of Composer from all ActiveRecord models.
+      # @return [Clearly::Query::Composer]
+      def self.from_active_record
+        models = ActiveRecord::Base
+            .descendants
+            .reject { |d| d.name == 'ActiveRecord::SchemaMigration' }
+            .sort { |a, b| a.name <=> b.name }
+            .uniq { |d| d.arel_table.name }
+
+        definitions = models.map do |d|
+          if d.name.include?('HABTM_')
+            Clearly::Query::Definition.new({table: d.arel_table})
+          else
+            Clearly::Query::Definition.new({model: d, hash: d.clearly_query_def})
+          end
+        end
+
+        Composer.new(definitions)
+      end
+
+      # Composes a query from a parsed filter hash.
+      # @param [ActiveRecord::Base] model
+      # @param [Hash] hash
+      # @return [Arel::Nodes::Node, Array<Arel::Nodes::Node>]
+      def query(model, hash)
+        definition = select_definition_from_model(model)
+        # default combiner is :and
+        parse_query(definition, :and, hash)
+      end
+
+      private
+
+      # figure out which model spec to use as the base from the table
+      # select from available definitions
+      # @param [Arel::Table] table
+      # @return [Clearly::Query::Definition]
+      def select_definition_from_table(table)
+        validate_table(table)
+        matches = @definitions.select { |definition| definition.table.name == table.name }
+        if matches.size != 1
+          fail Clearly::Query::QueryArgumentError, "exactly one definition must match, found '#{matches.size}'"
+        end
+
+        matches.first
+      end
+
+      # figure out which model spec to use as the base from the model
+      # select rom available definitions
+      # @param [ActiveRecord::Base] model
+      # @return [Clearly::Query::Definition]
+      def select_definition_from_model(model)
+        validate_model(model)
+        select_definition_from_table(model.arel_table)
+      end
+
+      # Parse a filter hash.
+      # @param [Clearly::Query::Definition] definition
+      # @param [Symbol] query_key
+      # @param [Hash] query_value
+      # @return [Array<Arel::Nodes::Node>]
+      def parse_query(definition, query_key, query_value)
+        if query_value.blank? || query_value.size < 1
+          msg = "filter hash must have at least 1 entry, got '#{query_value.size}'"
+          fail Clearly::Query::QueryArgumentError.new(msg, {hash: query_value})
+        end
+
+        logical_operators = Clearly::Query::Compose::Conditions::OPERATORS_LOGICAL
+
+        mapped_fields = definition.field_mappings.keys
+        standard_fields = definition.all_fields - mapped_fields
+
+        conditions = []
+
+        if logical_operators.include?(query_key)
+          # first deal with logical operators
+          condition = parse_logical_operator(definition, query_key, query_value)
+          conditions.push(condition)
+
+        elsif standard_fields.include?(query_key)
+          # then cater for standard fields
+          field_conditions = parse_standard_field(definition, query_key, query_value)
+          conditions.push(*field_conditions)
+
+        elsif mapped_fields.include?(query_key)
+          # then deal with mapped fields
+          field_conditions = parse_mapped_field(definition, query_key, query_value)
+          conditions.push(*field_conditions)
+
+        elsif @table_names.any? { |tn| query_key.to_s.downcase.start_with?(tn) }
+          # finally deal with fields from other tables
+          field_conditions = parse_custom(definition, query_key, query_value)
+          conditions.push(field_conditions)
+        else
+          fail Clearly::Query::QueryArgumentError.new("unrecognised operator or field '#{query_key}'")
+        end
+
+        conditions
+
+      end
+
+      # Parse a logical operator and it's value.
+      # @param [Clearly::Query::Definition] definition
+      # @param [Symbol] logical_operator
+      # @param [Hash] value
+      # @return [Arel::Nodes::Node]
+      def parse_logical_operator(definition, logical_operator, value)
+        validate_definition_instance(definition)
+        validate_symbol(logical_operator)
+        validate_hash(value)
+        conditions = value.map { |key, value| parse_query(definition, key, value) }
+        condition_combine(logical_operator, *conditions)
+      end
+
+      # Parse a standard field and it's conditions.
+      # @param [Clearly::Query::Definition] definition
+      # @param [Symbol] field
+      # @param [Hash] value
+      # @return [Array<Arel::Nodes::Node>]
+      def parse_standard_field(definition, field, value)
+        validate_definition_instance(definition)
+        validate_symbol(field)
+        validate_hash(value)
+        value.map do |operator, operation_value|
+          condition_components(operator, definition.table, field, definition.all_fields, operation_value)
+        end
+      end
+
+      # Parse a mapped field and it's conditions.
+      # @param [Clearly::Query::Definition] definition
+      # @param [Symbol] field
+      # @param [Hash] value
+      # @return [Array<Arel::Nodes::Node>]
+      def parse_custom(definition, field, value)
+        validate_definition_instance(definition)
+        validate_symbol(field)
+        fail Clearly::Query::QueryArgumentError.new('field name must contain a dot (.)') unless field.to_s.include?('.')
+
+        validate_hash(value)
+
+        # extract table and field
+        dot_index = field.to_s.index('.')
+
+        other_table = field[0, dot_index].to_sym
+        other_model = other_table.to_s.classify.constantize
+        other_field = field[(dot_index + 1)..field.length].to_sym
+
+        table_names = definition.associations_flat.map { |a| a[:join].table_name.to_sym }
+        validate_name(other_table, table_names)
+
+        models = definition.associations_flat.map { |a| a[:join] }
+        validate_association(other_model, models)
+
+        other_definition = select_definition_from_model(other_model)
+
+        conditions = parse_standard_field(other_definition, other_field, value)
+        subquery(definition, other_definition, conditions)
+      end
+
+      # Parse a mapped field
+      # @param [Clearly::Query::Definition] definition
+      # @param [Symbol] field mapped field
+      # @param [Hash] value
+      # @return [Array<Arel::Nodes::Node>]
+      def parse_mapped_field(definition, field, value)
+        validate_definition_instance(definition)
+        mapping = definition.get_field_mapping(field)
+        validate_node_or_attribute(mapping)
+        validate_hash(value)
+        value.map do |operator, operation_value|
+          condition_node(operator, mapping, operation_value)
+        end
+      end
+
+      # Build a subquery restricting definition to conditions on other_definition.
+      # @param [Clearly::Query::Definition] definition
+      # @param [Clearly::Query::Definition] other_definition
+      # @param [Array<Arel::Nodes::Node>] conditions
+      # @return [Array<Arel::Nodes::Node>]
+      def subquery(definition, other_definition, conditions)
+        validate_definition_instance(definition)
+        validate_definition_instance(other_definition)
+        [conditions].flatten.each { |c| validate_node_or_attribute(c) }
+
+        current_model = definition.model
+        current_table = definition.table
+        current_joins = definition.joins
+
+        other_table = other_definition.table
+        other_model = other_definition.model
+        other_joins = other_definition.joins
+
+        # build an exist subquery to apply conditions that
+        # refer to another table
+
+        subquery = other_definition.table
+
+        # add conditions to subquery
+        [conditions].flatten.each do |c|
+          subquery = subquery.where(c)
+        end
+
+        # add joins that provide other table access to current table
+
+
+        which_joins = current_joins
+        join_paths_index = nil
+        join_path_current_index = nil
+        join_path_other_index = nil
+        which_joins.each_with_index do |item, index|
+          join_path_current_index = item.find_index { |j| j[:join] == current_model }
+          join_path_other_index = item.find_index { |j| j[:join] == other_model }
+          if !join_path_current_index.nil? && !join_path_other_index.nil?
+            join_paths_index = index
+            break
+          end
+        end
+
+        first_index = [join_path_current_index, join_path_other_index].min
+        last_index = [join_path_current_index, join_path_other_index].max
+        relevant_joins = which_joins[join_paths_index][first_index..last_index]
+
+
+        relevant_joins.each do |j|
+          join_table = j[:join]
+          join_condition = j[:on]
+
+          # assume this is an arel_table if it doesn't respond to .arel_table
+          arel_table = join_table.respond_to?(:arel_table) ? join_table.arel_table : join_table
+
+          if arel_table.name == other_table.name && !join_condition.nil?
+            # add join as condition if this is the main table in the subquery
+            subquery = subquery.where(join_condition)
+          elsif arel_table.name != other_table.name && !join_condition.nil?
+            # add full join if this is not the main table in the subquery
+            subquery = subquery.join(arel_table).on(join_condition)
+          end
+
+        end
+
+        subquery.project(1).exists
+      end
+
+    end
+  end
+end

data/lib/clearly/query/definition.rb

@@ -0,0 +1,165 @@
+module Clearly
+  module Query
+
+    # Validates and represents a model query specification definition.
+    class Definition
+      include Clearly::Query::Compose::Comparison
+      include Clearly::Query::Compose::Core
+      include Clearly::Query::Compose::Range
+      include Clearly::Query::Compose::Subset
+      include Clearly::Query::Compose::Special
+      include Clearly::Query::Validate
+
+      # @return [ActiveRecord::Base] active record model for this definition
+      attr_reader :model
+
+      # @return [Arel::Table] arel table for this definition
+      attr_reader :table
+
+      # @return [Array<Symbol>] available model fields
+      attr_reader :all_fields
+
+      # @return [Array<Symbol>] available text model fields
+      attr_reader :text_fields
+
+      # @return [Array<Hash>] mapped model fields
+      attr_reader :field_mappings
+
+      # @return [Array<Hash>] model associations hierarchy
+      attr_reader :associations
+
+      # @return [Array<Hash>] model associations flat array
+      attr_reader :associations_flat
+
+      # @return [Array<Array<Hash>>] associations organised to calculate joins
+      attr_reader :joins
+
+      # @return [Hash] defaults
+      attr_reader :defaults
+
+      # Create a Definition
+      # @param [Hash] opts the options to create a message with.
+      # @option opts [ActiveRecord::Base] :model (nil) the ActiveRecord model
+      # @option opts [Hash] :hash (nil) the model definition hash
+      # @option opts [Arel::Table] :table (nil) the arel table
+      # @return [Clearly::Query::Definition]
+      def initialize(opts)
+        opts = {model: nil, hash: nil, table: nil}.merge(opts)
+
+        # two ways to go: model and hash, or table and joins
+        result = nil
+        result = create_from_model(opts[:model], opts[:hash]) unless opts[:model].nil?
+        result = create_from_table(opts[:table]) if result.nil? && !opts[:table].nil?
+
+        fail Clearly::Query::QueryArgumentError.new('could not build definition from options') if result.nil?
+        result
+      end
+
+      # Build custom field from model mappings
+      # @param [Symbol] column_name
+      # @return [Arel::Nodes::Node, Arel::Attributes::Attribute, String]
+      def get_field_mapping(column_name)
+        value = @field_mappings[column_name]
+        if @field_mappings.keys.include?(column_name) && !value.blank?
+          value
+        else
+          nil
+        end
+      end
+
+      private
+
+      # Create a Definition from an ActiveRecord model.
+      # @param [ActiveRecord::Base] model the ActiveRecord model
+      # @param [Hash] hash the model definition hash
+      # @return [Clearly::Query::Definition]
+      def create_from_model(model, hash)
+        validate_model(model)
+        validate_definition(hash)
+
+        @model = model
+        @table = relation_table(model)
+
+        @all_fields = hash[:fields][:valid]
+        @text_fields = hash[:fields][:text]
+
+        mappings = {}
+        hash[:fields][:mappings].each { |m| mappings[m[:name]] = m[:value] }
+        @field_mappings = mappings
+
+        @associations = hash[:associations]
+        @associations_flat = build_associations_flat(@associations)
+
+        if @associations.size > 0
+          node = {join: model, on: nil, associations: hash[:associations]}
+          graph = Clearly::Query::Graph.new(node, :associations)
+          @joins = graph.branches
+        else
+          @joins = []
+        end
+
+        @defaults = hash[:defaults]
+
+        self
+      end
+
+      # Create a Definition for a has and belongs to many table.
+      # @param [Arel::Table] table the arel table
+      # @return [Clearly::Query::Definition]
+      def create_from_table(table)
+        validate_table(table)
+
+        @model = nil
+        @table = table
+        @all_fields = []
+        @text_fields = []
+        @field_mappings = []
+        @associations = []
+        @associations_flat = []
+        @joins = []
+        @defaults = {}
+
+        table_name = table.name
+        associated_table_names = table_name.split('_')
+
+        # assumes associated tables primary key is 'id'
+        # assumes associated table names are the plural version of HABTM _id columns
+        associated_table_names.each do |t|
+          arel_table = Arel::Table.new(t.to_sym)
+          id_column = "#{t.singularize}_id"
+          join = {join: arel_table, on: arel_table[:id].eq(table[id_column]), available: true}
+
+          @all_fields.push(id_column)
+          @associations.push(join)
+          @associations_flat.push(join)
+          @joins.push([join])
+        end
+
+        self
+      end
+
+      # Create a flat array of joins.
+      # @param [Array<Hash>] associations
+      # @return [Array<Hash>] associations
+      def build_associations_flat(associations)
+        joins = []
+
+        if associations.is_a?(Array)
+          more_associations = associations.map { |i| build_associations_flat(i) }
+          joins.push(*more_associations.flatten.compact) if more_associations.size > 0
+
+        elsif associations.is_a?(Hash)
+          joins.push(associations.except(:associations))
+
+          if associations[:associations] && associations[:associations].size > 0
+            more_associations = build_associations_flat(associations[:associations])
+            joins.push(*more_associations.compact) if more_associations.size > 0
+          end
+        end
+
+        joins.uniq
+      end
+
+    end
+  end
+end