namo 0.31.0 → 0.31.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1241332321c6f9d7643932d1b53949bfb12eb8596b1e388c206a9fad705efaf7
-  data.tar.gz: 00c558afd1fe979599820a39539f3216b496557a69f94229a59fc45c48cfd062
+  metadata.gz: 820a3c18db30a81cef333ad6b6bd95cd3129610d8d237a0a4f14554d23bdd2e9
+  data.tar.gz: 8b0c94985ae46c47e8b129eecd7fe7eba7d30f499aea917b2c9e80b1edf2ad7c
 SHA512:
-  metadata.gz: 74b61473e59179fcd559d52eb98435ab9127499c17403174c1505f5076d1c6d2dd1f829ea8a69403da948709d047d42603bb1fd6bc32205bfb1bb3b0459d47c8
-  data.tar.gz: c9690afd20a5ab0de834d9dcca3b2a310e4da3e4811b0a29545e60290f1cb62f7571e8c177bacd405b380e8bfe6f78358a075c9c2eb5a4519654843c90ddaf5a
+  metadata.gz: a5631205eb63c196e4ba9d6b8cf5bf54807e61a462e55645e216aeb5515d767934413c226a0cb567ae0637002e6c3a80a3490c6db7c94397ae17da2c42ae8c8f
+  data.tar.gz: 829d09221f044a4572ff7b97bc76c3a84cd7c8ce8e9e2ee8656b2ac5c82a3753d2f793223bdf3125a0e22d925bf86e19078680b78d6dcde7077248aef7488740

data/CHANGELOG

@@ -1,5 +1,24 @@
 # CHANGELOG
 
+## 20260824
+
+0.31.2: ~ Namo#inspect: the derived: suffix names only what the rows do not carry.
+
+1. ~ Namo#inspect: the derived: suffix names only the derived dimensions the rendered rows do not already carry, and is omitted where they all do. A formula which raises, a parameterised one which cannot be materialised without its arguments, and any formula on a Namo with no rows to render, are named as before, being nowhere else in the output. Namo::Collection renders no rows and so names every one of its own. Namo::Row is unchanged, naming its formulae in every case.
+2. ~ README.md: the Inspection output section, and the block whose suffix goes.
+3. ~ ROADMAP.md: + 0.31.2.
+4. ~ Namo::VERSION: /0.31.1/0.31.2/
+
+
+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,33 @@ 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 and the stored rows, with any derived dimensions among them:
 
 ```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}
-# ] derived: [:revenue]>
+#   {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}
+# ]>
 ```
 
 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, so a computed dimension renders exactly as a stored one does — which is the claim the library makes about it. Where there is no value to show, the rendering omits it rather than failing, and the `derived:` suffix names it: a formula which raises, a parameterised one which cannot be materialised without its arguments, and any formula at all on a Namo with no rows to render.
+
+The suffix carries only those. Where every derived dimension rendered a value it has nothing left to say and does not appear. Ask `derived_dimensions` when you want the distinction named.
+
+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 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.
 
 ```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.2'
 end

data/lib/namo.rb

@@ -250,7 +250,8 @@ class Namo
   end
 
   def inspect
-    "#<#{self.class}#{inspected_name}#{inspected_rows}#{inspected_derived}>"
+    rendered = @data.first(INSPECTED_ROWS).map{|row| [row, inspected_derivations(row)]}
+    "#<#{self.class}#{inspected_name}#{inspected_rows(rendered)}#{inspected_derived(rendered)}>"
   end
 
   protected
@@ -278,15 +279,35 @@ class Namo
   # The rows as they are stored, never the derived values: inspect is called
   # for every result in a console, and evaluating a formula there would cost a
   # pass over the data per access and raise whatever the formula raises.
-  def inspected_rows
+  def inspected_rows(rendered)
     return ' []' if @data.empty?
-    shown = @data.first(INSPECTED_ROWS).map{|row| "  #{row.inspect}"}.join(",\n")
+    shown = rendered.map{|row, derived| "  #{row.merge(derived).inspect}"}.join(",\n")
     shown += "\n  ... #{@data.length - INSPECTED_ROWS} more rows" if @data.length > INSPECTED_ROWS
     " [\n#{shown}\n]"
   end
 
-  def inspected_derived
-    derived_dimensions.empty? ? '' : " derived: #{derived_dimensions.inspect}"
+  # 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
+
+  # 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.
+  def inspected_derived(rendered = [])
+    unshown = derived_dimensions.reject do |dimension|
+      rendered.any? && rendered.all?{|_, derived| derived.key?(dimension)}
+    end
+    unshown.empty? ? '' : " derived: #{unshown.inspect}"
   end
 
   def initialize(positional_data = nil, data: [], formulae: {}, name: nil)

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,33 @@ 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]>"
+    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]>"
+    end
+
+    it "names a derived dimension on a Namo with no rows, there being nowhere else to learn of it" do
+      namo = Namo.new([])
+      namo[:b] = proc{|row| row[:a] + 1}
+      _(namo.inspect).must_equal "#<Namo [] derived: [:b]>"
+    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.2
 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: