namo 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40c2256efac2663b7593bb1f7e4c3ca08fa07e6e225c75fcef3d6d8658f3794b
-  data.tar.gz: abd7bd9076d7019c245d942425232dcf0966edb076cf6d50fdedf7b74efea90f
+  metadata.gz: 4a7dd953b56fb4f692b0e92822cb6d5dcf9a38f8645a913aedc06333441ad305
+  data.tar.gz: b492295ead6b4a9ea5647290eef7d008e86e6cbc0275176f45f2ea76b1692854
 SHA512:
-  metadata.gz: 2b5045c4160d8812fa3f04f10dc027bf8c6cfaf937405cec0570a31af52babdc1f2dc6e25db249a9b9dea81afc9806f617203ae71dded576974fe9512bd4ec00
-  data.tar.gz: a553ef0ae27d67bf28d8d91ba9e2e71f217f8ee23ff3d177ad207dd520f30971730774a51660830d98d79a6189cee16f1227dbd168282f3a27c4316912a6f29f
+  metadata.gz: 35a4a0acebfa4f01b83948c7a1639606cb58f9de7c0e75c8cf5886654128526cbe5554e4670503b74b5687674da00929a1b3252ee7bf30d2ecb7db976b580de5
+  data.tar.gz: ce62a04e0e1a7db2e1ec1a5f20674e000baadf3de64186ea1afe2718d8acdd36189e612aa14c6ca71a8e6330009aa0bfa380b797020ee9fbb69a6a49e9390e90

data/CHANGELOG

@@ -1,6 +1,25 @@
 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.
+
+1. + lib/Namo/Enumerable.rb: New module Namo::Enumerable holding each and the subset-returning Enumerable methods (select plus its filter/find_all aliases, reject, sort_by, first, last, take, drop, take_while, drop_while, uniq, partition), moved verbatim from Namo. The module does `include ::Enumerable` — the leading :: is required, because under the nested `class Namo; module Enumerable` scope a bare `Enumerable` resolves to Namo::Enumerable itself and raises a cyclic-include error.
+2. ~ lib/namo.rb: Remove the inline each and the eleven subset methods; remove `include Enumerable`; + `require_relative './Namo/Enumerable'` and `include Namo::Enumerable` (which transitively brings stdlib Enumerable into the ancestor chain below the module, so the overrides win and map/reduce/etc. still fall through). Pure reorganisation — no behaviour change.
+3. ~ test/namo_test.rb: + Namo::Enumerable module tests — it is a Module, Namo includes it and stdlib Enumerable, and it precedes ::Enumerable in Namo.ancestors so the overrides resolve first. The existing Enumerable subset tests are unchanged and remain green, evidencing the move is behaviour-preserving.
+4. ~ ROADMAP.md: + note in the 0.11.0 section that, as of 0.11.1, these methods live in the Namo::Enumerable module; bump Date to 20260601.
+5. ~ Namo::VERSION: /0.11.0/0.11.1/
+
 20260531
 0.11.0: ~ Subset Enumerable methods (select, reject, sort_by, first, last, take, drop, take_while, drop_while, uniq, partition) return Namos
 

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/Enumerable.rb

