namo 0.11.1 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ad4994109308fd955b2f508afe1f07251bc4287406ed7f27eb8a484a61dfabcf
-  data.tar.gz: 04be0a1d0e8f97b86932a3e5e8953bfe3b0e51fe16bcb80b5dec9a5a73aecd36
+  metadata.gz: 4a7dd953b56fb4f692b0e92822cb6d5dcf9a38f8645a913aedc06333441ad305
+  data.tar.gz: b492295ead6b4a9ea5647290eef7d008e86e6cbc0275176f45f2ea76b1692854
 SHA512:
-  metadata.gz: 507a77ecfc3d23fe1ad4ef14783b2e4f86ff44b58431cb93b8e4aa41c12bf4778f03c7a3bdca7f8958620b3d2e3bba3292cdfbcd5636c8286661aed100398b30
-  data.tar.gz: fa6acfcf416108a871e0697ae998cef8701263446abee9089c62e1cfb24c102d22f002e643f89890a7c40ad2ccedca3dd7d58ebf04125fb4a87d17f58a908abd
+  metadata.gz: 35a4a0acebfa4f01b83948c7a1639606cb58f9de7c0e75c8cf5886654128526cbe5554e4670503b74b5687674da00929a1b3252ee7bf30d2ecb7db976b580de5
+  data.tar.gz: ce62a04e0e1a7db2e1ec1a5f20674e000baadf3de64186ea1afe2718d8acdd36189e612aa14c6ca71a8e6330009aa0bfa380b797020ee9fbb69a6a49e9390e90

data/CHANGELOG

@@ -1,6 +1,16 @@
 CHANGELOG
 _________
 
+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
@@ -715,6 +725,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.12.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
@@ -246,8 +247,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]

metadata

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