namo 0.31.0 → 0.31.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1241332321c6f9d7643932d1b53949bfb12eb8596b1e388c206a9fad705efaf7
-  data.tar.gz: 00c558afd1fe979599820a39539f3216b496557a69f94229a59fc45c48cfd062
+  metadata.gz: e5235177577fcae1dd01a8a3172fc3933e77a5483f123ba6f436bd58a6eca68e
+  data.tar.gz: b2c023063fa95cca3f6ec38f324a116bf013339003d4051338a7c84b57251944
 SHA512:
-  metadata.gz: 74b61473e59179fcd559d52eb98435ab9127499c17403174c1505f5076d1c6d2dd1f829ea8a69403da948709d047d42603bb1fd6bc32205bfb1bb3b0459d47c8
-  data.tar.gz: c9690afd20a5ab0de834d9dcca3b2a310e4da3e4811b0a29545e60290f1cb62f7571e8c177bacd405b380e8bfe6f78358a075c9c2eb5a4519654843c90ddaf5a
+  metadata.gz: 3278fdcba0888a5899930abb399c3cc3b1aff49d7bb27ceefc223524c4247cb4c85ca0274ba58254965229e9cec131c014a544fce61444e8d6e34221896047e5
+  data.tar.gz: 94cdb60c0bc852b456ded744a63f8e7fda0dbf884d2ff085b0908cfb80d26f48588b4254b7d389cb68b4bce0f668d3a528ce5eeba22bd80ea4a50331c6ccb2e8

data/CHANGELOG

@@ -1,5 +1,16 @@
 # CHANGELOG
 
+## 20260824
+
+0.31.1: ~ Namo#inspect, Namo::Row#inspect: derived dimensions render their values.
+
+1. ~ Namo#inspect: a derived dimension renders with its value, in among the stored ones, rather than being named only. Where there is no value to show it is omitted and the derived: suffix names it alone: a formula which raises, and a parameterised one which cannot be materialised without its arguments.
+2. ~ Namo::Row#inspect: the same.
+3. ~ README.md: the Inspection output section rewritten, and the two blocks whose rendering changes.
+4. ~ ROADMAP.md: + 0.31.1.
+5. ~ Namo::VERSION: /0.31.0/0.31.1/
+
+
 ## 20260822
 
 0.31.0: + Namo#inspect, Namo::Collection#inspect, Namo::Row#inspect, and Namo::Formulae#inspect.

data/README.md

@@ -972,29 +972,31 @@ sales[:product, :quarter, :revenue].to_h
 
 ### Inspection output
 
-`inspect` renders the class, the stored rows, and the names of any derived dimensions:
+`inspect` renders the class, the stored rows with any derived dimensions among them, and the names of those derived dimensions:
 
 ```ruby
 sales.inspect
 # => #<Namo [
-#   {product: "Widget", quarter: "Q1", price: 10.0, quantity: 100},
-#   {product: "Widget", quarter: "Q2", price: 10.0, quantity: 150},
-#   {product: "Gadget", quarter: "Q1", price: 25.0, quantity: 40},
-#   {product: "Gadget", quarter: "Q2", price: 25.0, quantity: 60}
+#   {product: "Widget", quarter: "Q1", price: 10.0, quantity: 100, revenue: 1000.0},
+#   {product: "Widget", quarter: "Q2", price: 10.0, quantity: 150, revenue: 1500.0},
+#   {product: "Gadget", quarter: "Q1", price: 25.0, quantity: 40, revenue: 1000.0},
+#   {product: "Gadget", quarter: "Q2", price: 25.0, quantity: 60, revenue: 1500.0}
 # ] derived: [:revenue]>
 ```
 
 A name, where the Namo carries one, follows the class: `#<Namo :sales [`. A subclass reports its own name in place of `Namo`.
 
