factbase 0.8.0 → 0.9.1

data/lib/factbase/query.rb

@@ -4,9 +4,9 @@
 # SPDX-License-Identifier: MIT
 
 require_relative '../factbase'
-require_relative 'syntax'
-require_relative 'fact'
 require_relative 'accum'
+require_relative 'fact'
+require_relative 'syntax'
 require_relative 'tee'
 
 # Query.
@@ -21,40 +21,37 @@ require_relative 'tee'
 # License:: MIT
 class Factbase::Query
   # Constructor.
-  # @param [Factbase] fb Factbase
   # @param [Array<Fact>] maps Array of facts to start with
-  # @param [Mutex] mutex Mutex to sync all modifications to the +maps+
-  # @param [String] query The query as a string
-  def initialize(fb, maps, mutex, query)
-    @fb = fb
+  # @param [String|Factbase::Term] term The query term
+  def initialize(maps, term, fb)
     @maps = maps
-    @mutex = mutex
-    @query = query
+    @term = term.is_a?(String) ? Factbase::Syntax.new(term).to_term : term
+    @fb = fb
   end
 
   # Print it as a string.
   # @return [String] The query as a string
   def to_s
-    @query.to_s
+    @term.to_s
   end
 
   # Iterate facts one by one.
+  # @param [Factbase] fb The factbase
   # @param [Hash] params Optional params accessible in the query via the "$" symbol
   # @yield [Fact] Facts one-by-one
   # @return [Integer] Total number of facts yielded
-  def each(params = {})
-    return to_enum(__method__, params) unless block_given?
-    term = Factbase::Syntax.new(@fb, @query).to_term
+  def each(fb = @fb, params = {})
+    return to_enum(__method__, fb, params) unless block_given?
     yielded = 0
-    @maps.each do |m|
+    params = params.transform_keys(&:to_s) if params.is_a?(Hash)
+    (@term.predict(@maps, params) || @maps).each do |m|
       extras = {}
-      f = Factbase::Fact.new(@fb, @mutex, m)
-      params = params.transform_keys(&:to_s) if params.is_a?(Hash)
+      f = Factbase::Fact.new(m)
       f = Factbase::Tee.new(f, params)
       a = Factbase::Accum.new(f, extras, false)
-      r = term.evaluate(a, @maps)
+      r = @term.evaluate(a, @maps, fb)
       unless r.is_a?(TrueClass) || r.is_a?(FalseClass)
-        raise "Unexpected evaluation result of type #{r.class}, must be Boolean at #{@query.inspect}"
+        raise "Unexpected evaluation result of type #{r.class}, must be Boolean at #{@term.inspect}"
       end
       next unless r
       yield Factbase::Accum.new(f, extras, true)
@@ -64,32 +61,30 @@ class Factbase::Query
   end
 
   # Read a single value.
+  # @param [Factbase] fb The factbase
   # @param [Hash] params Optional params accessible in the query via the "$" symbol
-  # @return The value evaluated
-  def one(params = {})
-    term = Factbase::Syntax.new(@fb, @query).to_term
+  # @return [String|Integer|Float|Time|Array|NilClass] The value evaluated
+  def one(fb = @fb, params = {})
     params = params.transform_keys(&:to_s) if params.is_a?(Hash)
-    r = term.evaluate(Factbase::Tee.new(nil, params), @maps)
+    r = @term.evaluate(Factbase::Tee.new(Factbase::Fact.new({}), params), @maps, fb)
     unless %w[String Integer Float Time Array NilClass].include?(r.class.to_s)
-      raise "Incorrect type #{r.class} returned by #{@query.inspect}"
+      raise "Incorrect type #{r.class} returned by #{@term.inspect}"
     end
     r
   end
 
   # Delete all facts that match the query.
+  # @param [Factbase] fb The factbase to delete from
   # @return [Integer] Total number of facts deleted
-  def delete!
-    term = Factbase::Syntax.new(@fb, @query).to_term
+  def delete!(fb = @fb)
     deleted = 0
-    @mutex.synchronize do
-      @maps.delete_if do |m|
-        f = Factbase::Fact.new(@fb, @mutex, m)
-        if term.evaluate(f, @maps)
-          deleted += 1
-          true
-        else
-          false
-        end
+    @maps.delete_if do |m|
+      f = Factbase::Fact.new(m)
+      if @term.evaluate(f, @maps, fb)
+        deleted += 1
+        true
+      else
+        false
       end
     end
     deleted

