namo 0.16.0 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dcb7aafe4522ff115c12464016fef1a6909047975829523b095105f601a7ae60
-  data.tar.gz: 81f150f5f370f836734908a30e1ecd600b856f90c0151a698fa25bd117530d92
+  metadata.gz: 1ed38a77d14075cbe3c28ff53097d539c2fefe4a91ff515e165e02c280311fd3
+  data.tar.gz: ba009835a59174f2e60327f3583753d2e6c2b0e81b06f23de4a15dd792981526
 SHA512:
-  metadata.gz: 6fd5a96f0fdf85e6ffb8a3cfa2d1a560d5da1d118072e95cd549af43149ff2a4c963de122b9026c29c0817e33fcfbd2ba3ece969ee1f6f5d92738c3d7f38b73a
-  data.tar.gz: 78ba07312d7e4f4d4ac85a6ca572852964ed7055d48687361d8a86f9cb998122f421e75418ba67bc978bf78d7b0cc22315ebb800ca734e8ade07817bae886736
+  metadata.gz: 7328696a6b4032561fa1b68c0eb4d3e7d3582ee4d5fc24926779112413867f1713100d9c21a3aa2f18c299e50802c866b5c95e874e569f4ef41f40e7b3924f58
+  data.tar.gz: 8028776be37f1f183ca2cefc3c9de7229d6918cf37d05b5f925675dd2ffd7d05603cc21ba53665f74094991b0c8d08f22479de2f50ee35e36ba772777bdbfb6e

data/CHANGELOG

@@ -1,6 +1,95 @@
 CHANGELOG
 _________
 
+20260613
+0.18.0: + Namo::Collection — hierarchical aggregate of named Namos with summary/detail views.
+
+1. + lib/Namo/Collection.rb: Namo::Collection < Namo, the first family member beyond Namo
+   itself. Holds @members (an Array of named Namos, attr_reader :members) whose substance is
+   the collection; the inherited @data is a derived view rebuilt from the members. << accepts a
+   member or an array (via flatten), replaces by name (last-write-wins, unless member.name.nil?
+   so nil-named members always append), rebuilds @data = detail.data, and returns self. find(name)
+   returns the named member or nil (find(nil) is nil, and an unnamed member never matches),
+   shadowing Enumerable#find on Collections. summary(dimension, by: :member, reducer: :sum)
+   reduces each member to a {by => member.name, dimension => reduced} row; detail(by: :member)
+   unions the members' rows under the inject-iff-absent conditional
+   (row.key?(by) ? row : row.merge(by => member.name)); both return a fresh Namo (non-mutating).
+   as_summary(...) and as_detail(by = :member) set @data to the chosen view and return self
+   (mutating); the view persists until the next << re-materialises detail. Private initialize
+   sets @members = [] before super.
+2. ~ lib/namo.rb: + require_relative './Namo/Collection'.
+3. + test/Namo/Collection_test.rb: empty members; lazy detail materialisation and selection;
+   pure-live reflection of <<; <<' add/replace-by-name/array/unnamed/returns-self; find by name,
+   absent, nil, and unnamed; summary's labelled rows, custom by:, :mean reducer (local Array#mean),
+   and non-mutation; detail's plain-Namo return, inject-iff-absent both ways, and non-mutation;
+   live recomputation after <<; as_summary/as_detail mutate and return self and surface the
+   summary's columns in dimensions; as_* view persistence until the next <<; assembly round-trip
+   (as_detail(:assembly) injects and is retained, removed only by contraction); subclass default
+   by: via a Car < Namo::Collection overriding summary/detail.
+4. ~ README.md: + Collections section after Named Namos — the GT-budget example (Car/SubAssembly,
+   <<, summary, detail), lazy detail materialisation, the four view methods and the
+   non-mutating/mutating split, the inject-iff-absent rule, << replace-by-name with use-site
+   handling of unnamed members, the rebuild-on-<< view lifetime, and forward-notes to group_by
+   (0.19.0) and freeze-gated memoisation (2.x).
+5. ~ ROADMAP.md: Promote 0.18.0 to shipped, recording the resolved materialisation model
+   (rebuild-on-<<, as_* persists until the next <<, diverging from the drafted pure-live-per-access
+   / transient wording) and the find/Enumerable#find shadowing; Current state -> 0.18.0; Summary
+   folds in Namo::Collection; next phase -> group_by (0.19.0). The upcoming 0.18.0 design block
+   folded into the shipped entry.
+6. ~ COMPARISON.md: Aggregation entry repointed — Namo::Collection shipped (0.18.0), group_by
+   constructor still planned (0.19.0); persistent-named-collection retained as Namo's novelty
+   versus the other tools' transient group-by intermediates.
+7. ~ Namo::VERSION: /0.17.0/0.18.0/
+
+20260613
+0.17.0: + parameterised formulae — formulae with required parameters beyond (row, namo) receive arguments at access time through Row#[].
+
+1. ~ lib/Namo/Row.rb: Row#[] gains a trailing splat and forwards call-site arguments. Dispatch
+   generalises from exact arity 2 to required-parameter count via the new private
+   collection_scoped? and required_parameter_count — one required parameter or none stays
+   row-scoped, two or more call formula.call(self, @namo, *arguments). Settles the 0.15.0
+   negative-arity deferral: |row, *rest| and ->(row, namo = nil){} stay row-scoped;
+   |row, namo, *fields| is collection-scoped with optional arguments.
+2. ~ lib/Namo/Row.rb: + argument-count enforcement — the new private expected_argument_counts
+   and raise_unless_expected_arguments raise ArgumentError ("wrong number of arguments for
+   :sma (given 0, expected 2)") on the wrong count for any dimension: too few or too many for
+   a fixed-arity formula, fewer than required for a splatted one, any at all for a data
+   dimension, a row-scoped formula, or a two-arity formula. Checked before the Namo-context
+   guard, whose message generalises from "two-arity formula" to "collection-scoped formula".
+3. ~ lib/namo.rb: the no-arg values (and so coordinates and to_h) materialise via the new
+   private materialisable_dimensions, omitting formulae that require arguments (private
+   requires_arguments? and required_parameter_count); explicit asks — values(:dim),
+   coordinates(:dim), naming the dimension in a projection, selecting on it — raise through
+   Row#[]. dimensions and derived_dimensions still list the name; the empty-Namo case returns
+   [] without invoking the formula.
+4. ~ test/Namo/Row_test.rb: + "#[] parameterised formulae" describe — arity 3 and 4 receive
+   (row, namo, args...), trailing-splat forwarding (arity -3 and -4), one-required-parameter
+   procs stay row-scoped, a row-scoped formula calling a parameterised one with arguments,
+   missing-Namo-context raise; + "#[] argument-count enforcement" describe — the message
+   matrix for too few, too many, splat minimum, and arguments handed to data dimensions,
+   row-scoped, two-arity, and missing dimensions.
+5. ~ test/namo_test.rb: + "#[]= parameterised formulae" describe — resolution with arguments
+   through yielded Rows, one definition serving different fields and periods, Enumerable
+   predicates, a one-arity formula referencing a parameterised one, dimension listing, bulk
+   views omitting, explicit values/coordinates/projection/selection raises, carry through
+   contraction, selection (windowing over the filtered rows), and set operators, the
+   one-arity wrapper materialisation idiom, namo-plus-splat formulae materialising in the
+   bulk views, and the empty-Namo case.
+6. ~ README.md: + Parameterised formulae subsection under Formulae — access-time arguments,
+   the required-parameter scope rule, argument-count enforcement, materialisation behaviour,
+   and the wrapper idiom.
+7. ~ ROADMAP.md: Promote 0.17.0 to shipped with the dispatch-rule, enforcement, and
+   materialisation rationale; Current state -> 0.17.0; Summary folds in parameterised
+   formulae; next phase -> Namo::Collection (0.18.0). Date bumped.
+8. ~ COMPARISON.md: Parameterised formulae -> shipped (0.17.0), the entry noting access-time
+   arguments and argument-count enforcement. Date bumped.
+9. ~ EXAMPLES.md: The finance section's composition blocks (all three Namo stages) corrected
+   from max_by, which returns a Row, to sort_by + last(1), which returns the Namo the 0.14.0
+   block contract requires — the 1.x stage, parameterised sma included, now runs end to end
+   against this release. The finance highlight notes the parameterised formula as shipped
+   (0.17.0). Date bumped.
+10. ~ Namo::VERSION: /0.16.0/0.17.0/
+
 20260612
 0.16.0: ~ data/formula exclusivity — projection drops the formulae it materialises; * and ** raise on a data/formula name collision.
 

data/README.md

@@ -686,6 +686,36 @@ One-arity formulae are unchanged, and the two forms mix freely — a one-arity f
 
 Resolving a two-arity formula needs a Namo to window over. A `Row` constructed directly, without one, raises an `ArgumentError` naming the formula rather than letting the missing context surface as an unrelated error.
 
+#### Parameterised formulae
+
+A formula can declare parameters beyond `(row, namo)`. The arguments arrive at access time, through `Row#[]`, so one definition serves every column and every setting:
+
+```ruby
+prices[:sma] = proc do |row, namo, field, period|
+  window = namo[symbol: row[:symbol], date: ->(d){d <= row[:date]}].last(period)
+  window.sum{|r| r[field]} / window.count.to_f
+end
+
+prices.last[:sma, :close, 20]    # 20-period moving average of close
+prices.last[:sma, :volume, 50]   # 50-period moving average of volume
+```
+
+The number of *required* parameters decides a formula's calling convention. One means row-scoped, two or more means collection-scoped, and everything past the second receives the arguments given at the call site. A trailing splat or optional after `(row, namo)` makes the arguments optional — `proc{|row, namo, *fields|}` accepts any number, including none. A proc whose second parameter is optional (`->(row, namo = nil){...}`) requires only one, so it stays row-scoped.
+
+Argument counts are enforced. Asking with the wrong number — too few for the formula's parameters, too many for a fixed-arity proc, or any at all for a data dimension or an unparameterised formula — raises an `ArgumentError` stating the counts, rather than letting `nil` flow into the formula body:
+
+```ruby
+prices.last[:sma]            # ArgumentError: wrong number of arguments for :sma (given 0, expected 2)
+prices.last[:close, 20]      # ArgumentError: wrong number of arguments for :close (given 1, expected 0)
+```
+
+A formula that requires arguments can't be materialised without them. `values(:sma)`, `coordinates(:sma)`, naming `:sma` in a projection, and selecting on it all raise the same `ArgumentError`; the no-argument `values`, `coordinates`, and `to_h` omit the dimension, returning everything that can be materialised. `dimensions` and `derived_dimensions` still list it — it is queryable, with arguments. To materialise particular values, bind the arguments in a one-arity wrapper and ask for that:
+
+```ruby
+prices[:sma_close_20] = proc{|row| row[:sma, :close, 20]}
+prices[:date, :sma_close_20]   # materialises per the usual projection rule
+```
+
 ### Polymorphic `[]=`
 
 `[]=` dispatches on the type of the value assigned. A proc registers a formula, as above. Anything else broadcasts the value to every row:
@@ -895,6 +925,121 @@ 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.
 
+### Collections
+
+`Namo::Collection` is a hierarchical aggregate — a Namo that holds an Array of named Namos (its `members`) and exposes summary and detail views across them. It is the first member of the Namo family beyond `Namo` itself.
+
+The motivating case is a hierarchical budget. Each sub-assembly of a car (`powertrain`, `chassis`, `body`, ...) is a Namo with shared columns; the whole car is a `Collection` of those sub-assemblies, queryable both at summary level ("weight by assembly") and detail level ("every line item across all assemblies"):
+
+```ruby
+class Car < Namo::Collection
+  def summary(dimension, by: :assembly, reducer: :sum)
+    super
+  end
+
+  def detail(by: :assembly)
+    super
+  end
+end
+
+class SubAssembly < Namo; end
+
+powertrain = SubAssembly.new(name: :powertrain, data: [
+  {component: 'engine', weight: 200, cost: 50000},
+  {component: 'gearbox', weight: 80, cost: 20000}
+])
+chassis = SubAssembly.new(name: :chassis, data: [{component: 'frame', weight: 150, cost: 30000}])
+body    = SubAssembly.new(name: :body, data: [{component: 'panels', weight: 60, cost: 15000}])
+
+gt = Car.new
+gt << [powertrain, chassis, body]
+
+gt.summary(:weight).to_a
+# => [
+#   {assembly: :powertrain, weight: 280},
+#   {assembly: :chassis, weight: 150},
+#   {assembly: :body, weight: 60}
+# ]
+
+gt.summary(:weight).values(:weight).sum    # total weight by summing the assembly summaries
+# => 490
+
+gt.detail.values(:weight).sum              # total weight by summing every line item
+# => 490
+```
+
+`Car` overrides `summary`/`detail` only to set `by: :assembly` as the per-class default and then calls `super`. A bare `Namo::Collection.new` works equally well, defaulting `by:` to `:member` and taking it at the call site.
+
+#### Lazy detail, behaving as its line items
+
+A Collection's substance is its `members`; the inherited `@data` is a *derived view* of them. Any inherited row-operation — selection, projection, `each`, `values`, the set and composition operators — reads that view, so a Collection transparently behaves as its **detail** (the lossless union of its members' rows). Nothing has to be called first:
+
+```ruby
+gt.values(:weight)
+# => [200, 80, 150, 60]
+
+gt[component: 'engine'].values(:cost)
+# => [50000]
+```
+
+Detail is the lazy view because a Collection's rows simply *are* its members' rows; a summary is a reduction you pose against them, so it is never reached by accident — only through `summary` or `as_summary`.
+
+#### Four view methods
+
+The views come in a non-mutating pair and a mutating pair:
+
+- `summary(dimension, by:, reducer:)` and `detail(by:)` are **non-mutating** — each returns a fresh `Namo` derived from the members, leaving the Collection untouched. Use these when you want a view to keep: assign the result to a variable and operate on it independently.
+- `as_summary(dimension, by:, reducer:)` and `as_detail(by)` are **mutating** — each sets the Collection's data to the chosen view and returns `self`, for a fluent step. (`as_detail` carries no `dimension`, so its label argument is positional: `as_detail(:assembly)`.)
+
+```ruby
+gt.summary(:cost, reducer: :mean)          # a fresh Namo; gt is unchanged
+gt.as_summary(:weight)                     # gt's data becomes the summary; returns gt
+gt.as_detail(:assembly)                    # gt's data becomes the detail; returns gt
+```
+
+`reducer:` is any method the member's column responds to — `:sum` (the default) and `:mean` are typical (`:mean` via a statistics gem that adds `Array#mean`).
+
+#### Inject-iff-absent
+
+`detail(by:)` unions the members' rows and labels each with its origin, but only when that label isn't already present:
+
+- If `by` is **already a dimension** in a member's rows, the row passes through untouched — the dimension is intrinsic.
+- If `by` is **not** present, `detail` injects it (`row.merge(by => member.name)`), promoting the member's name into a dimension.
+
+This single conditional is where assembly (`<<`, members named extrinsically) and partition (`group_by`, members named by an intrinsic value — 0.19.0) meet. For an assembled Collection, `as_detail(:assembly)` is the dimension-creating step: it promotes the member name into real data and **retains** it. From then on the structure is intrinsic and round-trips are exact; the promoted dimension is removed only by explicit contraction (`gt[-:assembly]`), never automatically.
+
+#### `<<` and unnamed members
+
+`<<` accepts a single member or an array of them. A member whose `name` collides with an existing member's **replaces** it (last-write-wins), making the name → member mapping a dictionary rather than a multimap:
+
+```ruby
+gt << SubAssembly.new(name: :powertrain, data: [...])   # replaces the existing :powertrain
+gt << [front_suspension, rear_suspension]               # adds each
+```
+
+There is no insertion-time guard against unnamed members. An unnamed member is simply appended (no name to collide on) and is unfindable by `find` — the honest consequence of having no name, not an error. `find(name)` returns the member with that name, or `nil`:
+
+```ruby
+gt.find(:chassis)    # => the chassis SubAssembly
+gt.find(:missing)    # => nil
+```
+
+(`find(name)` is member lookup; it shadows `Enumerable#find` on Collections. Predicate search over rows remains available as `detect`.)
+
+#### View lifetime and liveness
+
+Materialisation is pure-live: the Collection rebuilds its data view from the current members on every `<<`, with no memoisation. So a mutation is reflected immediately — add a member, then summarise or detail, and the new member is included.
+
+A mutating `as_summary`/`as_detail` view **persists until the next `<<`**, which re-materialises detail. So `as_summary` is for "be the summary for this immediate chain":
+
+```ruby
+gt.as_summary(:weight).values(:weight)    # => [280, 150, 60]   (the summary)
+gt << front_suspension                     # re-materialises detail
+gt.values(:weight)                         # => [200, 80, 150, 60, ...]   (line items again)
+```
+
+Freeze-gated memoisation is a 2.x optimisation — opt-in via `freeze`, transparent, and never changing this observable behaviour. `group_by` (0.19.0) is the partition-side constructor for the same type: it splits a Namo into a `Collection`, the mirror of assembling one with `<<`.
+
 ## 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/Rakefile

@@ -21,7 +21,7 @@ namespace :docs do
   task :md2pdf => :md4print do
     Dir.glob('docs/*.print.md').each do |f|
       pdf = f.sub(/\.md$/, '.pdf')
-      sh "pandoc #{f} --pdf-engine=xelatex -V geometry:margin=1in -V mainfont=Charter -V monofont=Menlo -o #{pdf}"
+      sh "pandoc #{f} --pdf-engine=xelatex --include-in-header script/print.preamble.tex -V geometry:margin=1in -V mainfont=Charter -V monofont=Menlo -o #{pdf}"
     end
   end
 

data/lib/Namo/Collection.rb

@@ -0,0 +1,52 @@
+# Namo/Collection.rb
+# Namo::Collection
+
+class Namo
+  class Collection < Namo
+    attr_reader :members
+
+    def <<(*members)
+      members.flatten.each do |member|
+        @members.reject!{|existing| existing.name == member.name} unless member.name.nil?
+        @members << member
+      end
+      @data = detail.data
+      self
+    end
+
+    def find(name)
+      @members.find{|member| member.name == name} unless name.nil?
+    end
+
+    def summary(dimension, by: :member, reducer: :sum)
+      rows = @members.map do |member|
+        {by => member.name, dimension => member.values(dimension).send(reducer)}
+      end
+      Namo.new(rows)
+    end
+
+    def detail(by: :member)
+      rows = @members.flat_map do |member|
+        member.data.map{|row| row.key?(by) ? row : row.merge(by => member.name)}
+      end
+      Namo.new(rows)
+    end
+
+    def as_summary(dimension, by: :member, reducer: :sum)
+      @data = summary(dimension, by: by, reducer: reducer).data
+      self
+    end
+
+    def as_detail(by = :member)
+      @data = detail(by: by).data
+      self
+    end
+
+    private
+
+    def initialize(positional_data = nil, data: [], formulae: {}, name: nil)
+      @members = []
+      super
+    end
+  end
+end

data/lib/Namo/Row.rb

@@ -3,14 +3,15 @@
 
 class Namo
   class Row
-    def [](name)
+    def [](name, *arguments)
+      raise_unless_expected_arguments(name, arguments)
       if @formulae.key?(name)
-        case @formulae[name].arity
-        when 2
+        formula = @formulae[name]
+        if collection_scoped?(formula)
           raise_unless_namo_context(name)
-          @formulae[name].call(self, @namo)
+          formula.call(self, @namo, *arguments)
         else
-          @formulae[name].call(self)
+          formula.call(self)
         end
       else
         @row[name]
@@ -56,9 +57,32 @@ class Namo
       @namo = namo
     end
 
+    def collection_scoped?(formula)
+      required_parameter_count(formula) >= 2
+    end
+
+    def required_parameter_count(formula)
+      formula.arity >= 0 ? formula.arity : -formula.arity - 1
+    end
+
+    def expected_argument_counts(name)
+      formula = @formulae[name]
+      return [0, 0] unless formula && collection_scoped?(formula)
+      minimum = required_parameter_count(formula) - 2
+      maximum = formula.arity >= 0 ? minimum : nil
+      [minimum, maximum]
+    end
+
+    def raise_unless_expected_arguments(name, arguments)
+      minimum, maximum = expected_argument_counts(name)
+      return if arguments.length >= minimum && (maximum.nil? || arguments.length <= maximum)
+      expected = maximum.nil? ? "#{minimum}+" : minimum.to_s
+      raise ArgumentError, "wrong number of arguments for #{name.inspect} (given #{arguments.length}, expected #{expected})"
+    end
+
     def raise_unless_namo_context(name)
       unless @namo
-        raise ArgumentError, "two-arity formula #{name.inspect} requires a Namo context, but this Row has none"
+        raise ArgumentError, "collection-scoped formula #{name.inspect} requires a Namo context, but this Row has none"
       end
     end
   end

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.16.0'
+  VERSION = '0.18.0'
 end

data/lib/namo.rb

@@ -3,6 +3,7 @@
 
 require_relative './Namo/NegatedDimension'
 require_relative './Namo/Row'
+require_relative './Namo/Collection'
 require_relative './Namo/Enumerable'
 require_relative './Namo/VERSION'
 require_relative './Symbol'
@@ -28,7 +29,7 @@ class Namo
 
   def values(*dims)
     if dims.empty?
-      dimensions.each_with_object({}){|dim, hash| hash[dim] = values_for(dim)}
+      materialisable_dimensions.each_with_object({}){|dim, hash| hash[dim] = values_for(dim)}
     elsif dims.length == 1
       values_for(dims.first)
     else
@@ -246,6 +247,19 @@ class Namo
     end
   end
 
+  def materialisable_dimensions
+    dimensions.reject{|dim| requires_arguments?(dim)}
+  end
+
+  def requires_arguments?(name)
+    formula = @formulae[name]
+    !!formula && required_parameter_count(formula) > 2
+  end
+
+  def required_parameter_count(formula)
+    formula.arity >= 0 ? formula.arity : -formula.arity - 1
+  end
+
   def raise_unless_namo(other)
     unless other.is_a?(Namo)
       raise TypeError, "can't compare Namo with #{other.class}"

data/test/Namo/Collection_test.rb

