factbase 0.16.7 → 0.17.0

data/lib/factbase/terms/head.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# Represents a 'head' term in the Factbase.
+# It retrieves the first N results from a query.
+class Factbase::Head < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = 'head'
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] _fact The fact
+  # @param [Array<Factbase::Fact>] _maps All maps available
+  # @param [Factbase] _fb Factbase to use for sub-queries
+  # @return [Boolean] Always true
+  def evaluate(_fact, _maps, _fb)
+    true
+  end
+
+  def predict(maps, fb, params)
+    assert_args(2)
+    max = @operands[0]
+    raise "An integer is expected as first argument of '#{@op}'" unless max.is_a?(Integer)
+    term = @operands[1]
+    raise "A term is expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
+    fb.query(term, maps).each(fb, params).to_a
+      .take(max)
+      .map { |m| m.all_properties.to_h { |k| [k, m[k]] } }
+  end
+end

data/lib/factbase/terms/inverted.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# Evaluates whether a value is inverted within a given factbase context.
+class Factbase::Inverted < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = 'inverted'
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] _fact The fact
+  # @param [Array<Factbase::Fact>] _maps All maps available
+  # @param [Factbase] _fb Factbase to use for sub-queries
+  # @return [Boolean] Whether the value is inverted
+  def evaluate(_fact, _maps, _fb)
+    true
+  end
+
+  def predict(maps, fb, params)
+    assert_args(1)
+    term = @operands[0]
+    raise "A term is expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
+    fb.query(term, maps).each(fb, params).to_a
+      .reverse
+      .map { |m| m.all_properties.to_h { |k| [k, m[k]] } }
+  end
+end

data/lib/factbase/terms/{aliases.rb → join.rb}

@@ -3,24 +3,24 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-require_relative '../../factbase'
+require_relative 'base'
 
-# Aliases terms.
-#
-# Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
-# License:: MIT
-module Factbase::Aliases
-  def as(fact, maps, fb)
-    assert_args(2)
-    a = @operands[0]
-    raise "A symbol is expected as first argument of 'as'" unless a.is_a?(Symbol)
-    vv = _values(1, fact, maps, fb)
-    vv&.each { |v| fact.send(:"#{a}=", v) }
-    true
+# The Factbase::Join class is a specialized term that performs
+# join operations between facts based on specified attribute mappings.
+class Factbase::Join < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
   end
 
-  def join(fact, maps, fb)
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] True if succeeded
+  def evaluate(fact, maps, fb)
     assert_args(2)
     jumps = @operands[0]
     raise "A string is expected as first argument of 'join'" unless jumps.is_a?(String)

data/lib/factbase/terms/logical.rb

@@ -11,77 +11,6 @@ require_relative '../../factbase'
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
 module Factbase::Logical
-  # 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
-
-  # 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
-
-  # 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(_values(0, fact, maps, fb), 0)
-  end
-
-  # 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(_values(i, fact, maps, fb), i)
-    end
-    false
-  end
-
-  # 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(_values(i, fact, maps, fb), i)
-    end
-    true
-  end
-
-  # 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, fb) || (a.evaluate(fact, maps, fb) && b.evaluate(fact, maps, fb))
-  end
-
-  # 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 = _values(0, fact, maps, fb)
-    return v unless v.nil?
-    _values(1, fact, maps, fb)
-  end
-
   # Simplifies AND or OR expressions by removing duplicates
   # @return [Factbase::Term] Simplified term
   def and_or_simplify
@@ -109,16 +38,4 @@ module Factbase::Logical
   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?
-    return val if val.is_a?(TrueClass) || val.is_a?(FalseClass)
-    raise "Boolean is expected, while #{val.class} received from #{@operands[pos]}"
-  end
 end

data/lib/factbase/terms/lt.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'compare'
+
+# Represents a less-than term in the Factbase system.
+# This class is used to evaluate whether a given fact satisfies
+# a less-than comparison with the specified operands.
+class Factbase::Lt < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @op = Factbase::Compare.new(:<, operands)
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] The result of the less-than comparison
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/lte.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'compare'
+
+# Represents a less-than-equal term in the Factbase.
+# This class is used to evaluate whether a given fact satisfies
+# a less-than-equal comparison with the specified operands.
+class Factbase::Lte < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @op = Factbase::Compare.new(:<=, operands)
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] The result of the less-than-equal comparison
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/many.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# Represents a 'many' term in the Factbase that evaluates to true if a property
+# has multiple values. This class is used to check if there are more
+# than one values associated with a specific property in a fact.
+class Factbase::Many < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] True if many
+  def evaluate(fact, maps, fb)
+    assert_args(1)
+    v = _values(0, fact, maps, fb)
+    !v.nil? && v.size > 1
+  end
+end

