namo 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9d29843b2d9895ba401fa013ea83753f548458bc09bcd8e61218400f81950e33
-  data.tar.gz: 6b8772e13cd773d41ae4cabddb019bddb533cbc9a24ece7729977543e462a30c
+  metadata.gz: c0aa48a727f9cc67fae8eea94dcfa8227c66a34aa8918ac65e30b33b7685c82b
+  data.tar.gz: c8f634b5c41f35337fb843d286edf80cbdabef951b076dd36533f5a2531c3715
 SHA512:
-  metadata.gz: 22c4c03943617b1ec56e45ace4722019e6d54bb12f9b30fb3e2b85eebce132477a380ccde5529ea65782be03f060abd7507ebbfbe8b06d3c8ad10d7b90319061
-  data.tar.gz: 17e0163a3353024bec9826d5fc95773893d8195dbb7efe87ff7e814da7c74ca1391f168ca10025a6deb9fcd44e7ecae8fc3a10c44f29f9ef1e2018a0de96aa97
+  metadata.gz: 9b196446a0d02dc61790a25ea416bfebdd591020cfd6ef89430f5e8b9d8bd1239cc265bca83f0cd6dde4d42ce3c3927074ac69e1d4e79ae88db667b95caeadf3
+  data.tar.gz: 3680f44daa8e1e78921d1d286c7f436947b6e436c9308d62038c17a1f9658ae4ccc23196afb2eb44e6b3efb41398ab1b39d8cf3bf813f87c24df12c7cb975586

data/CHANGELOG

@@ -1,6 +1,22 @@
 CHANGELOG
 _________
 
+20260520
+0.7.0: + derived-dimension surfacing, lazy single-column access, live views
+
+1. + Namo#data_dimensions: Returns the storage dimensions as a plain Array (keys of the first row).
+2. + Namo#derived_dimensions: Returns the formula names as a plain Array.
+3. + Namo#values(*dims): Per-dimension full sequences (duplicates preserved, in row order). With no args, returns a Hash {dim => sequence} across the queryable namespace. With one arg, lazily computes and returns just that column as an Array. With multiple args, returns a subset Hash containing each requested dimension. Unknown dimensions propagate as nil per row, matching Row#[] and Namo#[] selection conventions — values(:unknown) returns an Array of nils; values(:known, :unknown) returns {known: [...], unknown: [nil, ...]}.
+4. + Namo#coordinates(*dims): Per-dimension unique-value sets. Same argument shape as #values; coordinates(dim) == values(dim).uniq. Unknown dimensions therefore appear as [nil].
+5. + Namo#to_h: Alias for the full values Hash.
+6. ~ Namo#dimensions: Now covers the queryable namespace (storage + derived) instead of storage-only. Return type stays a plain Array. Memoisation removed: every call recomputes from current state (live view).
+7. ~ Namo#coordinates: Memoisation removed (was @coordinates ||= ...). Now covers the queryable namespace; coordinates(:derived_dim) and coordinates[:derived_dim] work, evaluating the formula across all rows. New positional-args API supports lazy single-column access.
+8. ~ Namo#canonical_data: Sorts by data_dimensions to preserve 0.6.0 row-equality semantics under the broader dimensions definition.
+9. /raise_unless_matching_dimensions/raise_unless_matching_data_dimensions/: Private helper renamed to reflect what it actually compares.
+10. ~ test/namo_test.rb: + Tests for #data_dimensions, #derived_dimensions, the no-arg/single-arg/multi-arg forms of #values and #coordinates, derived-dimension surfacing in #dimensions, #to_h, the coordinates(dim) == values(dim).uniq consistency property, and live-view semantics (added rows / formulae reflected on next call).
+11. ~ Rakefile: + -V mainfont=Charter -V monofont=Menlo on pandoc invocation in docs:md2pdf, for a cleaner serif body font and so code spans containing Unicode math glyphs (e.g. ∅) render correctly under xelatex.
+12. ~ Namo::VERSION: /0.6.0/0.7.0/
+
 20260511
 0.6.0: + equality, pattern-match, and subset/superset operators
 