@@ -0,0 +1,250 @@
+require 'minitest/autorun'
+require 'minitest-spec-context'
+
+require_relative '../../lib/namo'
+
+class Array
+  def mean
+    sum.to_f / size
+  end
+end unless [].respond_to?(:mean)
+
+class SubAssembly < Namo; end
+
+class Car < Namo::Collection
+  def summary(dimension, by: :assembly, reducer: :sum)
+    super
+  end
+
+  def detail(by: :assembly)
+    super
+  end
+end
+
+describe Namo::Collection do
+  let(:powertrain) do
+    SubAssembly.new(name: :powertrain, data: [
+      {component: 'engine', weight: 200, cost: 50000},
+      {component: 'gearbox', weight: 80, cost: 20000},
+    ])
+  end
+
+  let(:chassis) do
+    SubAssembly.new(name: :chassis, data: [{component: 'frame', weight: 150, cost: 30000}])
+  end
+
+  let(:body) do
+    SubAssembly.new(name: :body, data: [{component: 'panels', weight: 60, cost: 15000}])
+  end
+
+  let(:wheels) do
+    SubAssembly.new(name: :wheels, data: [{component: 'tyres', weight: 40, cost: 8000}])
+  end
+
+  let(:collection) do
+    Namo::Collection.new.tap{|c| c << [powertrain, chassis, body]}
+  end
+
+  describe "construction" do
+    it "starts with empty members" do
+      _(Namo::Collection.new.members).must_equal []
+    end
+  end
+
+  describe "lazy detail materialisation" do
+    it "materialises detail on a bare row-operation without a prior as_detail" do
+      _(collection.values(:weight)).must_equal [200, 80, 150, 60]
+    end
+
+    it "supports selection against the materialised detail" do
+      _(collection[component: 'engine'].values(:component)).must_equal ['engine']
+    end
+
+    it "reflects a newly added member on the next operation" do
+      before = collection.values(:weight)
+      collection << wheels
+      _(collection.values(:weight)).must_equal before + [40]
+    end
+  end
+
+  describe "#<<" do
+    it "adds a member" do
+      collection = Namo::Collection.new
+      collection << powertrain
+      _(collection.members.size).must_equal 1
+      _(collection.find(:powertrain)).must_be_same_as powertrain
+    end
+
+    it "replaces a member with a colliding name (last-write-wins)" do
+      collection = Namo::Collection.new
+      collection << powertrain
+      replacement = SubAssembly.new(name: :powertrain, data: [{component: 'hybrid', weight: 250, cost: 70000}])
+      collection << replacement
+      _(collection.members.size).must_equal 1
+      _(collection.find(:powertrain)).must_be_same_as replacement
+    end
+
+    it "adds each member from an array" do
+      collection = Namo::Collection.new
+      collection << [powertrain, chassis]
+      _(collection.members.size).must_equal 2
+    end
+
+    it "appends an unnamed member, which is unfindable by name" do
+      collection = Namo::Collection.new
+      collection << SubAssembly.new(data: [{component: 'misc', weight: 5, cost: 100}])
+      collection << SubAssembly.new(data: [{component: 'other', weight: 6, cost: 200}])
+      _(collection.members.size).must_equal 2
+    end
+
+    it "returns self" do
+      collection = Namo::Collection.new
+      _(collection << powertrain).must_be_same_as collection
+    end
+  end
+
+  describe "#find" do
+    it "returns the member with the given name" do
+      _(collection.find(:chassis)).must_be_same_as chassis
+    end
+
+    it "returns nil for an absent name" do
+      _(collection.find(:engine)).must_be_nil
+    end
+
+    it "returns nil for find(nil)" do
+      _(collection.find(nil)).must_be_nil
+    end
+
+    it "never matches an unnamed member" do
+      collection = Namo::Collection.new
+      collection << SubAssembly.new(data: [{component: 'misc', weight: 5, cost: 100}])
+      _(collection.find(nil)).must_be_nil
+    end
+  end
+
+  describe "#summary" do
+    it "reduces each member to a labelled row" do
+      summary = collection.summary(:weight)
+      _(summary.values(:member)).must_equal [:powertrain, :chassis, :body]
+      _(summary.values(:weight)).must_equal [280, 150, 60]
+    end
+
+    it "labels with a custom by dimension" do
+      summary = collection.summary(:weight, by: :assembly)
+      _(summary.values(:assembly)).must_equal [:powertrain, :chassis, :body]
+    end
+
+    it "reduces with a custom reducer" do
+      summary = collection.summary(:weight, reducer: :mean)
+      _(summary.values(:weight)).must_equal [140.0, 150.0, 60.0]
+    end
+
+    it "is non-mutating — leaves the collection's data untouched" do
+      collection.summary(:weight)
+      _(collection.values(:weight)).must_equal [200, 80, 150, 60]
+    end
+  end
+
+  describe "#detail" do
+    it "returns a plain Namo" do
+      _(collection.detail).must_be_instance_of Namo
+    end
+
+    it "unions the members' rows, injecting the by dimension when absent" do
+      detail = collection.detail
+      _(detail.values(:member)).must_equal [:powertrain, :powertrain, :chassis, :body]
+      _(detail.values(:weight)).must_equal [200, 80, 150, 60]
+    end
+
+    it "does not inject when the by dimension is already present" do
+      collection = Namo::Collection.new
+      collection << SubAssembly.new(name: :ignored, data: [{member: :preexisting, weight: 5}])
+      _(collection.detail.values(:member)).must_equal [:preexisting]
+    end
+
+    it "is non-mutating — leaves the collection's data untouched" do
+      collection.detail(by: :assembly)
+      _(collection.dimensions).wont_include :assembly
+    end
+  end
+
+  describe "live recomputation (no memoisation in 1.x)" do
+    it "reflects a mutation on the next detail call" do
+      before = collection.detail.values(:weight).size
+      collection << wheels
+      _(collection.detail.values(:weight).size).must_equal before + 1
+    end
+
+    it "reflects a mutation on the next summary call" do
+      collection << wheels
+      _(collection.summary(:weight).values(:member)).must_equal [:powertrain, :chassis, :body, :wheels]
+    end
+  end
+
+  describe "#as_summary / #as_detail" do
+    it "as_summary sets the data to the summary view and returns self" do
+      result = collection.as_summary(:weight)
+      _(result).must_be_same_as collection
+      _(collection.values(:weight)).must_equal [280, 150, 60]
+    end
+
+    it "as_detail sets the data to the detail view and returns self" do
+      collection.as_summary(:weight)
+      result = collection.as_detail
+      _(result).must_be_same_as collection
+      _(collection.values(:weight)).must_equal [200, 80, 150, 60]
+    end
+
+    it "exposes the summary's columns in dimensions immediately after as_summary" do
+      collection.as_summary(:weight)
+      _(collection.dimensions.sort).must_equal [:member, :weight].sort
+    end
+  end
+
+  describe "as_* view lifetime (rebuild-on-<<: persists until the next <<)" do
+    it "keeps the summary view across a bare row-operation" do
+      collection.as_summary(:weight)
+      _(collection.values(:weight)).must_equal [280, 150, 60]
+      _(collection[member: :powertrain].values(:weight)).must_equal [280]
+    end
+
+    it "re-materialises detail on the next <<" do
+      collection.as_summary(:weight)
+      collection << wheels
+      _(collection.values(:weight)).must_equal [200, 80, 150, 60, 40]
+    end
+  end
+
+  describe "assembly round-trip" do
+    it "injects :assembly via as_detail and retains it through a later << and as_detail" do
+      collection.as_detail(:assembly)
+      _(collection.dimensions).must_include :assembly
+      _(collection.coordinates(:assembly)).must_equal [:powertrain, :chassis, :body]
+      collection << wheels
+      collection.as_detail(:assembly)
+      _(collection.dimensions).must_include :assembly
+      _(collection.coordinates(:assembly)).must_equal [:powertrain, :chassis, :body, :wheels]
+    end
+
+    it "removes :assembly only by explicit contraction" do
+      collection.as_detail(:assembly)
+      contracted = collection[-:assembly]
+      _(contracted.dimensions).wont_include :assembly
+    end
+  end
+
+  describe "subclass with a default by:" do
+    let(:car) do
+      Car.new.tap{|c| c << [powertrain, chassis, body]}
+    end
+
+    it "uses the subclass default :assembly for summary" do
+      _(car.summary(:weight).values(:assembly)).must_equal [:powertrain, :chassis, :body]
+    end
+
+    it "uses the subclass default :assembly for detail" do
+      _(car.detail.values(:assembly)).must_equal [:powertrain, :powertrain, :chassis, :body]
+    end
+  end
+end

data/test/Namo/Row_test.rb

@@ -94,6 +94,111 @@ describe Namo::Row do
     end
   end
 
