activerecord-refined 0.10.2 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9270b5bf04c083f8cefdd5c669810a63a94a2073c1cae49ba28027693ee5b684
-  data.tar.gz: 23f7e622c8b6b1e85cf670798b705aec8e57c0149315c5fb50699fc95d10ee18
+  metadata.gz: 8ee6cc682434a9d10c523f5df80085c460ba44fc6fa8653304a38fbd0cf85c83
+  data.tar.gz: 55185eb38377c3ba4cb57136a68157531527f8ec7ea4e5cc568c95be88cdf2a1
 SHA512:
-  metadata.gz: dcd5cbfab0c7d60498b21a25240f29ae224aa6de7b5fd0a37c627ee10e0f642ed4bb66740734bca03f64f3b231032e273163d68fc9de59b3c07447bef1f69eab
-  data.tar.gz: e701353709c2f8dfb7ebc38a9bdfb9e8b56c940579f139beed543f20391cf8d50166391c3de1718d85797185f4bcfb0cec3a3f4a2d91948c1344527f0ea18e6e
+  metadata.gz: 5dc45baffd355d00a918c144ae802c4f8f5ab2288b792bf1660f16978d65fd909e449b9c65a14fff834a89011eb632b2428c1fd9abaf5bdc5705f557e336551a
+  data.tar.gz: b6b35bebfc29eaba5c793268fc7e343aed5323e7078c81a25a1add336969e415b0951fe6d92bc8abe4e513151bfe3c94acadefd2d59a5a320fd2bb2f5f9778bc

data/.yardopts

@@ -1,6 +1,6 @@
 --markup markdown
 --no-private
---title "ActiveRecord::Refined"
+--title "activerecord-refined"
 --readme docs/index.md
 lib/**/*.rb
 -

data/README.md

