namo 0.25.1 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd20f662edb4f305d6c74b5a100c536c20ad57ce31f7044498f76eebe2fbbf68
-  data.tar.gz: e242043273cac5866c8dda07aec202c69954d36072f8092b50bb817b6ca24bb8
+  metadata.gz: 326ba6ba610149b0998452136812f313617014d5e68fc066d5c81ace134ad8eb
+  data.tar.gz: ddd93f8e3866169c6bc6835c5720375fbfd53860b2e036f1540dcb567414b61c
 SHA512:
-  metadata.gz: 581cbeae8e0eeca1fb35db857d2acad566ecd21dc8d967e921161620b6a994e26293b17026e806c0c754851fe8da175bf3e260afe98e8f2899853fcb1e20fda3
-  data.tar.gz: cdc1687745394bf2931469daf7823d0c724436aea4a0c4657505f39beae1afe8a6224406682f9d630672a12fc6554b9872044ee8d72d93acfd03d7459bb32282
+  metadata.gz: 9402c8b7193dd068d624b883f9e2b7492942cf67dcf0c3d697e85bb77c2615deb205538cf86c5b341e567e25990241235b88bd5bfa0582b0cace025c65a7fa10
+  data.tar.gz: 40af6d9dd32c57b4a60e038887fbc4c73c7a6412e25854688b9ff8ddc5ee35c6419d30fcb76ce6e0ee5cdcf491c757a3ebcd1f81ec584ad41243413300b8c40f

data/CHANGELOG

@@ -1,5 +1,18 @@
 # CHANGELOG
 
+## 20260704
+
+0.26.0: + Namo#detach, Namo::Formulae#detach — remove a formula by name or a formulary's methods by module, completing the attach/attach!/detach family.
+
+detach becomes the sanctioned formula-removal idiom, displacing the namo.formulae.delete(:name) reach-through. It is by-name with no provenance (the store is a snapshot): the Module arm removes whatever currently holds each of the module's method names. There is no detach! (removing a formula can't collide with data, so no guard to force through) and no removal operator (<< appends; per the 0.14.0 principle, no >>).
+
+1. + Namo::Formulae#detach(constituent) — dispatches a Symbol to @store.delete(constituent); a Module to deleting each of its public_instance_methods(false) names, after the same Namo::Formulary marker guard attach uses (an untagged module raises ArgumentError); anything else raises TypeError naming the class, in the << else-arm's style. Returns self. Placed directly after attach/<<. Formulae#delete is unchanged — it stays the store-level primitive detach sits on.
+2. + Namo#detach(constituent) — forwards to @formulae.detach and returns self, placed with the attach family (after attach!, before <<). No guard at the Namo level: there is no data-side interaction, so the Formulae worker owns the dispatch and the raises. Collection inherits detach harmlessly.
+3. ~ test/Namo/Formulae_test.rb: + a "#detach" describe in the formulary tier — both arms return self; the Symbol arm removes the named formula and no-ops on an absent name; the Module arm removes exactly the formulary's method names, leaves a []= name it doesn't contribute, and deletes a []= overwrite occupying a formulary-method name (the by-name/no-provenance pin); ArgumentError on an untagged module; TypeError on a String and a Hash naming the class; chaining removes both. ~ test/namo_test.rb: + a "#detach" describe under formularies — returns the Namo; removes a []= formula from the queryable namespace (derived_dimensions drops it, values returns one nil per row); leaves other formulae resolving; the Module arm empties derived_dimensions; a data dimension is a no-op (the column survives); an absent name no-ops returning the Namo; TypeError on a non-Symbol non-Module and ArgumentError on an untagged module; the #dimensions "reflects mutation" test migrates sales.formulae.delete(:revenue) to sales.detach(:revenue). ~ test/Namo/Collection_test.rb: + a "#detach" describe pinning that a Collection inherits detach — a formulary attached to the collection detaches, so the detail rows no longer resolve its name.
+4. ~ README.md: + a "Removing a formula" note under Formulae (detach removes a formula, returns the Namo, chains, no-ops on an absent name; complements contraction across the data/derived and algebra/mutation splits; never touches @data); + a detach(Module) note in the Formularies section (the reverse of attach, by-name with no provenance, raises on an untagged module, the attach/attach!/detach family, no << removal counterpart, no detach!).
+5. ~ ROADMAP.md: + the 0.26.0 release entry recording the settled decisions (by-name/no-provenance, marker required, loose-on-absent, derived-side-only, no-bang, no-operator, single-argument/chaining, untouched-host-ancestry); current-state bumped to 0.26.0; detach folded into the Summary's formulary vocabulary and the 1.0.0 feature list.
+6. ~ Namo::VERSION: /0.25.1/0.26.0/
+
 ## 20260703
 
 0.25.1: Fix documentation and reformat CHANGELOG to use Markdown headers.

