namo 0.31.3 → 0.31.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 611590edfde52f5713b8fe41daf28b5986a26f4df3a5c28631dace995c31b98c
-  data.tar.gz: f098e612be772d3232598020963f6b3ed5c9a786f4827de25312e90aff23bc48
+  metadata.gz: 77e56d154536ec5ebde8dbb2d660277007a76d4ec108c6b669ff96399f9991d7
+  data.tar.gz: 79baaf53cfd3417b5db049b7c2ea6701c60580e97f41235bcafb91538c49d427
 SHA512:
-  metadata.gz: a28b1d267f69eb14a9ee8d7a9cbdba9de57132be4577a39892e3f679e0ccee293a88a2d526ceda0ff6232317bdb8028ae3f04858160c7a38cbc4cb640c5fff16
-  data.tar.gz: e615d6be239ccd8a563922e3b51f5044a745733a4ef3f120b78ab5b07f84a4ff5be37373386853fb9d1484146471fc7034d58af9aee9172e4ae967e341ba0c39
+  metadata.gz: ffa93bb4ad5f35eaffcefa76778dbffc843bc24a95130327d4da88e8ae8e3103fdc6a28a2eabaf0f38b996b768e6125f7e1538612ac8c922e0bb7c495870f128
+  data.tar.gz: 24e8d924c61152922e757ab30b87662cede03e6dcb85dbb2cd964de4b9230ee4d65617e74760b7e37a3d8831dd332c3f46e829adfbaa82cf275f2a9108528558

data/CHANGELOG

@@ -1,5 +1,28 @@
 # CHANGELOG
 
+## 20260826
+
+0.31.5: ~ Namo::Collection#detail, #as_detail: the detail view carries the members' formulae.
+
+1. ~ Namo::Collection#detail: the returned Namo carries the members' formulae, folded in member order so that a later member wins a name collision, as a later member wins a collision of names in <<. It had been built with none, so the view documented at 0.18.0 as the lossless union of the members' rows dropped every derived dimension: group_by hands each member the source's formulae, and detail handed them back stripped.
+2. ~ Namo::Collection#as_detail: merges the detail view's formulae into the Collection's own, the Collection having become that view. Without it the round trip still lost them, as_detail having taken only the data.
+3. ~ script/demo: the collections section checks the round trip with === rather than ==, == comparing row multisets alone and so unable to see the formulae go missing, which is why this stood.
+4. ~ README.md: the four views, on which of them carries formulae and why.
+5. ~ ROADMAP.md: + 0.31.5.
+6. ~ Namo::VERSION: /0.31.4/0.31.5/
+
+
+## 20260826
+
+0.31.4: ~ Namo::Collection#inspect: the members are rendered, nested under their names.
+
+1. ~ Namo::Collection#inspect: the members are rendered nested under their names rather than listed as bare labels beside a row count, the members being the substance and the data view derived from them. The Namo::INSPECTED_ROWS budget is spread across the members shown — one member renders ten of its rows, five render two apiece, ten render one each and are put on one line — and members beyond it are elided with a count, as rows are. The member list had no cap at all: 2,641 members emitted 22,704 characters on a single line, which is the failure INSPECTED_ROWS was introduced at 0.31.0 to end. A member renders nested as it renders alone, its derived values among its stored ones and its own derived: suffix naming whatever none of its rendered rows could materialise. The detail view's row count closes the block, and a Collection's own formulae are named after it, being a namespace its members cannot resolve.
+2. + Namo#inspected_data: the rendered rows, the count of those not shown, and the derived dimensions none of them carries — protected, so Namo::Collection can render its members' rows without going through Namo#inspect and repeating each member's name, and still report what a member reports of itself.
+3. ~ README.md: the Inspection output section, and the two group_by examples whose rendering changes.
+4. ~ ROADMAP.md: + 0.31.4.
+5. ~ Namo::VERSION: /0.31.3/0.31.4/
+
+
 ## 20260824
 
 0.31.3: ~ Namo#to_a: derived dimensions are carried alongside the stored ones.

data/README.md

@@ -996,14 +996,27 @@ Evaluation is bounded by the row cap rather than by the data — at most ten row
 
 Rows beyond `Namo::INSPECTED_ROWS` — ten — are elided with a count of the remainder, so the output stays bounded however large the data: a thousand-row Namo renders its first ten rows and then `... 990 more rows`.
 
-A `Row` renders itself, its derived values and its formula names in every case, having no `derived_dimensions` of its own to be asked, and never the Namo it came from. A `Collection` renders its member names and its row count, the members being its substance and the data view derived from them.
+A `Row` renders itself, its derived values and its formula names in every case, having no `derived_dimensions` of its own to be asked, and never the Namo it came from.
+
+A `Collection` renders its members, nested under their names, because the members are its substance and `@data` is a view derived from them. The `INSPECTED_ROWS` budget is spread across the members shown rather than spent on one: a single member renders ten of its rows, five members render two apiece, ten render one each and are put on one line. Members beyond that are elided with a count, as rows are, so a Collection of thousands renders in a dozen lines. The total row count of the detail view closes the block.
+
+A member renders nested as it would render alone: its derived values among its stored ones, and its own `derived:` suffix naming whatever it cannot materialise. A Collection's own formulae are a separate namespace — it cannot resolve its members' and they cannot resolve its — so they are named in a suffix of the Collection's own, after the closing bracket.
 
 ```ruby
 sales.first
 # => #<Namo::Row {product: "Widget", quarter: "Q1", price: 10.0, quantity: 100, revenue: 1000.0} derived: [:revenue]>
 
 sales.group_by(:quarter)
-# => #<Namo::Collection members: ["Q1", "Q2"], 4 rows>
+# => #<Namo::Collection [
+#   "Q1" => [
+#     {product: "Widget", quarter: "Q1", price: 10.0, quantity: 100, revenue: 1000.0},
+#     {product: "Gadget", quarter: "Q1", price: 25.0, quantity: 40, revenue: 1000.0}
+#   ],
+#   "Q2" => [
+#     {product: "Widget", quarter: "Q2", price: 10.0, quantity: 150, revenue: 1500.0},
+#     {product: "Gadget", quarter: "Q2", price: 25.0, quantity: 60, revenue: 1500.0}
+#   ]
+# ] 4 rows>
 ```
 
 ### Named Namos
@@ -1108,6 +1121,8 @@ Detail is the lazy view because a Collection's rows simply *are* its members' ro
 
 #### Four view methods
 
+`detail` carries the members' formulae, its rows being the members' rows — folded in member order, so a later member wins a name collision as it wins a collision of names in `<<`. A `summary`'s rows are reductions, holding neither the dimensions those formulae read nor the rows they read them from, so it carries none.
+
 The views come in a non-mutating pair and a mutating pair:
 
 - `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.
@@ -1204,7 +1219,14 @@ Freeze-gated memoisation is a 2.x optimisation — opt-in via `freeze`, transpar
 
 ```ruby
 prices.group_by(:symbol)
-# => #<Namo::Collection members: [:BHP, :RIO, :CBA]>
+# => #<Namo::Collection [
+#   :BHP => [
+#     {symbol: :BHP, date: "2025-01-02", close: 42.5},
+#     {symbol: :BHP, date: "2025-01-03", close: 43.0}
+#   ],
+#   :RIO => [{symbol: :RIO, date: "2025-01-02", close: 118.0}],
+#   :CBA => [{symbol: :CBA, date: "2025-01-02", close: 96.4}]
+# ] 4 rows>
 
 prices.group_by(:symbol).summary(:close, reducer: :mean)
 # => Namo with {member:, close:} rows — mean close per symbol

data/lib/Namo/Collection.rb

@@ -25,21 +25,24 @@ class Namo
 
     def summary(dimension = nil, by: :member, reducer: :sum, &block)
       raise ArgumentError, "summary needs a dimension or a block" unless dimension || block
-      rows =
+      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(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)
+      rows = (
+        @members.flat_map do |member|
+          member.data.map{|row| row.key?(by) ? row : row.merge(by => member.name)}
+        end
+      )
+      Namo.new(rows, formulae: member_formulae)
     end
 
     def as_summary(dimension = nil, by: :member, reducer: :sum, &block)
@@ -49,16 +52,61 @@ class Namo
 
     def as_detail(positional_by = nil, by: :member)
       by = positional_by || by
-      @data = detail(by).data
+      view = detail(by)
+      @data = view.data
+      @formulae = @formulae.merge(view.formulae)
       self
     end
 
+    # The members are the substance, so they are what is rendered.  A list of names
+    # and a row count described the derived view and called it the object, and the
+    # list was unbounded besides: 2,641 members emitted 22,704 characters on one
+    # line, which is the failure INSPECTED_ROWS was introduced to end.
+    #
+    # That budget is now spread across the members shown rather than spent on one
+    # member's rows: one member renders ten of its rows, ten members render one
+    # apiece, five render two.
     def inspect
