activerecord-refined 0.3.2 → 0.4.0

data/lib/active_record/refined/ast.rb

@@ -1,15 +1,38 @@
 module ActiveRecord
   module Refined
     module AST
+      # Column aliases and function names are written into the SQL as given,
+      # where a value would have been quoted, so anything that is not a plain
+      # name is refused.  Quoting them instead would need the model's adapter,
+      # which does not reach this far, and quoting with the wrong one would be
+      # a bug of its own -- MySQL does not read "x" as an identifier.
+      NAME = /[[:alpha:]_][[:alnum:]_$]*/
+      ALIAS_NAME = /\A#{NAME}\z/
+      FUNCTION_NAME = /\A#{NAME}(\.#{NAME})?\z/
+
+      def self.check_name(name, pattern, what)
+        return name if pattern.match?(name.to_s)
+        raise ArgumentError, "#{name.inspect} is not a plain #{what}"
+      end
+
       # Predicate builders shared by symbols, qualified columns and
       # expressions. Imported into the Symbol refinement with
       # Refinement#import_methods, so every method must be defined with def.
       module Predications
+        # == and != mean SQL = and <>, and = NULL is never true there, so nil
+        # is rejected rather than silently rewritten to IS NULL.  null? builds
+        # its node directly and stays clear of this check.
         def ==(other)
+          if other.nil?
+            raise ArgumentError, "== does not take nil; use null? instead"
+          end
           Comparison.new(self, :==, other)
         end
 
         def !=(other)
+          if other.nil?
+            raise ArgumentError, "!= does not take nil; use !null? instead"
+          end
           Comparison.new(self, :!=, other)
         end
 
@@ -53,17 +76,118 @@ module ActiveRecord
           Like.new(self, pattern)
         end
 
-        def start_with?(prefix)
-          Like.new(self, "#{Like.escape(prefix)}%", Like::ESCAPE)
+        def ilike?(pattern)
+          Like.new(self, pattern, nil, case_sensitive: false)
+        end
+
+        # Case-insensitive equality, folded on both sides rather than left to
+        # the collation, so it means the same thing on every adapter.
+        def casecmp?(value)
+          if value.nil?
+            raise ArgumentError, "casecmp? does not take nil; use null? instead"
+          end
+          Comparison.new(Function.new("LOWER", [self]), :==,
+                         Function.new("LOWER", [value]))
+        end
+
+        # Null-safe comparison: unlike = and <>, these treat NULL as a value,
+        # so not_distinct_from? is the one equality that may take nil.
+        def distinct_from?(value)
+          DistinctFrom.new(self, value, negated: true)
+        end
+
+        def not_distinct_from?(value)
+          DistinctFrom.new(self, value)
+        end
+
+        def start_with?(*prefixes)
+          if prefixes.empty?
+            raise ArgumentError, "start_with? needs at least one prefix"
+          end
+          Like.any(self, prefixes.map {|prefix| "#{Like.escape(prefix)}%" })
         end
 
-        def end_with?(suffix)
-          Like.new(self, "%#{Like.escape(suffix)}", Like::ESCAPE)
+        def end_with?(*suffixes)
+          if suffixes.empty?
+            raise ArgumentError, "end_with? needs at least one suffix"
+          end
+          Like.any(self, suffixes.map {|suffix| "%#{Like.escape(suffix)}" })
         end
 
         def include?(substring)
           Like.new(self, "%#{Like.escape(substring)}%", Like::ESCAPE)
         end
+
+        # The array comparisons carry the meaning of their Ruby namesakes.
+        # member? is Enumerable's element test, so an Array argument is
+        # rejected rather than quietly meaning something Array#member? does
+        # not; whole-array comparisons go by the Set and Array names.
+        def member?(element)
+          if element.is_a?(::Array) || element.is_a?(::Set)
+            raise ArgumentError,
+              "member? takes a single element; use superset? to require every element"
+          end
+          ArrayPredicate.new(self, :"@>", [element])
+        end
+
+        def superset?(elements)
+          ArrayPredicate.new(self, :"@>", ArrayPredicate.elements(elements, "superset?"))
+        end
+
+        def subset?(elements)
+          ArrayPredicate.new(self, :"<@", ArrayPredicate.elements(elements, "subset?"))
+        end
+
+        def intersect?(elements)
+          ArrayPredicate.new(self, :"&&", ArrayPredicate.elements(elements, "intersect?"))
+        end
+      end
+
+      # Arithmetic builders shared by symbols, qualified columns and
+      # expressions.  Imported into the Symbol refinement like Predications,
+      # so every method must be defined with def.
+      module Arithmetics
+        def +(other)
+          Arithmetic.new(self, :+, other)
+        end
+
+        def -(other)
+          Arithmetic.new(self, :-, other)
+        end
+
+        def *(other)
+          Arithmetic.new(self, :*, other)
+        end
+
+        def /(other)
+          Arithmetic.new(self, :/, other)
+        end
+      end
+
+      # Aggregate builders shared by symbols, qualified columns and
+      # expressions.  Imported into the Symbol refinement like Predications,
+      # so every method must be defined with def.
+      module Aggregations
+        # DISTINCT is Arel's only aggregate modifier, and only for count.
+        def count(distinct: false)
+          Aggregate.new(self, :count, distinct: distinct)
+        end
+
+        def sum
+          Aggregate.new(self, :sum)
+        end
+
+        def average
+          Aggregate.new(self, :average)
+        end
+
+        def maximum
+          Aggregate.new(self, :maximum)
+        end
+
+        def minimum
+          Aggregate.new(self, :minimum)
+        end
       end
 
       class Node
