factbase 0.17.1 → 0.18.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 91ef3ed499ea15abb77bc39cfed30eb9af704921e86c3c03c7bdd9b13cb44270
-  data.tar.gz: 3c2e80d00620e0de14ec4be35ff08b28393793c69742dda9bda55c4a5ae01c8f
+  metadata.gz: 90b1ab3d82ed371b4de11b7eceb98137b2a7687bc2625e61d4d54a6538849b34
+  data.tar.gz: f9fd82d8254d7cfa646a742db6989790791ce157ce53d9e5a310f8f8f8c0db11
 SHA512:
-  metadata.gz: 9c6e18a32a5ae773e78672e449cce031a2c7641b1291b9f637ccb28afb6afddc87091955ce06e75c0e35326f4db37b04fac5b827b1cdc203a8b0262c105ca2c3
-  data.tar.gz: 923207d8494313e1af4fae0ecf3068372a5dde28924840edbe1b6d625127afb7e4eb2cf44c9f86a28d9d7fc650336abce9c9b99cd492b3ff29bcbb4cf214c83e
+  metadata.gz: ae0d064e075f304c9fae6f4903c961293d07e186ee6bdf4e180d5f407f5b166f2b3cc345cec612d8184675394a2ee504197d4c13d9ce0f480cffd850d7d10169
+  data.tar.gz: b53da29f44f9ad5520bed3602c9c7dadf882115856ddb344dfba95a32017cd2e89c4582a7a160baa2ed611ff37acd0ba39e8fb9a8aa8ed7bec62f0acf9f0ee70

data/Gemfile

@@ -12,7 +12,7 @@ gem 'minitest-reporters', '~>1.7', require: false
 gem 'os', '~>1.1', require: false
 gem 'qbash', '~>0.4', require: false
 gem 'rake', '~>13.2', require: false
-gem 'rdoc', '6.16.1', require: false # GPL
+gem 'rdoc', '6.17.0', require: false # GPL
 gem 'rubocop', '~>1.74', require: false
 gem 'rubocop-minitest', '~>0.38', require: false
 gem 'rubocop-performance', '~>1.25', require: false

data/Gemfile.lock

@@ -68,7 +68,7 @@ GEM
     racc (1.8.1)
     rainbow (3.1.1)
     rake (13.3.1)
-    rdoc (6.16.1)
+    rdoc (6.17.0)
       erb
       psych (>= 4.0.0)
       tsort
@@ -140,7 +140,7 @@ DEPENDENCIES
   os (~> 1.1)
   qbash (~> 0.4)
   rake (~> 13.2)
-  rdoc (= 6.16.1)
+  rdoc (= 6.17.0)
   rubocop (~> 1.74)
   rubocop-minitest (~> 0.38)
   rubocop-performance (~> 1.25)

data/lib/factbase/lazy_taped.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+require_relative 'taped'
+require_relative 'lazy_taped_hash'
+
+# A lazy decorator of an Array with HashMaps that defers copying until modification.
+class Factbase::LazyTaped
+  def initialize(origin)
+    @origin = origin
+    @copied = false
+    @maps = nil
+    @pairs = nil
+    @inserted = []
+    @deleted = []
+    @added = []
+  end
+
+  # Returns a hash mapping copied maps to their originals.
+  # This is used during transaction commit to identify which original facts
+  # were modified, allowing the factbase to update the correct entries.
+  def pairs
+    return {} unless @pairs
+    result = {}.compare_by_identity
+    @pairs.each { |copied, original| result[copied] = original }
+    result
+  end
+
+  # Returns the unique object IDs of maps that were inserted (newly created).
+  # This is used during transaction commit to identify new facts that need
+  # to be added to the factbase.
+  def inserted
+    @inserted.uniq
+  end
+
+  # Returns the unique object IDs of maps that were deleted.
+  # This is used during transaction commit to identify facts that need
+  # to be removed from the factbase.
+  def deleted
+    @deleted.uniq
+  end
+
+  # Returns the unique object IDs of maps that were modified (properties added).
+  # This is used during transaction commit to track the churn (number of changes).
+  def added
+    @added.uniq
+  end
+
+  def find_by_object_id(oid)
+    (@maps || @origin).find { |m| m.object_id == oid }
+  end
+
+  def size
+    (@maps || @origin).size
+  end
+
+  def empty?
+    (@maps || @origin).empty?
+  end
+
+  def <<(map)
+    ensure_copied
+    @maps << map
+    @inserted.append(map.object_id)
+  end
+
+  def each
+    return to_enum(__method__) unless block_given?
+    if @copied
+      @maps.each do |m|
+        yield Factbase::Taped::TapedHash.new(m, @added)
+      end
+    else
+      @origin.each do |m|
+        yield LazyTapedHash.new(m, self, @added)
+      end
+    end
+  end
+
+  def delete_if
+    ensure_copied
+    @maps.delete_if do |m|
+      r = yield m
+      @deleted.append(@pairs[m].object_id) if r
+      r
+    end
+  end
+
+  def to_a
+    (@maps || @origin).to_a
+  end
+
+  def &(other)
+    if other == [] || (@maps || @origin).empty?
+      return Factbase::Taped.new([], inserted: @inserted, deleted: @deleted, added: @added)
+    end
+    join(other, &:&)
+  end
+
+  def |(other)
+    return Factbase::Taped.new(to_a, inserted: @inserted, deleted: @deleted, added: @added) if other == []
+    if (@maps || @origin).empty?
+      return Factbase::Taped.new(other, inserted: @inserted, deleted: @deleted, added: @added)
+    end
+    join(other, &:|)
+  end
+
+  def ensure_copied
+    return if @copied
+    @pairs = {}.compare_by_identity
+    @maps =
+      @origin.map do |m|
+        n = m.transform_values(&:dup)
+        @pairs[n] = m
+        n
+      end
+    @copied = true
+  end
+
+  def get_copied_map(original_map)
+    ensure_copied
+    @maps.find { |m| @pairs[m].equal?(original_map) }
+  end
+
+  private
+
+  def join(other)
+    n = yield (@maps || @origin).to_a, other.to_a
+    raise 'Cannot join with another Taped' if other.respond_to?(:inserted)
+    raise 'Can only join with array' unless other.is_a?(Array)
+    Factbase::Taped.new(
+      n,
+      inserted: @inserted,
+      deleted: @deleted,
+      added: @added
+    )
+  end
+end

