factbase 0.7.5 → 0.9.0

data/lib/factbase/terms/logical.rb

@@ -11,49 +11,79 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Logical
-  def always(_fact, _maps)
+  # Always returns true, regardless of the fact
+  # @param [Factbase::Fact] _fact The fact (unused)
+  # @param [Array<Factbase::Fact>] _maps All maps available (unused)
+  # @return [Boolean] Always returns true
+  def always(_fact, _maps, _fb)
     assert_args(0)
     true
   end
 
-  def never(_fact, _maps)
+  # Always returns false, regardless of the fact
+  # @param [Factbase::Fact] _fact The fact (unused)
+  # @param [Array<Factbase::Fact>] _maps All maps available (unused)
+  # @return [Boolean] Always returns false
+  def never(_fact, _maps, _fb)
     assert_args(0)
     false
   end
 
-  def not(fact, maps)
+  # Logical negation (NOT) of an operand
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @return [Boolean] Negated boolean result of the operand
+  def not(fact, maps, fb)
     assert_args(1)
-    !_only_bool(the_values(0, fact, maps), 0)
+    !_only_bool(_values(0, fact, maps, fb), 0)
   end
 
-  def or(fact, maps)
+  # Logical OR of multiple operands
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @return [Boolean] True if any operand evaluates to true, false otherwise
+  def or(fact, maps, fb)
     (0..@operands.size - 1).each do |i|
-      return true if _only_bool(the_values(i, fact, maps), i)
+      return true if _only_bool(_values(i, fact, maps, fb), i)
     end
     false
   end
 
-  def and(fact, maps)
+  # Logical AND of multiple operands
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @return [Boolean] True if all operands evaluate to true, false otherwise
+  def and(fact, maps, fb)
     (0..@operands.size - 1).each do |i|
-      return false unless _only_bool(the_values(i, fact, maps), i)
+      return false unless _only_bool(_values(i, fact, maps, fb), i)
     end
     true
   end
 
-  def when(fact, maps)
+  # Logical implication (IF...THEN)
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @return [Boolean] True if first operand is false OR both are true
+  def when(fact, maps, fb)
     assert_args(2)
     a = @operands[0]
     b = @operands[1]
-    !a.evaluate(fact, maps) || (a.evaluate(fact, maps) && b.evaluate(fact, maps))
+    !a.evaluate(fact, maps, fb) || (a.evaluate(fact, maps, fb) && b.evaluate(fact, maps, fb))
   end
 
-  def either(fact, maps)
+  # Returns the first non-nil value or the second value
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @return [Object] First operand if not nil, otherwise second operand
+  def either(fact, maps, fb)
     assert_args(2)
-    v = the_values(0, fact, maps)
+    v = _values(0, fact, maps, fb)
     return v unless v.nil?
-    the_values(1, fact, maps)
+    _values(1, fact, maps, fb)
   end
 
+  # Simplifies AND or OR expressions by removing duplicates
+  # @return [Factbase::Term] Simplified term
   def and_or_simplify
     strs = []
     ops = []
@@ -65,17 +95,26 @@ module Factbase::Term::Logical
       ops << o
     end
     return ops[0] if ops.size == 1
-    Factbase::Term.new(@fb, @op, ops)
+    self.class.new(@op, ops)
   end
 
+  # Simplifies AND expressions by removing duplicates
+  # @return [Factbase::Term] Simplified term
   def and_simplify
     and_or_simplify
   end
 
+  # Simplifies OR expressions by removing duplicates
+  # @return [Factbase::Term] Simplified term
   def or_simplify
     and_or_simplify
   end
 
+  # Helper method to ensure a value is boolean
+  # @param [Object] val The value to check
+  # @param [Integer] pos The position of the operand
+  # @return [Boolean] The boolean value
+  # @raise [RuntimeError] If value is not a boolean
   def _only_bool(val, pos)
     val = val[0] if val.respond_to?(:each)
     return false if val.nil?

data/lib/factbase/terms/math.rb

@@ -11,54 +11,54 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Math
-  def plus(fact, maps)
-    arithmetic(:+, fact, maps)
+  def plus(fact, maps, fb)
+    _arithmetic(:+, fact, maps, fb)
   end
 