-      "#<#{self.class}#{inspected_name} members: #{@members.map(&:name).inspect}, #{@data.length} rows#{inspected_derived}>"
+      "#<#{self.class}#{inspected_name} #{inspected_members} #{@data.length} rows#{inspected_derived}>"
     end
 
     private
 
+    # The members' formulae, folded in member order so that a later member wins a
+    # name collision, as a later member wins a collision of names in <<.  The
+    # detail view is the members' rows, so it must be able to answer what the
+    # members can answer of them; group_by hands every member the same formulae,
+    # so only an assembled Collection can have members which disagree.
+    def member_formulae
+      @members.map(&:formulae).reduce(Formulae.new){|merged, formulae| merged.merge(formulae)}
+    end
+
+    def inspected_members
+      return '[]' if @members.empty?
+      shown = [@members.length, INSPECTED_ROWS].min
+      each = [INSPECTED_ROWS / shown, 1].max
+      rendered = @members.first(shown).map{|member| "  #{member.name.inspect} => #{inspected_member(member, each)}"}.join(",\n")
+      rendered += "\n  ... #{@members.length - shown} more members" if @members.length > shown
+      "[\n#{rendered}\n]"
+    end
+
+    # A member showing a single row is rendered on one line: three lines of brackets
+    # to carry one row is the shape a Collection of many members lands in, and it
+    # cost more than the rows did.  On what is rendered rather than on the limit,
+    # so a member holding one row of a larger allowance reads the same way.
+    def inspected_member(member, limit)
+      rows, remainder, unshown = member.inspected_data(limit)
+      elided = remainder > 0
+      suffix = inspected_derived_names(unshown)
+      if rows.length == 1
+        "[#{rows.join}#{elided ? ", ... #{remainder} more rows" : ''}]#{suffix}"
+      else
+        body = rows.map{|row| "    #{row}"}.join(",\n")
+        body += "\n    ... #{remainder} more rows" if elided
+        "[\n#{body}\n  ]#{suffix}"
+      end
+    end
+
     def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
       @members = []
       super

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.31.3'
+  VERSION = '0.31.5'
 end

data/lib/namo.rb

@@ -262,6 +262,16 @@ class Namo
 
   protected
 
+  # The rendered rows, the count of those not shown, and the derived dimensions
+  # none of them carries.  Shared with Collection, which renders its members' rows
+  # rather than its own and must report what a member would report of itself.
+  def inspected_data(limit)
+    rendered = @data.first(limit).map{|row| [row, inspected_derivations(row)]}
+    [rendered.map{|row, derived| row.merge(derived).inspect},
+      @data.length - limit,
+      unshown_derived(rendered)]
+  end
+
   def row_multiset
     @data.tally
   end
@@ -278,6 +288,13 @@ class Namo
 
   private
 
+  def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
+    @data = positional_data || data
+    @formulae = formulae.is_a?(Formulae) ? formulae : Formulae.new(formulae)
+    @name = name
+    attach_included_formularies
+  end
+
   def inspected_name
     @name.nil? ? '' : " #{@name.inspect}"
   end
@@ -308,19 +325,19 @@ class Namo
   # Only those the rows above do not already carry.  A formula which raises, and a
   # parameterised one which cannot be materialised without its arguments, render
   # no value and would otherwise be nowhere in the output at all.  A Collection
-  # renders no rows and so passes none, naming every one of them.
+  # renders no rows of its own and so passes none, naming every one of them.
   def inspected_derived(rendered = [])
-    unshown = derived_dimensions.reject do |dimension|
-      rendered.any? && rendered.all?{|_, derived| derived.key?(dimension)}
-    end
+    inspected_derived_names(unshown_derived(rendered))
+  end
+
+  def inspected_derived_names(unshown)
     unshown.empty? ? '' : " derived: #{unshown.inspect}"
   end
 
-  def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
-    @data = positional_data || data
-    @formulae = formulae.is_a?(Formulae) ? formulae : Formulae.new(formulae)
-    @name = name
-    attach_included_formularies
+  def unshown_derived(rendered)
+    derived_dimensions.reject do |dimension|
+      rendered.any? && rendered.all?{|_, derived| derived.key?(dimension)}
+    end
   end
 
   def add_row(row)

data/test/Namo/Collection_test.rb

@@ -347,15 +347,147 @@ describe Namo::Collection do
     end
   end
 
+  describe "the detail view and its formulae" do
+    def readings
+      namo = Namo.new([
+        {station: "Melbourne", month: "2025-01", high_temp: 26.4, mean_temp: 25.9},
+        {station: "Perth", month: "2025-01", high_temp: 32.0, mean_temp: 30.0}])
+      namo[:anomaly] = proc{|row| (row[:high_temp] - row[:mean_temp]).round(1)}
+      namo
+    end
+
+    it "carries the members' formulae, the view being the members' rows" do
+      _(readings.group_by(:station).detail(:station).derived_dimensions).must_equal [:anomaly]
+    end
+
+    it "answers a derived dimension through the detail view" do
+      _(readings.group_by(:station).detail(:station).values(:anomaly)).must_equal [0.5, 2.0]
+    end
+
+    # == compares row multisets and cannot see a formula go missing, so it called
+    # the partition exact while the derived dimensions were being dropped.  === is
+    # the operator which compares the formula names too.
+    it "inverts the partition exactly, formulae and all" do
+      source = readings
+      _(source.group_by(:station).as_detail(:station)).must_be :===, source
+    end
+
+    it "folds the members' formulae, a later member winning the name" do
+      first = Namo.new([{a: 1}], name: :first)
+      first[:b] = proc{|row| :from_first}
+      second = Namo.new([{a: 2}], name: :second)
+      second[:b] = proc{|row| :from_second}
+      collection = Namo::Collection.new
+      collection << first << second
+      _(collection.detail.values(:b)).must_equal [:from_second, :from_second]
+    end
+
+    # A summary's rows are reductions, holding neither the dimensions the members'
+    # formulae read nor the rows they read them from, so it carries none.
+    it "leaves the summary without them" do
+      _(readings.group_by(:station).summary(:high_temp).derived_dimensions).must_equal []
+    end
+  end
+
   describe "#inspect" do
-    it "renders the member names and the row count" do
+    def collection_of(members, rows_each)
+      rows = (1..members).flat_map{|member| (1..rows_each).map{|row| {group: "g#{member}", n: row}}}
+      Namo.new(rows).group_by(:group)
+    end
+
+    it "renders each member nested, under its name" do
       collection = Namo::Collection.new
       collection << Namo.new([{a: 1}], name: :first) << Namo.new([{a: 2}], name: :second)
-      _(collection.inspect).must_equal "#<Namo::Collection members: [:first, :second], 2 rows>"
+      _(collection.inspect).must_equal <<~INSPECT.chomp
+        #<Namo::Collection [
+          :first => [{a: 1}],
+          :second => [{a: 2}]
+        ] 2 rows>
+      INSPECT
     end
 
     it "renders an empty Collection" do