@@ -1,4 +1,4 @@
-# ActiveRecord::Refined
+# activerecord-refined
 
 [![gem](https://img.shields.io/gem/v/activerecord-refined.svg)](https://rubygems.org/gems/activerecord-refined)
 [![test](https://github.com/shugo/activerecord-refined/actions/workflows/test.yml/badge.svg)](https://github.com/shugo/activerecord-refined/actions/workflows/test.yml)
@@ -14,21 +14,12 @@ 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.
+**[Try it in your browser](https://shugo.github.io/activerecord-refined/)**
 
 ## Requirements
 
 * Ruby 4.1 or later (for `Proc#refined`; not released yet, so a `ruby-master` build is needed for now)
-* Active Record 7.0 or later
+* Active Record 7.2 or later
 
 ## Installation
 
@@ -92,28 +83,28 @@ block DSL and through Active Record's other argument styles. Only query
 construction (through `to_sql`) is measured — every style produces the same
 SQL, so execution costs the same regardless.
 
-Queries built per second (ruby 4.1.0dev, Active Record 8.1.3, one machine —
+Queries built per second (ruby 4.1.0dev, Active Record 8.1.3.1, one machine —
 treat the ratios, not the absolute numbers, as the result):
 
 | query | string | arel | block (this gem) | hash | relation and/or |
 | --- | --- | --- | --- | --- | --- |
-| simple equality | 42.5k | 42.0k | 37.7k | 31.5k | — |
-| range (BETWEEN) | — | 34.6k | 32.7k | 24.8k | — |
-| LIKE | 41.5k | 41.0k | 36.8k | — | — |
-| compound AND/OR | 34.4k | 27.7k | 24.4k | — | 11.9k |
+| simple equality | 40.9k | 40.5k | 36.1k | 31.5k | — |
+| range (BETWEEN) | — | 33.7k | 31.8k | 24.7k | — |
+| LIKE | 40.1k | 39.9k | 36.4k | — | — |
+| compound AND/OR | 32.8k | 26.7k | 23.4k | — | 11.4k |
 
 Allocated memory per built query:
 
 | query | arel | block (this gem) | hash | string | relation and/or |
 | --- | --- | --- | --- | --- | --- |
-| simple equality | 2,600 B | 2,832 B | 3,328 B | 3,448 B | — |
-| compound AND/OR | 3,208 B | 3,584 B | — | 4,680 B | 9,120 B |
+| simple equality | 2,176 B | 2,392 B | 2,576 B | 2,976 B | — |
+| compound AND/OR | 2,744 B | 3,104 B | — | 4,144 B | 7,152 B |
 
 In short: the block DSL is 6–13% slower than hand-written Arel (which it
 compiles to), a little faster than hash conditions, and both faster and
 leaner than `where(...).and(where(...).or(where(...)))` relation chains,
 which pay for structural-compatibility checks and relation copies. The
-`Proc#refined` call itself costs about 150 ns of the ~25 μs build — the
+`Proc#refined` call itself costs about 170 ns of the ~28 μs build — the
 re-interpretation of the block is not where the time goes. Against a
 database round trip of tens to hundreds of microseconds, none of these
 differences are visible in an application.
@@ -123,8 +114,8 @@ under the refinements, `Proc#refined` deep-copies its instruction sequence,
 nested blocks included. The copy is made lazily on the refined proc's first
 call and memoized per block and refinement list for the life of the process,
 so it is paid once per `where { ... }` call site, not per query — the
-benchmark measures the copy at the size of the original (568 bytes for the
-simple-equality block, 888 bytes for the compound one), and a thousand
+benchmark measures the copy at the size of the original (552 bytes for the
+simple-equality block, 872 bytes for the compound one), and a thousand
 further calls from the same call site copy nothing. Steady state, an
 application holds one extra copy of each distinct query block's bytecode:
 a few hundred bytes per call site. "Per call site" assumes blocks compiled
@@ -187,6 +178,12 @@ CI runs one job per adapter with the servers as service containers, Oracle
 and SQL Server included — those two have no local server here and run on CI
 alone, their clients opted in the same way.
 
+Coverage is opt-in: `COVERAGE=1 rake test` writes an HTML report to
+`coverage/`, and `COVERAGE=1 rake test:all` merges the adapters' runs into
+one — the number worth reading, since a dialect's lines are reached only by
+its own adapter's leg. The Oracle and SQL Server dialects stay mostly
+uncovered locally for the same reason their tests run on CI alone.
+
 ## Releasing
 
 Pushing a `v*` tag runs `.github/workflows/push_gem.yml`, which builds the gem

data/activerecord-refined.gemspec

@@ -3,11 +3,11 @@
 
 lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require "activerecord-refined/version"
+require "active_record/refined/version"
 
 Gem::Specification.new do |gem|
   gem.name          = "activerecord-refined"
-  gem.version       = Activerecord::Refined::VERSION
+  gem.version       = ActiveRecord::Refined::VERSION
   gem.authors       = ["Shugo Maeda"]
   gem.email         = ["shugo@ruby-lang.org"]
   gem.description   = "Adding clean and powerful query syntax on Active Record using refinements"
@@ -25,10 +25,11 @@ Gem::Specification.new do |gem|
   # ruby-master builds, which sort before the 4.1.0 release.
   gem.required_ruby_version = ">= 4.1.0.dev"
 
-  gem.add_dependency "activerecord", [">= 7.0"]
+  gem.add_dependency "activerecord", [">= 7.2"]
   gem.add_development_dependency "sqlite3", [">= 0"]
   gem.add_development_dependency "minitest", [">= 0"]
   gem.add_development_dependency "rake", [">= 0"]
+  gem.add_development_dependency "simplecov", [">= 0"]
   # What cuts a release: `bump patch --tag`, then push with --follow-tags.
   gem.add_development_dependency "bump", [">= 0"]
   # What benchmark/query_building.rb measures with.

data/docs/conditions.md

@@ -196,7 +196,9 @@ Author.where { !:country.null? }            # NOT (country IS NULL)
 
 Combine predicates with `&`, `|` and `!`. Ruby's operator precedence makes the
 parentheses around each comparison necessary, though the `?` methods above need
-none:
+none. Leaving them off is mostly refused, but beside `true`, `false` or `nil`
+it is Ruby's own `&` that runs, and the condition to its right is lost without
+a word: `:active == true & cond` is `:active == true`.
 
 ```ruby
 Author.where { (:age >= 18) & ((:country == "JP") | (:country == "US")) }

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

@@ -9,32 +9,49 @@ Item.where { :price * :quantity > 1000 }
 Item.select { sum(:price * :quantity).as(:total) }
 ```
 
-The number may stand on the left — only a column or an expression on the
-right builds a query, so Ruby's own arithmetic is untouched — and
-`BigDecimal` is a number here, being what a decimal column's values are,
-quoted as the exact decimal on either side. A `Rational` is refused: no
-decimal spells `1/3r` exactly, and `to_d` is what says the decimal meant.
+A number may stand on the left of an expression, and Ruby's own arithmetic
+is untouched. Before a bare column, though, the number is written with
+`value`: to Ruby, `20 - :quantity` is a number minus a symbol, and the number
+has no way to know the symbol is a column. `BigDecimal` is a number here,
+being what a decimal column's values are, quoted as the exact decimal on
+either side. A `Rational` is refused: no decimal spells `1/3r` exactly, and
+`to_d` is what says the decimal meant.
 
 ```ruby
-Item.select { greatest(20 - :quantity, 0).as(:shortfall) }
-Item.where { BigDecimal("1.08") * :price > 500 }
+Item.select { greatest(value(20) - :quantity, 0).as(:shortfall) }
+Item.select { (100 - (:price * :quantity)).as(:headroom) }
+Item.where { :price * BigDecimal("1.08") > 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 +96,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 +115,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 +138,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

@@ -1,4 +1,4 @@
-# ActiveRecord::Refined
+# activerecord-refined
 
 Adding clean and powerful query syntax on Active Record using refinements.
 
@@ -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

@@ -58,17 +58,17 @@ show("an aggregate over an expression",
   LineItem.select { sum(:price * :quantity).as(:total) },
   LineItem.select { sum(:price * :quantity).as(:total) }.first.total)
 
-# The number may stand on the left; only a column or an expression on the
-# right builds a query, so Ruby's own arithmetic is untouched.  BigDecimal
-# is a number here too -- what a decimal column's values are.
-show("the number on the left, and a BigDecimal",
-  LineItem.select { [:sku, (12 - :quantity).as(:to_the_dozen)] },
-  LineItem.select { [:sku, (12 - :quantity).as(:to_the_dozen)] }.
+# A number may stand on the left of an expression; before a bare column it
+# is written with value().  BigDecimal is a number here too -- what a
+# decimal column's values are.
+show("the number on the left",
+  LineItem.select { [:sku, (value(12) - :quantity).as(:to_the_dozen)] },
+  LineItem.select { [:sku, (value(12) - :quantity).as(:to_the_dozen)] }.
     map { |i| [i.sku, i.to_the_dozen] })
 
 show("a tax through BigDecimal, exact on the wire",
-  LineItem.select { [:sku, (BigDecimal("1.1") * :price).as(:taxed)] },
-  LineItem.select { [:sku, (BigDecimal("1.1") * :price).as(:taxed)] }.
+  LineItem.select { [:sku, (BigDecimal("1.1") * (:price * :quantity)).as(:taxed)] },
+  LineItem.select { [:sku, (BigDecimal("1.1") * (:price * :quantity)).as(:taxed)] }.
     map { |i| [i.sku, i.taxed] })
 
 # A duration moves a date.  Each adapter spells the move its own way; SQLite
@@ -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)] },

data/lib/active_record/refined/ast/arithmetics.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module ActiveRecord
+  module Refined
+    module AST
+      # The arithmetic and the bitwise operations on a column or an
+      # expression.  Ruby puts the operators above the comparisons, so
+      # `:price * :quantity > 100` groups the way it reads.  A number may
+      # stand on the left of an expression, `20 - (:a + :b)`, but before a
+      # bare column it is written as a value: `value(20) - :quantity`.
+      #
+      # Bitwise AND and OR are named, not spelled `&` and `|`: those two are
+      # AND and OR between conditions and mean nothing else anywhere.  The
+      # rest keep their operators, with {#bitwise_xor} and {#bitwise_not}
+      # beside `^` and `~` for a reader who would rather have the name.
+      # Oracle, which has no bitwise operators at all, refuses every one.
+      #
+      # @example
+      #   LineItem.where { :price * :quantity > 1000 }
+      #   LineItem.select { :flags.bitwise_and(4).as(:featured) }
+      #
+      # 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
+        # `+`; with an Active Support duration on the right, a date moved: `:due_on + 3.days`.
+        # @return [AST::Arithmetic]
+        def +(other)
+          Arithmetic.new(self, :+, other)
+        end
+
+        # `-`; with a duration on the right, a date moved back.
+        # @return [AST::Arithmetic]
+        def -(other)
+          Arithmetic.new(self, :-, other)
+        end
+
+        # `*`.
+        # @return [AST::Arithmetic]
+        def *(other)
+          Arithmetic.new(self, :*, other)
+        end
+
+        # `/`.
+        # @return [AST::Arithmetic]
+        def /(other)
+          Arithmetic.new(self, :/, other)
+        end
+
+        # `&` is AND, and a column is not a condition, so this refuses:
+        # {#bitwise_and} is the SQL operator, and `.true?` makes a boolean
+        # column a condition.
+        # @raise [ArgumentError]
+        def &(other)
+          AST.refuse_logical(:&, "AND", "bitwise_and", other)
+        end
+
+        # `|` is OR, and refuses here as `&` does.
+        # @raise [ArgumentError]
+        def |(other)
+          AST.refuse_logical(:|, "OR", "bitwise_or", other)
+        end
+
+        # Bitwise AND: `"flags" & 4`.  It is spelled as a name because `&`
+        # is AND, and a method binds tighter than any comparison, so nothing
+        # has to be parenthesised to be compared.
+        # @return [AST::Bitwise]
+        # @example
+        #   Post.where { :flags.bitwise_and(4) > 0 }
+        def bitwise_and(other)
+          Bitwise.new(self, :&, other)
+        end
+
+        # Bitwise OR.
+        # @return [AST::Bitwise]
+        def bitwise_or(other)
+          Bitwise.new(self, :|, other)
+        end
+
+        # Bitwise XOR: `#` on PostgreSQL, `^` on MySQL, and the two operations it is made of on SQLite.
+        # @return [AST::Bitwise]
+        def ^(other)
+          Bitwise.new(self, :^, other)
+        end
+
+        # {#^} under a name.
+        # @return [AST::Bitwise]
+        def bitwise_xor(other)
+          Bitwise.new(self, :^, other)
+        end
+
+        # A shift left.
+        # @return [AST::Bitwise]
+        def <<(other)
+          Bitwise.new(self, :<<, other)
+        end
+
+        # A shift right.
+        # @return [AST::Bitwise]
+        def >>(other)
+          Bitwise.new(self, :>>, other)
+        end
+
+        # Bitwise NOT.
+        # @return [AST::BitwiseNot]
+        def ~
+          BitwiseNot.new(self)
+        end
+
+        # {#~} under a name.  `!` is not the one to reach for: it is Ruby's
+        # own on a column and answers `false`, which no query ever wanted.
+        # @return [AST::BitwiseNot]
+        def bitwise_not
+          BitwiseNot.new(self)
+        end
+      end
+
+      # The named bitwise operations for a number on the left, imported into
+      # the numeric refinements: 4.bitwise_and(:flags).  The operators reach
+      # an expression on the right through {Node#coerce} instead.
+      # @private
+      module NumericArithmetics
+        def bitwise_and(other)
+          Bitwise.new(self, :&, other)
+        end
+
+        def bitwise_or(other)
+          Bitwise.new(self, :|, other)
+        end
+
+        def bitwise_xor(other)
+          Bitwise.new(self, :^, other)
+        end
+      end
+    end
+  end
+end