-  def minus(fact, maps)
-    arithmetic(:-, fact, maps)
+  def minus(fact, maps, fb)
+    _arithmetic(:-, fact, maps, fb)
   end
 
-  def times(fact, maps)
-    arithmetic(:*, fact, maps)
+  def times(fact, maps, fb)
+    _arithmetic(:*, fact, maps, fb)
   end
 
-  def div(fact, maps)
-    arithmetic(:/, fact, maps)
+  def div(fact, maps, fb)
+    _arithmetic(:/, fact, maps, fb)
   end
 
-  def zero(fact, maps)
+  def zero(fact, maps, fb)
     assert_args(1)
-    vv = the_values(0, fact, maps)
+    vv = _values(0, fact, maps, fb)
     return false if vv.nil?
     vv.any? { |v| (v.is_a?(Integer) || v.is_a?(Float)) && v.zero? }
   end
 
-  def eq(fact, maps)
-    cmp(:==, fact, maps)
+  def eq(fact, maps, fb)
+    _cmp(:==, fact, maps, fb)
   end
 
-  def lt(fact, maps)
-    cmp(:<, fact, maps)
+  def lt(fact, maps, fb)
+    _cmp(:<, fact, maps, fb)
   end
 
-  def gt(fact, maps)
-    cmp(:>, fact, maps)
+  def gt(fact, maps, fb)
+    _cmp(:>, fact, maps, fb)
   end
 
-  def lte(fact, maps)
-    cmp(:<=, fact, maps)
+  def lte(fact, maps, fb)
+    _cmp(:<=, fact, maps, fb)
   end
 
-  def gte(fact, maps)
-    cmp(:>=, fact, maps)
+  def gte(fact, maps, fb)
+    _cmp(:>=, fact, maps, fb)
   end
 
-  def cmp(op, fact, maps)
+  def _cmp(op, fact, maps, fb)
     assert_args(2)
-    lefts = the_values(0, fact, maps)
+    lefts = _values(0, fact, maps, fb)
     return false if lefts.nil?
-    rights = the_values(1, fact, maps)
+    rights = _values(1, fact, maps, fb)
     return false if rights.nil?
     lefts.any? do |l|
       l = l.floor if l.is_a?(Time) && op == :==
@@ -69,12 +69,12 @@ module Factbase::Term::Math
     end
   end
 
-  def arithmetic(op, fact, maps)
+  def _arithmetic(op, fact, maps, fb)
     assert_args(2)
-    lefts = the_values(0, fact, maps)
+    lefts = _values(0, fact, maps, fb)
     return nil if lefts.nil?
     raise 'Too many values at first position, one expected' unless lefts.size == 1
-    rights = the_values(1, fact, maps)
+    rights = _values(1, fact, maps, fb)
     return nil if rights.nil?
     raise 'Too many values at second position, one expected' unless rights.size == 1
     v = lefts[0]

data/lib/factbase/terms/meta.rb

@@ -11,46 +11,46 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Meta
-  def exists(fact, _maps)
+  def exists(fact, _maps, _fb)
     assert_args(1)
-    !by_symbol(0, fact).nil?
+    !_by_symbol(0, fact).nil?
   end
 
-  def absent(fact, _maps)
+  def absent(fact, _maps, _fb)
     assert_args(1)
-    by_symbol(0, fact).nil?
+    _by_symbol(0, fact).nil?
   end
 
-  def size(fact, _maps)
+  def size(fact, _maps, _fb)
     assert_args(1)
-    v = by_symbol(0, fact)
+    v = _by_symbol(0, fact)
     return 0 if v.nil?
     return 1 unless v.respond_to?(:to_a)
     v.size
   end
 
-  def type(fact, _maps)
+  def type(fact, _maps, _fb)
     assert_args(1)
-    v = by_symbol(0, fact)
+    v = _by_symbol(0, fact)
     return 'nil' if v.nil?
     v = v[0] if v.respond_to?(:each) && v.size == 1
     v.class.to_s
   end
 
-  def nil(fact, maps)
+  def nil(fact, maps, fb)
     assert_args(1)
-    the_values(0, fact, maps).nil?
+    _values(0, fact, maps, fb).nil?
   end
 