+  describe "#[] parameterised formulae" do
+    let(:namo) do
+      Namo.new([row_data])
+    end
+
+    let(:contextual_row) do
+      Namo::Row.new(row_data, formulae, namo)
+    end
+
+    it "calls an arity-3 formula with the Row, the yielding Namo, and one argument" do
+      seen = nil
+      formulae[:scaled] = ->(r, n, factor){seen = [r, n, factor]; r[:price] * factor}
+      _(contextual_row[:scaled, 3]).must_equal 30.0
+      _(seen[0]).must_be_same_as contextual_row
+      _(seen[1].equal?(namo)).must_equal true
+      _(seen[2]).must_equal 3
+    end
+
+    it "calls an arity-4 formula with two arguments" do
+      formulae[:metric] = ->(r, n, field, factor){r[field] * factor}
+      _(contextual_row[:metric, :quantity, 2]).must_equal 200
+    end
+
+    it "forwards a trailing splat's arguments past a required one (arity -4)" do
+      formulae[:dim] = proc{|r, n, field, *rest| [field, rest]}
+      _(contextual_row[:dim, :price]).must_equal [:price, []]
+      _(contextual_row[:dim, :price, 1, 2]).must_equal [:price, [1, 2]]
+    end
+
+    it "treats a splat directly after namo as collection-scoped taking any number of arguments (arity -3)" do
+      formulae[:dim] = proc{|r, n, *rest| rest}
+      _(contextual_row[:dim]).must_equal []
+      _(contextual_row[:dim, 1, 2, 3]).must_equal [1, 2, 3]
+    end
+
+    it "keeps a one-required-parameter proc row-scoped regardless of trailing optionals" do
+      seen = :unset
+      formulae[:dim] = ->(r, n = :fallback){seen = n; 1}
+      contextual_row[:dim]
+      _(seen).must_equal :fallback
+    end
+
+    it "lets a row-scoped formula call a parameterised formula with arguments" do
+      formulae[:metric] = ->(r, n, field, factor){r[field] * factor}
+      formulae[:double_quantity] = ->(r){r[:metric, :quantity, 2]}
+      _(contextual_row[:double_quantity]).must_equal 200
+    end
+
+    it "raises ArgumentError naming the formula when a parameterised formula has no Namo context" do
+      formulae[:metric] = ->(r, n, field){r[field]}
+      error = _(proc{row[:metric, :price]}).must_raise ArgumentError
+      _(error.message).must_match(/metric/)
+    end
+  end
+
+  describe "#[] argument-count enforcement" do
+    let(:namo) do
+      Namo.new([row_data])
+    end
+
+    let(:contextual_row) do
+      Namo::Row.new(row_data, formulae, namo)
+    end
+
+    it "raises when a parameterised formula is given too few arguments" do
+      formulae[:metric] = ->(r, n, field, period){r[field] * period}
+      error = _(proc{contextual_row[:metric, :price]}).must_raise ArgumentError
+      _(error.message).must_equal "wrong number of arguments for :metric (given 1, expected 2)"
+    end
+
+    it "raises when a fixed-arity parameterised formula is given too many arguments" do
+      formulae[:metric] = ->(r, n, field){r[field]}
+      error = _(proc{contextual_row[:metric, :price, 20]}).must_raise ArgumentError
+      _(error.message).must_equal "wrong number of arguments for :metric (given 2, expected 1)"
+    end
+
+    it "raises when a splatted parameterised formula is given fewer than its required arguments" do
+      formulae[:metric] = proc{|r, n, field, *rest| r[field]}
+      error = _(proc{contextual_row[:metric]}).must_raise ArgumentError
+      _(error.message).must_equal "wrong number of arguments for :metric (given 0, expected 1+)"
+    end
+
+    it "raises when arguments are given for a data dimension" do
+      error = _(proc{row[:price, 20]}).must_raise ArgumentError
+      _(error.message).must_equal "wrong number of arguments for :price (given 1, expected 0)"
+    end
+
+    it "raises when arguments are given for a row-scoped formula" do
+      formulae[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      error = _(proc{row[:revenue, 20]}).must_raise ArgumentError
+      _(error.message).must_equal "wrong number of arguments for :revenue (given 1, expected 0)"
+    end
+
+    it "raises when arguments are given for a two-arity formula" do
+      formulae[:row_count] = ->(r, n){n.count}
+      error = _(proc{contextual_row[:row_count, 1]}).must_raise ArgumentError
+      _(error.message).must_equal "wrong number of arguments for :row_count (given 1, expected 0)"
+    end
+
+    it "raises when arguments are given for a missing dimension" do
+      error = _(proc{row[:missing, 1]}).must_raise ArgumentError
+      _(error.message).must_equal "wrong number of arguments for :missing (given 1, expected 0)"
+    end
+  end
+
   describe "#match?" do
     it "matches a single value" do
       _(row.match?(product: 'Widget')).must_equal true

data/test/namo_test.rb

@@ -797,6 +797,129 @@ describe Namo do
     end
   end
 
+  describe "#[]= parameterised formulae" do
+    let(:price_data) do
+      [
+        {symbol: 'AAA', date: 1, close: 10.0, volume: 100},
+        {symbol: 'AAA', date: 2, close: 20.0, volume: 200},
+        {symbol: 'AAA', date: 3, close: 30.0, volume: 300},
+      ]
+    end
+
+    let(:prices) do
+      Namo.new(price_data)
+    end
+
+    # A parameterised moving average: the field and the window length arrive at
+    # access time, so one definition serves every column and every period.
+    let(:sma) do
+      proc do |row, namo, field, period|
+        window = namo[symbol: row[:symbol], date: ->(d){d <= row[:date]}].last(period)
+        window.sum{|r| r[field]} / window.count.to_f
+      end
+    end
+
+    it "resolves with arguments through a yielded Row" do
+      prices[:sma] = sma
+      _(prices.first[:sma, :close, 2]).must_equal 10.0
+      _(prices.last[:sma, :close, 2]).must_equal 25.0
+    end
+
+    it "serves different fields and periods from one definition" do
+      prices[:sma] = sma
+      _(prices.last[:sma, :close, 3]).must_equal 20.0
+      _(prices.last[:sma, :volume, 2]).must_equal 250.0
+    end
+
+    it "resolves inside an Enumerable predicate" do
+      prices[:sma] = sma
+      result = prices.select{|row| row[:sma, :close, 2] > 12.0}
+      _(result).must_be_kind_of Namo
+      _(result.values(:date)).must_equal [2, 3]
+    end
+
+    it "lets a one-arity formula reference a parameterised formula with arguments" do
+      prices[:sma] = sma
+      prices[:rising] = proc{|row| row[:sma, :close, 1] > row[:sma, :close, 3]}
+      _(prices.values(:rising)).must_equal [false, true, true]
+    end
+
+    it "lists a parameterised dimension in dimensions and derived_dimensions" do
+      prices[:sma] = sma
+      _(prices.dimensions).must_equal [:symbol, :date, :close, :volume, :sma]
+      _(prices.derived_dimensions).must_equal [:sma]
+    end
+
+    it "omits a parameterised dimension from the no-arg values, coordinates, and to_h" do
+      prices[:sma] = sma
+      _(prices.values.keys).must_equal [:symbol, :date, :close, :volume]
+      _(prices.coordinates.keys).must_equal [:symbol, :date, :close, :volume]
+      _(prices.to_h.keys).must_equal [:symbol, :date, :close, :volume]
+    end
+
+    it "raises when values is asked for a parameterised dimension by name" do
+      prices[:sma] = sma
+      error = _(proc{prices.values(:sma)}).must_raise ArgumentError
+      _(error.message).must_equal "wrong number of arguments for :sma (given 0, expected 2)"
+    end
+
+    it "raises when coordinates is asked for a parameterised dimension by name" do
+      prices[:sma] = sma
+      _(proc{prices.coordinates(:sma)}).must_raise ArgumentError
+    end
+
+    it "raises when a projection names a parameterised dimension" do
+      prices[:sma] = sma
+      _(proc{prices[:date, :sma]}).must_raise ArgumentError
+    end
+
+    it "raises when a selection selects on a parameterised dimension" do
+      prices[:sma] = sma
+      _(proc{prices[sma: ->(v){v > 12.0}]}).must_raise ArgumentError
+    end
+
+    it "carries a parameterised formula through contraction" do
+      prices[:sma] = sma
+      contracted = prices[-:volume]
+      _(contracted.derived_dimensions).must_equal [:sma]
+      _(contracted.first[:sma, :close, 2]).must_equal 10.0
+    end
+
+    it "carries a parameterised formula through selection, windowing over the filtered rows" do
+      prices[:sma] = sma
+      filtered = prices[date: 2..3]
+      _(filtered.first[:sma, :close, 2]).must_equal 20.0
+    end
+
+    it "materialises through a one-arity wrapper that binds the arguments" do
+      prices[:sma] = sma
+      prices[:sma_close_2] = proc{|row| row[:sma, :close, 2]}
+      _(prices.values(:sma_close_2)).must_equal [10.0, 15.0, 25.0]
+      _(prices[:date, :sma_close_2].values(:sma_close_2)).must_equal [10.0, 15.0, 25.0]
+    end
+
+    it "includes a namo-plus-splat formula in the bulk views, called with no extra arguments" do
+      prices[:flexible] = proc{|row, namo, *rest| rest.empty? ? namo.count : rest.sum}
+      _(prices.values.keys).must_include :flexible
+      _(prices.values(:flexible)).must_equal [3, 3, 3]
+      _(prices.first[:flexible, 1, 2, 4]).must_equal 7
+    end
+
+    it "carries a parameterised formula through a set-operator result" do
+      a = Namo.new(price_data.take(2))
+      b = Namo.new([price_data.last])
+      a[:sma] = sma
+      _((a + b).last[:sma, :close, 2]).must_equal 25.0
+    end
+
+    it "returns [] for a parameterised dimension on an empty Namo without invoking the formula" do
+      invoked = false
+      empty = Namo.new([], formulae: {sma: ->(row, namo, field, period){invoked = true; 0}})
+      _(empty.values(:sma)).must_equal []
+      _(invoked).must_equal false
+    end
+  end
+
   describe "data/formula exclusivity" do
     context "projection" do
       let(:price_data) do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: namo
 version: !ruby/object:Gem::Version
-  version: 0.16.0
+  version: 0.18.0
 platform: ruby
 authors:
 - thoran
@@ -64,6 +64,7 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- lib/Namo/Collection.rb
 - lib/Namo/Enumerable.rb
 - lib/Namo/NegatedDimension.rb
 - lib/Namo/Row.rb
@@ -71,6 +72,7 @@ files:
 - lib/Symbol.rb
 - lib/namo.rb
 - namo.gemspec
+- test/Namo/Collection_test.rb
 - test/Namo/NegatedDimension_test.rb
 - test/Namo/Row_test.rb
 - test/Symbol_test.rb