activerecord-refined 0.8.0 → 0.9.0

data/activerecord-refined.gemspec

@@ -1,33 +1,47 @@
 # -*- encoding: utf-8 -*-
-lib = File.expand_path('../lib', __FILE__)
+# frozen_string_literal: true
+
+lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'activerecord-refined/version'
+require "activerecord-refined/version"
 
 Gem::Specification.new do |gem|
   gem.name          = "activerecord-refined"
   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'
-  gem.summary       = 'Write Active Record queries as Ruby expressions'
-  gem.homepage      = 'https://github.com/shugo/activerecord-refined'
+  gem.description   = "Adding clean and powerful query syntax on Active Record using refinements"
+  gem.summary       = "Write Active Record queries as Ruby expressions"
+  gem.homepage      = "https://github.com/shugo/activerecord-refined"
 
   # sandbox/ is a site, not part of the library: its Gemfile.lock and
-  # package-lock.json have no business in anyone's bundle.  CLAUDE.md is
-  # addressed to whoever is working on the repository, not to anyone using it.
-  gem.files         = `git ls-files`.split($/).grep_v(%r{^sandbox/|^CLAUDE\.md$})
-  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  # package-lock.json have no business in anyone's bundle.  CLAUDE.md and
+  # .claude/ are addressed to whoever is working on the repository, not to
+  # anyone using it.
+  gem.files         = `git ls-files`.split($/).grep_v(%r{^sandbox/|^CLAUDE\.md$|^\.claude/})
+  gem.executables   = gem.files.grep(%r{^bin/}).map { |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
   gem.require_paths = ["lib"]
 
   # Proc#refined is available since Ruby 4.1. 4.1.0.dev is required to allow
   # ruby-master builds, which sort before the 4.1.0 release.
-  gem.required_ruby_version = '>= 4.1.0.dev'
+  gem.required_ruby_version = ">= 4.1.0.dev"
 
-  gem.add_dependency 'activerecord', ['>= 7.0']
-  gem.add_development_dependency 'sqlite3', ['>= 0']
-  gem.add_development_dependency 'minitest', ['>= 0']
-  gem.add_development_dependency 'rake', ['>= 0']
+  gem.add_dependency "activerecord", [">= 7.0"]
+  gem.add_development_dependency "sqlite3", [">= 0"]
+  gem.add_development_dependency "minitest", [">= 0"]
+  gem.add_development_dependency "rake", [">= 0"]
   # What cuts a release: `bump patch --tag`, then push with --follow-tags.
-  gem.add_development_dependency 'bump', ['>= 0']
+  gem.add_development_dependency "bump", [">= 0"]
+  # What benchmark/query_building.rb measures with.
+  gem.add_development_dependency "benchmark-ips", [">= 0"]
+  gem.add_development_dependency "memory_profiler", [">= 0"]
+  # The style is Rails' own: .rubocop.yml is theirs with this repository's
+  # paths, and these are the plugins it loads.
+  gem.add_development_dependency "rubocop", [">= 0"]
+  gem.add_development_dependency "rubocop-minitest", [">= 0"]
+  gem.add_development_dependency "rubocop-packaging", [">= 0"]
+  gem.add_development_dependency "rubocop-performance", [">= 0"]
+  gem.add_development_dependency "rubocop-rails", [">= 0"]
+  gem.add_development_dependency "rubocop-md", [">= 0"]
 end

data/benchmark/query_building.rb

@@ -1,14 +1,14 @@
+# frozen_string_literal: true
+
 # Compares the cost of building the same queries through this gem's block
 # DSL and through Active Record's other argument styles: hash conditions,
 # string conditions, raw Arel, and relation and/or chains.  Only query
 # construction (through to_sql) is measured; every style produces the same
 # SQL, which the script prints first as a sanity check.
 #
-# Run without bundler, so the profiling gems don't need to live in the
-# Gemfile:
+# The profiling gems are development dependencies, so:
 #
-#   gem install benchmark-ips memory_profiler
-#   ruby -Ilib benchmark/query_building.rb
+#   bundle exec ruby benchmark/query_building.rb
 
 require "benchmark/ips"
 require "memory_profiler"
@@ -18,7 +18,7 @@ require "activerecord-refined"
 ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
 ActiveRecord::Schema.verbose = false
 ActiveRecord::Schema.define do
-  create_table(:users) {|t| t.string :name; t.integer :age }
+  create_table(:users) { |t| t.string :name; t.integer :age }
 end
 
 class User < ActiveRecord::Base; end
@@ -49,12 +49,12 @@ VARIANTS = {
     "relation" => -> { User.where(age: 18..).and(User.where(name: "alice").or(User.where(name: "bob"))).to_sql },
     "block"    => -> { User.where { (:age >= 18) & ((:name == "alice") | (:name == "bob")) }.to_sql },
   },
-}
+}.freeze
 
 puts "=== generated SQL (sanity) ==="
 VARIANTS.each do |group, variants|
   puts "--- #{group} ---"
