namo 0.26.1 → 0.28.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ae1191c5889356a1f8442673b3f44588521aa07f3f379fe58c9afa85b574c8
-  data.tar.gz: c38c7996e0a31e6050adcd9162dbbd6bde3b1c8b12cbaf0b1ab6a7848eeffb78
+  metadata.gz: cf138a52a691a4d50f093e506e5018d652a66ab23846593e2622cbe23710c8ef
+  data.tar.gz: a8bbdc8cdf8af2b8c3df9881d468cc0445ffca7dd1f4523c614a2e71a8acc4c5
 SHA512:
-  metadata.gz: 3bf0fb1cf44efc3096388e5adda7503802003e3b49a6539404cefed47ea03af1ca2414089e2599d0d7e0e1676f1a674f3bfadc80131ca4c88401d8c87d38b4c7
-  data.tar.gz: f8ea345eee0bca6cf22ea50f470874becce72795649a0e28bba8df3027c70511634accf961f61aa0647177214e18ad139bb24a5870a534ec9e0de096023b67bc
+  metadata.gz: 58c3cb00aee14efb44155a9a4a8e5eaa748aa51389f0ac19c27f4d8a077970cac3b605e7d1ffad2c95329782fdf04755ee1e8975b9e2d34209705a1e8f780014
+  data.tar.gz: 7492096f83494f4c5a976b602796e3611c4eef1e920cc6b6179ff1b63e7f7fcd7a7f1e12ab2d637d3a1ef8fb4a0eeeb0364a0068ff3cbe12332b8e4b0e0d20c2

data/CHANGELOG

@@ -1,7 +1,29 @@
 # CHANGELOG
 