-      _(Namo::Collection.new.inspect).must_equal "#<Namo::Collection members: [], 0 rows>"
+      _(Namo::Collection.new.inspect).must_equal "#<Namo::Collection [] 0 rows>"
+    end
+
+    # The budget is INSPECTED_ROWS spread across the members shown, so the output
+    # is bounded by what was asked for rather than by how the data is shaped.
+    it "gives a lone member the whole row budget" do
+      rendered = collection_of(1, 50).inspect
+      _(rendered.scan(/\{group:/).length).must_equal Namo::INSPECTED_ROWS
+      _(rendered).must_include "... 40 more rows"
+    end
+
+    it "gives five members two rows apiece" do
+      rendered = collection_of(5, 9).inspect
+      _(rendered.scan(/\{group:/).length).must_equal Namo::INSPECTED_ROWS
+      _(rendered).must_include "... 7 more rows"
+    end
+
+    it "gives ten members one row apiece, on one line each" do
+      rendered = collection_of(10, 4).inspect
+      _(rendered.scan(/\{group:/).length).must_equal Namo::INSPECTED_ROWS
+      _(rendered).must_include %q{"g1" => [{group: "g1", n: 1}, ... 3 more rows]}
+    end
+
+    it "elides the members beyond the budget, with a count" do
+      rendered = collection_of(2641, 130).inspect
+      _(rendered).must_include "... 2631 more members"
+      _(rendered.lines.length).must_equal 13
+    end
+
+    # 2,641 members emitted 22,704 characters on a single line before the budget.
+    it "stays bounded as the members multiply" do
+      _(collection_of(2641, 130).inspect.length).must_be :<, collection_of(10, 130).inspect.length * 2
+    end
+
+    it "reports the total row count of the detail view" do
+      _(collection_of(3, 7).inspect).must_include "] 21 rows>"
+    end
+
+    # Where the two rules meet: 0.31.2 names only what the rendered rows do not
+    # carry.  A member's formula is carried, since its rows are what is rendered; a
+    # Collection's own applies to the data view, which the nested form never shows,
+    # so naming it is the only way to learn it is there.
+    it "names its own derived dimensions while showing its members' inline" do
+      member = Namo.new([{part: "block", weight: 90}], name: :powertrain)
+      member[:light] = proc{|row| row[:weight] < 50}
+      collection = Namo::Collection.new
+      collection << member
+      collection[:heavy] = proc{|row| row[:weight] > 50}
+      _(collection.derived_dimensions).must_equal [:heavy]
+      _(member.derived_dimensions).must_equal [:light]
+      _(collection.inspect).must_include "{part: \"block\", weight: 90, light: false}"
+      _(collection.inspect).must_include "] 1 rows derived: [:heavy]>"
+    end
+
+    # Nested, a member must say what it says of itself: a formula it cannot
+    # materialise is named in its own inspect, and vanishing here would make the
+    # nested rendering quieter than the parts it is made of.
+    it "carries a member's own suffix for what that member cannot materialise" do
+      member = Namo.new([{part: "block", weight: 90}], name: :powertrain)
+      member[:light] = proc{|row| row[:weight] < 50}
+      member[:scaled] = proc{|row, namo, factor| row[:weight] * factor}
+      collection = Namo::Collection.new
+      collection << member
+      _(member.inspect).must_include "derived: [:scaled]"
+      _(collection.inspect).must_include ":powertrain => [{part: \"block\", weight: 90, light: false}] derived: [:scaled]"
+    end
+
+    it "carries no suffix when only its members hold formulae" do
+      member = Namo.new([{part: "block", weight: 90}], name: :powertrain)
+      member[:light] = proc{|row| row[:weight] < 50}
+      collection = Namo::Collection.new
+      collection << member
+      _(collection.inspect).wont_include "derived:"
+    end
+
+    it "renders a member's derived dimensions among its stored ones" do
+      member = Namo.new([{a: 1}], name: :first)
+      member[:b] = proc{|row| row[:a] + 1}
+      collection = Namo::Collection.new
+      collection << member
+      _(collection.inspect).must_include "{a: 1, b: 2}"
     end
   end
 

data/test/sizing_test.rb

@@ -0,0 +1,42 @@
+# test/sizing_test.rb
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+require_relative '../lib/namo'
+
+# script/sizing produces the figures in ROADMAP.md's "What size it is for".  A
+# measurement whose script has rotted is a measurement nobody can repeat, which is
+# the condition the script exists to end — so assert it still runs, at sizes small
+# enough not to make the suite a benchmark.
+
+describe 'script/sizing' do
+  def sizing(*arguments)
+    root = File.expand_path('..', __dir__)
+    IO.popen([File.join(root, 'script', 'sizing'), *arguments],
+      chdir: root, err: [:child, :out]){|io| io.read}
+  end
+
+  it "reports a row per size asked for" do
+    output = sizing('2000', '4000')
+    _($?.success?).must_equal true
+    _(output).must_match(/^\| 2,000 \| \d+ ms \|/)
+    _(output).must_match(/^\| 4,000 \| \d+ ms \|/)
+  end
+
+  it "renders as the table the ROADMAP carries" do
+    _(sizing('2000').lines.first).must_equal "| rows | group_by | per row | bytes/row |\n"
+  end
+
+  it "refuses a size it cannot measure" do
+    sizing('0')
+    _($?.success?).must_equal false
+  end
+
+  it "needs nothing but the gem's own dependencies" do
+    root = File.expand_path('..', __dir__)
+    output = IO.popen({'RUBYLIB' => nil}, [File.join(root, 'script', 'sizing'), '2000'],
+      chdir: root, err: [:child, :out]){|io| io.read}
+    _(output).wont_match(/LoadError/)
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.31.3
+  version: 0.31.5
 platform: ruby
 authors:
 - thoran
@@ -82,6 +82,7 @@ files:
 - test/console_test.rb
 - test/demo_test.rb
 - test/namo_test.rb
+- test/sizing_test.rb
 homepage: https://github.com/thoran/namo
 licenses:
 - MIT
@@ -100,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.18
+rubygems_version: 4.0.19
 specification_version: 4
 summary: Named dimensional data for Ruby.
 test_files: []