data/lib/factbase/lazy_taped_array.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+
+class Factbase::LazyTaped
+  # Decorator of Array that triggers copy-on-write.
+  # @todo #424:30min Add dedicated unit tests for LazyTapedArray class.
+  #  Currently this class is tested indirectly through LazyTaped tests.
+  #  We should add explicit tests for all public methods including each, [],
+  #  to_a, any?, <<, and uniq! to ensure proper copy-on-write behavior.
+  class LazyTapedArray
+    # Creates a new lazy array wrapper.
+    # @param origin [Array] The original array to wrap
+    # @param key [String] The key in the parent hash where this array is stored
+    # @param taped_hash [LazyTapedHash] The parent hash wrapper that owns this array
+    # @param added [Array] Accumulator for tracking object IDs of modified facts
+    def initialize(origin, key, taped_hash, added)
+      @origin = origin
+      @key = key
+      @taped_hash = taped_hash
+      @added = added
+    end
+
+    def each(&)
+      return to_enum(__method__) unless block_given?
+      current_array.each(&)
+    end
+
+    def [](idx)
+      current_array[idx]
+    end
+
+    def to_a
+      current_array.to_a
+    end
+
+    def any?(pattern = nil, &)
+      pattern ? current_array.any?(pattern) : current_array.any?(&)
+    end
+
+    def <<(item)
+      @taped_hash.ensure_copied_map
+      @added.append(@taped_hash.tracking_id)
+      @taped_hash.get_copied_array(@key) << item
+    end
+
+    def uniq!
+      @taped_hash.ensure_copied_map
+      @added.append(@taped_hash.tracking_id)
+      @taped_hash.get_copied_array(@key).uniq!
+    end
+
+    private
+
+    def current_array
+      @taped_hash.copied? ? @taped_hash.get_copied_array(@key) : @origin
+    end
+  end
+end

data/lib/factbase/lazy_taped_hash.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../factbase'
+require_relative 'lazy_taped_array'
+
+class Factbase::LazyTaped
+  # Decorator of Hash that triggers copy-on-write.
+  # @todo #424:30min Add dedicated unit tests for LazyTapedHash class.
+  #  Currently this class is tested indirectly through LazyTaped tests.
+  #  We should add explicit tests for all public methods including keys, map,
+  #  bracket access, bracket assignment, and the copy-on-write behavior.
+  class LazyTapedHash
+    # Creates a new LazyTapedHash decorator.
+    # @param origin [Hash] The original hash being wrapped (not yet copied)
+    # @param lazy_taped [Factbase::LazyTaped] The parent LazyTaped instance that manages copy-on-write
+    # @param added [Array] Array to track object IDs of maps that have been modified
+    def initialize(origin, lazy_taped, added)
+      @origin = origin
+      @lazy_taped = lazy_taped
+      @added = added
+      @copied_map = nil
+    end
+
+    def keys
+      current_map.keys
+    end
+
+    def map(&)
+      current_map.map(&)
+    end
+
+    def [](key)
+      v = current_map[key]
+      v = LazyTapedArray.new(v, key, self, @added) if v.is_a?(Array)
+      v
+    end
+
+    def []=(key, value)
+      ensure_copied_map
+      @copied_map[key] = value
+      @added.append(@copied_map.object_id)
+    end
+
+    def ensure_copied_map
+      return if @copied_map
+      @copied_map = @lazy_taped.get_copied_map(@origin)
+    end
+
+    def get_copied_array(key)
+      ensure_copied_map
+      @copied_map[key]
+    end
+
+    def tracking_id
+      @copied_map ? @copied_map.object_id : @origin.object_id
+    end
+
+    def copied?
+      !@copied_map.nil?
+    end
+
+    private
+
+    def current_map
+      @copied_map || @origin
+    end
+
+    def method_missing(method, *, &)
+      current_map.send(method, *, &)
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      current_map.respond_to?(method, include_private)
+    end
+  end
+end

