namo 0.31.3 → 0.31.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 611590edfde52f5713b8fe41daf28b5986a26f4df3a5c28631dace995c31b98c
-  data.tar.gz: f098e612be772d3232598020963f6b3ed5c9a786f4827de25312e90aff23bc48
+  metadata.gz: 3a5b005cb03bb42a9a9319632833f382a8ae2480ce04160f326a831f534da50a
+  data.tar.gz: f344e285a0d457af4ad633c98a33aab02cefe49fd273251ad9bdc7bdd3d98afa
 SHA512:
-  metadata.gz: a28b1d267f69eb14a9ee8d7a9cbdba9de57132be4577a39892e3f679e0ccee293a88a2d526ceda0ff6232317bdb8028ae3f04858160c7a38cbc4cb640c5fff16
-  data.tar.gz: e615d6be239ccd8a563922e3b51f5044a745733a4ef3f120b78ab5b07f84a4ff5be37373386853fb9d1484146471fc7034d58af9aee9172e4ae967e341ba0c39
+  metadata.gz: 8025bdb29748fc3076649dc59a38139075c03a9692c5c684295cb5060334e8e8c0c45dea9001dd942d68d0e3302910464c9141157a42d61af85eb751420bf0d8
+  data.tar.gz: 8fc50fc83aab71b68cb6e70dc4178e95dc8e2f3e6983480ccbcc4553915b61dde52f00cf8d2f1570988d5129df7e0534b13db8b3dc7413602d1fefc64b694613

data/CHANGELOG

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## 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
@@ -1204,7 +1217,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,20 +25,23 @@ 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
+      rows = (
+        @members.flat_map do |member|
+          member.data.map{|row| row.key?(by) ? row : row.merge(by => member.name)}
+        end
+      )
       Namo.new(rows)
     end
 
@@ -53,12 +56,46 @@ class Namo
       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
 
+    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.4'
 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

@@ -348,14 +348,104 @@ describe Namo::Collection do
   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.4
 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: []