activerecord-refined 0.10.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5fbffdc14c0f8cb45b09818e5cf8dffae6495f3c685c28ec9a1c90aceb47b1c
-  data.tar.gz: a20af3e848a3fecf80dd541ea81de1a8a3860ddee7b86c0327f45edb0d5bdb91
+  metadata.gz: 29722b871b0d5cbc7a8a35f201c2930f6e252419c0d4097a0f7476e2e5d57c7e
+  data.tar.gz: 24a324dcd539b4d8295c297256a8670bbd2359a7495f5c8506020ce4f681ad47
 SHA512:
-  metadata.gz: 8098cd09333a48a439c8065f9d666d828af2355bbcbf20d9be6f53700ad8019d51aa6b60b9a00e385ad6b640eb54580b0f81e7b7751f9d315ead52eeb508ef2b
-  data.tar.gz: 78a59ed6b51183f33d61ba6cde598e07820ed2518736a7486a9dd89c5d13d6a456f788cd313007fc66d3c2369db59e6f89d780901a9b5e0d982eeedce8e8bb35
+  metadata.gz: 69ece64722eacc0223671ce291696f7d9dd3feb8714673b0b7e2971a52c5a188154f1b821cc626a87b1236565462a4516f1c19b2ccf7bc7c5b849e7340b56fcf
+  data.tar.gz: 2ee8961a088d820e546e9cffe98e0ac836e8fb191b8120beebaa15bcc9e5b11ce8b88a1edccdc0580a12448aa0203a1631bd10bba905dc9ccdc066c6b6d24695

data/.yardopts

@@ -1,7 +1,7 @@
 --markup markdown
---plugin markdown-relative-links
 --no-private
 --title "ActiveRecord::Refined"
+--readme docs/index.md
 lib/**/*.rb
 -
 docs/conditions.md

data/README.md

@@ -14,42 +14,22 @@ 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.
 