-  variants.each {|name, thunk| puts "  #{name.ljust(8)} #{thunk.call}" }
+  variants.each { |name, thunk| puts "  #{name.ljust(8)} #{thunk.call}" }
 end
 
 puts
@@ -63,7 +63,7 @@ VARIANTS.each do |group, variants|
   puts "--- #{group} ---"
   Benchmark.ips do |x|
     x.config(warmup: 0.5, time: 2)
-    variants.each {|name, thunk| x.report(name, &thunk) }
+    variants.each { |name, thunk| x.report(name, &thunk) }
     x.compare!
   end
 end
@@ -93,7 +93,7 @@ iseq_count = -> {
   counts = ObjectSpace.count_imemo_objects
   counts[:imemo_iseq] || counts[:iseq]
 }
-context = ActiveRecord::Refined::BlockContext.new
+context = ActiveRecord::Refined::BlockContext.new(User)
 syntax = ActiveRecord::Refined::BlockSyntax
 
 {
@@ -117,13 +117,13 @@ puts
 puts "=== where the block path spends its time ==="
 block = proc { :name == "alice" }
 refined_block = block.refined(ActiveRecord::Refined::BlockSyntax)
-context = ActiveRecord::Refined::BlockContext.new
+context = ActiveRecord::Refined::BlockContext.new(User)
 Benchmark.ips do |x|
   x.config(warmup: 0.5, time: 2)
   x.report("Proc#refined alone") { block.refined(ActiveRecord::Refined::BlockSyntax) }
   x.report("instance_exec of pre-refined proc") { context.instance_exec(&refined_block) }
   x.report("refined + instance_exec") {
-    ActiveRecord::Refined::BlockContext.new.instance_exec(&block.refined(ActiveRecord::Refined::BlockSyntax))
+    ActiveRecord::Refined::BlockContext.new(User).instance_exec(&block.refined(ActiveRecord::Refined::BlockSyntax))
   }
   x.compare!
 end

data/examples/aggregations.rb

@@ -1,16 +1,18 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# frozen_string_literal: true
 
-require 'active_record'
-require 'activerecord-refined'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
-ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+require "active_record"
+require "activerecord-refined"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
 ActiveRecord::Migration.verbose = false
 
 class Setup < ActiveRecord::Migration[8.1]
   def up
-    create_table(:authors) {|t| t.string :name; t.integer :age; t.string :country }
-    create_table(:posts)   {|t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
-    create_table(:comments){|t| t.string :body; t.integer :post_id; t.integer :score }
+    create_table(:authors) { |t| t.string :name; t.integer :age; t.string :country }
+    create_table(:posts)   { |t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
+    create_table(:comments) { |t| t.string :body; t.integer :post_id; t.integer :score }
   end
 end
 Setup.new.up
@@ -54,11 +56,11 @@ puts
 #    coalesce function + GROUP BY + aggregates + multiple ORDER BY
 query2 =
   Author.
-    group { coalesce(:country, 'unknown') }.
-    order { [count(:id).desc, coalesce(:country, 'unknown').asc] }.
+    group { coalesce(:country, "unknown") }.
+    order { [count(:id).desc, coalesce(:country, "unknown").asc] }.
     select {
       [
-        coalesce(:country, 'unknown').as(:country),
+        coalesce(:country, "unknown").as(:country),
         count(:id).as(:author_count),
         avg(:age).as(:avg_age),
       ]
@@ -74,7 +76,7 @@ query3 =
   Author.
     joins(:posts) { :posts[:author_id] == :authors[:id] }.
     joins(:comments) { :comments[:post_id] == :posts[:id] }.
-    where { !:posts[:title].include?('draft') & (:comments[:score] >= 0) }.
+    where { !:posts[:title].include?("draft") & (:comments[:score] >= 0) }.
     group { :authors[:id] }.
     having { sum(:comments[:score]) > 10 }.
     order { sum(:comments[:score]).desc }.

data/examples/complex_joins.rb

@@ -1,16 +1,18 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# frozen_string_literal: true
 
-require 'active_record'
-require 'activerecord-refined'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
-ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+require "active_record"
+require "activerecord-refined"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
 ActiveRecord::Migration.verbose = false
 
 class Setup < ActiveRecord::Migration[8.1]
   def up
-    create_table(:authors) {|t| t.string :name; t.integer :age; t.string :country; t.integer :mentor_id }
-    create_table(:posts)   {|t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
-    create_table(:comments){|t| t.string :body; t.integer :post_id; t.integer :score }
+    create_table(:authors) { |t| t.string :name; t.integer :age; t.string :country; t.integer :mentor_id }
+    create_table(:posts)   { |t| t.string :title; t.integer :author_id; t.integer :likes; t.boolean :published }
+    create_table(:comments) { |t| t.string :body; t.integer :post_id; t.integer :score }
   end
 end
 Setup.new.up
@@ -47,7 +49,7 @@ query2 =
     joins(:posts) { :posts[:author_id] == :authors[:id] }.
     joins(:comments) { :comments[:post_id] == :posts[:id] }.
     where {
-      !:posts[:title].include?('draft') &
+      !:posts[:title].include?("draft") &
         !:comments[:score].in?([0, -1]) &
         (:authors[:age] >= 18)
     }
@@ -98,14 +100,14 @@ puts
 begin
   Author.right_outer_joins(:posts)
 rescue ArgumentError => e
-  puts '--- and it says so without one ---'
+  puts "--- and it says so without one ---"
   puts "  #{e.message}"
   puts
 end
 
 # 6. CROSS JOIN: every row against every row, so there is no condition to
 #    give and no block to write it in.  `as` still names the table.
-puts '--- 6. CROSS JOIN ---'
+puts "--- 6. CROSS JOIN ---"
 puts Author.cross_joins(:posts).to_sql
 puts Author.cross_joins(:authors, as: :others).
   select { [:authors[:name].as(:a), :others[:name].as(:b)] }.to_sql

data/examples/ctes.rb

@@ -1,15 +1,17 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# frozen_string_literal: true
 
-require 'active_record'
-require 'activerecord-refined'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
-ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+require "active_record"
+require "activerecord-refined"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
 ActiveRecord::Migration.verbose = false
 
 class Setup < ActiveRecord::Migration[8.1]
   def up
-    create_table(:categories) {|t| t.string :name; t.integer :parent_id }
-    create_table(:products)   {|t| t.string :name; t.integer :category_id; t.integer :price }
+    create_table(:categories) { |t| t.string :name; t.integer :parent_id }
+    create_table(:products)   { |t| t.string :name; t.integer :category_id; t.integer :price }
   end
 end
 Setup.new.up
@@ -20,14 +22,14 @@ end
 class Product < ActiveRecord::Base
 end
 
-electronics = Category.create!(name: 'electronics')
-computers   = Category.create!(name: 'computers', parent_id: electronics.id)
-laptops     = Category.create!(name: 'laptops', parent_id: computers.id)
-groceries   = Category.create!(name: 'groceries')
+electronics = Category.create!(name: "electronics")
+computers   = Category.create!(name: "computers", parent_id: electronics.id)
+laptops     = Category.create!(name: "laptops", parent_id: computers.id)
+groceries   = Category.create!(name: "groceries")
 
-Product.create!(name: 'ultrabook', category_id: laptops.id, price: 1200)
-Product.create!(name: 'keyboard', category_id: computers.id, price: 80)
-Product.create!(name: 'apple', category_id: groceries.id, price: 2)
+Product.create!(name: "ultrabook", category_id: laptops.id, price: 1200)
+Product.create!(name: "keyboard", category_id: computers.id, price: 80)
+Product.create!(name: "apple", category_id: groceries.id, price: 2)
 
 # 1. Recursive CTE: every category below 'electronics', itself included.
 #    The recursive member joins the CTE by name, so its ON clause is a block
@@ -47,7 +49,7 @@ subtree =
     ]
   ).from_cte(:tree)
 
-puts '--- 1. Recursive CTE walking a category tree ---'
+puts "--- 1. Recursive CTE walking a category tree ---"
 puts subtree.to_sql
 puts subtree.order { :name }.pluck(:name).inspect
 puts
@@ -68,14 +70,14 @@ forest =
     ]
   ).from_cte(:tree).order { [:depth, :id] }
 
-puts '--- 2. Recursive CTE carrying the root and the depth down ---'
+puts "--- 2. Recursive CTE carrying the root and the depth down ---"
 puts forest.to_sql
-puts forest.map {|c| [c.name, c.root_id, c.depth] }.inspect
+puts forest.map { |c| [c.name, c.root_id, c.depth] }.inspect
 
 # The alias from_cte puts on the CTE is what lets this `where` qualify
 # root_id; without it the column would be looked for in a table the query no
 # longer has.
-puts forest.where { :root_id == electronics.id }.map {|c| [c.name, c.depth] }.inspect
+puts forest.where { :root_id == electronics.id }.map { |c| [c.name, c.depth] }.inspect
 puts
 
 # 3. The same CTE as a subquery: products anywhere under 'electronics'.
@@ -88,7 +90,7 @@ products_below =
     ]
   ).joins(:tree) { :tree[:id] == :products[:category_id] }
 
