factbase 0.16.7 → 0.17.0

data/lib/factbase/terms/absent.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# Represents a term that evaluates to true if the specified operand is absent in the fact.
+class Factbase::Absent < 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 absent
+  def evaluate(fact, _maps, _fb)
+    assert_args(1)
+    _by_symbol(0, fact).nil?
+  end
+end

data/lib/factbase/terms/aggregates.rb

@@ -21,10 +21,6 @@ module Factbase::Aggregates
     _best(maps) { |v, b| v > b }
   end
 
-  def count(_fact, maps, _fb)
-    maps.size
-  end
-
   def nth(_fact, maps, _fb)
     assert_args(2)
     pos = @operands[0]
@@ -36,15 +32,6 @@ module Factbase::Aggregates
     m[k.to_s]
   end
 
-  def first(_fact, maps, _fb)
-    assert_args(1)
-    k = @operands[0]
-    raise "A symbol is expected, but #{k} provided" unless k.is_a?(Symbol)
-    first = maps[0]
-    return nil if first.nil?
-    first[k.to_s]
-  end
-
   def sum(_fact, maps, _fb)
     k = @operands[0]
     raise "A symbol is expected, but '#{k}' provided" unless k.is_a?(Symbol)

data/lib/factbase/terms/always.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# The term 'always' that always evaluates to true.
+# If you want to return all the facts you might use '(always)' query.
+class Factbase::Always < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands = [])
+    super()
+    @operands = operands
+    @op = :always
+  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 true
+  def evaluate(_fact, _maps, _fb)
+    assert_args(0)
+    true
+  end
+end

data/lib/factbase/terms/and.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 'and' term that represents a logical AND operation between multiple operands.
+class Factbase::And < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :and
+  end
+
+  # Evaluate term on a fact.
+  # @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 evaluate(fact, maps, fb)
+    (0..(@operands.size - 1)).each do |i|
+      return false unless Factbase::Boolean.new(_values(i, fact, maps, fb), @operands[i]).bool?
+    end
+    true
+  end
+end

data/lib/factbase/terms/arithmetic.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# Factbase::Arithmetic is a class for performing arithmetic operations.
+class Factbase::Arithmetic < Factbase::TermBase
+  # Constructor.
+  # @param [Symbol] operation The arithmetic operation (e.g., :+, :-, :*, :/)
+  # @param [Array] operands Operands
+  def initialize(operation, operands)
+    super()
+    @op = operation
+    @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 result of the arithmetic operation
+  def evaluate(fact, maps, fb)
+    assert_args(2)
+    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 = _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]
+    r = rights[0]
+    if v.is_a?(Time) && r.is_a?(String)
+      (num, units) = r.split
+      num = num.to_i
+      r =
+        case units
+        when 'seconds', 'second'
+          num
+        when 'minutes', 'minute'
+          num * 60
+        when 'hours', 'hour'
+          num * 60 * 60
+        when 'days', 'day'
+          num * 60 * 60 * 24
+        when 'weeks', 'week'
+          num * 60 * 60 * 24 * 7
+        else
+          raise "Unknown time unit '#{units}' in '#{r}"
+        end
+    end
+    v.send(@op, r)
+  end
+end

data/lib/factbase/terms/as.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+#
+# The Factbase::As class is a specialized term that evaluates
+# and assigns values to a specific attribute of a fact.
+class Factbase::As < 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 succeeded
+  def evaluate(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
+  end
+end

data/lib/factbase/terms/{debug.rb → assert.rb}

@@ -3,24 +3,26 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-require_relative '../../factbase'
+require_relative 'base'
 
-# Debug terms.
-#
-# Author:: Yegor Bugayenko (yegor256@gmail.com)
-# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
-# License:: MIT
-module Factbase::Debug
-  def traced(fact, maps, fb)
-    assert_args(1)
-    t = @operands[0]
-    raise "A term is expected, but '#{t}' provided" unless t.is_a?(Factbase::Term)
-    r = t.evaluate(fact, maps, fb)
-    puts "#{self} -> #{r}"
-    r
+# The `Factbase::Assert` class represents an assertion term in the Factbase system.
+# It verifies that a given condition evaluates to true, raising an error with
+# a specified message if the assertion fails.
+class Factbase::Assert < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = 'assert'
   end
 
-  def assert(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] Returns true if the assertion passes, otherwise raises an error with the provided message
+  def evaluate(fact, maps, fb)
     assert_args(2)
     message = @operands[0]
     unless message.is_a?(String)

data/lib/factbase/terms/base.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+# Test for unique term.
+# Author:: Volodya Lombrozo (volodya.lombrozo@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+
+# Base class for all terms.
+class Factbase::TermBase
+  require_relative 'shared'
+  include Factbase::TermShared
+
+  protected :assert_args, :_by_symbol, :_values, :to_s
+end

data/lib/factbase/terms/boolean.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# Boolean value checker.
+class Factbase::Boolean
+  # Constructor.
+  # @param [Object] val The value to check
+  # @param [Object] from The source of the value (for error messages)
+  # @return [Boolean] The boolean value
+  # @raise [RuntimeError] If value is not a boolean
+  def initialize(val, from)
+    @val = val
+    @from = from
+  end
+
+  # @return [Boolean] The boolean value
+  # @raise [RuntimeError] If value is not a boolean
+  def bool?
+    val = @val
+    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 #{@from}"
+  end
+end

data/lib/factbase/terms/compare.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# Term 'compare'.
+# Compares two values using a specified operation.
+class Factbase::Compare < Factbase::TermBase
+  # Constructor.
+  # @param [Symbol] operation Operation to perform, e.g. :>, :<, :<=, :>=, :==
+  # @param [Array] operands Operands
+  def initialize(operation, operands)
+    super()
+    @op = operation
+    @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] The result of the comparison
+  def evaluate(fact, maps, fb)
+    assert_args(2)
+    lefts = _values(0, fact, maps, fb)
+    return false if lefts.nil?
+    rights = _values(1, fact, maps, fb)
+    return false if rights.nil?
+    lefts.any? do |l|
+      l = l.floor if l.is_a?(Time) && @op == :==
+      rights.any? do |r|
+        r = r.floor if r.is_a?(Time) && @op == :==
+        l.send(@op, r)
+      end
+    end
+  end
+end

