namo 0.15.0 → 0.17.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7d2d5b27fc7c414edd9d13ac80d87bc6f99c87b2f94a42b8f192c3e5a4f08daa
-  data.tar.gz: 91ff974cb3c20802cf0afea77563211a1d29abda66bf9960ed18611fbaf09410
+  metadata.gz: f84d86032e9397e8db4a4d7a4150474c30215cf9339ec2158a38802aad1a4d49
+  data.tar.gz: 830b874e04b36acd7ab848351419ed5ceb848e0108b95602184b7e6131812e01
 SHA512:
-  metadata.gz: f309aa497bde5bd05083f844f8d123257917da3e74abe07e4e18a8aff3dd362ab0e2c2b4b6df0791cb3a1b55ea53f9f7914a89eda74c2d158c0d7e5cf1e6b358
-  data.tar.gz: 62040149299672f673de4216cc7123e78e0135902d5a5ad3c948e74e7d2906b184b9ac6a6e84238f000d85a63b3ccc0b6dc894c3cdb74a65fb6ec1d7df0d6e33
+  metadata.gz: 1b409a5004f78619ea60186404e6f156fadbc660755cc9fc3c64cfe8a028a3ffdd7bb35dd252510ece1814674f0b02af7b347b1ea42c1280390e7d7a982f0de0
+  data.tar.gz: 15c2c28dafa605ee5a93e5ebb3bee4e5a1f8301dca7cfb11675e1f197db62052975a0f9b74a9096638062b4d40cd85b5752ce5e52c3b0c5f39463fed421aec6c

data/CHANGELOG

@@ -1,6 +1,100 @@
 CHANGELOG
 _________
 
+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.
+
+1. ~ lib/namo.rb: Namo#[]'s positive-projection branch carries @formulae minus the projected
+   derived names — naming a derived dimension materialises it (stored values, computed against
+   the yielding Namo, windowed over any same-call selection) and drops the formula; omitted
+   formulae carry live and recompute from the result's own rows. Contraction and selection-only
+   calls are unchanged. The projection list is the materialise/live selector.
+2. ~ lib/namo.rb: Namo#* and Namo#** raise ArgumentError via the new private
+   raise_unless_data_formula_exclusivity when one operand's data dimension is the other's
+   derived dimension, block and no-block forms alike. Formula-vs-formula stays left-wins; the
+   set operators need no guard (matching-data-dimensions blocks the asymmetric case); the
+   constructor stays unguarded.
+3. ~ test/namo_test.rb: + "data/formula exclusivity" describe — access-path agreement on a
+   materialised dimension, dimension-listing, dependent-formula carry, omitted-formula
+   liveness, live-without-inputs caveat, two-arity windowing at materialisation,
+   contraction/selection unchanged, subclass type, composition collision raises (both
+   directions, both operators, block forms), left-wins formula merge, contraction-first
+   resolution.
+4. ~ test/namo_test.rb: + "range selection" context under #[] — basic range, beginless and
+   endless forms, range composed with projection, range on a formula-defined dimension
+   (Row_test holds the predicate matrix; these pin the Namo-level wiring).
+5. ~ README.md: + Projection of derived dimensions subsection under Formulae (naming
+   materialises, omitting carries live); data/formula collision sentences under Composition
+   and Cartesian product.
+6. ~ ROADMAP.md: Promote 0.16.0 to shipped; Current state -> 0.16.0; Summary folds in
+   exclusivity; next phase -> 0.17.0. window.length -> window.count and n.length -> n.count
+   in the remaining future-release examples (0.17.0, 2.x, 4.x) — Namo has no #length,
+   extending the 0.15.0 correction.
+7. ~ COMPARISON.md: Repoint the pre-renumbering planned markers to what shipped — proc-based,
+   regex-based, and mixed selection -> shipped (0.8.0); Enumerable methods return Namos ->
+   shipped (0.11.0), with the entry summary's parity sentence and the Sorting entry's
+   "as of 0.14.0" corrected to 0.11.0; values and to_h -> shipped (0.7.0). Aspect classes ->
+   not planned, the entry rewritten to record 0.7.0's plain-return-types decision (Namo#===
+   and subclassing cover case dispatch; a Matcher factory can serve a finer split later).
+   Aggregation repointed from 2.x to group_by returning a Namo::Collection at 0.19.0 (gated
+   on Collection at 0.18.0), with summary/members examples; bare names stay 2.x. Parameterised
+   formulae stays planned (0.17.0), its example's window.length -> window.count.
+8. ~ EXAMPLES.md: + Epidemiology / public health section — a cross-row (two-arity) rolling
+   weekly average in the four-stage format (Polars, then Namo 1.x/2.x/3.x), with the
+   (row, namo) window over the yielding Namo and a one-arity formula referencing the
+   two-arity one. window.length -> window.count in the finance 1.x and 2.x stages. Date
+   bumped to 20260612.
+9. ~ Namo::VERSION: /0.15.0/0.16.0/
+
 20260612
 0.15.0: + two-arity formulae — procs with arity 2 receive (row, namo) for cross-row computation.
 

data/README.md

@@ -353,7 +353,7 @@ ohlcv * fundamentals
 
 Inner-join semantics: unmatched rows from either side are dropped. Output dimensions are `self.data_dimensions` followed by `other.data_dimensions` exclusive to other. Duplicates on shared coordinates are preserved multiplicatively — output multiplicity is the product of input multiplicities on each matching key.
 
-The two Namos must have at least one shared data dimension. No overlap raises an `ArgumentError` — the asymmetry with `**` is deliberate, and falling through to a Cartesian product would silently turn a logic error into a large pile of nonsense rows. Formulae merge from both sides; the left-hand side wins on conflict.
+The two Namos must have at least one shared data dimension. No overlap raises an `ArgumentError` — the asymmetry with `**` is deliberate, and falling through to a Cartesian product would silently turn a logic error into a large pile of nonsense rows. Formulae merge from both sides; the left-hand side wins on conflict. A name that is data on one side and a formula on the other also raises an `ArgumentError` — the operands disagree about what the name means, with no last-write order to appeal to — so resolve before composing: `audited[-:margin] * modelled`.
 
 #### Conditional join
 
@@ -404,7 +404,7 @@ products ** quarters
 
 Output has `self.data.length * other.data.length` rows. Output dimensions are `self.data_dimensions + other.data_dimensions`, in operand order. Duplicates are preserved multiplicatively.
 
-The two Namos must have **no** shared data dimensions — the precondition is the mirror image of `*`. Any overlap raises an `ArgumentError`; allowing it would produce rows with the same dimension named twice. Formulae merge from both sides; the left-hand side wins on conflict.
+The two Namos must have **no** shared data dimensions — the precondition is the mirror image of `*`. Any overlap raises an `ArgumentError`; allowing it would produce rows with the same dimension named twice. Formulae merge from both sides; the left-hand side wins on conflict, and a data/formula name collision between the operands raises, as for `*`.
 
 The visual relationship is intentional: `*` is the filtered version, `**` is the explosive version — more sigil, more output.
 
@@ -644,6 +644,20 @@ sales[product: 'Widget'][:revenue, :quarter]
 
 Formulae carry through selection — a filtered Namo instance remembers its formulae.
 
+#### Projection of derived dimensions
+
+Naming a derived dimension in a projection asks for its values: they are computed against the source and stored in the result's rows, and the formula is dropped — the name is a data dimension of the result. Omitting it carries the formula live, recomputing from the result's own rows on every access:
+
+```ruby
+sales[:price, :quantity, :revenue].derived_dimensions
+# => [] — :revenue is stored values, a snapshot taken at projection
+
+sales[:price, :quantity].derived_dimensions
+# => [:revenue] — :revenue recomputes from the projected rows on every access
+```
+
+The projection list is the selector: name a derived dimension for a snapshot, omit it to keep it as computation. A carried formula whose inputs the projection dropped breaks on access — the same caveat as contracting away a formula's inputs.
+
 #### Cross-row formulae
 
 A formula's arity selects its calling convention. A proc with **one** parameter receives the row, as above. A proc with **two** parameters receives `(row, namo)`, where `namo` is the Namo the row belongs to — so the formula can reach beyond the current row to the rest of the collection. That's what cross-row computation needs: moving windows, ranks, running totals, anything whose value depends on the row's neighbours.
@@ -672,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:

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/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.15.0'
+  VERSION = '0.17.0'
 end

data/lib/namo.rb

@@ -28,7 +28,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
@@ -71,7 +71,8 @@ class Namo
         rows.map(&:to_h)
       end
     )
-    self.class.new(projected, formulae: @formulae.dup)
+    carried = positive.any? ? @formulae.reject{|name, _| positive.include?(name)} : @formulae.dup
+    self.class.new(projected, formulae: carried)
   end
 
   def []=(name, value)
@@ -118,6 +119,7 @@ class Namo
   def *(other, &block)
     raise_unless_namo(other)
     raise_unless_shared_data_dimensions(other)