-## History
-
-This gem was formerly known as **activerecord-refinements**, created by Akira Matsuda
-to experiment with the initial implementation of Ruby 2.0 Refinements. Because of the
-Refinements' spec change, that implementation stopped working on Ruby 2.0.0 stable, and
-the project was left dormant for a long time.
-
-It has now been renamed to **activerecord-refined** and reimplemented on top of
-[`Proc#refined`](https://docs.ruby-lang.org/en/master/Proc.html#method-i-refined),
-which will be introduced in Ruby 4.1. `Proc#refined` returns a new proc that
-is evaluated with the given refinements activated, so a block written by the caller can
-be re-interpreted under the query DSL's refinements:
-
-```ruby
-def evaluate_block(&block)
-  refined_block = block.refined(ActiveRecord::Refined::BlockSyntax)
-  BlockContext.new.instance_exec(&refined_block)
-end
-```
-
-This is exactly what the old implementation needed and could not do, so the query syntax
-works again without monkey-patching `Symbol` globally.
-
 ## 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
 
-The [sandbox](https://shugo.github.io/activerecord-refined/) is there to skip
-that build: it carries its own Ruby 4.1. `sandbox/` in this repository is what
-it is made of.
-
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -66,152 +46,26 @@ Or install it yourself as:
 
 ## Usage
 
-Just require the gem, and `where`, `select`, `joins`, `left_outer_joins`, `having`,
-`order` and `group` will accept a block.
+With Bundler — a Rails application — there is nothing to write: the gem in
+the Gemfile is loaded, and `where`, `select`, `joins`, `left_outer_joins`,
+`having`, `order` and `group` accept a block. Elsewhere, require it:
 
 ```ruby
 require "activerecord-refined"
 ```
 
-Inside the 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.
-
-The reference — every method a symbol answers to inside a block, every
-function a block can call, and what the relation takes — is on
-[rubydoc.info](https://rubydoc.info/gems/activerecord-refined):
-[`BlockSyntax`](https://rubydoc.info/gems/activerecord-refined/ActiveRecord/Refined/BlockSyntax)
-for the symbol,
-[`BlockContext`](https://rubydoc.info/gems/activerecord-refined/ActiveRecord/Refined/BlockContext)
-for the block, and
-[`QueryMethods`](https://rubydoc.info/gems/activerecord-refined/ActiveRecord/Refined/QueryMethods)
-for the relation. What follows is a tour, a topic at a time; each has a page
-of its own under [docs/](docs/) that says the rest.
-
-### Conditions
-
-```ruby
-Author.where { :age.between?(20, 40) & :name.like?("A%") }
-Author.where { :country.in?(%w[JP US]) | :country.null? }
-Author.where { !:name.start_with?("A") }
-Author.where { :id.in?(Post.select(:author_id)) }               # IN (subquery)
-Author.where { exists?(Post.where { :posts[:author_id] == :authors[:id] }) }
-```
-
-`&`, `|` and `!` are AND, OR and NOT. A value on the right is quoted as Active
-Record quotes it, a column compares against a column, a relation is a
-subquery. [docs/conditions.md](docs/conditions.md) has the rest: the
-negations SQL spells for itself, `true?` and NULL, regular expressions,
-`ANY` and `ALL`, PostgreSQL arrays.
-
-### Joins
-
-```ruby
-Author.joins(:posts) { :posts[:author_id] == :authors[:id] }
-Employee.joins(:employees, as: :managers) { :managers[:id] == :employees[:manager_id] }
-```
-
-`joins`, `left_outer_joins`, `right_outer_joins`, `full_outer_joins` and
-`cross_joins` take the `ON` as a block and `as:` for a table alias; a
-relation joins as a subquery, and one marked `lateral` as a `LATERAL` one.
-[docs/joins.md](docs/joins.md).
-
-### Aggregates and functions
-
-```ruby
-Author.group { :country }.having { count(:*) > 1 }
-Author.select { [count(:*).filter { :age < 50 }.as(:young), avg(:age).as(:average)] }
-Post.group { :author_id }.select { string_agg(:title, ", ").order(:title).as(:titles) }
-Post.where { :created_at > current_timestamp - 7.days }
-Post.select { cast(:price, "decimal(10,2)").as(:price) }
-```
-
-The scalar functions are methods — `upper`, `coalesce`, `round` and the rest
-— spelled the adapter's way where the adapters differ, and `fn` reaches any
-other by name. [docs/functions.md](docs/functions.md).
-
-### Expressions
-
-```ruby
-LineItem.where { :price * :quantity > 1000 }
-Post.where { :flags & 4 > 0 }
-Author.select { :country.when("JP").then("Japan").else("elsewhere").as(:where) }
-Author.select { case_when { :age >= 60 }.then("senior").else("adult").as(:band) }
-```
-
-Arithmetic, the bitwise operators and `CASE` are expressions like a column,
-so they compare, alias and aggregate. [docs/expressions.md](docs/expressions.md).
-
-### JSON
-
-```ruby
-Doc.where { :meta.dig_text(:author, :name) == "alice" }
-Doc.where { :meta.key?(:draft) }
-Doc.update_all { { meta: :meta.bury(:author, :name, "alice") } }
-Post.group { :author_id }.select { json_arrayagg(:title).as(:titles) }
-```
+## Documentation
 
-`dig` and `dig_text`, `bury`, `except`, `key?` and `keys` read and change a
-document by the names Hash uses; `json_object` and `json_arrayagg` build one. The same block
-runs on PostgreSQL's `jsonb`, MySQL's JSON and SQLite's.
-[docs/json.md](docs/json.md).
+https://rubydoc.info/gems/activerecord-refined/
 
-### Window functions
+## Adapters
 
-```ruby
-Author.select { [:name, row_number.over.partition(:country).order(:age.desc).as(:rank)] }
-Post.select { sum(:likes).over.order(:created_at).rows(..0).as(:running_total) }
-```
-
-`over` on any aggregate or window function, then `partition`, `order`,
-`rows` and `range`. [docs/windows.md](docs/windows.md).
-
-### Ordering, aliases and collation
-
-```ruby
-Author.order { :country.asc.nulls_last }
-Author.select { upper(:name).as(:author) }
-Author.where { :name.collate(:nocase) == "alice" }
-```
-
-[docs/ordering.md](docs/ordering.md).
-
-### Grouping, CTEs and DISTINCT ON
-
-```ruby
-Sale.group { rollup(:region, :product) }
-Post.distinct_on { :author_id }.order { [:author_id, :likes.desc] }       # PostgreSQL
-Node.with_recursive(tree: [Node.where { :id == 1 }, Node.joins(:tree) { :nodes[:parent_id] == :tree[:id] }]).from_cte(:tree)
-```
-
-[docs/grouping.md](docs/grouping.md) and [docs/ctes.md](docs/ctes.md).
-
-### Writing
-
-```ruby
-Post.where { :published == true }.update_all { { likes: :likes + 1 } }
-Tally.upsert_all(rows, unique_by: :page) { { hits: :hits + excluded(:hits) } }
-```
-
-[docs/writing.md](docs/writing.md).
-
-### Time zones
-
-Active Record stores in UTC and a `Time` in a block is quoted the way Active
-Record quotes one, so `where { :created_at > Time.current - 1.day }` is right
-whatever `Time.zone` is; what the database says the time is —
-`current_timestamp`, `extract` — is the session's business.
-[docs/time_zones.md](docs/time_zones.md).
-
-## Other adapters
-
-SQLite, PostgreSQL, MySQL, MariaDB, Oracle and SQL Server are built in: each
+SQLite, PostgreSQL, MySQL, MariaDB, Oracle and SQL Server are supported: each
 is a `Dialect`, one class per family of spellings, asked for whatever the
-databases write differently. An adapter the gem does not know keeps the
-standard spellings, which reach further than you might expect; where they
-fall short, a dialect of your own says the rest. Subclass
+databases write differently, so that one block builds the right SQL on all
+six. An adapter the gem does not know keeps the standard spellings, which
+reach further than you might expect; where they fall short, a dialect of
+your own says the rest. Subclass
 `ActiveRecord::Refined::Dialect` — or the built-in family the database
 descends from — override only what it spells differently, and register it
 under the adapter's name:
@@ -278,6 +132,29 @@ once, as normal code is — building query blocks with a string `eval` mints
 a fresh instruction sequence per pass, each earning a copy of its own, and
 the memo keeps both alive for the life of the process.
 
+## History
+
+This gem was formerly known as **activerecord-refinements**, created by Akira Matsuda
+to experiment with the initial implementation of Ruby 2.0 Refinements. Because of the
+Refinements' spec change, that implementation stopped working on Ruby 2.0.0 stable, and
+the project was left dormant for a long time.
+
+It has now been renamed to **activerecord-refined** and reimplemented on top of
+[`Proc#refined`](https://docs.ruby-lang.org/en/master/Proc.html#method-i-refined),
+which will be introduced in Ruby 4.1. `Proc#refined` returns a new proc that
+is evaluated with the given refinements activated, so a block written by the caller can
+be re-interpreted under the query DSL's refinements:
+
+```ruby
+def evaluate_block(&block)
+  refined_block = block.refined(ActiveRecord::Refined::BlockSyntax)
+  BlockContext.new.instance_exec(&refined_block)
+end
+```
+
+This is exactly what the old implementation needed and could not do, so the query syntax
+works again without monkey-patching `Symbol` globally.
+
 ## Running the tests
 
 The tests only build SQL, but they need a live connection to do it. SQLite is
@@ -320,11 +197,3 @@ stored anywhere.
 bundle exec bump patch --tag # or bump {major,minor} etc.
 git push --follow-tags
 ```
-
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Push to the branch (`git push origin my-new-feature`)
-5. Create new Pull Request

data/activerecord-refined.gemspec

@@ -42,11 +42,7 @@ Gem::Specification.new do |gem|
   gem.add_development_dependency "rubocop-performance", [">= 0"]
   gem.add_development_dependency "rubocop-rails", [">= 0"]
   gem.add_development_dependency "rubocop-md", [">= 0"]
-  # What renders the reference: `yard server --reload` serves it locally, and
-  # rubydoc.info renders the same .yardopts.  The plugin turns the README's
-  # relative links to docs/*.md -- which GitHub follows as they are -- into
-  # links to YARD's file pages; where it is not installed, rubydoc.info among
-  # them, YARD says so and leaves the links relative.
+  # What renders the reference: `yard server --reload` serves it locally,
+  # and rubydoc.info renders the same .yardopts.
   gem.add_development_dependency "yard", [">= 0"]
-  gem.add_development_dependency "yard-markdown-relative-links", [">= 0"]
 end

data/docs/index.md

@@ -0,0 +1,70 @@
+# ActiveRecord::Refined
+
+Adding clean and powerful query syntax on Active Record using refinements.
+
+```ruby
+Author.
+  joins(:posts) { :posts[:author_id] == :authors[:id] }.
+  where { :authors[:age].in?(20..40) & (:posts[:published] == true) }
+# SELECT "authors".* FROM "authors"
+#   INNER JOIN "posts" ON "posts"."author_id" = "authors"."id"
+#   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
+  inside a block: `as`, `asc`, `desc`, `collate`, `[]`, and through it the
+  conditions of {ActiveRecord::Refined::AST::Predications Predications} and
+  the operators of {ActiveRecord::Refined::AST::Arithmetics Arithmetics}.
+- {ActiveRecord::Refined::BlockContext BlockContext} — what a block can call:
+  the aggregates, the scalar and window functions, `CASE`, `sql`, `fn`.
+- {ActiveRecord::Refined::QueryMethods QueryMethods} — what the relation
+  takes: the block forms of `where` and the rest, the joins, `from_cte`,
+  `distinct_on`, `lateral`.
+- {ActiveRecord::Refined::Writes Writes} — `update_all` and `upsert_all` with
+  a block.
+- {ActiveRecord::Refined::Dialect Dialect} — one class per family of SQL
+  spellings, and `register` for an adapter of your own.
+
+## Guides
+
+One topic at a time, each with the SQL it builds and where the adapters
+differ:
+
+- {file:docs/conditions.md Conditions} — comparisons, `LIKE`, `IN`, `NULL`,
+  `true?`, regular expressions, subqueries, `ANY` and `ALL`, arrays.
+- {file:docs/joins.md Joins} — the `ON` as a block, table aliases, subqueries
+  and `LATERAL`.
+- {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,
+  `CASE`.
+- {file:docs/json.md JSON} — `dig`, `bury`, `except`, `key?`, `keys`, the
+  JSON aggregates, and where the adapters' JSON types part.
+- {file:docs/windows.md Window functions} — `over`, `partition`, `order`,
+  frames.
+- {file:docs/ordering.md Aliases, ordering and collation}
+- {file:docs/grouping.md Grouping} — `DISTINCT ON`, `GROUPING SETS`,
+  `ROLLUP`, `CUBE`.
+- {file:docs/ctes.md Common table expressions} — `with_recursive` and
+  `from_cte`.
+- {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/lib/activerecord-refined/version.rb

@@ -2,6 +2,6 @@
 
 module Activerecord
   module Refined
-    VERSION = "0.10.0"
+    VERSION = "0.10.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: activerecord-refined
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.1
 platform: ruby
 authors:
   - Shugo Maeda
@@ -233,22 +233,6 @@ dependencies:
           - ">="
           - !ruby/object:Gem::Version
             version: "0"
-  - !ruby/object:Gem::Dependency
-    name: yard-markdown-relative-links
-    requirement: !ruby/object:Gem::Requirement
-      requirements:
-        -
-          - ">="
-          - !ruby/object:Gem::Version
-            version: "0"
-    type: :development
-    prerelease: false
-    version_requirements: !ruby/object:Gem::Requirement
-      requirements:
-        -
-          - ">="
-          - !ruby/object:Gem::Version
-            version: "0"
 description: Adding clean and powerful query syntax on Active Record using refinements
 email:
   - shugo@ruby-lang.org
@@ -265,6 +249,7 @@ files:
   - docs/expressions.md
   - docs/functions.md
   - docs/grouping.md
+  - docs/index.md
   - docs/joins.md
   - docs/json.md
   - docs/ordering.md