data/lib/factbase/rules.rb

@@ -37,11 +37,11 @@ class Factbase::Rules
   end
 
   def insert
-    Fact.new(@fb.insert, @check)
+    Fact.new(@fb.insert, @check, @fb)
   end
 
-  def query(query)
-    Query.new(@fb.query(query), @check)
+  def query(query, maps = nil)
+    Query.new(@fb.query(query, maps), @check, @fb)
   end
 
   def txn
@@ -53,7 +53,7 @@ class Factbase::Rules
       @check = before
       fbt.query('(always)').each do |f|
         next unless later.include?(f)
-        @check.it(f)
+        @check.it(f, @fb)
       end
     end
   end
@@ -63,9 +63,10 @@ class Factbase::Rules
   # This is an internal class, it is not supposed to be instantiated directly.
   #
   class Fact
-    def initialize(fact, check)
+    def initialize(fact, check, fb)
       @fact = fact
       @check = check
+      @fb = fb
     end
 
     def to_s
@@ -79,7 +80,7 @@ class Factbase::Rules
     others do |*args|
       r = @fact.method_missing(*args)
       k = args[0].to_s
-      @check.it(@fact) if k.end_with?('=')
+      @check.it(@fact, @fb) if k.end_with?('=')
       r
     end
   end
@@ -87,19 +88,19 @@ class Factbase::Rules
   # Query decorator.
   #
   # This is an internal class, it is not supposed to be instantiated directly.
-  #
   class Query
     decoor(:query)
 
-    def initialize(query, check)
+    def initialize(query, check, fb)
       @query = query
       @check = check
+      @fb = fb
     end
 
-    def each(params = {})
-      return to_enum(__method__, params) unless block_given?
-      @query.each do |f|
-        yield Fact.new(f, @check)
+    def each(fb = @fb, params = {})
+      return to_enum(__method__, fb, params) unless block_given?
+      @query.each(fb, params) do |f|
+        yield Fact.new(f, @check, fb)
       end
     end
   end
@@ -112,8 +113,8 @@ class Factbase::Rules
       @expr = expr
     end
 
-    def it(fact)
-      return if Factbase::Syntax.new(Factbase.new, @expr).to_term.evaluate(fact, [])
+    def it(fact, fb)
+      return if Factbase::Syntax.new(@expr).to_term.evaluate(fact, [], fb)
       e = "#{@expr[0..32]}..." if @expr.length > 32
       raise "The fact doesn't match the #{e.inspect} rule: #{fact}"
     end
@@ -128,7 +129,7 @@ class Factbase::Rules
       @facts = Set.new
     end
 
-    def it(fact)
+    def it(fact, _fb)
       a = fact[@uid]
       return if a.nil?
       @facts << a[0] unless @uid.nil?

data/lib/factbase/sync/sync_factbase.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require 'decoor'
+require_relative '../../factbase'
+
+# A synchronous thread-safe factbase.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::SyncFactbase
+  decoor(:origin)
+
+  # Constructor.
+  # @param [Factbase] origin Original factbase to decorate
+  # @param [Mutex] mutex Mutex to use for synchronization
+  def initialize(origin, mutex = Mutex.new)
+    @origin = origin
+    @mutex = mutex
+  end
+
+  # Insert a new fact and return it.
+  # @return [Factbase::Fact] The fact just inserted
+  def insert
+    @mutex.synchronize do
+      @origin.insert
+    end
+  end
+
+  # Convert a query to a term.
+  # @param [String] query The query to convert
+  # @return [Factbase::Term] The term
+  def to_term(query)
+    @origin.to_term(query)
+  end
+
+  # Create a query capable of iterating.
+  # @param [String] term The query to use for selections
+  # @param [Array<Hash>] maps Possible maps to use
+  def query(term, maps = nil)
+    term = to_term(term) if term.is_a?(String)
+    require_relative 'sync_query'
+    Factbase::SyncQuery.new(@origin.query(term, maps), @mutex, self)
+  end
+
+  # Run an ACID transaction.
+  # @return [Factbase::Churn] How many facts have been changed (zero if rolled back)
+  # @yield [Factbase] Block to execute in transaction
+  def txn
+    @origin.txn do |fbt|
+      yield Factbase::SyncFactbase.new(fbt, @mutex)
+    end
+  end
+end

