activerecord-refined 0.10.2 → 0.11.0

data/lib/active_record/refined.rb

@@ -27,8 +27,10 @@ module ActiveRecord
       # @!parse include AST::Arithmetics
 
       # @!method as(alias_name, quote: true)
-      #   The column under an alias: `AS "name"`.  The alias is quoted, so
-      #   the name asked for is the name that comes back on every adapter;
+      #   The column under an alias: `AS "name"`.  A number or a string takes
+      #   it too, for a literal in a select list; {BlockContext#value} carries
+      #   the literals that have no `as` of their own.  The alias is quoted,
+      #   so the name asked for is the name that comes back on every adapter;
       #   `quote: false` writes it bare, for a schema that wants the folding,
       #   and then it has to be a plain name.
       #   @param alias_name [Symbol, String]
@@ -36,6 +38,8 @@ module ActiveRecord
       #   @return [AST::As]
       #   @example
       #     Author.select { :name.as(:author) }   # "authors"."name" AS "author"
+      #     Node.select { [:id, 0.as(:depth)] }   # 0 AS "depth"
+      #     Post.select { [:title, "draft".as(:state)] }   # 'draft' AS "state"
 
       # @!method asc
       #   An ascending ordering, which takes `nulls_first` and `nulls_last`.
@@ -113,6 +117,31 @@ module ActiveRecord
           AST::As.new(AST::Value.new(self), alias_name, quote: quote)
         end
       end
+
+      # true, false and nil are refined not for the query's sake but for the
+      # mistake's: their own & | ^ answer a bare boolean, so Ruby reads
+      # `:active == true & cond` as `:active == (true & cond)` and the
+      # condition vanishes without an error.  Beside a column or a node of
+      # the query's they refuse instead; over plain values they stay Ruby's
+      # through super, so a flag computed in the block still computes.
+      [TrueClass, FalseClass, NilClass].each do |klass|
+        refine klass do
+          def &(other)
+            return super unless other.is_a?(::Symbol) || other.is_a?(AST::Node)
+            AST.refuse_ruby_operator(self, :&)
+          end
+
+          def |(other)
+            return super unless other.is_a?(::Symbol) || other.is_a?(AST::Node)
+            AST.refuse_ruby_operator(self, :|)
+          end
+
+          def ^(other)
+            return super unless other.is_a?(::Symbol) || other.is_a?(AST::Node)
+            AST.refuse_ruby_operator(self, :^)
+          end
+        end
+      end
     end
 
     # What a block can call: the aggregates, the functions, CASE, and the
@@ -185,8 +214,8 @@ module ActiveRecord
 
       # The rows of a group gathered into one JSON array, a value from each:
       # `jsonb_agg` on PostgreSQL, `json_group_array` on SQLite,
-      # `JSON_ARRAYAGG` elsewhere.  What it gives is JSON, which compares
-      # as a dug value does.
+      # `JSON_ARRAYAGG` on the MySQL family and Oracle; SQL Server has none.
+      # What it gives is JSON, which compares as a dug value does.
       # @return [AST::JsonAggregate]
       # @example
       #   Post.group { :author_id }.select { json_arrayagg(:title).as(:titles) }
@@ -195,7 +224,7 @@ module ActiveRecord
       end
 
       # The rows of a group gathered into one JSON object, a key and a value
-      # from each.
+      # from each, named as {#json_arrayagg} is; SQL Server has none.
       # @return [AST::JsonAggregate]
       # @example
       #   Post.select { json_objectagg(:title, :meta.dig(:stars)).as(:stars) }
@@ -219,7 +248,8 @@ module ActiveRecord
       # @!endgroup
       # @!group JSON
 
-      # A JSON array built in the row from the values given.
+      # A JSON array built in the row from the values given.  SQL Server
+      # spells the pair its own way and is not carried yet.
       # @return [AST::JsonBuild]
       # @example
       #   Post.select { json_array(:title, :likes).as(:pair) }
@@ -228,7 +258,8 @@ module ActiveRecord
       end
 
       # A JSON object built in the row from a hash whose values are
-      # expressions.
+      # expressions.  SQL Server spells the pair its own way and is not
+      # carried yet.
       # @param pairs [Hash{Symbol, String => Object}]
       # @return [AST::JsonBuild]
       # @example
