namo 0.26.1 → 0.27.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40ae1191c5889356a1f8442673b3f44588521aa07f3f379fe58c9afa85b574c8
-  data.tar.gz: c38c7996e0a31e6050adcd9162dbbd6bde3b1c8b12cbaf0b1ab6a7848eeffb78
+  metadata.gz: 5649b6afb8e1272273a87286f053376ad42caddec81eed0610a672f26bc7e66a
+  data.tar.gz: 77a5e0c6499c3d600b76753e28c5e600b0dcd6dc0968d93069a56e3b10fc7652
 SHA512:
-  metadata.gz: 3bf0fb1cf44efc3096388e5adda7503802003e3b49a6539404cefed47ea03af1ca2414089e2599d0d7e0e1676f1a674f3bfadc80131ca4c88401d8c87d38b4c7
-  data.tar.gz: f8ea345eee0bca6cf22ea50f470874becce72795649a0e28bba8df3027c70511634accf961f61aa0647177214e18ad139bb24a5870a534ec9e0de096023b67bc
+  metadata.gz: 33c03e6c39cee1242a576a8355928b041464c9049a5bbb54900b7654dc36a9dec44741edaf28a8408eb293f4fcf4b702736841e8cf3b3bae7ce43e6684b098f1
+  data.tar.gz: d0ad82d6b415a09ba086a9d6a7b0f06c24d1dfad8bb3eaad72e1a40c878f9a431ccfb093f781836a94d0d4f4ab6bdf8b7917ddb61123012bf1fd0455168e3e05

data/CHANGELOG

@@ -2,6 +2,15 @@
 
 ## 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)` 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)`.)
 
 ```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,10 +23,14 @@ 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
 
@@ -37,8 +41,8 @@ class Namo
       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
 

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.26.1'
+  VERSION = '0.27.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
@@ -251,6 +278,13 @@ 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
   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.27.0
 platform: ruby
 authors:
 - thoran