@@ -112,6 +236,8 @@ module ActiveRecord
 
       class Column < Node
         include Predications
+        include Arithmetics
+        include Aggregations
 
         attr_reader :table_name, :column_name
 
@@ -123,24 +249,55 @@ module ActiveRecord
         def to_arel(_table)
           Arel::Table.new(table_name)[column_name]
         end
+      end
+
+      # Arithmetic on columns and expressions.  Ruby's precedence puts these
+      # above the comparison operators, so :price * :quantity > 100 groups the
+      # way it reads.
+      class Arithmetic < Node
+        include Predications
+        include Arithmetics
+        include Aggregations
 
-        %i[count sum average maximum minimum].each do |func|
-          define_method(func) { Aggregate.new(self, func) }
+        attr_reader :left, :operator, :right
+
+        def initialize(left, operator, right)
+          @left = left
+          @operator = operator
+          @right = right
+        end
+
+        def to_arel(table)
+          to_arel_operand(left, table).
+            public_send(operator, to_arel_operand(right, table))
         end
       end
 
       class Aggregate < Node
         include Predications
+        include Arithmetics
 
-        attr_reader :operand, :function
+        attr_reader :operand, :function, :distinct
 
-        def initialize(operand, function)
+        def initialize(operand, function, distinct: false)
+          if distinct && function != :count
+            raise ArgumentError, "#{function} does not take distinct"
+          end
+          if distinct && operand == :*
+            raise ArgumentError, "count(:*) does not take distinct; name a column"
+          end
           @operand = operand
           @function = function
+          @distinct = distinct
         end
 
         def to_arel(table)
-          to_arel_operand(operand, table).public_send(function)
+          arel_operand = to_arel_operand(operand, table)
+          if function == :count
+            arel_operand.count(distinct)
+          else
+            arel_operand.public_send(function)
+          end
         end
       end
 
@@ -149,7 +306,7 @@ module ActiveRecord
 
         def initialize(operand, alias_name)
           @operand = operand
-          @alias_name = alias_name
+          @alias_name = AST.check_name(alias_name, ALIAS_NAME, "column alias")
         end
 
         def to_arel(table)
@@ -158,20 +315,33 @@ module ActiveRecord
       end
 
       class Ordering < Node
-        attr_reader :operand, :direction
+        attr_reader :operand, :direction, :nulls
 
-        def initialize(operand, direction)
+        def initialize(operand, direction, nulls = nil)
           @operand = operand
           @direction = direction
+          @nulls = nulls
+        end
+
+        # MySQL has no NULLS FIRST/LAST, but Arel emulates it there with a
+        # leading IS NULL ordering, so these are portable.
+        def nulls_first
+          Ordering.new(operand, direction, :nulls_first)
+        end
+
+        def nulls_last
+          Ordering.new(operand, direction, :nulls_last)
         end
 
         def to_arel(table)
-          to_arel_operand(operand, table).public_send(direction)
+          ordering = to_arel_operand(operand, table).public_send(direction)
+          nulls ? ordering.public_send(nulls) : ordering
         end
       end
 
       class Function < Node
         include Predications
+        include Arithmetics
 
         attr_reader :name, :args
 
@@ -210,12 +380,31 @@ module ActiveRecord
 
         def to_arel(table)
           arel_column = to_arel_operand(column, table)
-          arel_value = value.is_a?(Node) ? value.to_arel(table) : value
+          arel_value =
+            case value
+            when Node then value.to_arel(table)
+            when ActiveRecord::Relation then scalar_subquery(value)
+            else value
+            end
           arel_column.public_send(OPERATOR_MAP.fetch(operator), arel_value)
         end