@@ -253,16 +284,16 @@ module ActiveRecord
       #   `ATAN(x)`.
       #   @return [AST::Function]
       # @!method atan2(y, x)
-      #   `ATAN2(y, x)`.
+      #   `ATAN2(y, x)`: `ATN2` on SQL Server.
       #   @return [AST::Function]
       # @!method ceil(x)
-      #   `CEIL(x)`.
+      #   `CEIL(x)`: `CEILING` on SQL Server.
       #   @return [AST::Function]
       # @!method coalesce(*values)
       #   `COALESCE(a, b, ...)`: the first that is not NULL.
       #   @return [AST::Function]
       # @!method concat(*strings)
-      #   `CONCAT(a, b, ...)`.
+      #   `CONCAT(a, b, ...)`.  Oracle's takes exactly two.
       #   @return [AST::Function]
       # @!method cos(x)
       #   `COS(x)`.
@@ -274,13 +305,15 @@ module ActiveRecord
       #   `FLOOR(x)`.
       #   @return [AST::Function]
       # @!method length(string)
-      #   `LENGTH(string)`.
+      #   `LENGTH(string)`: `LEN` on SQL Server.  What it counts is the
+      #   family's own -- bytes on MySQL, characters elsewhere, and `LEN`
+      #   leaves trailing spaces out; {#char_length} is the portable count.
       #   @return [AST::Function]
       # @!method ln(x)
-      #   `LN(x)`.
+      #   `LN(x)`: `LOG` on SQL Server.
       #   @return [AST::Function]
       # @!method log(base, x)
-      #   `LOG(base, x)`.
+      #   `LOG(base, x)`.  SQL Server takes the arguments the other way round, and is refused.
       #   @return [AST::Function]
       # @!method lower(string)
       #   `LOWER(string)`.
@@ -289,7 +322,7 @@ module ActiveRecord
       #   `LTRIM(string)`.
       #   @return [AST::Function]
       # @!method mod(x, y)
-      #   `MOD(x, y)`.
+      #   `MOD(x, y)`.  SQL Server has only the % operator.
       #   @return [AST::Function]
       # @!method nullif(x, y)
       #   `NULLIF(x, y)`: NULL where the two are equal, x otherwise.
@@ -316,7 +349,7 @@ module ActiveRecord
       #   `SQRT(x)`.
       #   @return [AST::Function]
       # @!method substr(string, from, length = nil)
-      #   `SUBSTR(string, from, length)`.
+      #   `SUBSTR(string, from, length)`: `SUBSTRING` on SQL Server, which insists on the length.
       #   @return [AST::Function]
       # @!method tan(x)
       #   `TAN(x)`.
@@ -346,16 +379,16 @@ module ActiveRecord
       #   `LEAST(a, b, ...)`: `MIN` on SQLite.
       #   @return [AST::Function]
       # @!method log2(x)
-      #   `LOG2(x)`.  PostgreSQL and Oracle have none; `log(2, x)` is their spelling.
+      #   `LOG2(x)`.  PostgreSQL and Oracle have none -- `log(2, x)` is their spelling -- and SQL Server has neither.
       #   @return [AST::Function]
       # @!method log10(x)
       #   `LOG10(x)`.  Oracle has none.
       #   @return [AST::Function]
       # @!method trunc(x, places = 0)
-      #   `TRUNC(x, places)`: `TRUNCATE` on MySQL, which insists on the places.
+      #   `TRUNC(x, places)`: `TRUNCATE` on MySQL, which insists on the places.  SQL Server has none.
       #   @return [AST::Function]
       # @!method now
-      #   `NOW()`.  SQLite and Oracle have none; {#current_timestamp} reaches both.
+      #   `NOW()`.  SQLite, Oracle and SQL Server have none; {#current_timestamp} reaches all three.
       #   @return [AST::Function]
       # @!method bit_and(column)
       #   `BIT_AND(column)`, an aggregate.  PostgreSQL and MySQL have it.
@@ -792,9 +825,9 @@ module ActiveRecord
     module QueryMethods
       # `WHERE`, from a block: a condition built with the comparisons of
       # {BlockSyntax}, combined with `&`, `|` and `!`.