+    raise_unless_data_formula_exclusivity(other)
     shared = data_dimensions & other.data_dimensions
     combined_data = []
     @data.each do |left_row|
@@ -136,6 +138,7 @@ class Namo
   def **(other, &block)
     raise_unless_namo(other)
     raise_unless_disjoint_data_dimensions(other)
+    raise_unless_data_formula_exclusivity(other)
     combined_data = []
     @data.each do |left_row|
       if block
@@ -243,6 +246,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}"
@@ -266,4 +282,11 @@ class Namo
       raise ArgumentError, "dimensions in common, need no common dimensions: #{data_dimensions} vs #{other.data_dimensions}"
     end
   end
+
+  def raise_unless_data_formula_exclusivity(other)
+    collisions = (data_dimensions & other.derived_dimensions) | (derived_dimensions & other.data_dimensions)
+    if collisions.any?
+      raise ArgumentError, "name collision between data and formulae: #{collisions.inspect}"
+    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

@@ -491,6 +491,36 @@ describe Namo do
       end
     end
 
+    context "range selection" do
+      it "selects rows whose value falls within the range" do
+        result = sales[price: 5.0..15.0]
+        _(result.to_a.count).must_equal 2
+        _(result.to_a.map{|row| row[:product]}).must_equal ['Widget', 'Widget']
+      end
+
+      it "supports beginless and endless ranges" do
+        _(sales[price: ..15.0].to_a.count).must_equal 2
+        _(sales[quantity: 100..].to_a.count).must_equal 2
+      end
+
+      it "composes with projection in a single call" do
+        result = sales[:product, :quantity, quantity: 50..120]
+        _(result.to_a).must_equal [
+          {product: 'Widget', quantity: 100},
+          {product: 'Gadget', quantity: 60}
+        ]
+      end
+
+      it "selects on a formula-defined dimension" do
+        sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+        result = sales[revenue: 1200.0..]
+        _(result.to_a).must_equal [
+          {product: 'Widget', quarter: 'Q2', price: 10.0, quantity: 150},
+          {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60}
+        ]
+      end
+    end
+
     context "mixed proc and regex selection" do
       it "combines a proc and a regex across dimensions" do
         result = sales[product: /^W/, quantity: ->(v){v > 100}]