data/lib/factbase/sync/sync_query.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative '../../factbase'
+
+# Synchronized thread-safe query.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::SyncQuery
+  # Constructor.
+  # @param [Factbase::Query] origin Original query
+  # @param [Mutex] mutex The mutex
+  def initialize(origin, mutex, fb)
+    @origin = origin
+    @mutex = mutex
+    @fb = fb
+  end
+
+  # Iterate facts one by one.
+  # @param [Hash] params Optional params accessible in the query via the "$" symbol
+  # @yield [Fact] Facts one-by-one
+  # @return [Integer] Total number of facts yielded
+  def each(fb = @fb, params = {}, &)
+    return to_enum(__method__, fb, params) unless block_given?
+    try_lock do
+      @origin.each(fb, params, &)
+    end
+  end
+
+  # Read a single value.
+  # @param [Factbase] fb The factbase
+  # @param [Hash] params Optional params accessible in the query via the "$" symbol
+  # @return [String|Integer|Float|Time|Array|NilClass] The value evaluated
+  def one(fb = @fb, params = {})
+    try_lock do
+      @origin.one(fb, params)
+    end
+  end
+
+  # Delete all facts that match the query.
+  # @param [Factbase] fb The factbase
+  # @return [Integer] Total number of facts deleted
+  def delete!(fb = @fb)
+    try_lock do
+      @origin.delete!(fb)
+    end
+  end
+
+  private
+
+  def try_lock
+    locked = @mutex.try_lock
+    r = yield
+    @mutex.unlock if locked
+    r
+  end
+end

data/lib/factbase/syntax.rb

@@ -8,22 +8,11 @@ require 'time'
 require_relative '../factbase'
 require_relative 'fact'
 require_relative 'term'
-require_relative 'term_once'
 
-# Syntax.
+# Syntax parser.
 #
 # This is an internal class, it is not supposed to be instantiated directly.
 #
-# However, you can use it directly, if you need a parser of our syntax. You can
-# create your own "Term" class and let this parser make instances of it for
-# every term it meets in the query:
-#
-#  require 'factbase/syntax'
-#  t = Factbase::Syntax.new(Factbase.new, '(hello world)', MyTerm).to_term
-#
-# The +MyTerm+ class should have a constructor with two arguments:
-# the operator and the list of operands (Array).
-#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
@@ -33,19 +22,13 @@ class Factbase::Syntax
 
   # Ctor.
   #
-  # The class provided as the +term+ argument must have a three-argument
-  # constructor, similar to the class +Factbase::Term+. Also, it must be
+  # The class provided as the +term+ argument must have a constructor that accepts
+  # an operator, operands array, and a keyword argument fb. Also, it must be
   # a child of +Factbase::Term+.
   #
-  # @param [Factbase] fb Factbase
   # @param [String] query The query, for example "(eq id 42)"
-  # @param [Class] term The class to instantiate to make every term
-  def initialize(fb, query, term: Factbase::Term)
-    @fb = fb
+  def initialize(query)
     @query = query
-    raise "Term must be a Class, while #{term.class.name} provided" unless term.is_a?(Class)
-    raise "The 'term' must be a child of Factbase::Term, while #{term.name} provided" unless term <= Factbase::Term
-    @term = term
   end
 
   # Convert it to a term.
@@ -74,7 +57,7 @@ class Factbase::Syntax
     raise "Too many terms (#{@ast[1]} != #{@tokens.size})" if @ast[1] != @tokens.size
     t = @ast[0]
     raise 'No terms found in the AST' if t.nil?
-    raise "#{t.class.name} is not an instance of #{@term}, thus not a proper term" unless t.is_a?(@term)
+    raise "#{t.class.name} is not an instance of Term" unless t.is_a?(Factbase::Term)
     t
   end
 
@@ -82,9 +65,13 @@ class Factbase::Syntax
   # token at the position is not a literal (like 42 or "Hello") but a term,
   # the function recursively calls itself.
   #
-  # The function returns an two-elements array, where the first element
+  # The function returns a two-element array, where the first element
   # is the term/literal and the second one is the position where the
   # scanning should continue.
+  #
+  # @param [Array] tokens Array of tokens
+  # @param [Integer] at Position to start parsing from
+  # @return [Array<Factbase::Term,Integer>] The term detected and ending position
   def to_ast(tokens, at)
     raise "Closing too soon at ##{at}" if tokens[at] == :close
     return [tokens[at], at + 1] unless tokens[at] == :open
@@ -103,12 +90,12 @@ class Factbase::Syntax
       operands << operand
       break if tokens[at] == :close
     end