data/lib/factbase/terms/{strings.rb → matches.rb}

@@ -3,25 +3,25 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-require_relative '../../factbase'
+require_relative 'base'
 
-# String terms.
+# Matches term.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
-module Factbase::Strings
-  def concat(fact, maps, fb)
-    (0..(@operands.length - 1)).map { |i| _values(i, fact, maps, fb)&.first }.join
+class Factbase::Matches < Factbase::TermBase
+  def initialize(operands)
+    super()
+    @operands = operands
   end
 
-  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, fb)
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] True if the string matches the regexp, false otherwise
+  def evaluate(fact, maps, fb)
     assert_args(2)
     str = _values(0, fact, maps, fb)
     return false if str.nil?

data/lib/factbase/terms/minus.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# This class represents a 'minus' term within the Factbase.
+# It performs a subtraction operation over the given operands.
+class Factbase::Minus < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @minus = Factbase::Arithmetic.new(:-, operands)
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Object] Result of the subtraction
+  def evaluate(fact, maps, fb)
+    @minus.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/never.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# The term 'never' that never evaluates to true.
+class Factbase::Never < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands = [])
+    super()
+    @operands = operands
+    @op = :never
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] _fact The fact
+  # @param [Array<Factbase::Fact>] _maps All maps available
+  # @param [Factbase] _fb Factbase to use for sub-queries
+  # @return [Boolean] Always returns false
+  def evaluate(_fact, _maps, _fb)
+    assert_args(0)
+    false
+  end
+end

data/lib/factbase/terms/nil.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# A class representing a "nil" term in the Factbase system.
+# It evaluates to true if the value is nil.
+class Factbase::Nil < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] True if nil
+  def evaluate(fact, maps, fb)
+    assert_args(1)
+    _values(0, fact, maps, fb).nil?
+  end
+end

data/lib/factbase/terms/not.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'boolean'
+# The 'not' term that negates a boolean operand.
+# Logical negation (NOT) of an operand.
+class Factbase::Not < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :not
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @return [Boolean] Negated boolean result of the operand
+  def evaluate(fact, maps, fb)
+    assert_args(1)
+    !Factbase::Boolean.new(_values(0, fact, maps, fb), @operands[0]).bool?
+  end
+end

data/lib/factbase/terms/one.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# The term which property has exactly one value.
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::One < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Boolean] True if exactly one value
+  def evaluate(fact, maps, fb)
+    assert_args(1)
+    v = _values(0, fact, maps, fb)
+    !v.nil? && v.size == 1
+  end
+end

data/lib/factbase/terms/or.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'boolean'
+# The 'or' term that represents a logical OR operation between multiple operands.
+class Factbase::Or < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :or
+  end
+
+  # Evaluate term on a fact.
+  # @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 evaluate(fact, maps, fb)
+    (0..(@operands.size - 1)).each do |i|
+      return true if Factbase::Boolean.new(_values(i, fact, maps, fb), @operands[i]).bool?
+    end
+    false
+  end
+end

data/lib/factbase/terms/plus.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'arithmetic'
+
+# Represents a Plus term in the Factbase system.
+# This class is used to perform addition operations on operands.
+class Factbase::Plus < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @plus = Factbase::Arithmetic.new(:+, operands)
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Object] Result of the addition
+  def evaluate(fact, maps, fb)
+    @plus.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/prev.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# The Factbase::Unique class provides functionality for evaluating the uniqueness
+# of terms based on provided operands and facts.
+class Factbase::Prev < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] maps All maps available
+  # @param [Factbase] fb Factbase to use for sub-queries
+  # @return [Object] The previous value
+  def evaluate(fact, maps, fb)
+    assert_args(1)
+    before = @prev
+    v = _values(0, fact, maps, fb)
+    @prev = v
+    before
+  end
+end

data/lib/factbase/terms/shared.rb

@@ -0,0 +1,69 @@
+# 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

data/lib/factbase/terms/size.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# Factbase::Size is a term that calculates the size of an operand
+# when evaluated on a given fact.
+class Factbase::Size < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+  end
+
+  # Evaluate term on a fact.
+  # @param [Factbase::Fact] fact The fact
+  # @param [Array<Factbase::Fact>] _maps All maps available
+  # @param [Factbase] _fb Factbase to use for sub-queries
+  # @return [Integer] Size of the operand
+  def evaluate(fact, _maps, _fb)
+    assert_args(1)
+    v = _by_symbol(0, fact)
+    return 0 if v.nil?
+    return 1 unless v.respond_to?(:to_a)
+    v.size
+  end
+end