-  def many(fact, maps)
+  def many(fact, maps, fb)
     assert_args(1)
-    v = the_values(0, fact, maps)
+    v = _values(0, fact, maps, fb)
     !v.nil? && v.size > 1
   end
 
-  def one(fact, maps)
+  def one(fact, maps, fb)
     assert_args(1)
-    v = the_values(0, fact, maps)
+    v = _values(0, fact, maps, fb)
     !v.nil? && v.size == 1
   end
 end

data/lib/factbase/terms/ordering.rb

@@ -11,18 +11,18 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Ordering
-  def prev(fact, maps)
+  def prev(fact, maps, fb)
     assert_args(1)
     before = @prev
-    v = the_values(0, fact, maps)
+    v = _values(0, fact, maps, fb)
     @prev = v
     before
   end
 
-  def unique(fact, maps)
+  def unique(fact, maps, fb)
     @uniques = [] if @uniques.nil?
     assert_args(1)
-    vv = the_values(0, fact, maps)
+    vv = _values(0, fact, maps, fb)
     return false if vv.nil?
     vv = [vv] unless vv.respond_to?(:to_a)
     vv.each do |v|

data/lib/factbase/terms/strings.rb

@@ -11,22 +11,22 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Strings
-  def concat(fact, maps)
-    (0..@operands.length - 1).map { |i| the_values(i, fact, maps)&.first }.join
+  def concat(fact, maps, fb)
+    (0..@operands.length - 1).map { |i| _values(i, fact, maps, fb)&.first }.join
   end
 
-  def sprintf(fact, maps)
-    fmt = the_values(0, fact, maps)[0]
-    ops = (1..@operands.length - 1).map { |i| the_values(i, fact, maps)&.first }
+  def sprintf(fact, maps, fb)
+    fmt = _values(0, fact, maps, fb)[0]
+    ops = (1..@operands.length - 1).map { |i| _values(i, fact, maps, fb)&.first }
     format(*([fmt] + ops))
   end
 
-  def matches(fact, maps)
+  def matches(fact, maps, fb)
     assert_args(2)
-    str = the_values(0, fact, maps)
+    str = _values(0, fact, maps, fb)
     return false if str.nil?
     raise 'Exactly one string expected' unless str.size == 1
-    re = the_values(1, fact, maps)
+    re = _values(1, fact, maps, fb)
     raise 'Regexp is nil' if re.nil?
     raise 'Exactly one regexp expected' unless re.size == 1
     str[0].to_s.match?(re[0])

data/lib/factbase/terms/system.rb

@@ -11,9 +11,9 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::System
-  def env(fact, maps)
+  def env(fact, maps, fb)
     assert_args(2)
-    n = the_values(0, fact, maps)[0]
-    ENV.fetch(n.upcase) { the_values(1, fact, maps)[0] }
+    n = _values(0, fact, maps, fb)[0]
+    ENV.fetch(n.upcase) { _values(1, fact, maps, fb)[0] }
   end
 end

data/lib/factbase.rb

@@ -50,6 +50,24 @@ require 'yaml'
 #  fb2 = Factbase.new # it's empty
 #  fb2.import(File.binread(file))
 #
+# Here's how to use transactions to ensure data consistency:
+#
+#  fb = Factbase.new
+#  # Successful transaction
+#  fb.txn do |fbt|
+#    f = fbt.insert
+#    f.name = 'John'
+#    f.age = 30
+#    # If any error occurs here, all changes will be rolled back
+#  end
+#  # Transaction with rollback
+#  fb.txn do |fbt|
+#    f = fbt.insert
+#    f.name = 'Jane'
+#    f.age = 25
+#    raise Factbase::Rollback # This will undo all changes in this transaction
+#  end
+#
 # It's impossible to delete properties of a fact. It is however possible to
 # delete the entire fact, with the help of the +query()+ and then +delete!()+
 # methods.
@@ -57,26 +75,22 @@ require 'yaml'
 # It's important to use +binwrite+ and +binread+, because the content is
 # a chain of bytes, not a text.
 #
-# Objects of this class are thread-safe.
+# It is NOT thread-safe!
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase
   # Current version of the gem (changed by .rultor.yml on every release)
