activerecord-refined 0.3.3 → 0.5.0

data/lib/active_record/refined/ast.rb

@@ -1,6 +1,23 @@
 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/
+      # A SQL type as cast writes it: words, at most parenthesized with
+      # lengths -- double precision, decimal(10,2).
+      TYPE_NAME = /\A[[:alpha:]_][[:alnum:]_ ]*(\(\d+(, ?\d+)?\))?\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.
@@ -62,6 +79,30 @@ module ActiveRecord
           Like.new(self, pattern)
         end
 
+        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"
@@ -80,8 +121,75 @@ module ActiveRecord
           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)
-          Member.new(self, 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
 
@@ -113,6 +221,15 @@ module ActiveRecord
           else operand
           end
         end
+
+        # Resolves a function argument: a column or an expression as above,
+        # anything else a value to be quoted.
+        def to_arel_argument(arg, table)
+          case arg
+          when Node, Symbol then to_arel_operand(arg, table)
+          else Arel::Nodes.build_quoted(arg)
+          end
+        end
       end
 
       class Predicate < Node
@@ -131,6 +248,8 @@ module ActiveRecord
 
       class Column < Node
         include Predications
+        include Arithmetics
+        include Aggregations
 
         attr_reader :table_name, :column_name
 
@@ -142,24 +261,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
+
+        attr_reader :left, :operator, :right
 
-        %i[count sum average maximum minimum].each do |func|
-          define_method(func) { Aggregate.new(self, func) }
+        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
 
@@ -168,7 +318,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)
@@ -177,20 +327,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
 
@@ -200,16 +363,80 @@ module ActiveRecord
         end
 
         def to_arel(table)
-          arel_args = args.map do |arg|
-            case arg
-            when Node, Symbol then to_arel_operand(arg, table)
-            else Arel::Nodes.build_quoted(arg)
-            end
-          end
+          arel_args = args.map {|arg| to_arel_argument(arg, table) }
           Arel::Nodes::NamedFunction.new(name, arel_args)
         end
       end
 
+      # EXTRACT(field FROM expr).  The field is grammar rather than a value --
+      # a keyword the adapter reads bare -- so it has to be a plain name,
+      # which Arel upcases on the way out.
+      class Extract < Node
+        include Predications
+        include Arithmetics
+
+        attr_reader :field, :operand
+
+        def initialize(field, operand)
+          @field = AST.check_name(field, ALIAS_NAME, "extract field")
+          @operand = operand
+        end
+
+        def to_arel(table)
+          Arel::Nodes::Extract.new(to_arel_argument(operand, table), field.to_s)
+        end
+      end
+
+      # CAST(expr AS type).  The type is grammar too, written into the SQL as
+      # given -- it is the adapter's own name for the type, and whether it
+      # exists is the database's to say -- so it has to look like one:
+      # a plain name, at most parenthesized with lengths.
+      class Cast < Node
+        include Predications
+        include Arithmetics
+
+        attr_reader :operand, :sql_type
+
+        def initialize(operand, sql_type)
+          @operand = operand
+          @sql_type = AST.check_name(sql_type, TYPE_NAME, "SQL type")
+        end
+
+        def to_arel(table)
+          Arel::Nodes::NamedFunction.new(
+            "CAST",
+            [Arel::Nodes::As.new(to_arel_argument(operand, table),
+                                 Arel::Nodes::SqlLiteral.new(sql_type.to_s))])
+        end
+      end
+
+      # CURRENT_TIMESTAMP and its relatives, what the SQL grammar calls a
+      # datetime value function.  The grammar has them bare, and PostgreSQL
+      # and SQLite reject them written as calls, so unlike Function the name
+      # is emitted without parentheses.  A precision is the one thing that
+      # does go into parentheses, and it is written into the SQL as given, so
+      # only an Integer is accepted.
+      class DatetimeValueFunction < Node
+        include Predications
+        include Arithmetics
+
+        attr_reader :name, :precision
+
+        def initialize(name, precision = nil)
+          unless precision.nil? || precision.is_a?(Integer)
+            raise ArgumentError,
+              "#{precision.inspect} is not an Integer precision"
+          end
+          @name = name
+          @precision = precision
+        end
+
+        def to_arel(_table)
+          Arel::Nodes::SqlLiteral.new(
+            precision ? "#{name}(#{precision})" : name)
+        end
+      end
+
       # A plain SQL comparison. The value is passed through as it is, so a Range
       # or an Array compares against a PostgreSQL range or array column, the way
       # ActiveRecord's own force_equality? types do.
@@ -229,9 +456,27 @@ 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 (SELECT ...) for a
@@ -310,38 +555,80 @@ module ActiveRecord
             inject {|left, right| Or.new(left, right) }
         end
 
-        attr_reader :operand, :pattern, :escape
+        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 turns
-          # into ILIKE on PostgreSQL. like? means SQL LIKE on every adapter.
-          to_arel_operand(operand, table).matches(pattern, escape, true)
+          # 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
 
-      # Containment in a PostgreSQL array column.  The two flavors of "does it
-      # contain this?" split by name the way Ruby's own classes do: include? is
-      # String's substring match (LIKE), member? is Enumerable's element test,
-      # which String does not have.  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 Member < Predicate
-        attr_reader :operand, :elements
+      # 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, element)
+        def initialize(operand, value, negated: false)
           @operand = operand
-          @elements = element.is_a?(::Array) ? element : [element]
+          @value = value
+          @negated = negated
         end
 
         def to_arel(table)
           arel_operand = to_arel_operand(operand, table)
-          arel_operand.contains(Arel::Nodes.build_quoted(array_literal))
+          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