activerecord-refined 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9270b5bf04c083f8cefdd5c669810a63a94a2073c1cae49ba28027693ee5b684
-  data.tar.gz: 23f7e622c8b6b1e85cf670798b705aec8e57c0149315c5fb50699fc95d10ee18
+  metadata.gz: 0f77f34a31719d6697c0d77c378392a6bffa95f033345272e981c51f3fb6f977
+  data.tar.gz: bed64c1983fd76634d924a28a690e3b54705f9a948bf06735314ddd91bed0037
 SHA512:
-  metadata.gz: dcd5cbfab0c7d60498b21a25240f29ae224aa6de7b5fd0a37c627ee10e0f642ed4bb66740734bca03f64f3b231032e273163d68fc9de59b3c07447bef1f69eab
-  data.tar.gz: e701353709c2f8dfb7ebc38a9bdfb9e8b56c940579f139beed543f20391cf8d50166391c3de1718d85797185f4bcfb0cec3a3f4a2d91948c1344527f0ea18e6e
+  metadata.gz: cd03b6d8647c0aef54927c5c68f6c7145ebfcdfa1223abc9b9650905dbaf21281b05678cd708889297a75dfc388e17b886358ebd6db445948b209d1e84d9f6f1
+  data.tar.gz: 2d971fb7ea3f757569b3a8e0127c52693afd20a5eeb15523dd58d2747376f2e426833ef71a343c880e9d225fb9f1a37f1a3f16f1998ac96fb6341e7c5f3f8fb6

data/docs/ctes.md

@@ -18,11 +18,11 @@ Node.with_recursive(
   ]
 ).from_cte(:tree)
 # WITH RECURSIVE "tree" AS (
-#   SELECT "nodes"."id", "nodes"."name", "nodes"."parent_id", 0 AS depth
+#   SELECT "nodes"."id", "nodes"."name", "nodes"."parent_id", 0 AS "depth"
 #     FROM "nodes" WHERE "nodes"."id" = 1
 #   UNION ALL
 #   SELECT "nodes"."id", "nodes"."name", "nodes"."parent_id",
-#          ("tree"."depth" + 1) AS depth
+#          ("tree"."depth" + 1) AS "depth"
 #     FROM "nodes" INNER JOIN "tree" ON "nodes"."parent_id" = "tree"."id"
 # ) SELECT "nodes".* FROM "tree" AS "nodes"
 ```

data/docs/expressions.md

@@ -20,21 +20,35 @@ Item.select { greatest(20 - :quantity, 0).as(:shortfall) }
 Item.where { BigDecimal("1.08") * :price > 500 }
 ```
 
-`&`, `|`, `^`, `~`, `<<` and `>>` are SQL's bitwise operators. Between
-conditions `&` and `|` are AND and OR, and that is where they are defined,
-which leaves them free to mean here what SQL means by them:
+`bitwise_and`, `bitwise_or`, `^`, `~`, `<<` and `>>` are SQL's bitwise
+operations. The first two are named rather than spelled `&` and `|`, which
+mean AND and OR between conditions and nothing else anywhere; `bitwise_xor`
+and `bitwise_not` stand beside `^` and `~` for a reader who would rather have
+the name:
 
 ```ruby
-Post.where { :flags & 4 > 0 }
+Post.where { :flags.bitwise_and(4) > 0 }
 # WHERE ("posts"."flags" & 4) > 0
 
-Post.select { (:flags | 4).as(:flags) }
+Post.select { :flags.bitwise_or(4).as(:flags) }
 Post.select { (~:flags).as(:inverted) }
 ```
 
-Each parenthesises itself, which is what keeps Ruby's grouping: PostgreSQL
-gives `&` and `|` the same precedence and reads `a | b & c` from the left,
-where Ruby reads the `&` first.
+A method binds tighter than any comparison, so nothing has to be parenthesised
+to be compared. Each operation parenthesises itself in the SQL as well, since
+PostgreSQL gives `&` and `|` the same precedence and reads `a | b & c` from
+the left.
+
+Reaching for the operator on a column says which name was meant:
+
+```ruby
+Post.where { :flags & 4 }
+# ArgumentError: & between conditions is AND; bitwise_and is SQL's bitwise operator
+```
+
+Oracle has none of the operators — its one bit operation is the `BITAND`
+function — and the block refuses every one there rather than leaving its
+server to.
 
 A boolean column is refused rather than taken for the one bit it is stored as.
 MySQL and SQLite would quietly answer as `AND` would, PostgreSQL has no such