-  VERSION = '0.7.5'
+  VERSION = '0.9.0'
 
   # An exception that may be thrown in a transaction, to roll it back.
   class Rollback < StandardError; end
 
-  attr_reader :cache
-
   # Constructor.
   # @param [Array<Hash>] maps Array of facts to start with
-  def initialize(maps = [], cache: {})
+  def initialize(maps = [])
     @maps = maps
-    @mutex = Mutex.new
-    @cache = cache
   end
 
   # Size, the total number of facts in the factbase.
@@ -95,12 +109,9 @@ class Factbase
   # @return [Factbase::Fact] The fact just inserted
   def insert
     map = {}
-    @mutex.synchronize do
-      @maps << map
-    end
-    @cache.clear
+    @maps << map
     require_relative 'factbase/fact'
-    Factbase::Fact.new(self, @mutex, map)
+    Factbase::Fact.new(map)
   end
 
   # Create a query capable of iterating.
@@ -120,22 +131,27 @@ class Factbase
   # The full list of terms available in the query you can find in the
   # +README.md+ file of the repository.
   #
-  # @param [String] query The query to use for selections
-  # @param [Array<Hash>] maps Custom maps
-  def query(query, maps = @maps)
+  # @param [String|Factbase::Term] term The query to use for selections
+  # @param [Array<Hash>|nil] maps The subset of maps (if provided)
+  def query(term, maps = nil)
+    maps ||= @maps
+    term = to_term(term) if term.is_a?(String)
     require_relative 'factbase/query'
-    require_relative 'factbase/query_once'
-    Factbase::QueryOnce.new(
-      self,
-      Factbase::Query.new(self, maps, @mutex, query),
-      maps
-    )
+    Factbase::Query.new(maps, term, self)
+  end
+
+  # Convert a query to a term.
+  # @param [String] query The query to convert
+  # @return [Factbase::Term] The term
+  def to_term(query)
+    require_relative 'factbase/syntax'
+    Factbase::Syntax.new(query).to_term
   end
 
   # Run an ACID transaction, which will either modify the factbase
   # or rollback in case of an error.
   #
-  # If necessary to terminate a transaction and roolback all changes,
+  # If necessary to terminate a transaction and rollback all changes,
   # you should raise the +Factbase::Rollback+ exception:
   #
   #  fb = Factbase.new
@@ -144,53 +160,49 @@ class Factbase
   #    raise Factbase::Rollback
   #  end
   #
-  # A the end of this script, the factbase will be empty. No facts will
+  # At the end of this script, the factbase will be empty. No facts will be
   # inserted and all changes that happened in the block will be rolled back.
   #
   # @return [Factbase::Churn] How many facts have been changed (zero if rolled back)
   def txn
     pairs = {}
     before =
-      @mutex.synchronize do
-        @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
+      @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)
     begin
       require_relative 'factbase/light'
-      yield Factbase::Light.new(Factbase.new(taped, cache: @cache), @cache)
+      yield Factbase::Light.new(Factbase.new(taped))
     rescue Factbase::Rollback
       return 0
     end
     require_relative 'factbase/churn'
     churn = Factbase::Churn.new
-    @mutex.synchronize do
-      taped.inserted.each do |oid|
-        b = taped.find_by_object_id(oid)
-        next if b.nil?
-        @maps << b
-        churn.append(1, 0, 0)
-      end
-      garbage = []
-      taped.added.each do |oid|
-        b = taped.find_by_object_id(oid)
-        next if b.nil?
-        garbage << pairs[oid]
-        @maps << b
-        churn.append(0, 0, 1)
-      end
-      taped.deleted.each do |oid|
-        garbage << pairs[oid]
-        churn.append(0, 1, 0)
-      end
-      @maps.delete_if { |m| garbage.include?(m.object_id) }
+    taped.inserted.each do |oid|
+      b = taped.find_by_object_id(oid)
+      next if b.nil?
+      @maps << b
+      churn.append(1, 0, 0)
+    end
+    garbage = []
+    taped.added.each do |oid|
+      b = taped.find_by_object_id(oid)
+      next if b.nil?
+      garbage << pairs[oid]
+      @maps << b
+      churn.append(0, 0, 1)
+    end
+    taped.deleted.each do |oid|
+      garbage << pairs[oid]
+      churn.append(0, 1, 0)
     end
