namo 0.4.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0dbfe699c8bbb334e0f72bbfd1859b0eee910be2c72eaab988da633b58b438e6
-  data.tar.gz: 40238ef4593d7820bddfb6cb708823fa9c269a51def947e89cdb43e4b69cbae0
+  metadata.gz: 9d29843b2d9895ba401fa013ea83753f548458bc09bcd8e61218400f81950e33
+  data.tar.gz: 6b8772e13cd773d41ae4cabddb019bddb533cbc9a24ece7729977543e462a30c
 SHA512:
-  metadata.gz: 9e6dfd0bcf4b8d370373a43e507a4d208e4ccb4478e044eb138bf5f2bfa61612cbb4f10735be691c852d2f8bf672eca70720cc6a5c35cd5fb02fae224388e010
-  data.tar.gz: 2b147c6e7faf7b9f92e8e2457fcd657734a35946c326857e3b7c09177ceaa7f3ce4f0892bdcbb68ec251d673e1b298c1ed06416fe43918656734a58bd0c639ea
+  metadata.gz: 22c4c03943617b1ec56e45ace4722019e6d54bb12f9b30fb3e2b85eebce132477a380ccde5529ea65782be03f060abd7507ebbfbe8b06d3c8ad10d7b90319061
+  data.tar.gz: 17e0163a3353024bec9826d5fc95773893d8195dbb7efe87ff7e814da7c74ca1391f168ca10025a6deb9fcd44e7ecae8fc3a10c44f29f9ef1e2018a0de96aa97

data/CHANGELOG

@@ -1,6 +1,31 @@
 CHANGELOG
 _________
 
+20260511
+0.6.0: + equality, pattern-match, and subset/superset operators
+
+1. + Namo#==: Multiset equality on row data, ignoring class and formulae.
+2. + Namo#===: Analytical identity match — true iff other has the same dimensions and same formula names as self, ignoring rows and proc bodies. Returns false for non-Namo operands.
+3. + Namo#eql?: Strict equality requiring class match, multiset-equal data, and formula name match.
+4. + Namo#hash: Content-based hash, consistent with eql?.
+5. + Namo#<, #<=, #>, #>=: Multiset subset/superset relations on rows. Raise ArgumentError on mismatched dimensions, TypeError on non-Namo operand.
+6. ~ Namo#+, #-, #&, #|, #^: Error message on dimension mismatch updated to "dimensions don't match: X vs Y". Non-Namo operand now raises TypeError ("can't compare Namo with X") instead of NoMethodError.
+7. ~ lib/namo.rb, namo.gemspec: Minor cleanup (./-prefixed requires; gemspec whitespace).
+8. ~ test/namo_test.rb: Add tests for ==, ===, eql?, hash, <, <=, >, >=, equal?, and the new error message.
+9. ~ README.md: + Equality section, + Subset and superset section, + design-philosophy paragraph in the opening and one-line principle callouts in the dimensions, formulae, set-operator, and equality sections.
+10. + script/md4print, ~ Rakefile: + rake docs:print, docs:pdf, docs:all for regenerating docs/*.print.md and docs/*.print.pdf.
+11. ~ Namo::VERSION: /0.5.0/0.6.0/
+
+20260416
+0.5.0: + row-axis set operations: intersection (&), union (|), symmetric difference (^)
+
+1. + Namo#&: Intersection. Returns rows present in both Namo objects. Requires matching dimensions.
+2. + Namo#|: Union. Returns all rows from both sides, deduplicated. Requires matching dimensions.
+3. + Namo#^: Symmetric difference. Returns rows in one side but not both. Requires matching dimensions.
+4. ~ Namo_test.rb: Add tests for #&, #|, and #^.
+5. ~ README.md: + Intersection section, + Union section, + Symmetric difference section.
+6. ~ Namo::VERSION: /0.4.0/0.5.0/
+
 20260415
 0.4.0: + concatenation (+) and row removal (-)
 

data/README.md

@@ -4,6 +4,8 @@ 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.
+
 ## Installation
 
 ```
@@ -44,6 +46,8 @@ sales.coordinates[:quarter]
 # => ['Q1', 'Q2']
 ```
 
+Every key is a dimension; every value is a coordinate. There's no schema declaration and no choosing which column is "the index" — `price` and `quantity` are no less first-class than `product` and `quarter`.
+
 ### Selection
 
 Select by named dimension using keyword arguments:
@@ -155,6 +159,8 @@ Selection, projection, and contraction always return a new Namo instance, so eve
 
 ### Concatenation
 
+`+` is the first of Namo's binary operators: it takes a Namo on each side and returns a Namo. The same shape holds for `-`, `&`, `|`, `^`, `==`, `===`, `<`, `<=`, `>`, `>=` and (later) the composition operators — Namo in, Namo (or boolean) out — so analytical pipelines stay queryable end-to-end.
+
 `+` combines two Namo objects that share the same dimensions by appending the rows of the second to the first:
 
 ```ruby
@@ -205,6 +211,162 @@ sales - discontinued
 
 Removal is exact — every dimension, every value must match. The dimensions must match; different dimensions raise an `ArgumentError`. Formulae carry through from the left-hand side.
 
+### Intersection
+
+`&` returns the rows present in both Namo objects, like `Array#&`:
+
+```ruby
+sales = Namo.new([
+  {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100},
+  {product: 'Widget', quarter: 'Q2', price: 10.0, quantity: 150},
+  {product: 'Gadget', quarter: 'Q1', price: 25.0, quantity: 40},
+  {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60}
+])
+
+confirmed = Namo.new([
+  {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100},
+  {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60}
+])
+
+sales & confirmed
+# => #<Namo [
+#   {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100},
+#   {product: 'Gadget', quarter: 'Q2', price: 25.0, quantity: 60}
+# ]>
+```
+
+The dimensions must match; different dimensions raise an `ArgumentError`. Formulae carry through from the left-hand side.
+
+### Union
+
+`|` returns all rows from both sides, deduplicated, like `Array#|`:
+
+```ruby
+q1_sales = Namo.new([
+  {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100},
+  {product: 'Gadget', quarter: 'Q1', price: 25.0, quantity: 40}
+])
+
+all_sales = Namo.new([
+  {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100},
+  {product: 'Thingo', quarter: 'Q3', price: 5.0, quantity: 10}
+])
+
+q1_sales | all_sales
+# => #<Namo [
+#   {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100},
+#   {product: 'Gadget', quarter: 'Q1', price: 25.0, quantity: 40},
+#   {product: 'Thingo', quarter: 'Q3', price: 5.0, quantity: 10}
+# ]>
+```
+
+The dimensions must match; different dimensions raise an `ArgumentError`. Formulae merge from both sides; the left-hand side's formulae take precedence on conflict.
+
+### Symmetric Difference
+
+`^` returns rows that appear in one side but not both:
+
+```ruby
+set_a = Namo.new([
+  {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100},
+  {product: 'Gadget', quarter: 'Q1', price: 25.0, quantity: 40}
+])
+
+set_b = Namo.new([
+  {product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100},
+  {product: 'Thingo', quarter: 'Q3', price: 5.0, quantity: 10}
+])
+
+set_a ^ set_b
+# => #<Namo [
+#   {product: 'Gadget', quarter: 'Q1', price: 25.0, quantity: 40},
+#   {product: 'Thingo', quarter: 'Q3', price: 5.0, quantity: 10}
+# ]>
+```
+
+The dimensions must match; different dimensions raise an `ArgumentError`. Formulae merge from both sides; the left-hand side's formulae take precedence on conflict.
+
+### Equality
+
+Comparison on Namos is **multiset-theoretic on rows**: row order is ignored (it's an accident of ingestion, not data), but row multiplicities count (they *are* data). The same stance carries across the equality, pattern-match, and subset/superset operators below.
+
+`==` is multiset equality on rows. Class and formulae are ignored; row order is ignored; row multiplicities are not.
+
+```ruby
+a = Namo.new([{x: 1}, {x: 2}])
+b = Namo.new([{x: 2}, {x: 1}])
+
+a == b
+# => true
+
+a == Namo.new([{x: 1}, {x: 1}, {x: 2}])
+# => false
+```
+
+`eql?` is stricter: it also requires the class to match and the formula names to match. Like `===`, it ignores proc bodies — proc identity isn't a meaningful equivalence in Ruby (`proc{...} == proc{...}` is false), so neither `===` nor `eql?` uses it.
+
+`hash` is consistent with `eql?` and is content-based, so equal Namos hash equally and can be used as Hash keys:
+
+```ruby
+h = {a => 'first'}
+h[b]
+# => 'first'
+```
+
+`equal?` is unchanged from Ruby's default — it tests object identity.
+
+`===` answers a different question: does the candidate have the same dimensions and the same formula names? Row data is ignored, and so are the proc bodies themselves — only the names matter. This is the `===` semantics that case statements use, so Namos can serve as templates for analytical shape:
+
+```ruby
+sales_shape = Namo.new([{product: 'X', quarter: 'Q1', price: 0.0, quantity: 0}])
+sales_shape[:revenue] = proc{|row| row[:price] * row[:quantity]}
+
+q1 = Namo.new([{product: 'Widget', quarter: 'Q1', price: 10.0, quantity: 100}])
+q1[:revenue] = proc{|row| row[:price] * row[:quantity]}
+
+sales_shape === q1
+# => true (same dimensions, same formula name)
+
+sales_shape == q1
+# => false (different rows)
+```
+
+The two `:revenue` procs are independently-written and not the same object — `proc{...} == proc{...}` is false in Ruby. But `===` doesn't compare proc identity; it asks "do these Namos have the same analytical shape?" and the shape is the set of dimensions plus the set of formula names.
+
+Each comparison operator answers a distinct question: `eql?` is strictest (class + data + formula names); `==` is data identity; `===` is analytical identity; the subset operators are data containment.
+
+### Subset and Superset
+
+`<`, `<=`, `>`, `>=` are multiset subset and superset relations on rows.
+
+```ruby
+small = Namo.new([{x: 1}, {x: 2}])
+large = Namo.new([{x: 1}, {x: 2}, {x: 3}])
+
+small <= large
+# => true
+
+small < large
+# => true
+
+large > small
+# => true
+```
+
+Equal sets are `<=` and `>=` each other, but neither `<` nor `>`. Disjoint sets are none of the above — unless one side is empty, in which case it is a subset of (and disjoint with) the other.
+
+Multiplicity matters: a single `{x: 1}` is a proper subset of two `{x: 1}`s.
+
+```ruby
+one = Namo.new([{x: 1}])
+two = Namo.new([{x: 1}, {x: 1}])
+
+one < two
+# => true
+```
+
+The dimensions must match; different dimensions raise an `ArgumentError`. Comparing against a non-Namo raises a `TypeError`.
+
 ### Formulae
 
 Define computed dimensions using `[]=`:
@@ -221,6 +383,8 @@ 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 compose:
 
 ```ruby

data/Rakefile

@@ -6,4 +6,37 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/**/*_test.rb']
 end
 
+namespace :docs do
+  SOURCE_DOCS = %w{COMPARISON EXAMPLES README ROADMAP}
+
+  desc "Strip syntax highlighting from code blocks for printing"
+  task :md4print do
+    SOURCE_DOCS.each do |name|
+      sh "script/md4print #{name}.md"
+      sh "mv #{name}.print.md docs/"
+    end
+  end
+
+  desc "Render print-ready markdown to PDF"
+  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}"
+    end
+  end
+
+  desc "Remove intermediate .print.md files"
+  task :clean do
+    rm_f Dir.glob('docs/*.print.md')
+  end
+
+  desc "Remove all generated docs (intermediates and PDFs)"
+  task :clobber => :clean do
+    rm_f Dir.glob('docs/*.print.pdf')
+  end
+
+  desc "Regenerate all derived docs"
+  task :gen => [:md2pdf, :clean]
+end
+
 task default: :test

data/lib/Namo/VERSION.rb

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

data/lib/namo.rb

@@ -1,9 +1,9 @@
 # namo.rb
 # Namo
 
-require_relative 'Namo/NegatedDimension'
-require_relative 'Namo/Row'
-require_relative 'Symbol'
+require_relative './Namo/NegatedDimension'
+require_relative './Namo/Row'
+require_relative './Symbol'
 
 class Namo
   include Enumerable
@@ -57,19 +57,80 @@ class Namo
   end
 
   def +(other)
-    unless dimensions == other.dimensions
-      raise ArgumentError, "dimensions do not match"
-    end
+    raise_unless_namo(other)
+    raise_unless_matching_dimensions(other)
     self.class.new(@data + other.data, formulae: other.formulae.merge(@formulae))
   end
 
   def -(other)
-    unless dimensions == other.dimensions
-      raise ArgumentError, "dimensions do not match"
-    end
+    raise_unless_namo(other)
+    raise_unless_matching_dimensions(other)
     self.class.new(@data - other.data, formulae: @formulae.dup)
   end
 
+  def &(other)
+    raise_unless_namo(other)
+    raise_unless_matching_dimensions(other)
+    self.class.new(@data & other.data, formulae: @formulae.dup)
+  end
+
+  def |(other)
+    raise_unless_namo(other)
+    raise_unless_matching_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)
+    self.class.new((@data - other.data) + (other.data - @data), formulae: other.formulae.merge(@formulae))
+  end
+
+  def ==(other)
+    return false unless other.is_a?(Namo)
+    canonical_data == other.canonical_data
+  end
+
+  def ===(other)
+    return false unless other.is_a?(Namo)
+    dimensions.sort == other.dimensions.sort &&
+      @formulae.keys.sort == other.formulae.keys.sort
+  end
+
+  def eql?(other)
+    self.class == other.class &&
+      canonical_data == other.canonical_data &&
+      @formulae.keys.sort == other.formulae.keys.sort
+  end
+
+  def hash
+    [self.class, canonical_data, @formulae.keys.sort].hash
+  end
+
+  def <(other)
+    raise_unless_namo(other)
+    raise_unless_matching_dimensions(other)
+    proper_subset_of_rows?(other)
+  end
+
+  def <=(other)
+    raise_unless_namo(other)
+    raise_unless_matching_dimensions(other)
+    subset_of_rows?(other)
+  end
+
+  def >(other)
+    raise_unless_namo(other)
+    raise_unless_matching_dimensions(other)
+    other.proper_subset_of_rows?(self)
+  end
+
+  def >=(other)
+    raise_unless_namo(other)
+    raise_unless_matching_dimensions(other)
+    other.subset_of_rows?(self)
+  end
+
   def to_a
     @data.map do |row|
       row.keys.each_with_object({}) do |key, hash|
@@ -78,8 +139,36 @@ class Namo
     end
   end
 
+  protected
+
+  def canonical_data
+    @data.sort_by{|row| row.values_at(*dimensions.sort)}
+  end
+
+  def subset_of_rows?(other)
+    self_counts = canonical_data.tally
+    other_counts = other.canonical_data.tally
+    self_counts.all?{|row, count| (other_counts[row] || 0) >= count}
+  end
+
+  def proper_subset_of_rows?(other)
+    subset_of_rows?(other) && self != other
+  end
+
   private
 
+  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}"
+    end
+  end
+
   def initialize(data = nil, formulae: {})
     @data = data
     @formulae = formulae

data/namo.gemspec

@@ -19,7 +19,6 @@ Gem::Specification.new do |spec|
   spec.license = 'MIT'
 
   spec.required_ruby_version = '>= 2.7'
-
   spec.require_paths = ['lib']
 
   spec.files = [