-puts '--- 3. Recursive CTE joined from the outer query ---'
+puts "--- 3. Recursive CTE joined from the outer query ---"
 puts products_below.to_sql
 puts products_below.order { :name }.pluck(:name).inspect
 puts
@@ -107,7 +109,7 @@ expensive =
       ]
     }
 
-puts '--- 4. Plain CTE joined and aggregated ---'
+puts "--- 4. Plain CTE joined and aggregated ---"
 puts expensive.to_sql
-puts expensive.map {|c| [c.category, c.pricey_count, c.top_price] }.inspect
+puts expensive.map { |c| [c.category, c.pricey_count, c.top_price] }.inspect
 puts

data/examples/expressions.rb

@@ -1,9 +1,11 @@
-$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
+# frozen_string_literal: true
 
-require 'active_record'
-require 'activerecord-refined'
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), "..", "lib"))
 
-ActiveRecord::Base.establish_connection(adapter: 'sqlite3', database: ':memory:')
+require "active_record"
+require "activerecord-refined"
+
+ActiveRecord::Base.establish_connection(adapter: "sqlite3", database: ":memory:")
 ActiveRecord::Migration.verbose = false
 
 class Setup < ActiveRecord::Migration[8.1]
@@ -22,10 +24,10 @@ Setup.new.up
 class LineItem < ActiveRecord::Base
 end
 
