namo.rb 0.31.7

data/lib/namo.rb

@@ -0,0 +1,433 @@
+# namo.rb
+# Namo
+
+require_relative './Namo/NegatedDimension'
+require_relative './Namo/Formulary'
+require_relative './Namo/Formulae'
+require_relative './Namo/Row'
+require_relative './Namo/Collection'
+require_relative './Namo/Enumerable'
+require_relative './Namo/VERSION'
+require_relative './Symbol'
+
+class Namo
+  include Namo::Enumerable
+
+  attr_accessor :data
+  attr_accessor :formulae
+  attr_accessor :name
+
+  INSPECTED_ROWS = 10
+
+  def dimensions
+    data_dimensions + derived_dimensions
+  end
+
+  def data_dimensions
+    @data.first&.keys || []
+  end
+
+  def derived_dimensions
+    @formulae.keys
+  end
+
+  def values(*dims)
+    materialising do
+      if dims.empty?
+        materialisable_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
+  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)
+    rows = selections.any? ? select{|row| row.match?(selections)} : entries
+    negated, positive = names.partition{|n| n.is_a?(NegatedDimension)}
+    if negated.any? && positive.any?
+      raise ArgumentError, "cannot mix projection and contraction in a single call"
+    end
+    projected = (
+      if negated.any?
+        excluded = negated.map(&:name)
+        kept = data_dimensions - excluded
+        rows.map do |row|
+          kept.each_with_object({}){|name, hash| hash[name] = row[name]}
+        end
+      elsif positive.any?
+        rows.map do |row|
+          positive.each_with_object({}){|name, hash| hash[name] = row[name]}
+        end
+      else
+        rows.map(&:to_h)
+      end
+    )
+    carried = positive.any? ? @formulae.reject{|name, _| positive.include?(name)} : @formulae.dup
+    return_class.new(projected, formulae: carried)
+  end
+
+  def []=(name, value)
+    if value.respond_to?(:call)
+      @data.each{|row| row.delete(name)} if @data.first&.key?(name)
+      @formulae[name] = value
+    else
+      @formulae.delete(name)
+      @data.each{|row| row[name] = value}
+    end
+  end
+
+  def attach(modul)
+    collisions = attach_collisions(modul)
+    unless collisions.empty?
+      raise ArgumentError, "formulary methods collide with data dimensions: #{collisions.inspect}"
+    end
+    @formulae.attach(modul)
+    self
+  end
+
+  def attach!(modul)
+    attach_collisions(modul).each{|name| @data.each{|row| row.delete(name)}}
+    @formulae.attach(modul)
+    self
+  end
+
+  def detach(constituent)
+    @formulae.detach(constituent)
+    self
+  end
+
+  def <<(constituent)
+    case constituent
+    when Module then attach(constituent)
+    when Row then add_row(constituent.to_h)
+    when Hash then add_row(constituent)
+    else raise TypeError, "can't append #{constituent.class} to a Namo; expected a Module (formulary), a Hash, or a Row"
+    end
+  end
+
+  def +(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    return_class.new(@data + other.data, formulae: other.formulae.merge(@formulae))
+  end
+
+  def -(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    return_class.new(@data - other.data, formulae: @formulae.dup)
+  end
+
+  def &(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    return_class.new(@data & other.data, formulae: @formulae.dup)
+  end
+
+  def |(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    return_class.new((@data | other.data), formulae: other.formulae.merge(@formulae))
+  end
+
+  def ^(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    return_class.new((@data - other.data) + (other.data - @data), formulae: other.formulae.merge(@formulae))
+  end
+
+  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|
+      matched = other.data.select{|right_row| shared.all?{|dim| left_row[dim] == right_row[dim]}}
+      if block
+        candidates = other.class.new(matched, formulae: other.formulae.dup)
+        chosen = block.call(Row.new(left_row, @formulae, self), candidates)
+        chosen.data.each{|right_row| combined_data << left_row.merge(right_row)}
+      else
+        matched.each{|right_row| combined_data << left_row.merge(right_row)}
+      end
+    end
+    return_class.new(combined_data, formulae: other.formulae.merge(@formulae))
+  end
+
+  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
+        candidates = other.class.new(other.data, formulae: other.formulae.dup)
+        chosen = block.call(Row.new(left_row, @formulae, self), candidates)
+        chosen.data.each{|right_row| combined_data << left_row.merge(right_row)}
+      else
+        other.data.each{|right_row| combined_data << left_row.merge(right_row)}
+      end
+    end
+    return_class.new(combined_data, formulae: other.formulae.merge(@formulae))
+  end
+
+  def /(other)
+    raise_unless_namo(other)
+    kept = data_dimensions - other.data_dimensions
+    projected = @data.map do |row|
+      kept.each_with_object({}){|dim, hash| hash[dim] = row[dim]}
+    end
+    return_class.new(projected.uniq, formulae: @formulae.dup)
+  end
+
+  def ==(other)
+    return false unless other.is_a?(Namo)
+    row_multiset == other.row_multiset
+  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 &&
+      row_multiset == other.row_multiset &&
+      @formulae.keys.sort == other.formulae.keys.sort
+  end
+
+  def hash
+    [self.class, row_multiset, @formulae.keys.sort].hash
+  end
+
+  def <(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    proper_subset_of_rows?(other)
+  end
+
+  def <=(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    subset_of_rows?(other)
+  end
+
+  def >(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    other.proper_subset_of_rows?(self)
+  end
+
+  def >=(other)
+    raise_unless_namo(other)
+    raise_unless_matching_data_dimensions(other)
+    other.subset_of_rows?(self)
+  end
+
+  # Each row's own keys, in their own order, and then the derived dimensions which
+  # can be materialised without arguments — the rule values, coordinates and to_h
+  # already follow.  data is the stored rows, and stays so.
+  def to_a
+    materialising do
+      derived = materialisable_dimensions - data_dimensions
+      @data.map do |row|
+        subject = Row.new(row, @formulae, self)
+        stored = row.keys.each_with_object({}){|key, hash| hash[key] = row[key]}
+        derived.each_with_object(stored){|dimension, hash| hash[dimension] = subject[dimension]}
+      end
+    end
+  end
+
+  def inspect
+    rendered = @data.first(INSPECTED_ROWS).map{|row| [row, inspected_derivations(row)]}
+    "#<#{self.class}#{inspected_name}#{inspected_rows(rendered)}#{inspected_derived(rendered)}>"
+  end
+
+  protected
+
+  # The class an operation returns.  A subclass is its own kind of thing, so a
+  # projection of a PriceData is a PriceData; Namo::Collection is not, its kind
+  # being its members, which a row operation carries none of.
+  def return_class
+    self.class
+  end
+
+  # The rendered rows, the count of those not shown, and the derived dimensions
+  # none of them carries.  Shared with Collection, which renders its members' rows
+  # rather than its own and must report what a member would report of itself.
+  def inspected_data(limit)
+    rendered = @data.first(limit).map{|row| [row, inspected_derivations(row)]}
+    [rendered.map{|row, derived| row.merge(derived).inspect},
+      @data.length - limit,
+      unshown_derived(rendered)]
+  end
+
+  def row_multiset
+    @data.tally
+  end
+
+  def subset_of_rows?(other)
+    self_counts = row_multiset
+    other_counts = other.row_multiset
+    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 initialize(positional_data = nil, data: [], formulae: {}, name: nil)
+    @data = positional_data || data
+    @formulae = formulae.is_a?(Formulae) ? formulae : Formulae.new(formulae)
+    @name = name
+    attach_included_formularies
+  end
+
+  def inspected_name
+    @name.nil? ? '' : " #{@name.inspect}"
+  end
+
+  # The rows as they are stored, never the derived values: inspect is called
+  # for every result in a console, and evaluating a formula there would cost a
+  # pass over the data per access and raise whatever the formula raises.
+  def inspected_rows(rendered)
+    return ' []' if @data.empty?
+    shown = rendered.map{|row, derived| "  #{row.merge(derived).inspect}"}.join(",\n")
+    shown += "\n  ... #{@data.length - INSPECTED_ROWS} more rows" if @data.length > INSPECTED_ROWS
+    " [\n#{shown}\n]"
+  end
+
+  # A derived dimension is shown with its value, in among the stored ones.  A
+  # formula wanting arguments has no value to show without them, and one which
+  # raises has none to show either; the derived list still names both.
+  def inspected_derivations(row)
+    subject = Row.new(row, @formulae, self)
+    derived_dimensions.each_with_object({}) do |dimension, derived|
+      next if @formulae.required_parameter_count(dimension) > 2
+      derived[dimension] = subject[dimension]
+    rescue StandardError
+      next
+    end
+  end
+
+  # Only those the rows above do not already carry.  A formula which raises, and a
+  # parameterised one which cannot be materialised without its arguments, render
+  # no value and would otherwise be nowhere in the output at all.  A Collection
+  # renders no rows of its own and so passes none, naming every one of them.
+  def inspected_derived(rendered = [])
+    inspected_derived_names(unshown_derived(rendered))
+  end
+
+  def inspected_derived_names(unshown)
+    unshown.empty? ? '' : " derived: #{unshown.inspect}"
+  end
+
+  def unshown_derived(rendered)
+    derived_dimensions.reject do |dimension|
+      rendered.any? && rendered.all?{|_, derived| derived.key?(dimension)}
+    end
+  end
+
+  def add_row(row)
+    collisions = row.keys & derived_dimensions
+    unless collisions.empty?
+      raise ArgumentError, "row keys collide with formulae: #{collisions.inspect}"
+    end
+    @data << row
+    self
+  end
+
+  def attach_collisions(modul)
+    modul.public_instance_methods(false) & data_dimensions
+  end
+
+  def attach_included_formularies
+    self.class.ancestors.reverse.each do |modul|
+      next if modul.is_a?(Class) || !modul.include?(Namo::Formulary)
+      attach(modul)
+    end
+  end
+
+  def materialising
+    return yield if @materialised
+    @materialised = {}
+    begin
+      yield
+    ensure
+      @materialised = nil
+    end
+  end
+
+  def values_for(dim)
+    @materialised[dim] ||= (
+      if data_dimensions.include?(dim)
+        @data.map{|row_data| row_data[dim]}
+      else
+        @data.map{|row_data| Row.new(row_data, @formulae, self)[dim]}
+      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}"
+    end
+  end
+
+  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
+
+  def raise_unless_shared_data_dimensions(other)
+    if (data_dimensions & other.data_dimensions).empty?
+      raise ArgumentError, "no shared dimensions, need to have shared dimensions: #{data_dimensions} vs #{other.data_dimensions}"
+    end
+  end
+
+  def raise_unless_disjoint_data_dimensions(other)
+    if (data_dimensions & other.data_dimensions).any?
+      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/namo.rb.gemspec

@@ -0,0 +1,42 @@
+# namo.rb.gemspec
+
+require_relative './lib/Namo/VERSION'
+
+class Gem::Specification
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'namo.rb'
+  spec.version = Namo::VERSION
+
+  spec.summary = "Named dimensional data for Ruby."
+  spec.description = "A Ruby library for working with multi-dimensional data using named dimensions. Initialise from an array of hashes making it trivial to use with databases, CSV, JSON, and YAML. Dimensions and coordinates are inferred automatically."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'https://github.com/thoran/namo'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 2.7'
+  spec.require_paths = ['lib']
+
+  spec.files = [
+    Dir['lib/**/*.rb'],
+    Dir['test/**/*.rb'],
+    'CHANGELOG',
+    'Gemfile',
+    'LICENSE',
+    'namo.rb.gemspec',
+    'Rakefile',
+    'README.md',
+  ].flatten
+
+  spec.development_dependencies = %w{
+    minitest
+    minitest-spec-context
+    rake
+  }
+end