data/lib/factbase/term.rb

@@ -86,7 +86,7 @@ require_relative 'terms/max'
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
-class Factbase::Term
+class Factbase::Term < Factbase::TermBase
   # The operator of this term
   # @return [Symbol] The operator
   attr_reader :op
@@ -95,13 +95,11 @@ class Factbase::Term
   # @return [Array] The operands
   attr_reader :operands
 
-  require_relative 'terms/shared'
-  include Factbase::TermShared
-
   # Ctor.
   # @param [Symbol] operator Operator
   # @param [Array] operands Operands
   def initialize(operator, operands)
+    super()
     @op = operator
     @operands = operands
     @terms = {

data/lib/factbase/terms/agg.rb

@@ -26,7 +26,7 @@ class Factbase::Agg < Factbase::TermBase
       raise "A term is expected, but '#{selector}' provided"
     end
     term = @operands[1]
-    unless term.is_a?(Factbase::Term) || selector.is_a?(Factbase::TermBase)
+    unless term.is_a?(Factbase::Term) || term.is_a?(Factbase::TermBase)
       raise "A term is expected, but '#{term}' provided"
     end
     subset = fb.query(selector, maps).each(fb, fact).to_a

data/lib/factbase/terms/base.rb

@@ -10,8 +10,61 @@
 
 # Base class for all terms.
 class Factbase::TermBase
-  require_relative 'shared'
-  include Factbase::TermShared
+  # Turns it into a string.
+  # @return [String] The string of it
+  def to_s
+    @to_s ||=
+      begin
+        items = []
+        items << @op
+        items +=
+          @operands.map do |o|
+            if o.is_a?(String)
+              "'#{o.gsub("'", "\\\\'").gsub('"', '\\\\"')}'"
+            elsif o.is_a?(Time)
+              o.utc.iso8601
+            else
+              o.to_s
+            end
+          end
+        "(#{items.join(' ')})"
+      end
+  end
 
-  protected :assert_args, :_by_symbol, :_values, :to_s
+  private
+
+  def assert_args(num)
+    c = @operands.size
+    raise "Too many (#{c}) operands for '#{@op}' (#{num} expected)" if c > num
+    raise "Too few (#{c}) operands for '#{@op}' (#{num} expected)" if c < num
+  end
+
+  def _by_symbol(pos, fact)
+    o = @operands[pos]
+    raise "A symbol expected at ##{pos}, but '#{o}' (#{o.class}) provided" unless o.is_a?(Symbol)
+    k = o.to_s
+    fact[k]
+  end
+
+  # @return [Array|nil] Either array of values or NIL
+  def _values(pos, fact, maps, fb)
+    v = @operands[pos]
+    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::Term)
+    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::TermBase)
+    v = fact[v.to_s] if v.is_a?(Symbol)
+    return v if v.nil?
+    unless v.is_a?(Array)
+      v =
+        if v.respond_to?(:each)
+          v.to_a
+        else
+          [v]
+        end
+    end
+    raise 'Why not array?' unless v.is_a?(Array)
+    unless v.all? { |i| [Float, Integer, String, Time, TrueClass, FalseClass].any? { |t| i.is_a?(t) } }
+      raise 'Wrong type inside'
+    end
+    v
+  end
 end

data/lib/factbase/version.rb

@@ -9,5 +9,5 @@
 # License:: MIT
 class Factbase
   # Current version of the gem (changed by .rultor.yml on every release)
-  VERSION = '0.17.1' unless const_defined?(:VERSION)
+  VERSION = '0.18.0' unless const_defined?(:VERSION)
 end

data/lib/factbase.rb

@@ -164,17 +164,8 @@ class Factbase
   #
   # @return [Factbase::Churn] How many facts have been changed (zero if rolled back)
   def txn
-    pairs = {}
-    before =
-      @maps.map do |m|
-        n = m.transform_values(&:dup)
-        # rubocop:disable Lint/HashCompareByIdentity
-        pairs[n.object_id] = m.object_id
-        # rubocop:enable Lint/HashCompareByIdentity
-        n
-      end
-    require_relative 'factbase/taped'
-    taped = Factbase::Taped.new(before)
+    require_relative 'factbase/lazy_taped'
+    taped = Factbase::LazyTaped.new(@maps)
     require_relative 'factbase/churn'
     churn = Factbase::Churn.new
     catch :commit do