+## 20260711
+
+0.28.0: ~ Namo::Collection#detail/#as_detail: Accept the by label positionally or by keyword.
+
+Accept the by label positionally or by keyword (positional winning), per the constructor precedent — resolving the detail/as_detail calling-convention asymmetry.
+
+1. ~ Namo::Collection#detail(positional_by = nil, by: :member), #as_detail(positional_by = nil, by: :member): resolve by = positional_by || by, mirroring the constructor's @data = positional_data || data; positional wins. summary/as_summary unchanged — dimension stays their positional, by: the keyword modifier.
+2. ~ test/Namo/Collection_test.rb: + detail and as_detail each take the by label positionally or by keyword, positional winning over a conflicting keyword.
+3. ~ README.md: ~ the view-methods note — detail/as_detail take the label positionally or by keyword (the constructor's shape); replaces the "carries no dimension, so positional" rationale.
+4. ~ ROADMAP.md: + the 0.28.0 entry (twin asymmetry, constructor precedent, primary-dual/modifier-keyword scope); current-state bumped to 0.28.0; a forward-reference on the 0.18.0 note superseding its positional rationale.
+5. ~ docs/: regenerate the print-ready PDFs.
+6. ~ Namo::VERSION: /0.27.0/0.28.0/
+
 ## 20260710
 
+0.27.0: ~ Namo::Collection#summary/#as_summary: + an optional block for a per-member reduction beyond a single named reducer.
+
+1. ~ Namo::Collection#summary(dimension = nil, by:, reducer:, &block): dimension goes optional; with a block, maps each member through block.call(member).merge(by => member.name), the member label merged last so it wins; given neither a dimension nor a block, raises ArgumentError; the no-block path is byte-identical. as_summary forwards &block to summary and persists the result, so the block form lives in one place.
+2. ~ test/Namo/Collection_test.rb: + block-form summary returns one row per member merged with the member label; the member label wins over a by key the block returns; the neither-arg ArgumentError; the map/flat_map cardinality pin (summary one row per member, detail all rows per member); as_summary with a block sets the data and delegates. ~ the non-block custom-by test also pins the reduced value carried alongside the relabelled column.
+3. ~ README.md: + an "A block for per-member reductions" note under the Collection view methods (the one-row-per-member contract, the member-label-wins merge, an argmax example, the neither-arg raise); + a bare-collection call-site by: example beside the class-default prose; the summary/as_summary signatures gain (dimension = nil, ..., &block).
+4. ~ ROADMAP.md: + the 0.27.0 release entry (the block warrant from 0.14.0, summarise considered-and-refused, the pinned decisions, the transient-block serialisation-independence, the deferred group-scoped formula); current-state bumped to 0.27.0; the block form folded into the Summary vocabulary and the 1.0.0 feature list.
+5. ~ docs/: regenerate the print-ready PDFs.
+6. ~ Namo::VERSION: /0.26.1/0.27.0/
+
 0.26.1: Refactor Namo::Formulae#attach through a private #bind, and document mutability and the corrected collision-resolution idioms.
 
 1. ~ lib/Namo/Formulae.rb — attach binds each of a formulary's public method names through a new private bind(name, modul): marker guard, host.extend(modul), then self[name] = modul.instance_method(name).bind(host). attach and detach share one private raise_unless_formulary marker guard. bind stays private — attach is its only caller.

data/README.md

@@ -1046,7 +1046,15 @@ gt.detail.values(:weight).sum              # total weight by summing every line
 # => 490
 ```
 
-`Car` overrides `summary`/`detail` only to set `by: :assembly` as the per-class default and then calls `super`. A bare `Namo::Collection.new` works equally well, defaulting `by:` to `:member` and taking it at the call site.
+`Car` overrides `summary`/`detail` only to set `by: :assembly` as the per-class default and then calls `super`. A bare `Namo::Collection.new` works equally well, defaulting `by:` to `:member` and taking it at the call site:
+
+```ruby
+parts = Namo::Collection.new
+parts << [powertrain, chassis, body]
+
+parts.summary(:weight).values(:member)                    # default label => [:powertrain, :chassis, :body]
+parts.summary(:weight, by: :assembly).values(:assembly)   # call-site by:  => [:powertrain, :chassis, :body]
+```
 
 #### Lazy detail, behaving as its line items
 
@@ -1066,8 +1074,8 @@ Detail is the lazy view because a Collection's rows simply *are* its members' ro
 
 The views come in a non-mutating pair and a mutating pair:
 
-- `summary(dimension, by:, reducer:)` and `detail(by:)` are **non-mutating** — each returns a fresh `Namo` derived from the members, leaving the Collection untouched. Use these when you want a view to keep: assign the result to a variable and operate on it independently.
-- `as_summary(dimension, by:, reducer:)` and `as_detail(by)` are **mutating** — each sets the Collection's data to the chosen view and returns `self`, for a fluent step. (`as_detail` carries no `dimension`, so its label argument is positional: `as_detail(:assembly)`.)
+- `summary(dimension = nil, by:, reducer:, &block)` and `detail(by:)` are **non-mutating** — each returns a fresh `Namo` derived from the members, leaving the Collection untouched. Use these when you want a view to keep: assign the result to a variable and operate on it independently.
+- `as_summary(dimension = nil, by:, reducer:, &block)` and `as_detail(by = :member)` are **mutating** — each sets the Collection's data to the chosen view and returns `self`, for a fluent step. (`detail` and `as_detail` take the origin label either positionally or by the `by:` keyword, positional winning — the same shape the constructor gives `data` — so `as_detail(:assembly)` and `as_detail(by: :assembly)` are one call. `summary`/`as_summary` keep `by:` a keyword beside their `dimension` positional.)
 
 ```ruby
 gt.summary(:cost, reducer: :mean)          # a fresh Namo; gt is unchanged
@@ -1077,6 +1085,23 @@ gt.as_detail(:assembly)                    # gt's data becomes the detail; retur
 
 `reducer:` is any method the member's column responds to — `:sum` (the default) and `:mean` are typical (`:mean` via a statistics gem that adds `Array#mean`).
 
+#### A block for per-member reductions
+
+The single-`dimension`, single-`reducer` form reduces one column with one named method. Per-member work that wants several columns at once, or a reduction that isn't a single-column `send` — notably a *pick-by-extremum* ("the component of the heaviest part", an argmax that reduces no one column) — is supplied by an optional block. The block receives each member and returns the hash for that member's summary row; `summary` labels it with the member name and collects one row per member:
+
+```ruby
+gt.summary(by: :assembly) do |assembly|
+  heaviest = assembly.max_by{|part| part[:weight]}
+  {
+    part_count:    assembly.values(:weight).size,
+    heaviest_part: heaviest[:component],
+    total_cost:    assembly.values(:cost).sum,
+  }
+end
+```
+
+The contract is one row per member: `summary` maps members to rows, where `detail` flat-maps them to line items — the two views have opposite cardinality. The member label merges last, so a block returning a hash that carries the `by` key cannot override the group's identity — `by` is `summary`'s to set, not the block's. `as_summary` takes the same block and persists its result, delegating to `summary`. A `summary` given neither a `dimension` nor a block raises an `ArgumentError`.
+
 #### Inject-iff-absent
 
 `detail(by:)` unions the members' rows and labels each with its origin, but only when that label isn't already present:

data/lib/Namo/Collection.rb

@@ -23,27 +23,33 @@ class Namo
       @members.find{|member| member.name == name} unless name.nil?
     end
 
-    def summary(dimension, by: :member, reducer: :sum)
-      rows = @members.map do |member|
-        {by => member.name, dimension => member.values(dimension).send(reducer)}
-      end
+    def summary(dimension = nil, by: :member, reducer: :sum, &block)
+      raise ArgumentError, "summary needs a dimension or a block" unless dimension || block
+      rows =
+        if block
+          @members.map{|member| block.call(member).merge(by => member.name)}
+        else
+          @members.map{|member| {by => member.name, dimension => member.values(dimension).send(reducer)}}
+        end
       Namo.new(rows)
     end
 
-    def detail(by: :member)
+    def detail(positional_by = nil, by: :member)
+      by = positional_by || by
       rows = @members.flat_map do |member|
         member.data.map{|row| row.key?(by) ? row : row.merge(by => member.name)}
       end
       Namo.new(rows)
     end
 
-    def as_summary(dimension, by: :member, reducer: :sum)
-      @data = summary(dimension, by: by, reducer: reducer).data
+    def as_summary(dimension = nil, by: :member, reducer: :sum, &block)
+      @data = summary(dimension, by: by, reducer: reducer, &block).data
       self
     end
 
-    def as_detail(by = :member)
-      @data = detail(by: by).data
+    def as_detail(positional_by = nil, by: :member)
+      by = positional_by || by
+      @data = detail(by).data
       self
     end
 

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.26.1'
+  VERSION = '0.28.0'
 end

data/test/Namo/Collection_test.rb

@@ -181,9 +181,10 @@ describe Namo::Collection do
       _(summary.values(:weight)).must_equal [280, 150, 60]
     end
 
-    it "labels with a custom by dimension" do
+    it "labels with a custom by dimension, carrying the reduced value alongside" do
       summary = collection.summary(:weight, by: :assembly)
       _(summary.values(:assembly)).must_equal [:powertrain, :chassis, :body]
+      _(summary.values(:weight)).must_equal [280, 150, 60]
     end
 
     it "reduces with a custom reducer" do
@@ -195,6 +196,32 @@ describe Namo::Collection do
       collection.summary(:weight)
       _(collection.values(:weight)).must_equal [200, 80, 150, 60]
     end
+
+    it "with a block returns one row per member, the block's hash merged with the member label" do
+      result = collection.summary do |member|
+        {heaviest: member.max_by{|row| row[:weight]}[:component]}
+      end
+      _(result.values(:member)).must_equal [:powertrain, :chassis, :body]
+      _(result.values(:heaviest)).must_equal ['engine', 'frame', 'panels']
+    end
+
+    it "with a block, the member label wins over a by key the block returns" do
+      result = collection.summary(by: :assembly) do |member|
+        {assembly: :overridden, total: member.values(:weight).sum}
+      end
+      _(result.values(:assembly)).must_equal [:powertrain, :chassis, :body]
+      _(result.values(:total)).must_equal [280, 150, 60]
+    end
+
+    it "raises an ArgumentError when given neither a dimension nor a block" do
+      error = _(proc{collection.summary}).must_raise ArgumentError
+      _(error.message).must_match(/dimension or a block/)
+    end
+
+    it "yields one row per member (map), where detail yields all rows per member (flat_map)" do
+      _(collection.summary(:weight).data.size).must_equal collection.members.size
+      _(collection.detail.data.size).must_equal collection.members.sum{|member| member.data.size}
+    end
   end
 
   describe "#detail" do
@@ -218,6 +245,12 @@ describe Namo::Collection do
       collection.detail(by: :assembly)
       _(collection.dimensions).wont_include :assembly
     end
+
+    it "takes the by label positionally or by keyword, positional winning" do
+      _(collection.detail(:assembly).values(:assembly)).must_equal [:powertrain, :powertrain, :chassis, :body]
+      _(collection.detail(by: :assembly).values(:assembly)).must_equal [:powertrain, :powertrain, :chassis, :body]
+      _(collection.detail(:assembly, by: :ignored).values(:assembly)).must_equal [:powertrain, :powertrain, :chassis, :body]
+    end
   end
 
   describe "live recomputation (no memoisation in 1.x)" do
@@ -251,6 +284,21 @@ describe Namo::Collection do
       collection.as_summary(:weight)
       _(collection.dimensions.sort).must_equal [:member, :weight].sort
     end
+
+    it "as_summary with a block sets the data to the block summary and returns self" do
+      result = collection.as_summary(by: :assembly){|member| {count: member.values(:weight).size}}
+      _(result).must_be_same_as collection
+      _(collection.values(:assembly)).must_equal [:powertrain, :chassis, :body]
+      _(collection.values(:count)).must_equal [2, 1, 1]
+    end
+
+    it "as_detail takes the by label positionally or by keyword, positional winning" do
+      positional = Namo::Collection.new.tap{|c| c << [powertrain, chassis]}.as_detail(:assembly)
+      keyword    = Namo::Collection.new.tap{|c| c << [powertrain, chassis]}.as_detail(by: :assembly)
+      _(positional.values(:assembly)).must_equal [:powertrain, :powertrain, :chassis]
+      _(keyword.values(:assembly)).must_equal positional.values(:assembly)
+      _(Namo::Collection.new.tap{|c| c << powertrain}.as_detail(:assembly, by: :ignored).values(:assembly)).must_equal [:powertrain, :powertrain]
+    end
   end
 
   describe "as_* view lifetime (rebuild-on-<<: persists until the next <<)" do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.26.1
+  version: 0.28.0
 platform: ruby
 authors:
 - thoran
@@ -98,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.15
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Named dimensional data for Ruby.
 test_files: []