-LineItem.create!(sku: 'A-1', category: 'tools',  price: 1200, quantity: 2,  flags: 12)
-LineItem.create!(sku: 'A-2', category: 'tools',  price: 300,  quantity: 5,  flags: 10)
-LineItem.create!(sku: 'B-1', category: 'paper',  price: 80,   quantity: 10, flags: 3)
-LineItem.create!(sku: 'C-1', category: nil,      price: 50,   quantity: 1,  flags: 4)
+LineItem.create!(sku: "A-1", category: "tools",  price: 1200, quantity: 2,  flags: 12)
+LineItem.create!(sku: "A-2", category: "tools",  price: 300,  quantity: 5,  flags: 10)
+LineItem.create!(sku: "B-1", category: "paper",  price: 80,   quantity: 10, flags: 3)
+LineItem.create!(sku: "C-1", category: nil,      price: 50,   quantity: 1,  flags: 4)
 
 def show(title, relation, rows = nil)
   puts "--- #{title} ---"
@@ -36,31 +38,44 @@ end
 
 # 1. Arithmetic.  Ruby puts + - * / above the comparison operators, so an
 #    expression groups the way it reads, without parentheses.
-show('arithmetic in a condition',
+show("arithmetic in a condition",
   LineItem.where { :price * :quantity > 1000 },
   LineItem.where { :price * :quantity > 1000 }.pluck(:sku))
 
-show('arithmetic in a select list, and aggregated',
+show("arithmetic in a select list, and aggregated",
   LineItem.select { [:sku, (:price * :quantity).as(:subtotal)] },
   LineItem.select { [:sku, (:price * :quantity).as(:subtotal)] }.
-    map {|i| [i.sku, i.subtotal] })
+    map { |i| [i.sku, i.subtotal] })
 
-show('an aggregate over an expression',
+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)] }.
+    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)] }.
+    map { |i| [i.sku, i.taxed] })
+
 # 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.