@@ -79,12 +93,12 @@ since a literal that has been sent `as` has already said it is a value:
 
 ```ruby
 Node.select { [:id, value(0).as(:depth)] }
-# SELECT "nodes"."id", 0 AS depth FROM "nodes"
+# SELECT "nodes"."id", 0 AS "depth" FROM "nodes"
 
 Node.select { [:id, 0.as(:depth)] }         # the same thing
 
 Post.select { [:title, "draft".as(:state)] }
-# SELECT "posts"."title", 'draft' AS state FROM "posts"
+# SELECT "posts"."title", 'draft' AS "state" FROM "posts"
 ```
 
 What the shorthand does not cover, `value` still spells: `value(true)`,
@@ -98,10 +112,10 @@ that does not need it:
 
 ```ruby
 Author.select { :country.when("JP").then("Japan").else("elsewhere").as(:where) }
-# CASE "country" WHEN 'JP' THEN 'Japan' ELSE 'elsewhere' END AS where
+# CASE "country" WHEN 'JP' THEN 'Japan' ELSE 'elsewhere' END AS "where"
 
 Author.select { case_when { :age >= 60 }.then("senior").else("adult").as(:band) }
-# CASE WHEN "age" >= 60 THEN 'senior' ELSE 'adult' END AS band
+# CASE WHEN "age" >= 60 THEN 'senior' ELSE 'adult' END AS "band"
 
 Author.select { self.case(mod(:age, 10)).when(0).then("round").else("not").as(:v) }
 ```
@@ -121,5 +135,5 @@ Author.select {
 }
 
 Author.select { sum(case_when { :age >= 60 }.then(1).else(0)).as(:seniors) }
-# SUM(CASE WHEN "age" >= 60 THEN 1 ELSE 0 END) AS seniors
+# SUM(CASE WHEN "age" >= 60 THEN 1 ELSE 0 END) AS "seniors"
 ```

data/docs/functions.md

@@ -96,7 +96,7 @@ written, so a case-sensitive one can be spelled exactly:
 
 ```ruby
 Post.select { fn(:date_trunc, "day", :created_at).as(:day) }
-# SELECT date_trunc('day', "posts"."created_at") AS day
+# SELECT date_trunc('day', "posts"."created_at") AS "day"
 ```
 
 `op` is the same escape hatch for operators — PostgreSQL alone has dozens
@@ -107,10 +107,10 @@ allows an operator, so a letter, a space or a quote is refused rather than
 written into the SQL. Both sides take what `fn`'s arguments take — a
 column, an expression, a value quoted by the adapter — and a value is
 spelled in the adapter's own syntax, `to_json` saying a document, `'{a,b}'`
-an array; a Ruby Hash or Array is refused rather than guessed at. The
-result is parenthesized, its precedence being unknown, and so is an
-expression on either side, so a dug value cannot be re-grouped out from
-under it:
+an array; a Ruby Hash or Array is refused rather than guessed at. What it
+gives combines with `&`, `|` and `!` as a condition does. The result is
+parenthesized, its precedence being unknown, and so is an expression on
+either side, so a dug value cannot be re-grouped out from under it:
 
 ```ruby
 Post.where { op("&&", :tags, "{ruby,sql}") }
@@ -127,15 +127,19 @@ for by name, and an interpolation has a spelling that is not it: `?` and
 `:name` placeholders take values quoted by the adapter, through
 `sanitize_sql_array`. A `?` is rewritten only when there are positional binds
 to put in it, so PostgreSQL's `?` operators can share a statement with named
-binds, or with none. The result carries the predications and arithmetic, and
-is parenthesized where it stands inside a larger expression — its precedence
-is whatever was written — but comes out bare at the top of a select list,
-where parentheses would refuse an alias written into the string:
+binds, or with none. The result carries the predications and arithmetic,
+combines with `&`, `|` and `!` as a condition does, and is parenthesized
+where it stands inside a larger expression — its precedence is whatever was
+written — but comes out bare at the top of a select list, where parentheses
+would refuse an alias written into the string:
 
 ```ruby
 Post.where { sql("length(title) > ?", 10) }
 # WHERE (length(title) > 10)
 
+Post.where { sql("score > 0") & (:published == true) }
+# WHERE (score > 0) AND "posts"."published" = TRUE
+
 Post.where { sql("score + ?", 10) * 2 >= 60 }
 # WHERE (score + 10) * 2 >= 60
 
@@ -195,7 +199,7 @@ Post.where { extract(:year, :created_at) == 2026 }
 # SELECT "posts".* FROM "posts" WHERE EXTRACT(YEAR FROM "posts"."created_at") = 2026
 
 Post.select { cast(:price, "decimal(10,2)").as(:price) }
-# SELECT CAST("posts"."price" AS decimal(10,2)) AS price
+# SELECT CAST("posts"."price" AS decimal(10,2)) AS "price"
 ```
 
 A duration moves a date. Active Support's `7.days` and the rest go on the

data/docs/index.md