+    @maps.delete_if { |m| garbage.include?(m.object_id) }
     churn
   end
 
@@ -204,7 +216,7 @@ class Factbase
   #
   # The data is binary, it's not a text!
   #
-  # @return [Bytes] The chain of bytes
+  # @return [String] Binary string containing serialized data
   def export
     Marshal.dump(@maps)
   end
@@ -217,9 +229,9 @@ class Factbase
   #  fb.import(File.binread("foo.fb"))
   #
   # The facts that existed in the factbase before importing will remain there.
-  # The facts from the incoming byte stream will added to them.
+  # The facts from the incoming byte stream will be added to them.
   #
-  # @param [Bytes] bytes Byte array to import
+  # @param [String] bytes Binary string to import
   def import(bytes)
     raise 'Empty input, cannot load a factbase' if bytes.empty?
     @maps += Marshal.load(bytes)

data/test/factbase/cached/test_cached_factbase.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../test__helper'
+require_relative '../../../lib/factbase'
+require_relative '../../../lib/factbase/cached/cached_factbase'
+
+# Query test.
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class TestCachedFactbase < Factbase::Test
+  def test_inserts_and_queries
+    fb = Factbase::CachedFactbase.new(Factbase.new)
+    f = fb.insert
+    f.foo = 1
+    f.bar = 'test'
+    assert_equal(1, fb.query('(and (eq foo 1) (eq bar "test"))').each.to_a.size)
+  end
+end

data/test/factbase/cached/test_cached_query.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../test__helper'
+require_relative '../../../lib/factbase'
+require_relative '../../../lib/factbase/cached/cached_factbase'
+require_relative '../../../lib/factbase/indexed/indexed_factbase'
+require_relative '../../../lib/factbase/sync/sync_factbase'
+
+# Query test.
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class TestCachedQuery < Factbase::Test
+  def test_queries_many_times
+    fb = Factbase::CachedFactbase.new(Factbase.new)
+    total = 5
+    total.times { fb.insert }
+    total.times do
+      assert_equal(5, fb.query('(always)').each.to_a.size)
+    end
+  end
+
+  def test_negates_correctly
+    fb = Factbase::CachedFactbase.new(Factbase.new)
+    fb.insert.foo = 42
+    3.times do
+      assert_equal(1, fb.query('(always)').each.to_a.size)
+      assert_equal(0, fb.query('(not (always))').each.to_a.size)
+    end
+  end
+
+  def test_aggregates_too
+    fb = Factbase::IndexedFactbase.new(Factbase::CachedFactbase.new(Factbase.new))
+    10_000.times do |i|
+      f = fb.insert
+      f.foo = i
+      f.hello = 1
+    end
+    3.times do
+      q = fb.query('(eq foo (agg (exists hello) (min foo)))')
+      assert_equal(1, q.each.to_a.size)
+    end
+  end
+
+  def test_joins_too
+    fb = Factbase::IndexedFactbase.new(Factbase::CachedFactbase.new(Factbase.new))
+    total = 10
+    total.times do |i|
+      f = fb.insert
+      f.foo = i
+      f.hello = 1
+    end
+    3.times do
+      assert_equal(total, fb.query('(join "bar<=foo" (eq foo (agg (exists hello) (min foo))))').each.to_a.size)
+    end
+  end
+
+  def test_caches_while_being_decorated
+    fb = Factbase::SyncFactbase.new(Factbase::CachedFactbase.new(Factbase.new))
+    10_000.times do |i|
+      f = fb.insert
+      f.foo = i
+      f.hello = 1
+    end
+    3.times do
+      assert_equal(1, fb.query('(eq foo (agg (exists hello) (min foo)))').each.to_a.size)
+    end
+  end
+
+  def test_deletes_too
+    fb = Factbase::CachedFactbase.new(Factbase.new)
+    fb.insert.foo = 1
+    fb.query('(eq foo 1)').delete!
+    assert_equal(0, fb.query('(always)').each.to_a.size)
+  end
+end