namo 0.31.1 → 0.31.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e5235177577fcae1dd01a8a3172fc3933e77a5483f123ba6f436bd58a6eca68e
-  data.tar.gz: b2c023063fa95cca3f6ec38f324a116bf013339003d4051338a7c84b57251944
+  metadata.gz: 611590edfde52f5713b8fe41daf28b5986a26f4df3a5c28631dace995c31b98c
+  data.tar.gz: f098e612be772d3232598020963f6b3ed5c9a786f4827de25312e90aff23bc48
 SHA512:
-  metadata.gz: 3278fdcba0888a5899930abb399c3cc3b1aff49d7bb27ceefc223524c4247cb4c85ca0274ba58254965229e9cec131c014a544fce61444e8d6e34221896047e5
-  data.tar.gz: 94cdb60c0bc852b456ded744a63f8e7fda0dbf884d2ff085b0908cfb80d26f48588b4254b7d389cb68b4bce0f668d3a528ce5eeba22bd80ea4a50331c6ccb2e8
+  metadata.gz: a28b1d267f69eb14a9ee8d7a9cbdba9de57132be4577a39892e3f679e0ccee293a88a2d526ceda0ff6232317bdb8028ae3f04858160c7a38cbc4cb640c5fff16
+  data.tar.gz: e615d6be239ccd8a563922e3b51f5044a745733a4ef3f120b78ab5b07f84a4ff5be37373386853fb9d1484146471fc7034d58af9aee9172e4ae967e341ba0c39

data/CHANGELOG

@@ -2,6 +2,24 @@
 
 ## 20260824
 
+0.31.3: ~ Namo#to_a: derived dimensions are carried alongside the stored ones.
+
+1. ~ Namo#to_a: each row carries the derived dimensions which can be materialised without arguments, in among its stored keys, so to_a agrees with to_h and with dimensions about what the Namo holds. A formula wanting arguments is omitted, the rule values, coordinates and to_h already follow. Namo#data is unchanged and remains the stored rows; Namo::Row#to_h is unchanged, Row#==, Row#eql? and Namo#<< all reading through it.
+2. ~ README.md: the Extracting data section, and the parameterised-formula rule which now names to_a.
+3. ~ ROADMAP.md: + 0.31.3; the open question on which conversions materialise closes for to_a and stays open for Namo::Row.
+4. ~ Namo::VERSION: /0.31.2/0.31.3/
+
+Rebuilding a Namo from to_a now carries the derived dimensions in as stored data. Namo.new(other.to_a) followed by attaching the formulary which produced them raises, the 0.24.1 collision guard refusing the name twice over; []= accepts it, evicting the data. Where the stored rows are what is meant, data is the accessor for them. A formula whose inputs a projection has cut raises through to_a as it has always raised through to_h and values, which 0.16.0 settled as the caller's own choice.
+
+
+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.

data/README.md

@@ -717,7 +717,7 @@ prices.last[:sma]            # ArgumentError: wrong number of arguments for :sma
 prices.last[:close, 20]      # ArgumentError: wrong number of arguments for :close (given 1, expected 0)
 ```
 
-A formula that requires arguments can't be materialised without them. `values(:sma)`, `coordinates(:sma)`, naming `:sma` in a projection, and selecting on it all raise the same `ArgumentError`; the no-argument `values`, `coordinates`, and `to_h` omit the dimension, returning everything that can be materialised. `dimensions` and `derived_dimensions` still list it — it is queryable, with arguments. To materialise particular values, bind the arguments in a one-arity wrapper and ask for that:
+A formula that requires arguments can't be materialised without them. `values(:sma)`, `coordinates(:sma)`, naming `:sma` in a projection, and selecting on it all raise the same `ArgumentError`; the no-argument `values`, `coordinates`, `to_h` and `to_a` omit the dimension, returning everything that can be materialised. `dimensions` and `derived_dimensions` still list it — it is queryable, with arguments. To materialise particular values, bind the arguments in a one-arity wrapper and ask for that:
 
 ```ruby
 prices[:sma_close_20] = proc{|row| row[:sma, :close, 20]}