-Derived dimensions are *named*, not evaluated. A console calls `inspect` on every result, so evaluating there would cost a pass over the data on each one, would raise whatever a formula raises, and could not render a parameterised formula at all. Ask through `values`, `coordinates`, or a projection when you want the values.
+A derived dimension shows its value, in among the stored ones, and the `derived:` suffix names which of the keys are computed. Where there is no value to show it is omitted rather than the rendering failing: a formula which raises, and a parameterised one which cannot be materialised without its arguments, each render nothing and are named by the suffix alone.
+
+Evaluation is bounded by the row cap rather than by the data — at most ten rows are rendered, so at most ten evaluations per formula. A collection-scoped formula makes each of those a pass over the Namo, so inspecting a large one that carries such a formula is not free.
 
 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 and its formula names, 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, 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.
 
 ```ruby
 sales.first
-# => #<Namo::Row {product: "Widget", quarter: "Q1", price: 10.0, quantity: 100} derived: [:revenue]>
+# => #<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>

data/lib/Namo/Row.rb

@@ -44,11 +44,26 @@ class Namo
     end
 
     def inspect
-      "#<#{self.class} #{@row.inspect}#{inspected_derived}>"
+      "#<#{self.class} #{inspected_row}#{inspected_derived}>"
     end
 
     private
 
+    def inspected_row
+      @row.merge(inspected_derivations).inspect
+    end
+
+    # As Namo#inspected_derivations: the value where there is one to show, and
+    # the derived list to name it either way.
+    def inspected_derivations
+      @formulae.keys.each_with_object({}) do |dimension, derived|
+        next if @formulae.required_parameter_count(dimension) > 2
+        derived[dimension] = self[dimension]
+      rescue StandardError
+        next
+      end
+    end
+
     def inspected_derived
       @formulae.keys.empty? ? '' : " derived: #{@formulae.keys.inspect}"
     end

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.31.0'
+  VERSION = '0.31.1'
 end

data/lib/namo.rb

@@ -280,11 +280,28 @@ class Namo
   # pass over the data per access and raise whatever the formula raises.
   def inspected_rows
     return ' []' if @data.empty?
-    shown = @data.first(INSPECTED_ROWS).map{|row| "  #{row.inspect}"}.join(",\n")
+    shown = @data.first(INSPECTED_ROWS).map{|row| "  #{inspected_row(row)}"}.join(",\n")
     shown += "\n  ... #{@data.length - INSPECTED_ROWS} more rows" if @data.length > INSPECTED_ROWS
     " [\n#{shown}\n]"
   end
 
+  def inspected_row(row)
+    row.merge(inspected_derivations(row)).inspect
+  end
+
+  # A derived dimension is shown with its value, in among the stored ones.  A
+  # formula wanting arguments has no value to show without them, and one which
+  # raises has none to show either; the derived list still names both.
+  def inspected_derivations(row)
+    subject = Row.new(row, @formulae, self)
+    derived_dimensions.each_with_object({}) do |dimension, derived|
+      next if @formulae.required_parameter_count(dimension) > 2
+      derived[dimension] = subject[dimension]
+    rescue StandardError
+      next
+    end
+  end
+
   def inspected_derived
     derived_dimensions.empty? ? '' : " derived: #{derived_dimensions.inspect}"
   end

data/test/Namo/Row_test.rb

@@ -465,9 +465,15 @@ describe Namo::Row do
       _(Namo::Row.new({a: 1}, Namo::Formulae.new).inspect).must_equal "#<Namo::Row {a: 1}>"
     end
 
-    it "names derived dimensions without evaluating them" do
+    it "shows a derived dimension with its value, in among the stored ones" do
       formulae = Namo::Formulae.new
-      formulae[:b] = proc{|row| raise 'never called'}
+      formulae[:b] = proc{|row| row[:a] + 1}
+      _(Namo::Row.new({a: 1}, formulae).inspect).must_equal "#<Namo::Row {a: 1, b: 2} derived: [:b]>"
+    end
+
+    it "names a derived dimension whose formula raises, without a value" do
+      formulae = Namo::Formulae.new
+      formulae[:b] = proc{|row| raise 'no value to show'}
       _(Namo::Row.new({a: 1}, formulae).inspect).must_equal "#<Namo::Row {a: 1} derived: [:b]>"
     end
 

data/test/console_test.rb

@@ -0,0 +1,42 @@
+# test/console_test.rb
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+require_relative '../lib/namo'
+require_relative '../script/fixtures'
+
+# script/console exists so that a question asked at a prompt is asked of the same
+# data the demo put on the screen.  That is only true while both read
+# script/fixtures.rb, so what is worth asserting is the agreement rather than the
+# session: the names it defines, and that they hold what the fixtures say.
+
+describe 'script/console' do
+  def console(*expressions)
+    root = File.expand_path('..', __dir__)
+    IO.popen([File.join(root, 'script', 'console'), '--prompt', 'simple'],
+      'r+', chdir: root, err: [:child, :out]) do |io|
+      io.puts(expressions, 'exit')
+      io.close_write
+      io.read
+    end
+  end
+
+  it "defines the names it says it does" do
+    output = console('[readings, stations, months].map{|n| n.class}.inspect')
+    _(output).must_match(/\[Namo, Namo, Namo\]/)
+  end
+
+  it "gives sales the revenue formula" do
+    _(console('readings.derived_dimensions.inspect')).must_match(/\[:anomaly\]/)
+  end
+
+  it "holds what the fixtures hold, so it cannot drift from the demo" do
+    expected = eval(Fixtures.readings)
+    _(console('readings.to_a == ' + expected.inspect)).must_match(/true/)
+  end
+
+  it "starts without echoing its own source" do
+    _(console('1')).wont_match(/binding\.irb/)
+  end
+end

data/test/demo_test.rb

@@ -0,0 +1,88 @@
+# test/demo_test.rb
+
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+require_relative '../lib/namo'
+
+# script/demo is 300-odd lines exercising selection, projection, formulae,
+# group_by, summary, the operators and inspect, and nothing else runs it.  These
+# assert only that each section completes, which is the difference between a
+# demonstration which rots quietly and one which fails the suite when the library
+# moves under it.
+#
+# A process apiece, since the script is a program rather than a library and its
+# sections share a binding within a run.
+
+describe 'script/demo' do
+  def demo(*sections)
+    root = File.expand_path('..', __dir__)
+    IO.popen([File.join(root, 'script', 'demo'), *sections],
+      chdir: root, err: [:child, :out]){|io| io.read}
+  end
+
+  def sections
+    @sections ||= demo('--help').scan(/^  [* ] ([a-z_]+)$/).flatten
+  end
+
+  def cut
+    @cut ||= demo('--help').scan(/^  \* ([a-z_]+)$/).flatten
+  end
+
+  it "lists its sections" do
+    _(sections).wont_be_empty
+    _(sections).must_include 'ingestion'
+  end
+
+  it "runs every section without raising" do
+    failed = sections.reject do |section|
+      demo(section)
+      $?.success?
+    end
+    _(failed).must_be_empty
+  end
+
+  it "has a talk cut, and it is a subset of the sections" do
+    _(cut).wont_be_empty
+    _(cut - sections).must_be_empty
+  end
+
+  it "runs the talk cut" do
+    demo('talk')
+    _($?.success?).must_equal true
+  end
+
+  # The padding is what holds a section title in one place on the screen, and it
+  # can only pad down to the constants.  A section grown past them would silently
+  # start pushing the next one about.  Rows rather than lines, since a line wider
+  # than the window costs more than one of them.
+  #
+  # The cut rather than every section: those are the ones which have to fit on the
+  # day, and the rest are reference, free to run long and be scrolled.
+  it "has no section in the talk cut taller than the slide height" do
+    source = File.read(File.join(File.expand_path('..', __dir__), 'script', 'demo'))
+    height, width = %w[SLIDE_HEIGHT SLIDE_WIDTH].map{|name| source[/^#{name} = (\d+)$/, 1].to_i}
+    _([height, width].min).must_be :>, 0
+    overlong = cut.select do |section|
+      demo(section).lines.sum{|line| [(line.chomp.size / width.to_f).ceil, 1].max} > height
+    end
+    _(overlong).must_be_empty
+  end
+
+  it "runs the whole script" do
+    demo
+    _($?.success?).must_equal true
+  end
+
+  it "refuses a section it does not have" do
+    demo('nonexistent')
+    _($?.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', 'demo'), 'ingestion'],
+      chdir: root, err: [:child, :out]){|io| io.read}
+    _(output).wont_match(/LoadError/)
+  end
+end

data/test/namo_test.rb

@@ -3231,9 +3231,27 @@ describe Namo do
       _(Namo.new([]).inspect).must_equal "#<Namo []>"
     end
 
-    it "names derived dimensions without evaluating them" do
+    it "shows a derived dimension with its value, in among the stored ones" do
       namo = Namo.new([{a: 1}])
-      namo[:b] = proc{|row| raise 'never called'}
+      namo[:b] = proc{|row| row[:a] + 1}
+      _(namo.inspect).must_equal "#<Namo [\n  {a: 1, b: 2}\n] derived: [:b]>"
+    end
+
+    it "shows a collection-scoped derived value" do
+      namo = Namo.new([{a: 1}, {a: 2}])
+      namo[:total] = proc{|row, namo| namo.values(:a).sum}
+      _(namo.inspect).must_equal "#<Namo [\n  {a: 1, total: 3},\n  {a: 2, total: 3}\n] derived: [:total]>"
+    end
+
+    it "names a derived dimension whose formula raises, without a value" do
+      namo = Namo.new([{a: 1}])
+      namo[:b] = proc{|row| raise 'no value to show'}
+      _(namo.inspect).must_equal "#<Namo [\n  {a: 1}\n] derived: [:b]>"
+    end
+
+    it "names a derived dimension whose formula wants arguments, without a value" do
+      namo = Namo.new([{a: 1}])
+      namo[:b] = proc{|row, namo, factor| row[:a] * factor}
       _(namo.inspect).must_equal "#<Namo [\n  {a: 1}\n] derived: [:b]>"
     end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.31.1
 platform: ruby
 authors:
 - thoran
@@ -79,6 +79,8 @@ files:
 - test/Namo/NegatedDimension_test.rb
 - test/Namo/Row_test.rb
 - test/Symbol_test.rb
+- test/console_test.rb
+- test/demo_test.rb
 - test/namo_test.rb
 homepage: https://github.com/thoran/namo
 licenses: