namo 0.24.1 → 0.25.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 017c3006832fa49d8e63c5de42d927e0e2bb661f05ff322b002a3d1ba18758e2
-  data.tar.gz: 65a1c6b04337361f3b692423e85e8066f598ddbd028e0349e4c85b6ebabc183f
+  metadata.gz: cf81d723c5723d7737dd544596abbe5b69323f9f027a1aac7caef2cb857ebf5a
+  data.tar.gz: 6b1130eb34b16920641e594b52aaff58e9f275ac2a26b0089b21f62a6d8f6630
 SHA512:
-  metadata.gz: 989fbb45527739717202af6f6b74df7549488045c41acd3429ea190f7ec5ac4b54e527f684bba86201704ffd3647f2446b282c8f0cc48f2ca68677548e9e1c8b
-  data.tar.gz: '00494397772996dd29cf099c7c019d0909d5d61eafaa2dec42a827cc79cad7db0c60fc3ab5172a63acab77dd2034b4a6ad7a7a6440c94485870754563ba94e9f'
+  metadata.gz: fb7c989aeb34877ed56e83190bf947217370103420c6f5e5186a88316217f35c4c801d0ed1864bd0105129d3391c99a635ed756c1050bb57a6ce33c4fbffa0e5
+  data.tar.gz: da0f8fd20ccfa3f33b860059f33a8e65ddfed9bc157c02c1dd73389c3b907b8f4dbe82eeaf89f6a5e28a45274b74d8d03121ea7bdee9855d772242e4c50f8683

data/CHANGELOG

@@ -1,6 +1,18 @@
 CHANGELOG
 _________
 