data/README.md

@@ -4,7 +4,7 @@ Named dimensional data for Ruby.
 
 Namo is a Ruby library for working with multi-dimensional data using named dimensions. It infers dimensions and coordinates from plain arrays of hashes — the same shape you get from databases, CSV files, JSON, and YAML — so there's no reshaping step.
 
-The design rests on a few stances: every hash key is a dimension and none is privileged; formulae attach to a Namo alongside stored data and re-evaluate on each access; the operators that combine Namos all take Namos and return Namos, so analytical pipelines close; and the formula mechanism is type-agnostic — strings, dates, booleans, and arbitrary Ruby objects work as readily as numbers.
+The design rests on a few stances: every hash key is a dimension and none is privileged as a coordinate or value; formulae attach to a Namo alongside data and re-evaluate on each access, appearing as derived dimensions alongside the data dimensions; operators that combine Namos all take Namos and return Namos, so analytical pipelines close; and the formula mechanism is type-agnostic — strings, dates, booleans, and arbitrary Ruby objects work as readily as numbers.
 
 ## Installation
 
@@ -383,7 +383,7 @@ sales[:product, :quarter, :revenue]
 # ]>
 ```
 
-Formulae aren't materialised into stored columns — they re-evaluate on every access. A `:revenue` value reflects the current `:price` and `:quantity` at the moment you ask for it, so derived values stay in sync with whatever the underlying data is doing.
+Formulae aren't materialised into row data — they re-evaluate on every access. A `:revenue` value reflects the current `:price` and `:quantity` at the moment you ask for it, so derived values stay in sync with whatever the underlying data is doing.
 
 Formulae compose:
 
@@ -412,6 +412,78 @@ sales[product: 'Widget'][:revenue, :quarter]
 
 Formulae carry through selection — a filtered Namo instance remembers its formulae.
 
+### Coordinates and values
+
+`dimensions` covers the *queryable namespace* — every name you can ask for, whether it lives in the row data or is computed by a formula. Once formulae are defined, they appear alongside data dimensions:
+
+```ruby
+sales[:revenue] = proc{|row| row[:price] * row[:quantity]}
+
+sales.dimensions
+# => [:product, :quarter, :price, :quantity, :revenue]
+
+sales.data_dimensions
+# => [:product, :quarter, :price, :quantity]
+
+sales.derived_dimensions
+# => [:revenue]
+```
+
+`coordinates` gives the unique values per dimension, including derived ones:
+
+```ruby
+sales.coordinates[:product]
+# => ['Widget', 'Gadget']
+
+sales.coordinates[:revenue]
+# => [1000.0, 1500.0]
+```
+
+`values` gives the full per-row sequence — duplicates preserved, row order preserved:
+
+```ruby
+sales.values[:product]
+# => ['Widget', 'Widget', 'Gadget', 'Gadget']
+
+sales.values[:revenue]
+# => [1000.0, 1500.0, 1000.0, 1500.0]
+```
+
+Both `coordinates` and `values` accept positional arguments. With no args they return a Hash across the queryable namespace; with one arg they lazily compute and return just that column as an Array; with multiple args they return a subset Hash containing just the requested columns:
+
+```ruby
+sales.values(:product)
+# => ['Widget', 'Widget', 'Gadget', 'Gadget']
+
+sales.values(:product, :quarter)
+# => {
+#   product: ['Widget', 'Widget', 'Gadget', 'Gadget'],
+#   quarter: ['Q1', 'Q2', 'Q1', 'Q2']
+# }
+
+sales.coordinates(:revenue)
+# => [1000.0, 1500.0]
+```
+
+Single-arg access is lazy: `sales.values(:revenue)` evaluates the formula only across the rows of `:revenue`, without materialising the other columns. The bracket form (`sales.values[:revenue]`) still works through ordinary Hash lookup but pays for the full materialisation up front.
+
+`coordinates` is `values` with `.uniq` applied per column — `coordinates(dim) == values(dim).uniq` holds for every dimension.
+
+`to_h` is the Ruby-conventional alias for the full `values` Hash:
+
+```ruby
+sales.to_h
+# => {
+#   product: ['Widget', 'Widget', 'Gadget', 'Gadget'],
+#   quarter: ['Q1', 'Q2', 'Q1', 'Q2'],
+#   price: [10.0, 10.0, 25.0, 25.0],
+#   quantity: [100, 150, 40, 60],
+#   revenue: [1000.0, 1500.0, 1000.0, 1500.0]
+# }
+```
+
+Unknown dimensions propagate `nil` per row — `values(:missing)` returns `[nil, nil, ...]` rather than raising or returning a sentinel, matching the convention used by `Row#[]` and `[]` selection. Use `dimensions.include?(:dim)` if you need to check membership directly.
+
 ### Enumerable
 
 Namo includes `Enumerable`, so `each`, `reduce`, `map`, `select`, `min_by`, and all the rest work out of the box. Rows are yielded as `Row` objects, so formulae are accessible during enumeration:
@@ -443,7 +515,7 @@ sales.flat_map{|row| [row[:price]]}
 
 ### Extracting data
 
-`to_a` returns an array of hashes:
+`to_a` returns an array of hashes — the row-oriented form:
 
 ```ruby
 sales[:product, :quarter, :revenue].to_a
@@ -455,6 +527,17 @@ sales[:product, :quarter, :revenue].to_a
 # ]
 ```
 
+`to_h` returns a hash of arrays — the columnar form (see [Coordinates and values](#coordinates-and-values) above):
+
+```ruby
+sales[:product, :quarter, :revenue].to_h
+# => {
+#   product: ['Widget', 'Widget', 'Gadget', 'Gadget'],
+#   quarter: ['Q1', 'Q2', 'Q1', 'Q2'],
+#   revenue: [1000.0, 1500.0, 1000.0, 1500.0]
+# }
+```
+
 ## 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 -o #{pdf}"
+      sh "pandoc #{f} --pdf-engine=xelatex -V geometry:margin=1in -V mainfont=Charter -V monofont=Menlo -o #{pdf}"
     end
   end
 

data/lib/Namo/VERSION.rb

@@ -2,5 +2,5 @@
 # Namo::VERSION
 
 class Namo
-  VERSION = '0.6.0'
+  VERSION = '0.7.0'
 end

data/lib/namo.rb

@@ -12,15 +12,39 @@ class Namo
   attr_accessor :formulae
 
   def dimensions
-    @dimensions ||= @data.first.keys
+    @data.first.keys + @formulae.keys
   end
 
-  def coordinates
-    @coordinates ||= (
-      dimensions.each_with_object({}) do |dimension, hash|
-        hash[dimension] = @data.map{|row| row[dimension]}.uniq
-      end
-    )
+  def data_dimensions
+    @data.first.keys
+  end
+
+  def derived_dimensions
+    @formulae.keys
+  end
+
+  def values(*dims)
+    if dims.empty?
+      dimensions.each_with_object({}){|dim, hash| hash[dim] = values_for(dim)}
+    elsif dims.length == 1
+      values_for(dims.first)
+    else
+      dims.each_with_object({}){|dim, hash| hash[dim] = values_for(dim)}
+    end
+  end
+
+  def coordinates(*dims)
+    if dims.empty?
+      values.transform_values(&:uniq)
+    elsif dims.length == 1
+      values(dims.first).uniq
+    else
+      dims.each_with_object({}){|dim, hash| hash[dim] = values(dim).uniq}
+    end
+  end
+
+  def to_h
+    values
   end
 
   def [](*names, **selections)
@@ -32,7 +56,7 @@ class Namo
     projected = (
       if negated.any?
         excluded = negated.map(&:name)
-        kept = dimensions - excluded
+        kept = data_dimensions - excluded
         rows.map do |row|
           kept.each_with_object({}){|name, hash| hash[name] = row[name]}
         end
@@ -58,31 +82,31 @@ class Namo
 
   def +(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     self.class.new(@data + other.data, formulae: other.formulae.merge(@formulae))
   end
 
   def -(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     self.class.new(@data - other.data, formulae: @formulae.dup)
   end
 
   def &(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     self.class.new(@data & other.data, formulae: @formulae.dup)
   end
 
   def |(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     self.class.new((@data | other.data), formulae: other.formulae.merge(@formulae))
   end
 
   def ^(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     self.class.new((@data - other.data) + (other.data - @data), formulae: other.formulae.merge(@formulae))
   end
 
@@ -109,25 +133,25 @@ class Namo
 
   def <(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     proper_subset_of_rows?(other)
   end
 
   def <=(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     subset_of_rows?(other)
   end
 
   def >(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     other.proper_subset_of_rows?(self)
   end
 
   def >=(other)
     raise_unless_namo(other)
-    raise_unless_matching_dimensions(other)
+    raise_unless_matching_data_dimensions(other)
     other.subset_of_rows?(self)
   end
 
@@ -142,7 +166,7 @@ class Namo
   protected
 
   def canonical_data
-    @data.sort_by{|row| row.values_at(*dimensions.sort)}
+    @data.sort_by{|row| row.values_at(*data_dimensions.sort)}
   end
 
   def subset_of_rows?(other)
@@ -157,15 +181,23 @@ class Namo
 
   private
 
+  def values_for(dim)
+    if data_dimensions.include?(dim)
+      @data.map{|row_data| row_data[dim]}
+    else
+      @data.map{|row_data| Row.new(row_data, @formulae)[dim]}
+    end
+  end
+
   def raise_unless_namo(other)
     unless other.is_a?(Namo)
       raise TypeError, "can't compare Namo with #{other.class}"
     end
   end
 
-  def raise_unless_matching_dimensions(other)
-    unless dimensions == other.dimensions
-      raise ArgumentError, "dimensions don't match: #{dimensions} vs #{other.dimensions}"
+  def raise_unless_matching_data_dimensions(other)
+    unless data_dimensions == other.data_dimensions
+      raise ArgumentError, "dimensions don't match: #{data_dimensions} vs #{other.data_dimensions}"
     end
   end
 

data/test/namo_test.rb

@@ -21,19 +21,159 @@ describe Namo do
     it "infers dimensions from hash keys" do
       _(sales.dimensions).must_equal [:product, :quarter, :price, :quantity]
     end
+
+    it "includes derived dimensions after storage dimensions" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      sales[:label] = proc{|r| "#{r[:product]}-#{r[:quarter]}"}
+      _(sales.dimensions).must_equal [:product, :quarter, :price, :quantity, :revenue, :label]
+    end
+
+    it "reflects mutation on the next call" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(sales.dimensions).must_include :revenue
+      sales.formulae.delete(:revenue)
+      _(sales.dimensions).wont_include :revenue
+    end
+  end
+
+  describe "#data_dimensions" do
+    it "returns only the storage keys" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(sales.data_dimensions).must_equal [:product, :quarter, :price, :quantity]
+    end
+  end
+
+  describe "#derived_dimensions" do
+    it "returns only the formula keys" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(sales.derived_dimensions).must_equal [:revenue]
+    end
+
+    it "is empty when no formulae are defined" do
+      _(sales.derived_dimensions).must_equal []
+    end
   end
 
   describe "#coordinates" do
-    it "extracts unique values for each dimension" do
+    it "with no args returns a Hash of unique values for each dimension" do
       _(sales.coordinates).must_equal ({
         product: ['Widget', 'Gadget'],
         quarter: ['Q1', 'Q2'],
         price: [10.0, 25.0],
         quantity: [100, 150, 40, 60]
       })
+    end
+
+    it "0.6.0-style indexing still works" do
       _(sales.coordinates[:product]).must_equal ['Widget', 'Gadget']
       _(sales.coordinates[:quarter]).must_equal ['Q1', 'Q2']
     end
+
+    it "with one arg returns just that column's unique values as an Array" do
+      _(sales.coordinates(:product)).must_equal ['Widget', 'Gadget']
+    end
+
+    it "with one arg returns [nil] for an unknown dimension (nil values uniqued)" do
+      _(sales.coordinates(:missing)).must_equal [nil]
+    end
+
+    it "with one arg evaluates a derived dimension" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(sales.coordinates(:revenue)).must_equal [1000.0, 1500.0]
+    end
+
+    it "with multiple args returns a subset Hash" do
+      _(sales.coordinates(:product, :quarter)).must_equal({
+        product: ['Widget', 'Gadget'],
+        quarter: ['Q1', 'Q2']
+      })
+    end
+
+    it "with multiple args includes unknown dimensions as [nil]" do
+      _(sales.coordinates(:product, :missing)).must_equal({
+        product: ['Widget', 'Gadget'],
+        missing: [nil]
+      })
+    end
+
+    it "covers derived dimensions in the no-arg form" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(sales.coordinates[:revenue]).must_equal [1000.0, 1500.0]
+    end
+  end
+
+  describe "#values" do
+    it "with no args returns a Hash of full sequences for each dimension" do
+      _(sales.values).must_equal({
+        product: ['Widget', 'Widget', 'Gadget', 'Gadget'],
+        quarter: ['Q1', 'Q2', 'Q1', 'Q2'],
+        price: [10.0, 10.0, 25.0, 25.0],
+        quantity: [100, 150, 40, 60]
+      })
+    end
+
+    it "with one arg returns just that column as an Array, preserving duplicates and order" do
+      _(sales.values(:product)).must_equal ['Widget', 'Widget', 'Gadget', 'Gadget']
+      _(sales.values(:price)).must_equal [10.0, 10.0, 25.0, 25.0]
+    end
+
+    it "with one arg returns an Array of nils for an unknown dimension (one nil per row)" do
+      _(sales.values(:missing)).must_equal [nil, nil, nil, nil]
+    end
+
+    it "with one arg evaluates a derived dimension across all rows" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(sales.values(:revenue)).must_equal [1000.0, 1500.0, 1000.0, 1500.0]
+    end
+
+    it "with multiple args returns a subset Hash" do
+      _(sales.values(:product, :quarter)).must_equal({
+        product: ['Widget', 'Widget', 'Gadget', 'Gadget'],
+        quarter: ['Q1', 'Q2', 'Q1', 'Q2']
+      })
+    end
+
+    it "with multiple args includes unknown dimensions as Arrays of nils" do
+      _(sales.values(:product, :missing)).must_equal({
+        product: ['Widget', 'Widget', 'Gadget', 'Gadget'],
+        missing: [nil, nil, nil, nil]
+      })
+    end
+
+    it "covers derived dimensions in the no-arg form" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(sales.values[:revenue]).must_equal [1000.0, 1500.0, 1000.0, 1500.0]
+    end
+  end
+
+  describe "#to_h" do
+    it "returns the full values Hash" do
+      _(sales.to_h).must_equal sales.values
+    end
+  end
+
+  describe "aspect consistency" do
+    it "satisfies coordinates(dim) == values(dim).uniq for each dimension" do
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      sales.dimensions.each do |dim|
+        _(sales.coordinates(dim)).must_equal sales.values(dim).uniq
+      end
+    end
+  end
+
+  describe "live-view semantics" do
+    it "reflects added rows on next call" do
+      _(sales.values(:product)).must_equal ['Widget', 'Widget', 'Gadget', 'Gadget']
+      sales.data << {product: 'Thingo', quarter: 'Q3', price: 5.0, quantity: 10}
+      _(sales.values(:product)).must_equal ['Widget', 'Widget', 'Gadget', 'Gadget', 'Thingo']
+    end
+
+    it "reflects added formulae on next call" do
+      _(sales.derived_dimensions).must_equal []
+      sales[:revenue] = proc{|r| r[:price] * r[:quantity]}
+      _(sales.derived_dimensions).must_equal [:revenue]
+      _(sales.coordinates(:revenue)).must_equal [1000.0, 1500.0]
+    end
   end
 
   describe "#[]" do

metadata

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