@@ -767,6 +797,299 @@ 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
+        [
+          {symbol: 'AAA', date: 1, close: 10.0},
+          {symbol: 'AAA', date: 2, close: 20.0},
+          {symbol: 'AAA', date: 3, close: 30.0},
+        ]
+      end
+
+      let(:prices) do
+        Namo.new(price_data)
+      end
+
+      let(:sma) do
+        ->(row, namo){
+          window = namo[symbol: row[:symbol], date: ->(d){d <= row[:date]}]
+          window.values(:close).sum / window.count.to_f
+        }
+      end
+
+      it "agrees across all access paths on a materialised dimension" do
+        prices[:sma] = sma
+        projected = prices[:date, :sma]
+        _(projected.values(:sma)).must_equal [10.0, 15.0, 20.0]
+        _(projected.first[:sma]).must_equal projected.values(:sma).first
+        _(projected[sma: ->(v){v > 12.0}].values(:date)).must_equal [2, 3]
+      end
+
+      it "lists a materialised dimension as data, not derived, exactly once" do
+        prices[:sma] = sma
+        projected = prices[:date, :sma]
+        _(projected.data_dimensions).must_include :sma
+        _(projected.derived_dimensions).wont_include :sma
+        _(projected.dimensions.count(:sma)).must_equal 1
+      end
+
+      it "carries a dependent formula not named in the projection, resolving off the materialised column" do
+        prices[:sma] = sma
+        prices[:double_sma] = ->(row){row[:sma] * 2}
+        projected = prices[:date, :sma]
+        _(projected.derived_dimensions).must_equal [:double_sma]
+        _(projected.values(:double_sma)).must_equal [20.0, 30.0, 40.0]
+      end
+
+      it "carries an omitted formula live, recomputing from the result's own rows" do
+        sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+        projected = sales[:price, :quantity]
+        _(projected.derived_dimensions).must_equal [:revenue]
+        _(projected.values(:revenue)).must_equal [1000.0, 1500.0, 1000.0, 1500.0]
+        projected.data.first[:quantity] = 200
+        _(projected.values(:revenue).first).must_equal 2000.0
+      end
+
+      it "breaks on access when a carried formula's inputs were dropped (caveat emptor)" do
+        sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+        projected = sales[:product]
+        _(projected.derived_dimensions).must_equal [:revenue]
+        _ { projected.values(:revenue) }.must_raise NoMethodError
+      end
+
+      it "materialises a two-arity formula windowed over the yielding Namo" do
+        prices[:sma] = sma
+        _(prices[:date, :sma].values(:sma)).must_equal [10.0, 15.0, 20.0]
+      end
+
+      it "windows a two-arity materialisation over a same-call selection" do
+        prices[:sma] = sma
+        projected = prices[:date, :sma, date: 2..3]
+        _(projected.values(:sma)).must_equal [20.0, 25.0]
+      end
+
+      it "carries all formulae through a selection-only call" do
+        sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+        result = sales[price: ..15.0]
+        _(result.derived_dimensions).must_equal [:revenue]
+        _(result.values(:revenue)).must_equal [1000.0, 1500.0]
+      end
+
+      it "carries all formulae through contraction" do
+        sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+        result = sales[-:quarter]
+        _(result.derived_dimensions).must_equal [:revenue]
+        _(result.values(:revenue)).must_equal [1000.0, 1500.0, 1000.0, 1500.0]
+      end
+
+      it "returns pure materialised values and empty formulae when only derived names are projected" do
+        prices[:sma] = sma
+        projected = prices[:sma]
+        _(projected.to_a).must_equal [{sma: 10.0}, {sma: 15.0}, {sma: 20.0}]
+        _(projected.formulae).must_equal({})
+      end
+
+      it "returns an instance of self's class" do
+        subclass = Class.new(Namo)
+        namo = subclass.new([{x: 1}])
+        namo[:double] = ->(row){row[:x] * 2}
+        _(namo[:double].class).must_equal subclass
+      end
+    end
+
+    context "composition" do
+      let(:audited) do
+        Namo.new([
+          {symbol: 'BHP', margin: 0.3},
+          {symbol: 'RIO', margin: 0.25}
+        ])
+      end
+
+      let(:modelled) do
+        namo = Namo.new([
+          {symbol: 'BHP', price: 10.0, cost: 6.0},
+          {symbol: 'RIO', price: 20.0, cost: 16.0}
+        ])
+        namo[:margin] = proc{|r| (r[:price] - r[:cost]) / r[:price]}
+        namo
+      end
+
+      let(:audited_orders) do
+        Namo.new([{order: 'A', margin: 0.3}])
+      end
+
+      let(:modelled_tiers) do
+        namo = Namo.new([{tier: 'light', price: 10.0, cost: 6.0}])
+        namo[:margin] = proc{|r| (r[:price] - r[:cost]) / r[:price]}
+        namo
+      end
+
+      it "raises on * when self's data dimension is other's derived dimension" do
+        _ { audited * modelled }.must_raise ArgumentError
+      end
+
+      it "raises on * when self's derived dimension is other's data dimension" do
+        _ { modelled * audited }.must_raise ArgumentError
+      end
+
+      it "raises on ** when self's data dimension is other's derived dimension" do
+        _ { audited_orders ** modelled_tiers }.must_raise ArgumentError
+      end
+
+      it "raises on ** when self's derived dimension is other's data dimension" do
+        _ { modelled_tiers ** audited_orders }.must_raise ArgumentError
+      end
+
+      it "raises in the block forms of both operators" do
+        _ { audited.*(modelled){|row, candidates| candidates} }.must_raise ArgumentError
+        _ { audited_orders.**(modelled_tiers){|row, candidates| candidates} }.must_raise ArgumentError
+      end
+
+      it "names the colliding dimensions in the message" do
+        err = _ { audited * modelled }.must_raise ArgumentError
+        _(err.message).must_match(/name collision between data and formulae/)
+        _(err.message).must_include ':margin'
+      end
+
+      it "does not raise on a formula-vs-formula collision — left wins" do
+        left = Namo.new([{symbol: 'BHP', close: 42.5}])
+        right = Namo.new([{symbol: 'BHP', pe: 14.5}])
+        left[:margin] = proc{|r| :left}
+        right[:margin] = proc{|r| :right}
+        _((left * right).values(:margin)).must_equal [:left]
+      end
+
+      it "composes after explicit resolution by contraction" do
+        result = audited[-:margin] * modelled
+        _(result.values(:margin)).must_equal [0.4, 0.2]
+      end
+    end
+  end
+
   describe "#each" do
     it "yields Row objects" do
       rows = []

metadata

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