@@ -947,7 +947,7 @@ The transforming and reducing methods are deliberately left as Enumerable's defa
 
 ### Extracting data
 
-`to_a` returns an array of hashes — the row-oriented form:
+`to_a` returns an array of hashes — the row-oriented form, carrying derived dimensions alongside the stored ones, so it agrees with `to_h` and with `dimensions` about what the Namo holds:
 
 ```ruby
 sales[:product, :quarter, :revenue].to_a
@@ -959,6 +959,8 @@ sales[:product, :quarter, :revenue].to_a
 # ]
 ```
 
+`data` is the stored rows, without derived dimensions and without copying — it is the accessor for what the Namo was built from, where `to_a` is the conversion of what it can answer. A formula whose inputs a projection has cut raises through `to_a` as it does through `to_h` and `values`, which is [the caller's own choice](#projection-of-derived-dimensions) rather than a failure of the conversion.
+
 `to_h` returns a hash of arrays — the columnar form (see [Coordinates and values](#coordinates-and-values) above):
 
 ```ruby
@@ -972,7 +974,7 @@ sales[:product, :quarter, :revenue].to_h
 
 ### Inspection output
 
-`inspect` renders the class, the stored rows with any derived dimensions among them, and the names of those derived dimensions:
+`inspect` renders the class and the stored rows, with any derived dimensions among them:
 
 ```ruby
 sales.inspect
@@ -981,18 +983,20 @@ sales.inspect
 #   {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`.
 
-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.
+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, 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.
+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

data/lib/Namo/VERSION.rb

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

data/lib/namo.rb

@@ -241,16 +241,23 @@ class Namo
     other.subset_of_rows?(self)
   end
 
+  # Each row's own keys, in their own order, and then the derived dimensions which
+  # can be materialised without arguments — the rule values, coordinates and to_h
+  # already follow.  data is the stored rows, and stays so.
   def to_a
-    @data.map do |row|
-      row.keys.each_with_object({}) do |key, hash|
-        hash[key] = row[key]
+    materialising do
+      derived = materialisable_dimensions - data_dimensions
+      @data.map do |row|
+        subject = Row.new(row, @formulae, self)
+        stored = row.keys.each_with_object({}){|key, hash| hash[key] = row[key]}
+        derived.each_with_object(stored){|dimension, hash| hash[dimension] = subject[dimension]}
       end
     end
   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,17 +285,13 @@ 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| "  #{inspected_row(row)}"}.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_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.
@@ -302,8 +305,15 @@ class Namo
     end
   end
 
-  def inspected_derived
-    derived_dimensions.empty? ? '' : " derived: #{derived_dimensions.inspect}"
+  # 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/console_test.rb

@@ -33,7 +33,7 @@ describe 'script/console' do
 
   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/)
+    _(console('readings.data == ' + expected.inspect)).must_match(/true/)
   end
 
   it "starts without echoing its own source" do

data/test/namo_test.rb

@@ -488,8 +488,8 @@ describe Namo do
         sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
         result = sales[revenue: ->(v){v >= 1500.0}]
         _(result.to_a).must_equal [
-          {product: 'Widget', quarter: 'Q2', price: 10.0, quantity: 150},
-          {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60}
+          {product: 'Widget', quarter: 'Q2', price: 10.0, quantity: 150, revenue: 1500.0},
+          {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60, revenue: 1500.0}
         ]
       end
     end
@@ -571,8 +571,8 @@ describe Namo do
         sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
         result = sales[revenue: 1200.0..]
         _(result.to_a).must_equal [
-          {product: 'Widget', quarter: 'Q2', price: 10.0, quantity: 150},
-          {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60}
+          {product: 'Widget', quarter: 'Q2', price: 10.0, quantity: 150, revenue: 1500.0},
+          {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60, revenue: 1500.0}
         ]
       end
     end
@@ -602,7 +602,7 @@ describe Namo do
       sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
       sales[:cost] = proc{|r| r[:quantity] * 4.0}
       sales[:profit] = proc{|r| r[:revenue] - r[:cost]}
-      _(sales[:product, :quarter, :profit].to_a).must_equal [
+      _(sales[:product, :quarter, :profit].data).must_equal [
         {product: "Widget", quarter: "Q1", profit: 600.0},
         {product: "Widget", quarter: "Q2", profit: 900.0},
         {product: "Gadget", quarter: "Q1", profit: 840.0},
@@ -1657,8 +1657,8 @@ describe Namo do
       sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
       result = sales.select{|row| row[:revenue] >= 1500.0}
       _(result.to_a).must_equal [
-        {product: 'Widget', quarter: 'Q2', price: 10.0, quantity: 150},
-        {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60}
+        {product: 'Widget', quarter: 'Q2', price: 10.0, quantity: 150, revenue: 1500.0},
+        {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60, revenue: 1500.0}
       ]
     end
 
@@ -2458,7 +2458,7 @@ describe Namo do
         dated[:cutoff] = proc{|r| r[:date]}
         result = dated.*(quarterly){|row, candidates| candidates[quarter_end: ->(qe){qe <= row[:cutoff]}].sort_by{|f| f[:quarter_end]}.last(1)}
         _(result.to_a).must_equal [
-          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2}
+          {symbol: 'BHP', date: '2025-05-20', close: 44.0, quarter_end: '2025-03-31', eps: 1.2, cutoff: '2025-05-20'}
         ]
       end
 
@@ -2638,8 +2638,8 @@ describe Namo do
         weighted_tiers[:premium] = proc{|t| t[:max_weight] > 15}
         result = orders.**(weighted_tiers){|row, candidates| candidates[premium: ->(v){v}]}
         _(result.to_a).must_equal [
-          {order: 'A', weight: 5, tier: 'heavy', max_weight: 20},
-          {order: 'B', weight: 15, tier: 'heavy', max_weight: 20}
+          {order: 'A', weight: 5, tier: 'heavy', max_weight: 20, premium: true},
+          {order: 'B', weight: 15, tier: 'heavy', max_weight: 20, premium: true}
         ]
       end
 
@@ -3067,6 +3067,41 @@ describe Namo do
     it "returns the data as an array of hashes" do
       _(sales.to_a).must_equal sample_data
     end
+
+    it "carries a derived dimension alongside the stored ones" do
+      sales[:revenue] = proc{|row| row[:price] * row[:quantity]}
+      _(sales.to_a.first).must_equal(
+        {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100, revenue: 1000.0})
+    end
+
+    it "agrees with to_h about which dimensions there are" do
+      sales[:revenue] = proc{|row| row[:price] * row[:quantity]}
+      _(sales.to_a.first.keys).must_equal sales.to_h.keys
+      _(sales.to_a.first.keys).must_equal sales.dimensions
+    end
+
+    it "omits a formula which cannot be materialised without its arguments" do
+      sales[:revenue] = proc{|row| row[:price] * row[:quantity]}
+      sales[:scaled] = proc{|row, namo, factor| row[:price] * factor}
+      _(sales.to_a.first.keys).wont_include :scaled
+      _(sales.to_a.first.keys).must_include :revenue
+      _(sales.derived_dimensions).must_include :scaled
+    end
+
+    it "raises where a carried formula's inputs were projected away, as 0.16.0 settled" do
+      sales[:revenue] = proc{|row| row[:price] * row[:quantity]}
+      _(->{sales[:product, :quarter].to_a}).must_raise NoMethodError
+    end
+
+    it "leaves data as the stored rows" do
+      sales[:revenue] = proc{|row| row[:price] * row[:quantity]}
+      _(sales.data).must_equal sample_data
+      _(sales.data.first.keys).wont_include :revenue
+    end
+
+    it "returns fresh rows rather than the stored ones" do
+      _(sales.to_a.first).wont_be_same_as sales.data.first
+    end
   end
 
   describe "#group_by" do
@@ -3234,13 +3269,19 @@ describe Namo do
     it "shows a derived dimension with its value, in among the stored ones" do
       namo = Namo.new([{a: 1}])
       namo[:b] = proc{|row| row[:a] + 1}
-      _(namo.inspect).must_equal "#<Namo [\n  {a: 1, b: 2}\n] derived: [:b]>"
+      _(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] derived: [:total]>"
+      _(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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.31.1
+  version: 0.31.3
 platform: ruby
 authors:
 - thoran