namo 0.11.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad4994109308fd955b2f508afe1f07251bc4287406ed7f27eb8a484a61dfabcf
-  data.tar.gz: 04be0a1d0e8f97b86932a3e5e8953bfe3b0e51fe16bcb80b5dec9a5a73aecd36
+  metadata.gz: ed83092f20799b8589b970ffa06ba8d9c976dc25e4545670e72e600895273548
+  data.tar.gz: ad2b6d939418fe8c0197fdc415a0f884179b374009a3397480b9e25e1814b993
 SHA512:
-  metadata.gz: 507a77ecfc3d23fe1ad4ef14783b2e4f86ff44b58431cb93b8e4aa41c12bf4778f03c7a3bdca7f8958620b3d2e3bba3292cdfbcd5636c8286661aed100398b30
-  data.tar.gz: fa6acfcf416108a871e0697ae998cef8701263446abee9089c62e1cfb24c102d22f002e643f89890a7c40ad2ccedca3dd7d58ebf04125fb4a87d17f58a908abd
+  metadata.gz: 791f6bd3afa3589546df37e9c6fb7b016de75a6c368202554b53cbc55b92e23c7e9821837ce2057ac8ea40b7f13ef42ec493bfcd061667fa3d293a217608996b
+  data.tar.gz: ec205a0df5900931bdf2df644522cffdbd7ef53d6d665fc8fa0ca3b18e79fc5e97971e0c089ea7254e446124866db91d43eed91dda9b0230b5a6f8d6abb9ada3

data/CHANGELOG

@@ -1,6 +1,25 @@
 CHANGELOG
 _________
 
+20260601
+0.13.0: Polymorphic []= — proc registers a formula, scalar broadcasts to every row.
+
+1. ~ lib/namo.rb: Namo#[]= now dispatches on value type. Parameter renamed `proc` -> `value`. A Proc registers a formula and clears any data column of the same name (`@data.each{|row| row.delete(name)} if @data.first&.key?(name)`); anything else broadcasts the value to every row and clears any formula of the same name (`@formulae.delete(name)`). Enforces the exclusive-storage invariant — a name is data or derived, never both — at the assignment site. Existing proc-registration behaviour preserved.
+2. ~ test/namo_test.rb: + "#[]= polymorphic dispatch" describe — proc registration (regression), data-column clear on proc assign, scalar broadcast, formula clear on scalar assign, array-broadcasts-as-value, both last-write-wins orderings, derived/data surfacing exactly once in `dimensions`, the no-data-column clear-guard short-circuit, and the empty-Namo case. Existing "#[]= formulae" describe unchanged.
+3. ~ README.md: + Polymorphic []= section (two branches, exclusivity rule, last-write-wins, symmetry with []), with the scalar-broadcast-vs-formula contrast and a note tying exclusivity to data_dimensions/derived_dimensions.
+4. ~ ROADMAP.md: Promote 0.13.0 from upcoming to shipped — `## Current state` bumped to 0.13.0, a `### 0.13.0 (2026-06-01)` entry added in the shipped section, the now-redundant `## 0.13.0` upcoming section removed, polymorphic []= folded into the Summary's completed vocabulary, "next phase" pointed at 0.14.0+.
+5. ~ Namo::VERSION: /0.12.0/0.13.0/
+
+20260601
+0.12.0: Constructor widening — keyword data: and name:.
+
+1. ~ lib/namo.rb: Namo#initialize widened from `(data = [], formulae: {})` to `(positional_data = nil, data: [], formulae: {}, name: nil)`. Data may now be passed positionally or by the `data:` keyword; positional wins when both are given (`@data = positional_data || data`). The positional default changes from `[]` to `nil` so it acts as a "not supplied" sentinel that lets `|| data` fall through to the keyword path; an explicit `Namo.new([])` still yields `@data == []` because the truthy empty array short-circuits. + `name:` keyword, stored in `@name`. Every pre-existing call site (positional data, positional data + keyword formulae, no-arg, formulae-only, and the operators' internal `self.class.new(rows, formulae: ...)`) is unaffected.
+2. + lib/namo.rb: `attr_accessor :name`, alongside the existing `:data` and `:formulae` accessors. Gives `name` reading and `name=` post-construction mutation. Operator results carry `name == nil` (the operators construct without `name:`), establishing the subclass guard convention: subclasses guard `initialize` side effects with `return unless name`, so operator-derived instances skip them and only explicitly-named constructions fire them.
+3. ~ test/namo_test.rb: + "construction" describe (positional data, positional + keyword formulae, no-arg empty, formulae-only, explicit `[]` honoured over the nil sentinel, keyword `data:`, positional-wins-over-keyword, and round-trips through a set operator and an Enumerable method). + "#name" describe (stored from keyword, defaults to nil, settable post-construction, nil on set-operator and Enumerable-derived results). + "subclass side-effect guard" describe — an anonymous Class.new(Namo) with a `return unless name`-guarded counter, asserting it fires for a named construction and stays untouched for an unnamed construction and an operator result.
+4. ~ README.md: + note in the Usage section that data may be passed positionally or by `data:`, with positional winning when both are given. + "Named Namos" section: the `name:` keyword, the `name`/`name=` accessor, nil-on-derivation for operator results, and the subclass guard convention with the TradingAnalysis / argument-less `super` example.
+5. ~ ROADMAP.md: Promote 0.12.0 from upcoming to shipped — `## Current state` bumped to 0.12.0, a `### 0.12.0 (2026-06-01)` entry added in the shipped section (written in shipped voice), and the now-redundant `## 0.12.0` upcoming section removed; fold the widened constructor into the Summary's completed vocabulary and point "next phase" at 0.13.0+.
+6. ~ Namo::VERSION: /0.11.1/0.12.0/
+
 20260601
 0.11.1: Extract the subset Enumerable methods into a Namo::Enumerable module.
 

data/README.md

@@ -33,6 +33,16 @@ sales = Namo.new([
 ])
 ```
 
+Data may be passed positionally, as above, or by the `data:` keyword where that reads more explicitly:
+
+```ruby
+sales = Namo.new(data: [
+  {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100}
+])
+```
+
+When both are given, the positional argument wins and the keyword `data:` is ignored.
+
 Dimensions and coordinates are inferred:
 
 ```ruby
@@ -575,6 +585,42 @@ sales[product: 'Widget'][:revenue, :quarter]
 
 Formulae carry through selection — a filtered Namo instance remembers its formulae.
 
+### Polymorphic `[]=`
+
+`[]=` dispatches on the type of the value assigned. A proc registers a formula, as above. Anything else broadcasts the value to every row:
+
+```ruby
+sales[:status] = 'active'
+sales.values(:status)
+# => ['active', 'active', 'active', 'active']
+
+sales[:revenue] = proc{|row| row[:price] * row[:quantity]}
+sales.values(:revenue)
+# => [1000.0, 1500.0, 1000.0, 1500.0]
+```
+
+The two branches mirror the polymorphism `[]` already has on the selection side, where a single bracket call dispatches over exact values, arrays, ranges, procs, and regexes. Rather than introduce a separate `broadcast` or `set_all` method for the scalar case, `[]=` reads the same way for both: `sales[:status] = 'active'` says "set status to active across this Namo," and `sales[:revenue] = proc{…}` says "derive revenue from each row."
+
+The two branches enforce **exclusive storage**: a name is either a data dimension or a derived dimension, never both. Assigning a proc clears any data column of that name; assigning anything else clears any formula of that name. The last write wins, and there is no shadowing:
+
+```ruby
+sales[:x] = 5                       # :x is a broadcast data value
+sales[:x] = proc{|row| row[:price]} # :x is now a formula — the broadcast value is gone
+
+sales[:x] = proc{|row| row[:price]} # :x is a formula
+sales[:x] = 5                       # :x is now a broadcast data value — the formula is gone
+```
+
+Exclusivity ties directly to the inspection vocabulary: a name assigned a scalar shows up in `data_dimensions`; a name assigned a proc shows up in `derived_dimensions`; never in both, so it appears in `dimensions` exactly once.
+
+Only a `Proc` takes the formula branch. An array is a value like any other, so it broadcasts as the per-row value rather than registering as a formula:
+
+```ruby
+sales[:weights] = [1, 2, 3]
+sales.values(:weights)
+# => [[1, 2, 3], [1, 2, 3], [1, 2, 3], [1, 2, 3]]
+```
+
 ### Coordinates and values
 
 `dimensions` covers the *queryable namespace* — every name you can ask for, whether it lives in the row data or is computed by a formula. Once formulae are defined, they appear alongside data dimensions:
@@ -715,6 +761,39 @@ sales[:product, :quarter, :revenue].to_h
 # }
 ```
 
+### Named Namos
+
+A Namo can carry a name, passed by the `name:` keyword and read or set through the `name` accessor:
+
+```ruby
+sales = Namo.new(data: rows, name: :sales)
+sales.name
+# => :sales
+
+sales.name = :renamed
+```
+
+A name defaults to `nil`, and operator results are name-less by design — the result of `+`, `*`, `select`, and the rest is a derived object, not the original, so giving it the parent's name would mislead:
+
+```ruby
+(sales + more).name
+# => nil
+```
+
+This `nil`-on-derivation behaviour is what lets subclasses with side effects in `initialize` guard those effects on the name. Operator-derived instances are name-less and skip the side effects; explicitly constructed instances pass `name:` and the side effects fire:
+
+```ruby
+class TradingAnalysis < Namo
+  def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
+    super
+    return unless name
+    register_indicators
+  end
+end
+```
+
+`super` with no parentheses forwards every argument — positional and keyword — to `Namo#initialize` unchanged. The `return unless name` guard means a subclass need not override every operator to stop the result of `*` or `select` from re-running its construction side effects: it guards on `name` instead.
+
 ## Why?
 
 Every other multi-dimensional array library requires you to pre-shape your data before you can work with it. Namo takes it in the form it likely already comes in.

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.11.1'
+  VERSION = '0.13.0'
 end

data/lib/namo.rb

@@ -12,6 +12,7 @@ class Namo
 
   attr_accessor :data
   attr_accessor :formulae
+  attr_accessor :name
 
   def dimensions
     data_dimensions + derived_dimensions
@@ -73,8 +74,15 @@ class Namo
     self.class.new(projected, formulae: @formulae.dup)
   end
 
-  def []=(name, proc)
-    @formulae[name] = proc
+  def []=(name, value)
+    case value
+    when Proc
+      @data.each{|row| row.delete(name)} if @data.first&.key?(name)
+      @formulae[name] = value
+    else
+      @formulae.delete(name)
+      @data.each{|row| row[name] = value}
+    end
   end
 
   def +(other)
@@ -246,8 +254,9 @@ class Namo
     end
   end
 
-  def initialize(data = [], formulae: {})
-    @data = data
+  def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
+    @data = positional_data || data
     @formulae = formulae
+    @name = name
   end
 end

data/test/namo_test.rb

@@ -33,6 +33,113 @@ describe Namo do
     end
   end
 
+  describe "construction" do
+    it "accepts positional data" do
+      _(Namo.new([{x: 1}]).data).must_equal [{x: 1}]
+    end
+
+    it "accepts positional data with keyword formulae" do
+      namo = Namo.new([{x: 1}], formulae: {y: proc{|r| r[:x] * 2}})
+      _(namo.data).must_equal [{x: 1}]
+      _(namo.values(:y)).must_equal [2]
+    end
+
+    it "produces an empty Namo with no arguments" do
+      namo = Namo.new
+      _(namo.data).must_equal []
+      _(namo.formulae).must_equal({})
+    end
+
+    it "accepts keyword formulae with no data" do
+      namo = Namo.new(formulae: {y: proc{|r| r[:x] * 2}})
+      _(namo.data).must_equal []
+      _(namo.derived_dimensions).must_equal [:y]
+    end
+
+    it "honours an explicit empty positional array over the nil sentinel" do
+      _(Namo.new([]).data).must_equal []
+    end
+
+    it "accepts data by keyword" do
+      _(Namo.new(data: [{x: 1}]).data).must_equal [{x: 1}]
+    end
+
+    it "lets positional data win when both positional and keyword data are given" do
+      _(Namo.new([{x: 1}], data: [{x: 2}]).data).must_equal [{x: 1}]
+    end
+
+    it "survives a round-trip through a set operator" do
+      a = Namo.new([{x: 1}])
+      b = Namo.new([{x: 2}])
+      _((a + b).data).must_equal [{x: 1}, {x: 2}]
+    end
+
+    it "survives a round-trip through an Enumerable method" do
+      namo = Namo.new([{x: 1}, {x: 2}])
+      _(namo.select{|row| row[:x] > 1}.data).must_equal [{x: 2}]
+    end
+  end
+
+  describe "#name" do
+    it "stores a name passed by keyword" do
+      _(Namo.new([{x: 1}], name: :foo).name).must_equal :foo
+    end
+
+    it "defaults to nil when no name is passed" do
+      _(Namo.new([{x: 1}]).name).must_be_nil
+    end
+
+    it "is settable post-construction" do
+      namo = Namo.new([{x: 1}])
+      namo.name = :bar
+      _(namo.name).must_equal :bar
+    end
+
+    it "is nil on a Namo derived from a set operator" do
+      a = Namo.new([{x: 1}], name: :a)
+      b = Namo.new([{x: 2}], name: :b)
+      _((a + b).name).must_be_nil
+    end
+
+    it "is nil on a Namo derived from an Enumerable method" do
+      namo = Namo.new([{x: 1}, {x: 2}], name: :original)
+      _(namo.select{|row| row[:x] > 1}.name).must_be_nil
+    end
+  end
+
+  describe "subclass side-effect guard" do
+    before do
+      @guard_class = Class.new(Namo) do
+        def self.fired
+          @fired ||= []
+        end
+        def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
+          super
+          return unless name
+          self.class.fired << name
+        end
+      end
+    end
+
+    it "fires guarded side effects for an explicitly named construction" do
+      @guard_class.new(data: [{x: 1}], name: :foo)
+      _(@guard_class.fired).must_equal [:foo]
+    end
+
+    it "skips guarded side effects for an unnamed construction" do
+      @guard_class.new(data: [{x: 1}])
+      _(@guard_class.fired).must_equal []
+    end
+
+    it "skips guarded side effects for an operator result" do
+      a = @guard_class.new(data: [{x: 1}], name: :a)
+      b = @guard_class.new(data: [{x: 2}], name: :b)
+      @guard_class.fired.clear
+      _((a + b).name).must_be_nil
+      _(@guard_class.fired).must_equal []
+    end
+  end
+
   describe "#dimensions" do
     it "infers dimensions from hash keys" do
       _(sales.dimensions).must_equal [:product, :quarter, :price, :quantity]
@@ -453,6 +560,93 @@ describe Namo do
     end
   end
 
+  describe "#[]= polymorphic dispatch" do
+    it "registers a formula when assigned a proc (existing behaviour preserved)" do
+      namo = Namo.new([{price: 10.0, quantity: 100}])
+      namo[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(namo.derived_dimensions).must_include :revenue
+      _(namo.values(:revenue)).must_equal [1000.0]
+    end
+
+    it "clears any data column of the same name when assigned a proc" do
+      namo = Namo.new([{x: 1}, {x: 2}])
+      _(namo.data_dimensions).must_include :x
+      namo[:x] = proc{|r| 99}
+      _(namo.data_dimensions).wont_include :x
+      _(namo.derived_dimensions).must_include :x
+      _(namo.values(:x)).must_equal [99, 99]
+    end
+
+    it "broadcasts a scalar to every row" do
+      namo = Namo.new([{a: 1}, {a: 2}, {a: 3}])
+      namo[:status] = 'active'
+      _(namo.values(:status)).must_equal ['active', 'active', 'active']
+    end
+
+    it "clears any formula of the same name when assigned a scalar" do
+      namo = Namo.new([{price: 10.0, quantity: 100}])
+      namo[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      namo[:revenue] = 0
+      _(namo.derived_dimensions).wont_include :revenue
+      _(namo.data_dimensions).must_include :revenue
+      _(namo.values(:revenue)).must_equal [0]
+    end
+
+    it "broadcasts an array as the value (array is not a proc)" do
+      namo = Namo.new([{a: 1}, {a: 2}])
+      namo[:weights] = [1, 2, 3]
+      _(namo.values(:weights)).must_equal [[1, 2, 3], [1, 2, 3]]
+    end
+
+    it "is last-write-wins: scalar then proc leaves a formula only" do
+      namo = Namo.new([{y: 7}])
+      namo[:x] = 5
+      namo[:x] = proc{|r| r[:y]}
+      _(namo.derived_dimensions).must_include :x
+      _(namo.data_dimensions).wont_include :x
+      _(namo.values(:x)).must_equal [7]
+    end
+
+    it "is last-write-wins: proc then scalar leaves a broadcast value only" do
+      namo = Namo.new([{y: 7}])
+      namo[:x] = proc{|r| r[:y]}
+      namo[:x] = 5
+      _(namo.data_dimensions).must_include :x
+      _(namo.derived_dimensions).wont_include :x
+      _(namo.values(:x)).must_equal [5]
+    end
+
+    it "surfaces a proc-assigned name as derived, not data, exactly once in dimensions" do
+      namo = Namo.new([{x: 1}, {x: 2}])
+      namo[:x] = proc{|r| 99}
+      _(namo.data_dimensions).wont_include :x
+      _(namo.derived_dimensions).must_include :x
+      _(namo.dimensions.count(:x)).must_equal 1
+    end
+
+    it "surfaces a scalar-assigned name as data, not derived, exactly once in dimensions" do
+      namo = Namo.new([{x: 1}])
+      namo[:rev] = proc{|r| r[:x]}
+      namo[:rev] = 5
+      _(namo.data_dimensions).must_include :rev
+      _(namo.derived_dimensions).wont_include :rev
+      _(namo.dimensions.count(:rev)).must_equal 1
+    end
+
+    it "does not walk rows to clear when no data column of that name exists" do
+      namo = Namo.new([{a: 1}])
+      namo[:b] = proc{|r| r[:a]}
+      _(namo.derived_dimensions).must_include :b
+      _(namo.values(:b)).must_equal [1]
+    end
+
+    it "handles an empty Namo without error" do
+      namo = Namo.new([])
+      namo[:x] = proc{|r| 1}
+      _(namo.derived_dimensions).must_include :x
+    end
+  end
+
   describe "#each" do
     it "yields Row objects" do
       rows = []

metadata

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