namo 0.12.0 → 0.13.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a7dd953b56fb4f692b0e92822cb6d5dcf9a38f8645a913aedc06333441ad305
-  data.tar.gz: b492295ead6b4a9ea5647290eef7d008e86e6cbc0275176f45f2ea76b1692854
+  metadata.gz: 9dfca5e33dc24464a1e109e6b2a32ff5d85fd171c24497832ae5bda3f91e07dc
+  data.tar.gz: d6f4fc0cf6db0dfd349e77588d186c42ebeb0fffea32e55771549e4114f224c2
 SHA512:
-  metadata.gz: 35a4a0acebfa4f01b83948c7a1639606cb58f9de7c0e75c8cf5886654128526cbe5554e4670503b74b5687674da00929a1b3252ee7bf30d2ecb7db976b580de5
-  data.tar.gz: ce62a04e0e1a7db2e1ec1a5f20674e000baadf3de64186ea1afe2718d8acdd36189e612aa14c6ca71a8e6330009aa0bfa380b797020ee9fbb69a6a49e9390e90
+  metadata.gz: 46a4fcb9ec264f6ef718225995b4e83aeac410a0ba3c5a2c8591640ea89e6b9af4ee2a25e4ec91d739e54e159eea192a592dae2732166339206f66a93307631d
+  data.tar.gz: 867849106103a6cdeaea5c1a67eba12d4d4b4d2c5ea439b7c669fd723847998668d33834c0f5cf58305aeb01016fd875d064d149141e8e9efba355897e2855da

data/CHANGELOG

@@ -1,6 +1,29 @@
 CHANGELOG
 _________
 
+20260604
+0.13.1: Correct the row-order claim across the docs and document the same-dimension-order precondition.
+
+1. ~ README.md: Scope the "row order is ignored" statement to the comparison operators
+   (==, eql?, ===, <, <=, >, >=) in the Equality section; drop "accident of ingestion".
+   + Positive note that row order is preserved through to_h/values, each, first, last,
+   take, drop, and +.
+2. ~ README.md: At Concatenation, state that the set operators require the same dimension
+   names in the same order, with guidance to normalise inputs to a common column order
+   before combining.
+3. ~ ROADMAP.md: Scope the 0.6.0 section's "row order is an accident of ingestion" to the
+   comparison operators; drop "accident of ingestion". Date bumped to 20260604.
+4. ~ Namo::VERSION: /0.13.0/0.13.1/
+
+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:.
 

data/README.md

@@ -226,7 +226,7 @@ all_sales = q1_sales + q2_sales
 # ]>
 ```
 
-The dimensions must match — concatenating Namo objects with different dimensions raises an `ArgumentError`. Formulae carry through from the left-hand side.
+The dimensions must match — the same dimension names in the same order — or the operator raises an `ArgumentError`. Two Namos holding the same columns in a different order must be normalised to a common column order before they can be combined. Formulae carry through from the left-hand side.
 
 ### Row Removal
 
@@ -449,7 +449,7 @@ This is the same pattern that makes `Array#-` useful with arrays that aren't sub
 
 ### Equality
 
-Comparison on Namos is **multiset-theoretic on rows**: row order is ignored (it's an accident of ingestion, not data), but row multiplicities count (they *are* data). The same stance carries across the equality, pattern-match, and subset/superset operators below.
+Comparison on Namos is **multiset-theoretic on rows**: the comparison operators — `==`, `eql?`, `===`, `<`, `<=`, `>`, `>=` — ignore row order, so two Namos holding the same rows in a different order compare equal, while row multiplicities count (they *are* data). That stance is shared across the equality, pattern-match, and subset/superset operators documented below. Row order is otherwise preserved: `to_h` and `values` depend on it for columnar alignment, and `each`, `first`, `last`, `take`, `drop`, and `+` all observe it. It is the comparison operators alone that treat the sequence of rows as a multiset.
 
 `==` is multiset equality on rows. Class and formulae are ignored; row order is ignored; row multiplicities are not.
 
@@ -585,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:

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.12.0'
+  VERSION = '0.13.1'
 end

data/lib/namo.rb

@@ -74,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)

data/test/namo_test.rb

@@ -560,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.12.0
+  version: 0.13.1
 platform: ruby
 authors:
 - thoran