+
+        private
+
+        # A relation compared against a column has to yield a single value, so
+        # unlike In there is no sensible default select list to fall back on.
+        def scalar_subquery(relation)
+          if relation.select_values.empty?
+            raise ArgumentError,
+              "#{operator} needs a subquery selecting one value; add a select"
+          end
+          relation = relation.send(:apply_join_dependency) if relation.eager_loading?
+          relation.arel
+        end
       end
 
-      # IN for a list of values, BETWEEN for a range.
+      # IN for a list of values, BETWEEN for a range, IN (SELECT ...) for a
+      # relation.
       class In < Predicate
         attr_reader :operand, :values
 
@@ -228,9 +417,49 @@ module ActiveRecord
           arel_operand = to_arel_operand(operand, table)
           case values
           when Range then arel_operand.between(values)
+          when ActiveRecord::Relation then arel_operand.in(subquery(values))
           else arel_operand.in(values)
           end
         end
+
+        private
+
+        # The same treatment ActiveRecord's own RelationHandler gives a
+        # relation used as a value: without an explicit select list the
+        # subquery selects the model's primary key.
+        def subquery(relation)
+          if relation.eager_loading?
+            relation = relation.send(:apply_join_dependency)
+          end
+          if relation.select_values.empty?
+            model = relation.model
+            if model.composite_primary_key?
+              raise ArgumentError,
+                "Cannot map composite primary key #{model.primary_key} to IN"
+            end
+            relation = relation.select(relation.table[model.primary_key])
+          end
+          relation.arel
+        end
+      end
+
+      # EXISTS (SELECT ...) for a relation.  Correlate the subquery with the
+      # outer table through qualified columns.  EXISTS only asks whether a row
+      # comes back, so unlike In there is no select list to fix up.
+      class Exists < Predicate
+        attr_reader :relation
+
+        def initialize(relation)
+          @relation = relation
+        end
+
+        def to_arel(_table)
+          subquery = relation
+          if subquery.eager_loading?
+            subquery = subquery.send(:apply_join_dependency)
+          end
+          subquery.arel.exists
+        end
       end
 
       class Like < Predicate
@@ -243,18 +472,104 @@ module ActiveRecord
           ActiveRecord::Base.sanitize_sql_like(string, ESCAPE)
         end
 
-        attr_reader :operand, :pattern, :escape
+        # ORs one LIKE per pattern, for the shortcuts that accept several
+        # literals the way String#start_with? does.
+        def self.any(operand, patterns)
+          patterns.map {|pattern| new(operand, pattern, ESCAPE) }.
+            inject {|left, right| Or.new(left, right) }
+        end
+
+        attr_reader :operand, :pattern, :escape, :case_sensitive
 
-        def initialize(operand, pattern, escape = nil)
+        def initialize(operand, pattern, escape = nil, case_sensitive: true)
           @operand = operand
           @pattern = pattern
           @escape = escape
+          @case_sensitive = case_sensitive
+        end
+
+        def to_arel(table)
+          # Arel matches case-insensitively unless told otherwise, which is
+          # what picks ILIKE over LIKE on PostgreSQL.
+          to_arel_operand(operand, table).matches(pattern, escape, case_sensitive)
+        end
+      end
+
+      # IS [NOT] DISTINCT FROM, spelled IS / IS NOT on SQLite and <=> on
+      # MySQL.  NULL compares as a value here, which is what separates these
+      # from = and <>.
+      class DistinctFrom < Predicate
+        attr_reader :operand, :value, :negated
+
+        def initialize(operand, value, negated: false)
+          @operand = operand
+          @value = value
+          @negated = negated
         end
 
         def to_arel(table)