-      # @yieldreturn [AST::Predicate]
+      # @yieldreturn [AST::Predicate, AST::Sql, AST::Operation]
       # @example
-      #   Author.where { :age >= 18 & :country.in?(%w[JP US]) }
+      #   Author.where { (:age >= 18) & :country.in?(%w[JP US]) }
       #   Author.where { !:name.like?("A%") }
       def where(opts = nil, *rest, &block)
         if block
@@ -818,7 +851,7 @@ module ActiveRecord
       end
 
       # `HAVING`, from a block: a condition over the aggregates of a group.
-      # @yieldreturn [AST::Predicate]
+      # @yieldreturn [AST::Predicate, AST::Sql, AST::Operation]
       # @example
       #   Author.group { :country }.having { count(:*) > 1 }
       def having(opts = nil, *rest, &block)
@@ -957,7 +990,7 @@ module ActiveRecord
       # subquery rather than the join.  SQLite and MariaDB have none.
       # @example
       #   top = Post.where { :posts[:author_id] == :authors[:id] }.order { :likes.desc }.limit(1)
-      #   Author.left_outer_joins(top.lateral, as: :top) { true }.select { [:name, :top[:title]] }
+      #   Author.left_outer_joins(top.lateral, as: :top).select { [:name, :top[:title]] }
       def lateral
         spawn.lateral!
       end
@@ -985,6 +1018,7 @@ module ActiveRecord
       # table within the query, which is what makes a self join expressible.
       # Without a block it is Active Record's own `joins`.
       # @param as [Symbol, nil]
+      # @yieldreturn [AST::Predicate, AST::Sql, AST::Operation]
       # @example
       #   Author.joins(:posts) { :posts[:author_id] == :authors[:id] }
       #   Employee.joins(:employees, as: :managers) { :managers[:id] == :employees[:manager_id] }
@@ -1001,6 +1035,7 @@ module ActiveRecord
 
       # `LEFT OUTER JOIN`, as {#joins} takes it.
       # @param as [Symbol, nil]
+      # @yieldreturn [AST::Predicate, AST::Sql, AST::Operation]
       # @example
       #   Author.left_outer_joins(:posts) { :posts[:author_id] == :authors[:id] }
       def left_outer_joins(*args, as: nil, &block)
@@ -1017,6 +1052,7 @@ module ActiveRecord
       # `RIGHT OUTER JOIN`, as {#joins} takes it, of a table or a relation;
       # an association name is not among what it takes.
       # @param as [Symbol, nil]
+      # @yieldreturn [AST::Predicate, AST::Sql, AST::Operation]
       # @example
       #   Post.right_outer_joins(:authors) { :posts[:author_id] == :authors[:id] }
       #
@@ -1033,6 +1069,7 @@ module ActiveRecord
       # `FULL OUTER JOIN`, as {#right_outer_joins} takes it.  The MySQL
       # family has none.
       # @param as [Symbol, nil]
+      # @yieldreturn [AST::Predicate, AST::Sql, AST::Operation]
       def full_outer_joins(*args, as: nil, &block)
         check_full_outer_support
         outer_joins(:full_outer_joins, Arel::Nodes::FullOuterJoin,

data/lib/activerecord-refined/version.rb

@@ -1,7 +1,12 @@
 # frozen_string_literal: true
 
+# The gem tooling's namespace, spelled as the gem name is, not as the
+# ActiveRecord constant the gem extends; only the gemspec reads it.
+# @private
 module Activerecord
+  # @private
   module Refined
-    VERSION = "0.10.2"
+    # @private
+    VERSION = "0.11.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-refined
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.11.0
 platform: ruby
 authors:
   - Shugo Maeda
@@ -272,6 +272,7 @@ files:
   - lib/active_record/refined/dialect/mariadb.rb
   - lib/active_record/refined/dialect/mysql.rb
   - lib/active_record/refined/dialect/mysql_compat.rb
+  - lib/active_record/refined/dialect/mysqlish_json_functions.rb
   - lib/active_record/refined/dialect/oracle.rb
   - lib/active_record/refined/dialect/postgresql.rb
   - lib/active_record/refined/dialect/sql_server.rb