data/lib/factbase/terms/concat.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# Concat term.
+#
+# Author:: Yegor Bugayenko (yegor256@gmail.com)
+# Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
+# License:: MIT
+class Factbase::Concat < Factbase::TermBase
+  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 [String] The concatenated string
+  def evaluate(fact, maps, fb)
+    (0..(@operands.length - 1)).map { |i| _values(i, fact, maps, fb)&.first }.join
+  end
+end

data/lib/factbase/terms/count.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+# The 'count' term is used to perform a count operation on a set of maps.
+class Factbase::Count < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :count
+  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] The count of maps
+  def evaluate(_fact, maps, _fb)
+    maps.size
+  end
+end

data/lib/factbase/terms/defn.rb

@@ -3,15 +3,26 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-require_relative '../../factbase'
+require_relative 'base'
 
-# Defn terms.
-#
+# Factbase::Defn is responsible for defining new terms in the Factbase system.
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024-2025 Yegor Bugayenko
 # License:: MIT
-module Factbase::Defn
-  def defn(_fact, _maps, _fb)
+class Factbase::Defn < 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] Term definition result
+  def evaluate(_fact, _maps, _fb)
     assert_args(2)
     fn = @operands[0]
     raise "A symbol expected as first argument of 'defn'" unless fn.is_a?(Symbol)
@@ -24,14 +35,4 @@ module Factbase::Defn
     # rubocop:enable Security/Eval
     true
   end
-
-  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)
-    if Factbase::Term.private_instance_methods(false).include?(fn)
-      Factbase::Term.class_eval("undef :#{fn}", __FILE__, __LINE__ - 1) # undef :foo
-    end
-    true
-  end
 end

data/lib/factbase/terms/div.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 'div' term within the Factbase.
+# It performs a division operation over the given operands.
+class Factbase::Div < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @div = 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 division
+  def evaluate(fact, maps, fb)
+    @div.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/either.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# Represents a logical "either" term.
+# The term evaluates its operands and returns the first non-nil value.
+class Factbase::Either < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :either
+  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] First operand if not nil, otherwise second operand
+  # @return [Boolean] True if first operand is false OR both are true
+  def evaluate(fact, maps, fb)
+    assert_args(2)
+    v = _values(0, fact, maps, fb)
+    return v unless v.nil?
+    _values(1, fact, maps, fb)
+  end
+end

data/lib/factbase/terms/env.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# The `Factbase::Env` class is used to evaluate terms based on environment variables.
+# It retrieves the value of an environment variable or returns a default value if the variable is not set.
+class Factbase::Env < 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 [String] The value of the environment variable or the default
+  def evaluate(fact, maps, fb)
+    assert_args(2)
+    n = _values(0, fact, maps, fb)[0]
+    ENV.fetch(n.upcase) { _values(1, fact, maps, fb)[0] }
+  end
+end

data/lib/factbase/terms/eq.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 an equality term in the Factbase.
+# This class encapsulates the evaluation of equality comparisons
+# between operands within the context of a Factbase.
+class Factbase::Eq < 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 equality comparison
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/exists.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2025 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+
+# Represents a term that checks if a certain condition exists within the factbase.
+# This class evaluates whether a specific term exists in the given context of facts.
+class Factbase::Exists < 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 exists
+  def evaluate(fact, _maps, _fb)
+    assert_args(1)
+    !_by_symbol(0, fact).nil?
+  end
+end

data/lib/factbase/terms/first.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 'first' term is used to retrieve the value of a specified key from the first map in a set of maps.
+class Factbase::First < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @operands = operands
+    @op = :first
+  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 value of the specified key from the first map
+  def evaluate(_fact, maps, _fb)
+    assert_args(1)
+    k = @operands[0]
+    raise "A symbol is expected, but #{k} provided" unless k.is_a?(Symbol)
+    first = maps[0]
+    return nil if first.nil?
+    first[k.to_s]
+  end
+end

data/lib/factbase/terms/gt.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 greater-than comparison term in the Factbase.
+# This class is used to evaluate whether a given fact satisfies
+# the greater-than condition with the provided operands.
+class Factbase::Gt < 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 greater-than comparison
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/gte.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 'compare'
+
+# It represents a term for evaluating whether a set of operands satisfies
+# the "greater-than-or-equal-to" (>=) condition within the context of a factbase.
+class Factbase::Gte < 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 greater-than-or-equal comparison
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end