-          # Arel matches case-insensitively unless told otherwise, which turns
-          # into ILIKE on PostgreSQL. like? means SQL LIKE on every adapter.
-          to_arel_operand(operand, table).matches(pattern, escape, true)
+          arel_operand = to_arel_operand(operand, table)
+          arel_value = value.is_a?(Node) ? value.to_arel(table) : value
+          if negated
+            arel_operand.is_distinct_from(arel_value)
+          else
+            arel_operand.is_not_distinct_from(arel_value)
+          end
+        end
+      end
+
+      # Comparisons against a PostgreSQL array column, named after the Ruby
+      # methods that mean the same thing: member? is Enumerable's element
+      # test, superset? and subset? are Set's whole-array containment, and
+      # intersect? is Array's "any element in common".  Each name maps to one
+      # operator; the elements are rendered as an array literal, which
+      # PostgreSQL coerces to the column's element type, so any expression
+      # works as the operand and no schema lookup is needed.
+      class ArrayPredicate < Predicate
+        # The whole-array comparisons take the collection kinds their
+        # namesakes compare against: an Array, or a Set for the Set methods.
+        def self.elements(arg, method_name)
+          case arg
+          when ::Array then arg
+          when ::Set then arg.to_a
+          else
+            raise ArgumentError, "#{method_name} takes an Array or Set of elements"
+          end
+        end
+
+        attr_reader :operand, :operator, :elements
+
+        def initialize(operand, operator, elements)
+          @operand = operand
+          @operator = operator
+          @elements = elements
+        end
+
+        def to_arel(table)
+          arel_operand = to_arel_operand(operand, table)
+          quoted = Arel::Nodes.build_quoted(array_literal)
+          case operator
+          when :"@>" then Arel::Nodes::Contains.new(arel_operand, quoted)
+          when :"&&" then Arel::Nodes::Overlaps.new(arel_operand, quoted)
+          else Arel::Nodes::InfixOperation.new(operator, arel_operand, quoted)
+          end
+        end
+
+        private
+
+        # PostgreSQL array input syntax: elements joined by commas inside
+        # braces, and an element is double-quoted whenever it is empty, spells
+        # NULL, or contains a character the parser treats specially.
+        def array_literal
+          encoded = elements.map do |value|
+            s = value.to_s
+            if s.empty? || s.casecmp?("null") || s.match?(/[\s{},"\\]/)
+              "\"#{s.gsub(/["\\]/) {|c| "\\#{c}" }}\""
+            else
+              s
+            end
+          end
+          "{#{encoded.join(',')}}"
         end
       end
 

data/lib/active_record/refined.rb

@@ -3,10 +3,8 @@ module ActiveRecord
     module BlockSyntax
       refine Symbol do
         import_methods AST::Predications
-
-        %i[count sum average maximum minimum].each do |func|
-          define_method(func) { AST::Aggregate.new(self, func) }
-        end
+        import_methods AST::Arithmetics
+        import_methods AST::Aggregations
 
         def as(alias_name)
           AST::As.new(self, alias_name)
@@ -27,18 +25,95 @@ module ActiveRecord
     end
 
     class BlockContext
+      # The model is only consulted to learn which adapter the query is being
+      # built for, which is what decides how a scalar function is spelled.
+      def initialize(model)
+        @model = model
+      end
+
       AGGREGATE_FUNCTIONS = {
-        count: :count, sum: :sum, avg: :average, min: :minimum, max: :maximum,
+        sum: :sum, avg: :average, min: :minimum, max: :maximum,
       }.freeze
 
       AGGREGATE_FUNCTIONS.each do |name, arel_func|
         define_method(name) {|column| AST::Aggregate.new(column, arel_func) }
       end
 
-      SCALAR_FUNCTIONS = %i[upper lower length trim coalesce abs round].freeze
+      def count(column, distinct: false)
+        AST::Aggregate.new(column, :count, distinct: distinct)
+      end
+
+      # Scalar functions, defined as real methods so that a typo is a
+      # NoMethodError and a name Kernel also answers to (format, hash, test)
+      # cannot quietly mean something else.
+      #
+      # The value lists the adapters that differ: a string is what the
+      # function is called there, nil says the adapter has no equivalent.  An
+      # adapter that is not listed spells it like the method.  The families
+      # are what the entries key on, so trilogy reads the mysql column.
+      #
+      # Availability was checked by calling each one; the SQLite figures
+      # assume the math functions its build usually enables.
+      SCALAR_FUNCTIONS = {
+        abs: {}, ceil: {}, coalesce: {}, concat: {}, exp: {}, floor: {},
+        length: {}, ln: {}, log: {}, lower: {}, ltrim: {}, mod: {},
+        nullif: {}, power: {}, replace: {}, round: {}, rtrim: {}, sqrt: {},
+        substr: {}, trim: {}, upper: {},
+        char_length: {sqlite: 'LENGTH'},
+        greatest: {sqlite: 'MAX'},
+        least: {sqlite: 'MIN'},
+        now: {sqlite: nil},
+        date_trunc: {sqlite: nil, mysql: nil},
+        # Named for Kernel#rand, which it also takes back: a block calling
+        # rand would otherwise get Ruby's and never reach the database.
+        rand: {sqlite: 'RANDOM', postgresql: 'RANDOM'},
+        # Two different functions share this name: printf formatting here, and
+        # on MySQL the one that puts separators in a number, which reads a
+        # printf template as the number zero rather than complaining.  The
+        # name keeps the one meaning; fn(:format, ...) reaches MySQL's.
+        format: {mysql: nil},
+      }.freeze
+
+      ADAPTER_FAMILIES = {
+        'sqlite3' => :sqlite,
+        'postgresql' => :postgresql,
+        'postgis' => :postgresql,
+        'mysql2' => :mysql,
+        'trilogy' => :mysql,
+      }.freeze
+
+      SCALAR_FUNCTIONS.each_key do |name|
+        define_method(name) {|*args| AST::Function.new(function_name(name), args) }
+      end
+
+      # Escape hatch for functions without a method of their own.  The name is
+      # emitted as written, so a case-sensitive one can be spelled exactly,
+      # and for that reason it has to be a plain name, optionally qualified by
+      # a schema; anything else is refused rather than written into the SQL.
+      def fn(name, *args)
+        AST::Function.new(
+          AST.check_name(name, AST::FUNCTION_NAME, "function name").to_s, args)
+      end
+
+      def exists?(relation)
+        AST::Exists.new(relation)
+      end
+
+      private
 
