factbase 0.8.0 → 0.9.0

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

@@ -32,7 +32,7 @@ class Factbase::Tallied
   end
 
   def query(query)
-    Query.new(@fb.query(query), @churn)
+    Query.new(@fb.query(query), @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

data/lib/factbase/terms/aliases.rb

@@ -11,16 +11,16 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Aliases
-  def as(fact, maps)
+  def as(fact, maps, fb)
     assert_args(2)
     a = @operands[0]
     raise "A symbol expected as first argument of 'as'" unless a.is_a?(Symbol)
-    vv = the_values(1, fact, maps)
+    vv = _values(1, fact, maps, fb)
     vv&.each { |v| fact.send(:"#{a}=", v) }
     true
   end
 
-  def join(fact, maps)
+  def join(fact, maps, fb)
     assert_args(2)
     jumps = @operands[0]
     raise "A string expected as first argument of 'join'" unless jumps.is_a?(String)
@@ -30,7 +30,7 @@ module Factbase::Term::Aliases
       .map { |j| j.size == 1 ? [j[0], j[0]] : j }
     term = @operands[1]
     raise "A term expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
-    subset = @fb.query(term.to_s, maps).each(fact).to_a
+    subset = fb.query(term, maps).each(fb, fact).to_a
     subset.each do |s|
       jumps.each do |to, from|
         s[from]&.each do |v|

data/lib/factbase/terms/casting.rb

@@ -11,30 +11,30 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Casting
-  def to_string(fact, maps)
+  def to_string(fact, maps, fb)
     assert_args(1)
-    vv = the_values(0, fact, maps)
+    vv = _values(0, fact, maps, fb)
     return nil if vv.nil?
     vv[0].to_s
   end
 
-  def to_integer(fact, maps)
+  def to_integer(fact, maps, fb)
     assert_args(1)
-    vv = the_values(0, fact, maps)
+    vv = _values(0, fact, maps, fb)
     return nil if vv.nil?
     vv[0].to_i
   end
 
-  def to_float(fact, maps)
+  def to_float(fact, maps, fb)
     assert_args(1)
-    vv = the_values(0, fact, maps)
+    vv = _values(0, fact, maps, fb)
     return nil if vv.nil?
     vv[0].to_f
   end
 
-  def to_time(fact, maps)
+  def to_time(fact, maps, fb)
     assert_args(1)
-    vv = the_values(0, fact, maps)
+    vv = _values(0, fact, maps, fb)
     return nil if vv.nil?
     Time.parse(vv[0].to_s)
   end

data/lib/factbase/terms/debug.rb

@@ -11,11 +11,11 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Debug
-  def traced(fact, maps)
+  def traced(fact, maps, fb)
     assert_args(1)
     t = @operands[0]
     raise "A term expected, but '#{t}' provided" unless t.is_a?(Factbase::Term)
-    r = t.evaluate(fact, maps)
+    r = t.evaluate(fact, maps, fb)
     puts "#{self} -> #{r}"
     r
   end

data/lib/factbase/terms/defn.rb

@@ -11,21 +11,21 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Term::Defn
-  def defn(_fact, _maps)
+  def defn(_fact, _maps, _fb)
     assert_args(2)
     fn = @operands[0]
     raise "A symbol expected as first argument of 'defn'" unless fn.is_a?(Symbol)
     raise "Can't use '#{fn}' name as a term" if Factbase::Term.instance_methods(true).include?(fn)
     raise "Term '#{fn}' is already defined" if Factbase::Term.private_instance_methods(false).include?(fn)
     raise "The '#{fn}' is a bad name for a term" unless fn.match?(/^[a-z_]+$/)
-    e = "class Factbase::Term\nprivate\ndef #{fn}(fact, maps)\n#{@operands[1]}\nend\nend"
+    e = "class Factbase::Term\nprivate\ndef #{fn}(fact, maps, fb)\n#{@operands[1]}\nend\nend"
     # rubocop:disable Security/Eval
     eval(e)
     # rubocop:enable Security/Eval
     true
   end
 
-  def undef(_fact, _maps)
+  def undef(_fact, _maps, _fb)
     assert_args(1)
     fn = @operands[0]
     raise "A symbol expected as first argument of 'undef'" unless fn.is_a?(Symbol)