@@ -188,30 +179,32 @@ class Factbase
     rescue Factbase::Rollback
       return churn
     end
-    seen = []
-    garbage = []
+    seen = {}.compare_by_identity
+    garbage = {}.compare_by_identity
+    pairs = taped.pairs
     taped.deleted.each do |oid|
-      garbage << pairs[oid]
-      seen << oid
+      original = @maps.find { |m| m.object_id == oid }
+      next if original.nil?
+      garbage[original] = true
       churn.append(0, 1, 0)
     end
     taped.inserted.each do |oid|
-      next if seen.include?(oid)
       b = taped.find_by_object_id(oid)
       next if b.nil?
-      seen << oid
+      next if seen.key?(b)
+      seen[b] = true
       @maps << b
       churn.append(1, 0, 0)
     end
     taped.added.each do |oid|
-      next if seen.include?(oid)
       b = taped.find_by_object_id(oid)
       next if b.nil?
-      garbage << pairs[oid]
+      next if seen.key?(b)
+      garbage[pairs[b]] = true
       @maps << b
       churn.append(0, 0, 1)
     end
-    @maps.delete_if { |m| garbage.include?(m.object_id) } unless garbage.empty?
+    @maps.delete_if { |m| garbage.key?(m) } unless garbage.empty?
     churn
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: factbase
 version: !ruby/object:Gem::Version
-  version: 0.17.1
+  version: 0.18.0
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -195,6 +195,9 @@ files:
 - lib/factbase/indexed/indexed_term.rb
 - lib/factbase/indexed/indexed_unique.rb
 - lib/factbase/inv.rb
+- lib/factbase/lazy_taped.rb
+- lib/factbase/lazy_taped_array.rb
+- lib/factbase/lazy_taped_hash.rb
 - lib/factbase/light.rb
 - lib/factbase/logged.rb
 - lib/factbase/pre.rb
@@ -248,7 +251,6 @@ files:
 - lib/factbase/terms/or.rb
 - lib/factbase/terms/plus.rb
 - lib/factbase/terms/prev.rb
-- lib/factbase/terms/shared.rb
 - lib/factbase/terms/simplified.rb
 - lib/factbase/terms/size.rb
 - lib/factbase/terms/sorted.rb

data/lib/factbase/terms/shared.rb

@@ -1,69 +0,0 @@
-# frozen_string_literal: true
-
-# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
-# SPDX-License-Identifier: MIT
-
-# This module provides shared methods for Factbase terms, including argument validation,
-# symbol-based lookups, and handling of operand values.
-# @todo #302:30min Remove this module and move its methods to Factbase::TermBase.
-#  Currently, we use it because we are required to inject all thesse methods into Factbase::Term.
-#  When all the terms will inherit from Factbase::TermBase, we can remove this module.
-module Factbase::TermShared
-  # Turns it into a string.
-  # @return [String] The string of it
-  def to_s
-    @to_s ||=
-      begin
-        items = []
-        items << @op
-        items +=
-          @operands.map do |o|
-            if o.is_a?(String)
-              "'#{o.gsub("'", "\\\\'").gsub('"', '\\\\"')}'"
-            elsif o.is_a?(Time)
-              o.utc.iso8601
-            else
-              o.to_s
-            end
-          end
-        "(#{items.join(' ')})"
-      end
-  end
-
-  private
-
-  def assert_args(num)
-    c = @operands.size
-    raise "Too many (#{c}) operands for '#{@op}' (#{num} expected)" if c > num
-    raise "Too few (#{c}) operands for '#{@op}' (#{num} expected)" if c < num
-  end
-
-  def _by_symbol(pos, fact)
-    o = @operands[pos]
-    raise "A symbol expected at ##{pos}, but '#{o}' (#{o.class}) provided" unless o.is_a?(Symbol)
-    k = o.to_s
-    fact[k]
-  end
-
-  # @return [Array|nil] Either array of values or NIL
-  def _values(pos, fact, maps, fb)
-    v = @operands[pos]
-    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::Term)
-    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::TermBase)
-    v = fact[v.to_s] if v.is_a?(Symbol)
-    return v if v.nil?
-    unless v.is_a?(Array)
-      v =
-        if v.respond_to?(:each)
-          v.to_a
-        else
-          [v]
-        end
-    end
-    raise 'Why not array?' unless v.is_a?(Array)
-    unless v.all? { |i| [Float, Integer, String, Time, TrueClass, FalseClass].any? { |t| i.is_a?(t) } }
-      raise 'Wrong type inside'
-    end
-    v
-  end
-end