-      SCALAR_FUNCTIONS.each do |name|
-        define_method(name) {|*args| AST::Function.new(name.to_s.upcase, args) }
+      def function_name(name)
+        spellings = SCALAR_FUNCTIONS.fetch(name)
+        return name.to_s.upcase unless spellings.key?(adapter_family)
+        spellings.fetch(adapter_family) ||
+          raise(NotImplementedError,
+                "#{name} has no equivalent on #{@model.connection_db_config.adapter}")
+      end
+
+      # An adapter nobody has classified keeps the standard spellings, and is
+      # left to say for itself what it cannot do.
+      def adapter_family
+        @adapter_family ||=
+          ADAPTER_FAMILIES[@model.connection_db_config.adapter] || :unknown
       end
     end
 
@@ -89,19 +164,39 @@ module ActiveRecord
         end
       end
 
-      def joins(*args, &block)
+      # A symbol names a table, which ActiveRecord's own from only takes as a
+      # string.  With `as` it is selected under another name, which is how a
+      # CTE stands in for the model's own table:
+      # with_recursive(tree: [...]).from(:tree, as: :nodes)
+      def from(value, subquery_name = nil, as: nil)
+        unless value.is_a?(Symbol)
+          if as
+            raise ArgumentError, "as: needs the table named as a symbol"
+          end
+          return super(value, subquery_name)
+        end
+        arel_table = Arel::Table.new(value)
+        arel_table = arel_table.alias(as) if as
+        super(arel_table, subquery_name)
+      end
+
+      # `as` names the table within the query, which is what makes a self
+      # join expressible: joins(:employees, as: :managers) { ... }.
+      def joins(*args, as: nil, &block)
         if block
-          super(build_join_node(args.first, Arel::Nodes::InnerJoin, &block))
+          super(build_join_node(args.first, Arel::Nodes::InnerJoin, as, &block))
         else
-          super
+          reject_join_alias(as)
+          super(*args, &block)
         end
       end
 
-      def left_outer_joins(*args, &block)
+      def left_outer_joins(*args, as: nil, &block)
         if block
-          joins(build_join_node(args.first, Arel::Nodes::OuterJoin, &block))
+          joins(build_join_node(args.first, Arel::Nodes::OuterJoin, as, &block))
         else
-          super
+          reject_join_alias(as)
+          super(*args, &block)
         end
       end
 
@@ -109,7 +204,7 @@ module ActiveRecord
 
       def evaluate_block(&block)
         refined_block = block.refined(ActiveRecord::Refined::BlockSyntax)
-        BlockContext.new.instance_exec(&refined_block)
+        BlockContext.new(klass).instance_exec(&refined_block)
       end
 
       def to_arel_field(node)
@@ -120,12 +215,16 @@ module ActiveRecord
         end
       end
 
-      def build_join_node(target_table, join_class, &block)
+      def reject_join_alias(alias_name)
+        return unless alias_name
+        raise ArgumentError, "as: needs a block to write the ON clause with"
+      end
+
+      def build_join_node(target_table, join_class, alias_name, &block)
         ast = evaluate_block(&block)
-        join_class.new(
-          Arel::Table.new(target_table),
-          Arel::Nodes::On.new(ast.to_arel(table))
-        )
+        arel_table = Arel::Table.new(target_table)
+        arel_table = arel_table.alias(alias_name) if alias_name
+        join_class.new(arel_table, Arel::Nodes::On.new(ast.to_arel(table)))
       end
     end
   end

data/lib/activerecord-refined/version.rb

@@ -1,5 +1,5 @@
 module Activerecord
   module Refined
-    VERSION = '0.3.2'
+    VERSION = '0.4.0'
   end
 end