-show('a bit test in a condition',
+show("a bit test in a condition",
   LineItem.where { :flags & 4 > 0 },
   LineItem.where { :flags & 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 ^.
-show('xor, spelled the way the adapter spells it',
+show("xor, spelled the way the adapter spells it",
   LineItem.select { [:sku, (:flags ^ 10).as(:xored)] },
-  LineItem.select { [:sku, (:flags ^ 10).as(:xored)] }.map {|i| [i.sku, i.xored] })
+  LineItem.select { [:sku, (:flags ^ 10).as(:xored)] }.map { |i| [i.sku, i.xored] })
 
 # A condition cannot be an operand, and neither can a boolean column: two of
 # the three adapters would quietly answer as AND does and the third has no
@@ -68,86 +83,106 @@ show('xor, spelled the way the adapter spells it',
 begin
   LineItem.where { :flags & (:price == 1) }
 rescue ArgumentError => e
-  puts '--- a condition is not an operand of & ---'
+  puts "--- a condition is not an operand of & ---"
   puts "  #{e.message}"
   puts
 end
 
 # 2. Aggregates.  count takes :* for COUNT(*) and distinct: true for
 #    COUNT(DISTINCT ...); the rest are sum, avg, min and max.
-show('COUNT(*) and COUNT(DISTINCT ...)',
+show("COUNT(*) and COUNT(DISTINCT ...)",
   LineItem.select { [count(:*).as(:rows), count(:category, distinct: true).as(:categories)] },
   LineItem.select { [count(:*).as(:rows), count(:category, distinct: true).as(:categories)] }.
-    map {|i| [i.rows, i.categories] })
+    map { |i| [i.rows, i.categories] })
 
 # filter takes the aggregate over the rows a condition holds for.  SQLite and
 # PostgreSQL have the FILTER clause; MySQL gets the CASE that means the same,
 # since an aggregate passes over the NULL a missed row leaves.
-show('two aggregates over different rows of the same query',
+show("two aggregates over different rows of the same query",
   LineItem.select {
-    [count(:*).as(:all), sum(:price).filter { :category == 'tools' }.as(:tools)]
+    [count(:*).as(:all), sum(:price).filter { :category == "tools" }.as(:tools)]
   },
   LineItem.select {
-    [count(:*).as(:all), sum(:price).filter { :category == 'tools' }.as(:tools)]
-  }.map {|i| [i.all, i.tools] })
+    [count(:*).as(:all), sum(:price).filter { :category == "tools" }.as(:tools)]
+  }.map { |i| [i.all, i.tools] })
 
 # CASE has two shapes: an operand to compare each when against, or a condition
 # on every when.  case is a Ruby keyword, so the method behind both is only
 # reachable through the receiver -- self.case -- and each shape has a shorthand
 # that does not need it.
-show('a CASE with an operand, through the shorthand',
-  LineItem.select { [:sku, :category.when('tools').then('hardware').else('other').as(:kind)] },
-  LineItem.select { [:sku, :category.when('tools').then('hardware').else('other').as(:kind)] }.
-    map {|i| [i.sku, i.kind] })
+show("a CASE with an operand, through the shorthand",
+  LineItem.select { [:sku, :category.when("tools").then("hardware").else("other").as(:kind)] },
+  LineItem.select { [:sku, :category.when("tools").then("hardware").else("other").as(:kind)] }.
+    map { |i| [i.sku, i.kind] })
 
-show('a CASE where each when carries its own condition',
+show("a CASE where each when carries its own condition",
   LineItem.select {
-    [:sku, case_when { :price >= 1000 }.then('dear').when { :price >= 100 }.
-      then('middling').else('cheap').as(:band)]
+    [:sku, case_when { :price >= 1000 }.then("dear").when { :price >= 100 }.
+      then("middling").else("cheap").as(:band)]
   },
   LineItem.select {
-    [:sku, case_when { :price >= 1000 }.then('dear').when { :price >= 100 }.
-      then('middling').else('cheap').as(:band)]
-  }.map {|i| [i.sku, i.band] })
+    [:sku, case_when { :price >= 1000 }.then("dear").when { :price >= 100 }.
+      then("middling").else("cheap").as(:band)]
+  }.map { |i| [i.sku, i.band] })
 
 # It is an expression like any other, so it goes inside an aggregate too.
-show('counting with a CASE',
+show("counting with a CASE",
   LineItem.select { sum(case_when { :price >= 100 }.then(1).else(0)).as(:dear_ones) },
   LineItem.select { sum(case_when { :price >= 100 }.then(1).else(0)).as(:dear_ones) }.
-    map {|i| i.dear_ones })
+    map { |i| i.dear_ones })
 
 # 3. Functions.  Seven scalar ones have methods of their own; fn reaches
 #    anything else, emitting the name as written.
-show('built-in functions and the fn escape hatch',
+show("built-in functions and the fn escape hatch",
   LineItem.
     where { length(:sku) == 3 }.
-    select { [upper(:sku).as(:sku), coalesce(:category, 'unsorted').as(:category)] },
+    select { [upper(:sku).as(:sku), coalesce(:category, "unsorted").as(:category)] },
   LineItem.
     where { length(:sku) == 3 }.
-    select { [upper(:sku).as(:sku), coalesce(:category, 'unsorted').as(:category)] }.
-    map {|i| [i.sku, i.category] })
+    select { [upper(:sku).as(:sku), coalesce(:category, "unsorted").as(:category)] }.
+    map { |i| [i.sku, i.category] })
 
-show('fn, for a function without a method of its own',
+show("fn, for a function without a method of its own",
   LineItem.select { fn(:hex, :price).as(:hex_price) },
   LineItem.select { fn(:hex, :price).as(:hex_price) }.map(&:hex_price))
 
+# op is the same for operators: the operator is emitted as written --
+# checked against the operator characters -- and both sides are quoted
+# values, columns or expressions.  What it gives compares like any other
+# expression.
+show("op, for an operator without a method of its own",
+  LineItem.where { op("%", :quantity, 2) == 1 },
+  LineItem.where { op("%", :quantity, 2) == 1 }.pluck(:sku))
+
+# sql is the last resort, and the one way a string means SQL inside a block:
+# a bare string is refused there, and ? and :name placeholders take quoted
+# values.  What it gives is parenthesized wherever it stands as an operand.
+show("sql, for what neither fn nor op can spell",
+  LineItem.where { sql("price % ?", 100) == 0 },
+  LineItem.where { sql("price % ?", 100) == 0 }.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)] },
+  LineItem.select { [:sku, "listed".as(:state)] }.map { |i| [i.sku, i.state] })
+
 # 4. Ordering.  asc and desc take nulls_first / nulls_last.  MySQL has no
 #    such syntax, but Arel emulates it there, so the order is the same
 #    everywhere.
-show('NULLS LAST',
+show("NULLS LAST",
   LineItem.order { [:category.asc.nulls_last, :sku.asc] },
   LineItem.order { [:category.asc.nulls_last, :sku.asc] }.pluck(:category, :sku))
 
 # Aggregates and expressions can be ordered by, too.
-show('grouped, aggregated and ordered by the aggregate',
+show("grouped, aggregated and ordered by the aggregate",
   LineItem.
     group { :category }.
     having { count(:*) > 1 }.
     order { sum(:price * :quantity).desc }.
-    select { [coalesce(:category, 'unsorted').as(:category), sum(:price * :quantity).as(:total)] },
+    select { [coalesce(:category, "unsorted").as(:category), sum(:price * :quantity).as(:total)] },
   LineItem.
     group { :category }.
     having { count(:*) > 1 }.
     order { sum(:price * :quantity).desc }.
-    select { [coalesce(:category, 'unsorted').as(:category), sum(:price * :quantity).as(:total)] }.
-    map {|i| [i.category, i.total] })
+    select { [coalesce(:category, "unsorted").as(:category), sum(:price * :quantity).as(:total)] }.
+    map { |i| [i.category, i.total] })