-    t = @term.new(@fb, op, operands)
-    t = Factbase::TermOnce.new(t, @fb.cache) if t.instance_of?(Factbase::Term)
+    t = Factbase::Term.new(op, operands)
     [t, at + 1]
   end
 
   # Turns a query into an array of tokens.
+  # @return [Array] Array of tokens
   def to_tokens
     list = []
     acc = ''

data/lib/factbase/tallied.rb

@@ -31,8 +31,8 @@ class Factbase::Tallied
     f
   end
 
-  def query(query)
-    Query.new(@fb.query(query), @churn)
+  def query(query, maps = nil)
+    Query.new(@fb.query(query, maps), @churn, @fb)
   end
 
   def txn
@@ -69,24 +69,25 @@ class Factbase::Tallied
   #
   # This is an internal class, it is not supposed to be instantiated directly.
   class Query
-    def initialize(query, churn)
+    def initialize(query, churn, fb)
       @query = query
       @churn = churn
+      @fb = fb
     end
 
-    def one(params = {})
-      @query.one(params)
+    def one(fb = @fb, params = {})
+      @query.one(fb, params)
     end
 
-    def each(params = {}, &)
-      return to_enum(__method__, params) unless block_given?
-      @query.each(params) do |f|
+    def each(fb = @fb, params = {}, &)
+      return to_enum(__method__, fb, params) unless block_given?
+      @query.each(fb, params) do |f|
         yield Fact.new(f, @churn)
       end
     end
 
-    def delete!
-      c = @query.delete!
+    def delete!(fb = @fb)
+      c = @query.delete!(fb)
       @churn.append(0, c, 0)
       c
     end

data/lib/factbase/taped.rb

@@ -59,6 +59,14 @@ class Factbase::Taped
     end
   end
 
+  def to_a
+    @origin.to_a
+  end
+
+  def group_by(&)
+    @origin.group_by(&)
+  end
+
   # Decorator of Hash.
   class TapedHash
     def initialize(origin, added)

data/lib/factbase/tee.rb

@@ -16,7 +16,9 @@ class Factbase::Tee
   # @param [Factbase::Fact] fact Primary fact to use for reading
   # @param [Factbase::Fact] upper Fact to access with a "$" prefix
   def initialize(fact, upper)
+    raise 'Fact is nil' if fact.nil?
     @fact = fact
+    raise 'Upper is nil' if upper.nil?
     @upper = upper
   end
 

data/lib/factbase/term.rb

@@ -17,8 +17,8 @@ require_relative 'tee'
 #
 #  require 'factbase/fact'
 #  require 'factbase/term'
-#  f = Factbase::Fact.new(Factbase.new, Mutex.new, { 'foo' => [42, 256, 'Hello, world!'] })
-#  t = Factbase::Term.new(Factbase.new, :lt, [:foo, 50])
+#  f = Factbase::Fact.new({ 'foo' => [42, 256, 'Hello, world!'] })
+#  t = Factbase::Term.new(:lt, [:foo, 50])
 #  assert(t.evaluate(f))
 #
 # The design of this class may look ugly, since it has a large number of
@@ -30,11 +30,19 @@ require_relative 'tee'
 # Moreover, it looks like the number of possible term types is rather limited
 # and currently we implement most of them.
 #
+# It is NOT thread-safe!
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 class Factbase::Term
-  attr_reader :op, :operands
+  # The operator of this term
+  # @return [Symbol] The operator
+  attr_reader :op
+
+  # The operands of this term
+  # @return [Array] The operands
+  attr_reader :operands
 
   require_relative 'terms/math'
   include Factbase::Term::Math
@@ -70,21 +78,41 @@ class Factbase::Term
   include Factbase::Term::Debug
 
   # Ctor.
-  # @param [Factbase] fb Factbase
   # @param [Symbol] operator Operator
   # @param [Array] operands Operands
-  def initialize(fb, operator, operands)
-    @fb = fb
+  def initialize(operator, operands)
     @op = operator
     @operands = operands
   end
 
+  def redress!(type, **args)
+    extend type
+    args.each { |k, v| send(:instance_variable_set, :"@#{k}", v) }
+    @operands.map do |op|
+      if op.is_a?(Factbase::Term)
+        op.redress!(type, **args)
+      else
+        op
+      end
+    end
+  end
+
+  # Try to predict which facts from the provided list
+  # should be evaluated. If no prediction can be made,
+  # the same list is returned.
+  # @param [Array<Hash>] maps Records to iterate, maybe
+  # @return [Array<Hash>] Records to iterate
+  def predict(maps, _params)
+    maps
+  end
+
   # Does it match the fact?
   # @param [Factbase::Fact] fact The fact
   # @param [Array<Factbase::Fact>] maps All maps available