data/README.md

@@ -716,6 +716,12 @@ prices[:sma_close_20] = proc{|row| row[:sma, :close, 20]}
 prices[:date, :sma_close_20]   # materialises per the usual projection rule
 ```
 
+#### Removing a formula
+
+`detach(:name)` removes a formula, returns the Namo, and chains — `sales.detach(:revenue).detach(:cost)`. Detaching a name that isn't there is a quiet no-op, so a cleanup step composes over any Namo without first checking whether the formula is present. It is the sanctioned way to drop a derived dimension, sitting over the store-level primitive `formulae.delete`.
+
+`detach` and contraction are complements across two axes. Contraction (`sales[-:price]`) is non-mutating — it returns a *new* Namo with a *data* dimension removed and the formulae carried. `detach` mutates the receiver and removes a *derived* dimension. So the pair spans both the data/derived split and the algebra/mutation split: contraction is algebra over data, `detach` is mutation of the derived side. `detach` never touches `@data` — naming a data dimension is a no-op and the column survives; removing a data dimension is contraction's job.
+
 #### Formularies
 
 A *formulary* is a reusable body of derived dimensions — a module whose public instance methods are formulae. A Namo attaches a formulary, and from then on those methods resolve as derived dimensions through the same interface as `[]=` formulae. The methods take `row` (and `namo`, and any further parameters) exactly as a `[]=` formula does:
@@ -772,6 +778,8 @@ Because each method is copied into the store, the rules already governing `[]=`
 
 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.
 
+`detach(OrderFlow)` is the reverse of `attach`: it removes the formulary's public method names from the store, so `flows.attach(OrderFlow)` then `flows.detach(OrderFlow)` leaves the formulae as they started. It works by name and keeps no provenance — the store is a snapshot, so `detach` removes *whatever currently holds each name*, including a `[]=` formula that later overwrote a formulary method of the same name. Like the `attach` side, the marker is required: `detach` raises `ArgumentError` for an untagged module, so you can only detach what could have been attached. The mutating family is `attach` / `attach!` / `detach`; `<<` has no removal counterpart (it *appends* constituents — a removal operator would be cuteness over clarity), and there is no `detach!` because removing a formula can't collide with data, so there is no guard for a bang to force through.
+
 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/Formulae.rb

@@ -25,6 +25,21 @@ class Namo
     end
     alias_method :<<, :attach
 
+    def detach(constituent)
+      case constituent
+      when Symbol
+        @store.delete(constituent)
+      when Module
+        unless constituent.include?(Namo::Formulary)
+          raise ArgumentError, "not a Namo::Formulary: #{constituent}"
+        end
+        constituent.public_instance_methods(false).each{|name| @store.delete(name)}
+      else
+        raise TypeError, "can't detach #{constituent.class} from a Formulae; expected a Symbol or a Module (formulary)"
+      end
+      self
+    end
+
     def derive(name, row, namo, *arguments)
       formula = self[name]
       if collection_scoped?(name)

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.25.1'
+  VERSION = '0.26.0'
 end

data/lib/namo.rb

@@ -103,6 +103,11 @@ class Namo
     self
   end
 
+  def detach(constituent)
+    @formulae.detach(constituent)
+    self
+  end
+
   def <<(constituent)
     case constituent
     when Module then attach(constituent)

data/test/Namo/Collection_test.rb

@@ -145,6 +145,15 @@ describe Namo::Collection do
     end
   end
 
+  describe "#detach" do
+    it "detaches a formulary attached to the collection, so the detail rows no longer resolve its name" do
+      collection << component_pricing
+      _(collection.values(:cost_per_kg)).must_equal [250, 250, 200, 250]
+      collection.detach(component_pricing)
+      _(collection.derived_dimensions).wont_include :cost_per_kg
+    end
+  end
+
   describe "#find" do
     it "returns the member with the given name" do
       _(collection.find(:chassis)).must_be_same_as chassis

data/test/Namo/Formulae_test.rb

@@ -330,6 +330,64 @@ describe Namo::Formulae do
       end
     end
 
+    describe "#detach" do
+      it "returns self for a Symbol" do
+        _(attached.detach(:signed_volume)).must_be_same_as attached
+      end
+
+      it "returns self for a Module" do
+        _(attached.detach(delta)).must_be_same_as attached
+      end
+
+      it "removes the named formula, leaving the others" do
+        attached.detach(:signed_volume)
+        _(attached.key?(:signed_volume)).must_equal false
+        _(attached.key?(:echo_namo)).must_equal true
+      end
+
+      it "is a no-op on an absent name, still returning self" do
+        _(attached.detach(:missing)).must_be_same_as attached
+        _(attached.key?(:signed_volume)).must_equal true
+      end
+
+      it "removes exactly the formulary's public method names via the Module arm" do
+        attached.detach(delta)
+        _(attached.keys).must_equal []
+      end
+
+      it "leaves a []= formula not among the formulary's methods when detaching the module" do
+        attached[:extra] = proc{|r| 0}
+        attached.detach(delta)
+        _(attached.key?(:extra)).must_equal true
+      end
+
+      it "deletes a []= overwrite occupying a formulary-method name" do
+        attached[:signed_volume] = proc{|r| 0}
+        attached.detach(delta)
+        _(attached.key?(:signed_volume)).must_equal false
+      end
+
+      it "raises ArgumentError for an untagged module" do
+        _(proc{attached.detach(untagged)}).must_raise ArgumentError
+      end
+
+      it "raises TypeError for a String, naming the class" do
+        error = _(proc{attached.detach("signed_volume")}).must_raise TypeError
+        _(error.message).must_match(/String/)
+      end
+
+      it "raises TypeError for a Hash, naming the class" do
+        error = _(proc{attached.detach({})}).must_raise TypeError
+        _(error.message).must_match(/Hash/)
+      end
+
+      it "chains, removing both named formulae" do
+        formulae[:cost] = cost
+        formulae.detach(:revenue).detach(:cost)
+        _(formulae.keys).must_equal []
+      end
+    end
+
     describe "carry-through" do
       it "preserves attached formularies through #dup" do
         _(attached.dup.keys).must_include :signed_volume

data/test/namo_test.rb

@@ -165,7 +165,7 @@ describe Namo do
     it "reflects mutation on the next call" do
       sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
       _(sales.dimensions).must_include :revenue
-      sales.formulae.delete(:revenue)
+      sales.detach(:revenue)
       _(sales.dimensions).wont_include :revenue
     end
   end
@@ -978,6 +978,56 @@ describe Namo do
         _(flows === other).must_equal true
       end
     end
+
+    describe "#detach" do
+      it "returns the Namo" do
+        _(flows.detach(:signed_volume)).must_be_same_as flows
+      end
+
+      it "removes a formula from the queryable namespace" do
+        namo = Namo.new(flow_data)
+        namo[:revenue] = proc{|r| r[:buys]}
+        namo.detach(:revenue)
+        _(namo.derived_dimensions).wont_include :revenue
+        _(namo.values(:revenue)).must_equal [nil, nil, nil]
+      end
+
+      it "leaves other formulae resolving" do
+        namo = Namo.new(flow_data)
+        namo[:revenue] = proc{|r| r[:buys]}
+        namo[:tally] = proc{|r| r[:sells]}
+        namo.detach(:revenue)
+        _(namo.values(:tally)).must_equal [40, 120, 75]
+      end
+
+      it "removes an attached formulary's methods via the Module arm" do
+        flows.detach(delta)
+        _(flows.derived_dimensions).must_equal []
+      end
+
+      it "never exposed the formulary's private helper" do
+        _(flows.derived_dimensions).wont_include :helper
+      end
+
+      it "never touches data — a data dimension is a no-op" do
+        flows.detach(:date)
+        _(flows.data_dimensions).must_include :date
+        _(flows.values(:date)).must_equal [1, 2, 3]
+      end
+
+      it "is a no-op on an absent name, returning the Namo" do
+        _(flows.detach(:missing)).must_be_same_as flows
+        _(flows.values(:signed_volume)).must_equal [20, -40, 0]
+      end
+
+      it "raises TypeError on a non-Symbol non-Module" do
+        _(proc{flows.detach("signed_volume")}).must_raise TypeError
+      end
+
+      it "raises ArgumentError on an untagged module" do
+        _(proc{flows.detach(untagged)}).must_raise ArgumentError
+      end
+    end
   end
 
   describe "formularies via class include" do

metadata

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