+20260703
+0.25.0: + Namo#attach! — attach a formulary, evicting any data column whose name a formulary method collides with, rather than raising.
+
+attach! evicts the colliding data columns first (as []='s proc-over-data assignment does), then attaches — the bang is the explicit consent that attach's raise withholds by default. << stays guarded: a Module still routes to attach.
+
+1. ~ Namo#attach — extract the collision set into a new private attach_collisions(modul) (modul.public_instance_methods(false) & data_dimensions); behaviour unchanged, still raises ArgumentError naming the collisions when the set is non-empty.
+2, + Namo#attach! — evicts each colliding data column (@data.each{|row| row.delete(name)} per colliding name, the column membership already confirmed by attach_collisions so no key-guard is needed), then forwards to @formulae.attach and returns self. The eviction mirrors []='s proc-branch clear. + private attach_collisions(modul). << is unchanged: a Module still routes to attach (the guarded form), so the operator stays safe and attach! is reached only by explicit call — one safe operator, one explicit forceful method, matching []= having no operator shortcut for its own eviction.
+3. ~ test/namo_test.rb: + an "#attach!" describe — attach! attaches as attach does for a non-colliding module (returns self, methods resolve); attach! evicts a colliding data column and registers the formulary method in its place, with all access paths (values, Row, selection) agreeing on the formula afterward and the name appearing once in derived_dimensions, not in data_dimensions; attach! over several colliding columns evicts all of them; attach! on a vanilla collision-free module leaves the data untouched; the existing attach collision-raise tests are unchanged, pinning that the guarded form still raises where attach! evicts.
+4. ~ README.md: ~ the Formularies section — + attach! as the forceful sibling of attach, with the materialised-snapshot refresh as the motivating case and the bang-is-consent rationale; + the self-eviction-recurses caveat (a formulary method that reads a column its own name evicts recurses on access, exclusive storage leaving no shadowed value behind the formula — the one way attach!'s eviction differs in feel from []='s); note that << stays the guarded form.
+5. ~ ROADMAP.md: + the 0.25.0 release entry; current-state bumped to 0.25.0.
+6. ~ Namo::VERSION: /0.24.1/0.25.0/
+
 20260629
 0.24.1: ~ Namo#add_row — guard row-append against a data/formula name collision.
 

data/README.md

@@ -768,6 +768,10 @@ Because each method is copied into the store, the rules already governing `[]=`
 - **Materialise-and-drop on projection.** Naming a formulary method in a projection snapshots its values into a data column *and drops the formula*, exactly as for a `[]=` formula: `flows[:date, :signed_volume]` returns a Namo reporting `:signed_volume` as data, not derived, with all access paths agreeing on the stored snapshot.
 - **Carry-through.** Selection, the set and composition operators, and a projection that *omits* the name all keep the formula live, computing against the result's own rows — the carry-through is free, because the formulae are ordinary store entries.
 
+`attach!` is the forceful sibling of `attach`. Where `attach` refuses a data collision, `attach!` **evicts** the colliding data columns first — deleting each one exactly as assigning a proc through `[]=` clears a same-named data column — then attaches. The bang is consent: `attach` won't destroy a column you never named, but `attach!` is you saying you meant to. The motivating case is refreshing a formulary over a *materialised snapshot* — once a derived dimension has been projected into a stored column (materialise-and-drop, above), re-attaching the formulary that defined it collides with the now-data column, and `attach!` re-attaches over it in one step where `attach` would require you to contract the column away first. `<<` stays the guarded form: a module through `<<` routes to `attach`, so the operator never evicts — only an explicit `attach!` call does.
+
+Note that there is no counterpart in `[]=`'s scalar-over-formula eviction and is worth naming: a formulary method that reads a column its own name evicts will **recurse** on access. The eviction removes the datum, and exclusive storage leaves no shadowed value behind the formula, so `Row#[]` re-enters the formula rather than falling back to data — a `def close(row); row[:close] * ...; end` attached with `attach!` over a `:close` data column has no `:close` data left to read. `[]=` rarely bites this way because you write the proc at the call site, beside the name it replaces; a formulary is authored elsewhere, so a method reading its own evicted column is easy to attach without noticing. Self-reference is unguarded here as everywhere in the formula mechanism — keep a formulary's inputs and outputs under distinct names, or `attach` (not `attach!`) and contract deliberately.
+
 Two Namos that expose the same names — one via `[]=`, one via a formulary — are `===`; a Namo with a formulary attached is not `===` to a vanilla Namo of the same data dimensions.
 
 Formulary methods take `row` explicitly and index it (`row[:buys]`), the same as `[]=` formulae. Resolving bare names inside a method body (`buys` for `row[:buys]`) and memoising derived values on a frozen Namo arrive in a later release; until then a formulary method is a plain function of its `row` (and `namo`).

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.24.1'
+  VERSION = '0.25.0'
 end

data/lib/namo.rb

@@ -89,7 +89,7 @@ class Namo
   end
 
   def attach(modul)
-    collisions = modul.public_instance_methods(false) & data_dimensions
+    collisions = attach_collisions(modul)
     unless collisions.empty?
       raise ArgumentError, "formulary methods collide with data dimensions: #{collisions.inspect}"
     end
@@ -97,6 +97,12 @@ class Namo
     self
   end
 
+  def attach!(modul)
+    attach_collisions(modul).each{|name| @data.each{|row| row.delete(name)}}
+    @formulae.attach(modul)
+    self
+  end
+
   def <<(constituent)
     case constituent
     when Module then attach(constituent)
@@ -268,6 +274,10 @@ class Namo
     self
   end
 
+  def attach_collisions(modul)
+    modul.public_instance_methods(false) & data_dimensions
+  end
+
   def attach_included_formularies
     self.class.ancestors.reverse.each do |modul|
       next if modul.is_a?(Class) || !modul.include?(Namo::Formulary)

data/test/namo_test.rb

@@ -747,6 +747,58 @@ describe Namo do
       end
     end
 
+    describe "#attach!" do
+      it "attaches as attach does for a non-colliding module" do
+        namo = Namo.new(flow_data)
+        _(namo.attach!(delta)).must_be_same_as namo
+        _(namo.values(:signed_volume)).must_equal [20, -40, 0]
+      end
+
+      it "evicts a colliding data column and registers the formulary method in its place" do
+        widened = Namo.new(flow_data.map{|row| row.merge(signed_volume: 999)})
+        widened.attach!(delta)
+        _(widened.data_dimensions).wont_include :signed_volume
+        _(widened.derived_dimensions).must_include :signed_volume
+        _(widened.dimensions.count(:signed_volume)).must_equal 1
+      end
+
+      it "agrees across all access paths on the evicted-then-derived name" do
+        widened = Namo.new(flow_data.map{|row| row.merge(signed_volume: 999)})
+        widened.attach!(delta)
+        _(widened.values(:signed_volume)).must_equal [20, -40, 0]
+        _(widened.entries.first[:signed_volume]).must_equal 20
+        _(widened[signed_volume: 20].values(:date)).must_equal [1]
+      end
+
+      it "evicts every colliding column when several collide" do
+        clash = Module.new do
+          include Namo::Formulary
+          def buys(row); row[:date] * 2; end
+          def sells(row); row[:date] * 3; end
+        end
+        namo = Namo.new(flow_data)
+        namo.attach!(clash)
+        _(namo.data_dimensions).wont_include :buys
+        _(namo.data_dimensions).wont_include :sells
+        _(namo.derived_dimensions).must_include :buys
+        _(namo.derived_dimensions).must_include :sells
+        _(namo.values(:buys)).must_equal [2, 4, 6]
+        _(namo.values(:sells)).must_equal [3, 6, 9]
+      end
+
+      it "leaves the data untouched when the module does not collide" do
+        namo = Namo.new(flow_data)
+        namo.attach!(delta)
+        _(namo.values(:buys)).must_equal [60, 80, 75]
+        _(namo.values(:sells)).must_equal [40, 120, 75]
+      end
+
+      it "raises through attach (the guarded form) where attach! evicts" do
+        widened = Namo.new(flow_data.map{|row| row.merge(signed_volume: 999)})
+        _(proc{widened.attach(delta)}).must_raise ArgumentError
+      end
+    end
+
     describe "#<<" do
       it "attaches a formulary, the same as #attach" do
         namo = Namo.new(flow_data)

metadata

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