@@ -11,17 +11,6 @@ Author.
 #   WHERE "authors"."age" BETWEEN 20 AND 40 AND "posts"."published" = TRUE
 ```
 
-Inside a block, symbols denote columns of the receiver's table, and
-`:table[:column]` denotes a qualified column. That holds in every position —
-on the right of a comparison too, so `:age == :retirement_age` compares two
-columns. A value is written as its literal, an enum's as its string; a symbol
-naming no column of the model is refused rather than compared against nothing
-anyone meant.
-
-**[Try it in your browser](https://shugo.github.io/activerecord-refined/)** —
-Ruby 4.1, Active Record, SQLite and PostgreSQL run in the page, so the examples
-build real SQL and return real rows without a `ruby-master` build of your own.
-
 ## Reference
 
 - {ActiveRecord::Refined::BlockSyntax BlockSyntax} — what a symbol answers to
@@ -50,7 +39,7 @@ differ:
 - {file:docs/functions.md Aggregates and functions} — `count`, `filter`,
   `string_agg`, the scalar functions, the clock, durations, `extract` and
   `cast`.
-- {file:docs/expressions.md Expressions} — arithmetic, the bitwise operators,
+- {file:docs/expressions.md Expressions} — arithmetic, the bitwise operations,
   `CASE`.
 - {file:docs/json.md JSON} — `dig`, `bury`, `except`, `key?`, `keys`, the
   JSON aggregates, and where the adapters' JSON types part.
@@ -64,7 +53,3 @@ differ:
 - {file:docs/writing.md Writing} — `update_all` and `upsert_all`.
 - {file:docs/time_zones.md Time zones} — what a block converts and what it
   leaves to the session.
-
-The repository's README, on
-[GitHub](https://github.com/shugo/activerecord-refined), has the history,
-the requirements, and how the tests and the release are run.

data/docs/windows.md

@@ -7,10 +7,10 @@ The window is built by chaining, as Arel's own is:
 
 ```ruby
 Author.select { avg(:age).over.partition(:country).as(:country_average) }
-# AVG("age") OVER (PARTITION BY "country") AS country_average
+# AVG("age") OVER (PARTITION BY "country") AS "country_average"
 
 Author.select { row_number.over.partition(:country).order(:age.desc).as(:rank) }
-# ROW_NUMBER() OVER (PARTITION BY "country" ORDER BY "age" DESC) AS rank
+# ROW_NUMBER() OVER (PARTITION BY "country" ORDER BY "age" DESC) AS "rank"
 
 Author.select { count(:*).over.as(:total) }   # COUNT(*) OVER () — every row
 ```

data/examples/expressions.rb

@@ -82,12 +82,12 @@ show("a due date a month on",
   LineItem.select { [:sku, (:ordered_on + 1.month).as(:due_on)] }.
     map { |i| [i.sku, i.due_on] })
 
-# The bitwise operators.  & and | are AND and OR between conditions, which is
-# what leaves them free here.  Each expression parenthesises itself, so the
-# grouping is Ruby's rather than the adapter's.
+# The bitwise operations.  AND and OR are what & and | mean, so those two go
+# by name here; a method binds tighter than any comparison, and the expression
+# parenthesises itself in the SQL so the adapter cannot regroup it.
 show("a bit test in a condition",
-  LineItem.where { :flags & 4 > 0 },
-  LineItem.where { :flags & 4 > 0 }.pluck(:sku))
+  LineItem.where { :flags.bitwise_and(4) > 0 },
+  LineItem.where { :flags.bitwise_and(4) > 0 }.pluck(:sku))
 
 # XOR is the one the three adapters do not share.  SQLite has none, so it gets
 # the two operations XOR is made of; PostgreSQL would say #, MySQL ^.
@@ -99,9 +99,9 @@ show("xor, spelled the way the adapter spells it",
 # the three adapters would quietly answer as AND does and the third has no
 # such operator, so the block refuses instead.
 begin
-  LineItem.where { :flags & (:price == 1) }
+  LineItem.where { :flags.bitwise_and(:price == 1) }
 rescue ArgumentError => e
-  puts "--- a condition is not an operand of & ---"
+  puts "--- a condition is not an operand of a bitwise operation ---"
   puts "  #{e.message}"
   puts
 end
@@ -184,6 +184,12 @@ show("sql, for what neither fn nor op can spell",
   LineItem.where { sql("price % ?", 100) == 0 },
   LineItem.where { sql("price % ?", 100) == 0 }.pluck(:sku))
 
+# What sql or op gives is a condition when what it holds is one, and
+# combines with & | ! like any other.
+show("an sql condition combined with a built one",
+  LineItem.where { sql("quantity > 4") & (:category == "tools") },
+  LineItem.where { sql("quantity > 4") & (:category == "tools") }.pluck(:sku))
+
 # A string sent `as` is a value, like a number.
 show("a string literal in a select list",
   LineItem.select { [:sku, "listed".as(:state)] },