@@ -0,0 +1,72 @@
+# Namo/Enumerable.rb
+# Namo::Enumerable
+
+class Namo
+  module Enumerable
+    include ::Enumerable
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      @data.each{|row_data| block.call(Row.new(row_data, @formulae))}
+    end
+
+    def select(&block)
+      self.class.new(@data.select{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+    end
+    alias_method :filter, :select
+    alias_method :find_all, :select
+
+    def reject(&block)
+      self.class.new(@data.reject{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+    end
+
+    def sort_by(&block)
+      self.class.new(@data.sort_by{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+    end
+
+    def first(n = nil)
+      if n
+        self.class.new(@data.first(n), formulae: @formulae.dup)
+      else
+        @data.first ? Row.new(@data.first, @formulae) : nil
+      end
+    end
+
+    def last(n = nil)
+      if n
+        self.class.new(@data.last(n), formulae: @formulae.dup)
+      else
+        @data.last ? Row.new(@data.last, @formulae) : nil
+      end
+    end
+
+    def take(n)
+      self.class.new(@data.take(n), formulae: @formulae.dup)
+    end
+
+    def drop(n)
+      self.class.new(@data.drop(n), formulae: @formulae.dup)
+    end
+
+    def take_while(&block)
+      self.class.new(@data.take_while{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+    end
+
+    def drop_while(&block)
+      self.class.new(@data.drop_while{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
+    end
+
+    def uniq(&block)
+      rows = block ? @data.uniq{|row| block.call(Row.new(row, @formulae))} : @data.uniq
+      self.class.new(rows, formulae: @formulae.dup)
+    end
+
+    def partition(&block)
+      matches, non_matches = @data.partition{|row| block.call(Row.new(row, @formulae))}
+      [
+        self.class.new(matches, formulae: @formulae.dup),
+        self.class.new(non_matches, formulae: @formulae.dup),
+      ]
+    end
+  end
+end

data/lib/Namo/VERSION.rb

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

data/lib/namo.rb

@@ -3,14 +3,16 @@
 
 require_relative './Namo/NegatedDimension'
 require_relative './Namo/Row'
+require_relative './Namo/Enumerable'
 require_relative './Namo/VERSION'
 require_relative './Symbol'
 
 class Namo
-  include Enumerable
+  include Namo::Enumerable
 
   attr_accessor :data
   attr_accessor :formulae
+  attr_accessor :name
 
   def dimensions
     data_dimensions + derived_dimensions
@@ -76,70 +78,6 @@ class Namo
     @formulae[name] = proc
   end
 
-  def each(&block)
-    return enum_for(:each) unless block_given?
-    @data.each{|row_data| block.call(Row.new(row_data, @formulae))}
-  end
-
-  def select(&block)
-    self.class.new(@data.select{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
-  end
-  alias_method :filter, :select
-  alias_method :find_all, :select
-
-  def reject(&block)
-    self.class.new(@data.reject{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
-  end
-
-  def sort_by(&block)
-    self.class.new(@data.sort_by{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
-  end
-
-  def first(n = nil)
-    if n
-      self.class.new(@data.first(n), formulae: @formulae.dup)
-    else
-      @data.first ? Row.new(@data.first, @formulae) : nil
-    end
-  end
-
-  def last(n = nil)
-    if n
-      self.class.new(@data.last(n), formulae: @formulae.dup)
-    else
-      @data.last ? Row.new(@data.last, @formulae) : nil
-    end
-  end
-
-  def take(n)
-    self.class.new(@data.take(n), formulae: @formulae.dup)
-  end
-
-  def drop(n)
-    self.class.new(@data.drop(n), formulae: @formulae.dup)
-  end
-
-  def take_while(&block)
-    self.class.new(@data.take_while{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
-  end
-
-  def drop_while(&block)
-    self.class.new(@data.drop_while{|row| block.call(Row.new(row, @formulae))}, formulae: @formulae.dup)
-  end
-
-  def uniq(&block)
-    rows = block ? @data.uniq{|row| block.call(Row.new(row, @formulae))} : @data.uniq
-    self.class.new(rows, formulae: @formulae.dup)
-  end
-
-  def partition(&block)
-    matches, non_matches = @data.partition{|row| block.call(Row.new(row, @formulae))}
-    [
-      self.class.new(matches, formulae: @formulae.dup),
-      self.class.new(non_matches, formulae: @formulae.dup),
-    ]
-  end
-
   def +(other)
     raise_unless_namo(other)
     raise_unless_matching_data_dimensions(other)
@@ -309,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]
@@ -913,6 +1020,22 @@ describe Namo do
     end
   end
 
+  describe "Namo::Enumerable module" do
+    it "is a Module supplying the subset methods" do
+      _(Namo::Enumerable).must_be_kind_of Module
+    end
+
+    it "is included in Namo, transitively including stdlib Enumerable" do
+      _(Namo.include?(Namo::Enumerable)).must_equal true
+      _(Namo.include?(Enumerable)).must_equal true
+    end
+
+    it "sits above stdlib Enumerable so its overrides win" do
+      ancestors = Namo.ancestors
+      _(ancestors.index(Namo::Enumerable) < ancestors.index(::Enumerable)).must_equal true
+    end
+  end
+
   describe "#+" do
     let(:more_data) do
       [

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.12.0
 platform: ruby
 authors:
 - thoran
@@ -64,6 +64,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- lib/Namo/Enumerable.rb
 - lib/Namo/NegatedDimension.rb
 - lib/Namo/Row.rb
 - lib/Namo/VERSION.rb