activerecord-refined 0.3.3 → 0.4.0

data/lib/active_record/refined/ast.rb

@@ -1,6 +1,20 @@
 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.
@@ -62,6 +76,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 +118,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
 
@@ -131,6 +236,8 @@ module ActiveRecord
 
       class Column < Node
         include Predications
+        include Arithmetics
+        include Aggregations
 
         attr_reader :table_name, :column_name
 
@@ -142,24 +249,55 @@ module ActiveRecord
         def to_arel(_table)
           Arel::Table.new(table_name)[column_name]
         end
+      end
 
-        %i[count sum average maximum minimum].each do |func|
-          define_method(func) { Aggregate.new(self, func) }
+      # 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
+
+        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 +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)
@@ -177,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
 
@@ -229,9 +380,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 +479,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 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
 
-      # 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
+      # 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, element)
+        def initialize(operand, operator, elements)
           @operand = operand
-          @elements = element.is_a?(::Array) ? element : [element]
+          @operator = operator
+          @elements = elements
         end
 
         def to_arel(table)
           arel_operand = to_arel_operand(operand, table)
-          arel_operand.contains(Arel::Nodes.build_quoted(array_literal))
+          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

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,23 +25,96 @@ 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 do |name|
-        define_method(name) {|*args| AST::Function.new(name.to_s.upcase, args) }
+      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
+
+      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
 
     module QueryMethods
@@ -93,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
 
@@ -113,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)
@@ -124,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.3'
+    VERSION = '0.4.0'
   end
 end