-  # @return [bool] TRUE if matches
-  def evaluate(fact, maps)
-    send(@op, fact, maps)
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] TRUE if matches
+  def evaluate(fact, maps, fb)
+    send(@op, fact, maps, fb)
   rescue NoMethodError => e
     raise "Probably the term '#{@op}' is not defined at #{self}:\n#{Backtrace.new(e)}"
   rescue StandardError => e
@@ -146,26 +174,26 @@ class Factbase::Term
     "(#{items.join(' ')})"
   end
 
-  private
-
-  def at(fact, maps)
+  def at(fact, maps, fb)
     assert_args(2)
-    i = the_values(0, fact, maps)
+    i = _values(0, fact, maps, fb)
     raise "Too many values (#{i.size}) at first position, one expected" unless i.size == 1
     i = i[0]
     return nil if i.nil?
-    v = the_values(1, fact, maps)
+    v = _values(1, fact, maps, fb)
     return nil if v.nil?
     v[i]
   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)
+  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
@@ -173,9 +201,9 @@ class Factbase::Term
   end
 
   # @return [Array|nil] Either array of values or NIL
-  def the_values(pos, fact, maps)
+  def _values(pos, fact, maps, fb)
     v = @operands[pos]
-    v = v.evaluate(fact, maps) if v.is_a?(Factbase::Term)
+    v = v.evaluate(fact, maps, fb) if v.is_a?(Factbase::Term)
     v = fact[v.to_s] if v.is_a?(Symbol)
     return v if v.nil?
     unless v.is_a?(Array)

data/lib/factbase/terms/aggregates.rb

@@ -11,30 +11,32 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Aggregates
-  def min(_fact, maps)
+  def min(_fact, maps, _fb)
     assert_args(1)
-    best(maps) { |v, b| v < b }
+    _best(maps) { |v, b| v < b }
   end
 
-  def max(_fact, maps)
+  def max(_fact, maps, _fb)
     assert_args(1)
-    best(maps) { |v, b| v > b }
+    _best(maps) { |v, b| v > b }
   end
 
-  def count(_fact, maps)
+  def count(_fact, maps, _fb)
     maps.size
   end
 
-  def nth(_fact, maps)
+  def nth(_fact, maps, _fb)
     assert_args(2)
     pos = @operands[0]
     raise "An integer expected, but #{pos} provided" unless pos.is_a?(Integer)
     k = @operands[1]
     raise "A symbol expected, but #{k} provided" unless k.is_a?(Symbol)
-    maps[pos][k.to_s]
+    m = maps[pos]
+    return nil if m.nil?
+    m[k.to_s]
   end
 
-  def first(_fact, maps)
+  def first(_fact, maps, _fb)
     assert_args(1)
     k = @operands[0]
     raise "A symbol expected, but #{k} provided" unless k.is_a?(Symbol)
@@ -43,7 +45,7 @@ module Factbase::Term::Aggregates
     first[k.to_s]
   end
 
-  def sum(_fact, maps)
+  def sum(_fact, maps, _fb)
     k = @operands[0]
     raise "A symbol expected, but '#{k}' provided" unless k.is_a?(Symbol)
     sum = 0
@@ -58,24 +60,24 @@ module Factbase::Term::Aggregates
     sum
   end
 
-  def agg(fact, maps)
+  def agg(fact, maps, fb)
     assert_args(2)
     selector = @operands[0]
     raise "A term expected, but '#{selector}' provided" unless selector.is_a?(Factbase::Term)
     term = @operands[1]
     raise "A term expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
-    subset = @fb.query(selector.to_s, maps).each(fact).to_a
-    term.evaluate(nil, subset)
+    subset = fb.query(selector, maps).each(fb, fact).to_a
+    term.evaluate(nil, subset, fb)
   end
 
-  def empty(fact, maps)
+  def empty(fact, maps, fb)
     assert_args(1)
     term = @operands[0]
     raise "A term expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
-    @fb.query(term.to_s, maps).each(fact).to_a.empty?
+    fb.query(term, maps).each(fb, fact).to_a.empty?
   end
 
-  def best(maps)
+  def _best(maps)
     k = @operands[0]
     raise "A symbol expected, but #{k} provided" unless k.is_a?(Symbol)
     best = nil