factbase 0.19.10 → 0.19.12

data/lib/factbase/terms/boolean.rb

@@ -23,6 +23,6 @@ class Factbase::Boolean
     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}"
+    raise(ArgumentError, "Boolean is expected, while #{val.class} received from #{@from}")
   end
 end

data/lib/factbase/terms/compare.rb

@@ -31,8 +31,24 @@ class Factbase::Compare < Factbase::TermBase
       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)
+        _compare(l, r)
       end
     end
   end
+
+  private
+
+  # Compare values with a contextual error if Ruby rejects the operands.
+  # @param [Object] left Left value
+  # @param [Object] right Right value
+  # @return [Boolean] The result of the comparison
+  def _compare(left, right)
+    left.__send__(@op, right)
+  rescue ArgumentError => e
+    raise(
+      RuntimeError,
+      "Cannot compare #{left.inspect} (#{left.class}) " \
+      "with #{right.inspect} (#{right.class}) using (compare #{@op}): #{e.message}"
+    )
+  end
 end

data/lib/factbase/terms/contains.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'compare'
+
+# Represents a 'contains' term in the Factbase.
+# Returns true if any value of the left operand contains any value of the right
+# as a substring. Operates on string values via `String#include?`.
+class Factbase::Contains < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @op = Factbase::Compare.new(:include?, 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 any left value includes any right value
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/defn.rb

@@ -25,13 +25,15 @@ class Factbase::Defn < Factbase::TermBase
   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)
-    raise "Can't use '#{fn}' name as a term" if Factbase::Term.method_defined?(fn)
-    raise "Term '#{fn}' is already defined" if Factbase::Term.private_method_defined?(fn, false)
-    raise "The '#{fn}' is a bad name for a term" unless fn.match?(/^[a-z_]+$/)
-    e = "class Factbase::Term\nprivate\ndef #{fn}(fact, maps, fb)\n#{@operands[1]}\nend\nend"
+    raise(ArgumentError, "A symbol expected as first argument of 'defn'") unless fn.is_a?(Symbol)
+    raise(ArgumentError, "Can't use '#{fn}' name as a term") if Factbase::Term.method_defined?(fn)
+    raise(ArgumentError, "Term '#{fn}' is already defined") if Factbase::Term.private_method_defined?(fn, false)
+    raise(ArgumentError, "The '#{fn}' is a bad name for a term") unless fn.match?(/^[a-z_]+$/)
     # rubocop:disable Security/Eval
-    eval(e)
+    eval(
+      "class Factbase::Term\nprivate\ndef #{fn}(fact, maps, fb)\n#{@operands[1]}\nend\nend",
+      binding, __FILE__, __LINE__ - 1
+    )
     # rubocop:enable Security/Eval
     true
   end

data/lib/factbase/terms/empty.rb

@@ -24,7 +24,7 @@ class Factbase::Empty < Factbase::TermBase
     assert_args(1)
     term = @operands[0]
     unless term.is_a?(Factbase::Term) || term.is_a?(Factbase::TermBase)
-      raise "A term is expected, but '#{term}' provided"
+      raise(ArgumentError, "A term is expected, but '#{term}' provided")
     end
     # rubocop:disable Lint/UnreachableLoop
     fb.query(term, maps).each(fb, fact) do

data/lib/factbase/terms/ends_with.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'compare'
+
+# Represents an 'ends_with' term in the Factbase.
+# Returns true if any value of the left operand ends with any value of the right.
+class Factbase::EndsWith < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @op = Factbase::Compare.new(:end_with?, 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 any left value ends with any right value
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/first.rb

@@ -22,9 +22,9 @@ class Factbase::First < Factbase::TermBase
   def evaluate(_fact, maps, _fb)
     assert_args(1)
     k = @operands[0]
-    raise "A symbol is expected, but #{k} provided" unless k.is_a?(Symbol)
+    raise(ArgumentError, "A symbol is expected, but #{k} provided") unless k.is_a?(Symbol)
     first = maps[0]
-    return nil if first.nil?
+    return if first.nil?
     first[k.to_s]
   end
 end

data/lib/factbase/terms/head.rb

@@ -27,11 +27,11 @@ class Factbase::Head < Factbase::TermBase
   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)
+    raise(ArgumentError, "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)
+    raise(ArgumentError, "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]] } }
+      .map! { |m| m.all_properties.to_h { |k| [k, m[k]] } }
   end
 end

data/lib/factbase/terms/inverted.rb

@@ -26,9 +26,9 @@ class Factbase::Inverted < Factbase::TermBase
   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)
+    raise(ArgumentError, "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]] } }
+      .map! { |m| m.all_properties.to_h { |k| [k, m[k]] } }
   end
 end

data/lib/factbase/terms/join.rb

@@ -23,18 +23,19 @@ class Factbase::Join < Factbase::TermBase
   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)
-    jumps = jumps.split(',')
-      .map(&:strip)
-      .map { |j| j.split('<=').map(&:strip) }
-      .map { |j| j.size == 1 ? [j[0], j[0]] : j }
+    raise(ArgumentError, "A string is expected as first argument of 'join'") unless jumps.is_a?(String)
+    jumps =
+      jumps.split(',')
+        .map(&:strip)
+        .map! { |j| j.split('<=').map(&:strip) }
+        .map! { |j| j.size == 1 ? [j[0], j[0]] : j }
     term = @operands[1]
-    raise "A term is expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
+    raise(ArgumentError, "A term is expected, but '#{term}' provided") unless term.is_a?(Factbase::Term)
     subset = fb.query(term, maps).each(fb, fact).to_a
     subset.each do |s|
       jumps.each do |to, from|
         s[from]&.each do |v|
-          fact.send(:"#{to}=", v)
+          fact.__send__(:"#{to}=", v)
         end
       end
     end

data/lib/factbase/terms/matches.rb

@@ -14,6 +14,7 @@ class Factbase::Matches < Factbase::TermBase
   def initialize(operands)
     super()
     @operands = operands
+    @regexps = {}
   end
 
   # Evaluate term on a fact.
@@ -25,10 +26,19 @@ class Factbase::Matches < Factbase::TermBase
     assert_args(2)
     str = _values(0, fact, maps, fb)
     return false if str.nil?
-    raise 'Exactly one string is expected' unless str.size == 1
+    raise(RuntimeError, 'Exactly one string is expected') unless str.size == 1
     re = _values(1, fact, maps, fb)
-    raise 'Regexp is nil' if re.nil?
-    raise 'Exactly one regexp is expected' unless re.size == 1
-    str[0].to_s.match?(re[0])
+    raise(RuntimeError, 'Regexp is nil') if re.nil?
+    raise(RuntimeError, 'Exactly one regexp is expected') unless re.size == 1
+    str[0].to_s.match?(regexp(re[0]))
+  end
+
+  private
+
+  def regexp(pattern)
+    key = pattern.to_s
+    @regexps[key] ||= Regexp.new(key)
+  rescue RegexpError => e
+    raise(RuntimeError, "Invalid regexp '#{key}': #{e.message}")
   end
 end

data/lib/factbase/terms/max.rb

@@ -4,8 +4,8 @@
 # SPDX-License-Identifier: MIT
 
 require_relative '../../factbase'
-require_relative 'best'
 require_relative 'base'
+require_relative 'best'
 
 # The 'max' term.
 # This term calculates the max value among the evaluated operands.

data/lib/factbase/terms/min.rb

@@ -4,8 +4,8 @@
 # SPDX-License-Identifier: MIT
 
 require_relative '../../factbase'
-require_relative 'best'
 require_relative 'base'
+require_relative 'best'
 
 # The 'min' term.
 # This term calculates the minimum value among the evaluated operands.

data/lib/factbase/terms/nth.rb

@@ -23,11 +23,11 @@ class Factbase::Nth < Factbase::TermBase
   def evaluate(_fact, maps, _fb)
     assert_args(2)
     pos = @operands[0]
-    raise "An integer is expected, but #{pos} provided" unless pos.is_a?(Integer)
+    raise(ArgumentError, "An integer is expected, but #{pos} provided") unless pos.is_a?(Integer)
     k = @operands[1]
-    raise "A symbol is expected, but #{k} provided" unless k.is_a?(Symbol)
+    raise(ArgumentError, "A symbol is expected, but #{k} provided") unless k.is_a?(Symbol)
     m = maps[pos]
-    return nil if m.nil?
+    return if m.nil?
     m[k.to_s]
   end
 end

data/lib/factbase/terms/plus.rb

@@ -3,8 +3,8 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-require_relative 'base'
 require_relative 'arithmetic'
+require_relative 'base'
 
 # Represents a Plus term in the Factbase system.
 # This class is used to perform addition operations on operands.

data/lib/factbase/terms/prev.rb

@@ -4,8 +4,8 @@
 # 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.
+# The Factbase::Prev class returns the previous value of a property
+# during iteration, enabling comparisons between consecutive facts.
 class Factbase::Prev < Factbase::TermBase
   # Constructor.
   # @param [Array] operands Operands
@@ -21,9 +21,6 @@ class Factbase::Prev < Factbase::TermBase
   # @return [Object] The previous value
   def evaluate(fact, maps, fb)
     assert_args(1)
-    before = @prev
-    v = _values(0, fact, maps, fb)
-    @prev = v
-    before
+    @prev.tap { @prev = _values(0, fact, maps, fb) }
   end
 end

data/lib/factbase/terms/sorted.rb

@@ -27,9 +27,9 @@ class Factbase::Sorted < Factbase::TermBase
   def predict(maps, fb, params)
     assert_args(2)
     prop = @operands[0]
-    raise "A symbol is expected as first argument of 'sorted'" unless prop.is_a?(Symbol)
+    raise(ArgumentError, "A symbol is expected as first argument of 'sorted'") unless prop.is_a?(Symbol)
     term = @operands[1]
-    raise "A term is expected, but '#{term}' provided" unless term.is_a?(Factbase::Term)
+    raise(ArgumentError, "A term is expected, but '#{term}' provided") unless term.is_a?(Factbase::Term)
     fb.query(term, maps).each(fb, params).to_a
       .reject { |m| m[prop].nil? }
       .sort_by { |m| m[prop].first }

data/lib/factbase/terms/sprintf.rb

@@ -22,8 +22,17 @@ class Factbase::Sprintf < Factbase::TermBase
   # @param [Factbase] fb Factbase to use for sub-queries
   # @return [String] The formatted string
   def evaluate(fact, maps, fb)
-    fmt = _values(0, fact, maps, fb)[0]
-    ops = (1..(@operands.length - 1)).map { |i| _values(i, fact, maps, fb)&.first }
+    formatted(
+      _values(0, fact, maps, fb)[0],
+      (1..(@operands.length - 1)).map { |i| _values(i, fact, maps, fb)&.first }
+    )
+  end
+
+  private
+
+  def formatted(fmt, ops)
     format(*([fmt] + ops))
+  rescue ArgumentError => e
+    raise(RuntimeError, "Cannot format #{ops.inspect} with '#{fmt}' in (sprintf ...): #{e.message}")
   end
 end

data/lib/factbase/terms/starts_with.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+# SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
+# SPDX-License-Identifier: MIT
+
+require_relative 'base'
+require_relative 'compare'
+
+# Represents a 'starts_with' term in the Factbase.
+# Returns true if any value of the left operand starts with any value of the right.
+class Factbase::StartsWith < Factbase::TermBase
+  # Constructor.
+  # @param [Array] operands Operands
+  def initialize(operands)
+    super()
+    @op = Factbase::Compare.new(:start_with?, 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 any left value starts with any right value
+  def evaluate(fact, maps, fb)
+    @op.evaluate(fact, maps, fb)
+  end
+end

data/lib/factbase/terms/sum.rb

@@ -6,7 +6,7 @@
 require_relative 'base'
 
 # This class represents a specialized 'sum' term.
-# This term  calculates the sum of values for a specified key.
+# This term calculates the sum of values for a specified key.
 class Factbase::Sum < Factbase::TermBase
   # Constructor.
   # @param [Array] operands Operands
@@ -23,7 +23,7 @@ class Factbase::Sum < Factbase::TermBase
   # @return [Integer] The sum of values for the specified key across all maps
   def evaluate(_fact, maps, _fb)
     k = @operands[0]
-    raise "A symbol is expected, but '#{k}' provided" unless k.is_a?(Symbol)
+    raise(ArgumentError, "A symbol is expected, but '#{k}' provided") unless k.is_a?(Symbol)
     sum = 0
     maps.each do |m|
       vv = m[k.to_s]

data/lib/factbase/terms/to_float.rb

@@ -22,7 +22,7 @@ class Factbase::ToFloat < Factbase::TermBase
   def evaluate(fact, maps, fb)
     assert_args(1)
     vv = _values(0, fact, maps, fb)
-    return nil if vv.nil?
-    vv[0].to_f
+    return if vv.nil?
+    Float(vv[0])
   end
 end

data/lib/factbase/terms/to_integer.rb

@@ -22,7 +22,7 @@ class Factbase::ToInteger < Factbase::TermBase
   def evaluate(fact, maps, fb)
     assert_args(1)
     vv = _values(0, fact, maps, fb)
-    return nil if vv.nil?
-    vv[0].to_i
+    return if vv.nil?
+    Integer(vv[0])
   end
 end

data/lib/factbase/terms/to_string.rb

@@ -22,7 +22,7 @@ class Factbase::ToString < Factbase::TermBase
   def evaluate(fact, maps, fb)
     assert_args(1)
     vv = _values(0, fact, maps, fb)
-    return nil if vv.nil?
+    return if vv.nil?
     vv[0].to_s
   end
 end

data/lib/factbase/terms/to_time.rb

@@ -22,7 +22,15 @@ class Factbase::ToTime < Factbase::TermBase
   def evaluate(fact, maps, fb)
     assert_args(1)
     vv = _values(0, fact, maps, fb)
-    return nil if vv.nil?
-    Time.parse(vv[0].to_s)
+    return if vv.nil?
+    parse(vv[0])
+  end
+
+  private
+
+  def parse(value)
+    Time.parse(value.to_s)
+  rescue ArgumentError => e
+    raise(RuntimeError, "Cannot parse '#{value}' as Time in (to_time ...): #{e.message}")
   end
 end

data/lib/factbase/terms/traced.rb

@@ -25,9 +25,9 @@ class Factbase::Traced < Factbase::TermBase
   def evaluate(fact, maps, fb)
     assert_args(1)
     t = @operands[0]
-    raise "A term is expected, but '#{t}' provided" unless t.is_a?(Factbase::Term)
+    raise(ArgumentError, "A term is expected, but '#{t}' provided") unless t.is_a?(Factbase::Term)
     r = t.evaluate(fact, maps, fb)
-    puts "#{self} -> #{r}" # rubocop:disable Lint/Debugger
+    puts("#{self} -> #{r}") # rubocop:disable Lint/Debugger
     r
   end
 end

data/lib/factbase/terms/undef.rb

@@ -24,9 +24,9 @@ class Factbase::Undef < Factbase::TermBase
   def evaluate(_fact, _maps, _fb)
     assert_args(1)
     fn = @operands[0]
-    raise "A symbol expected as first argument of 'undef'" unless fn.is_a?(Symbol)
+    raise(ArgumentError, "A symbol expected as first argument of 'undef'") unless fn.is_a?(Symbol)
     if Factbase::Term.private_method_defined?(fn, false)
-      Factbase::Term.class_eval("undef :#{fn}", __FILE__, __LINE__ - 1) # undef :foo
+      Factbase::Term.class_eval("undef :#{fn}", __FILE__, __LINE__ - 1)
     end
     true
   end

data/lib/factbase/terms/unique.rb

@@ -21,14 +21,10 @@ class Factbase::Unique < Factbase::TermBase
   # @return [Boolean] True if the value is unique, false otherwise
   def evaluate(fact, maps, fb)
     @seen = Set.new if @seen.nil?
-    raise "Too few operands for 'unique' (at least 1 expected)" if @operands.empty?
+    raise(ArgumentError, "Too few operands for 'unique' (at least 1 expected)") if @operands.empty?
     vv = (0..(@operands.size - 1)).map { |i| _values(i, fact, maps, fb) }
     return false if vv.any?(nil)
-    pass = true
-    Enumerator.product(*vv).to_a.each do |t|
-      pass = false if @seen.include?(t)
-      @seen << t
-    end
-    pass
+    tuples = Enumerator.product(*vv).to_a
+    tuples.none? { |t| @seen.include?(t) }.tap { tuples.each { |t| @seen << t } }
   end
 end

data/lib/factbase/terms/when.rb

@@ -22,8 +22,7 @@ class Factbase::When < Factbase::TermBase
   # @return [Boolean] True if first operand is false OR both are true
   def evaluate(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))
+    return true unless @operands[0].evaluate(fact, maps, fb)
+    @operands[1].evaluate(fact, maps, fb)
   end
 end

data/lib/factbase/to_json.rb

@@ -9,7 +9,7 @@ require_relative '../factbase/flatten'
 
 # Factbase to JSON converter.
 #
-# This class helps converting an entire Factbase to YAML format, for example:
+# This class helps converting an entire Factbase to JSON format, for example:
 #
 #  require 'factbase/to_json'
 #  fb = Factbase.new
@@ -28,6 +28,6 @@ class Factbase::ToJSON
   # Convert the entire factbase into JSON.
   # @return [String] The factbase in JSON format
   def json
-    Factbase::Flatten.new(Marshal.load(@fb.export), @sorter).it.to_json
+    Factbase::Flatten.new(@fb.each.to_a, @sorter).it.to_json
   end
 end

data/lib/factbase/to_xml.rb

@@ -10,7 +10,7 @@ require_relative '../factbase/flatten'
 
 # Factbase to XML converter.
 #
-# This class helps converting an entire Factbase to YAML format, for example:
+# This class helps converting an entire Factbase to XML format, for example:
 #
 #  require 'factbase/to_xml'
 #  fb = Factbase.new
@@ -29,24 +29,20 @@ class Factbase::ToXML
   # Convert the entire factbase into XML.
   # @return [String] The factbase in XML format
   def xml
-    bytes = @fb.export
-    meta = {
-      version: Factbase::VERSION,
-      size: bytes.size
-    }
+    meta = { version: Factbase::VERSION, size: @fb.export.size }
     Nokogiri::XML::Builder.new(encoding: 'UTF-8') do |xml|
       xml.fb(meta) do
-        Factbase::Flatten.new(Marshal.load(bytes), @sorter).it.each do |m|
+        Factbase::Flatten.new(@fb.each.to_a, @sorter).it.each do |m|
           xml.f_ do
             m.sort.to_h.each do |k, vv|
               if vv.is_a?(Array)
-                xml.send(:"#{k}_") do
+                xml.__send__(:"#{k}_") do
                   vv.each do |v|
-                    xml.send(:v, to_str(v), t: type_of(v))
+                    xml.__send__(:v, to_str(v), t: type_of(v))
                   end
                 end
               else
-                xml.send(:"#{k}_", to_str(vv), t: type_of(vv))
+                xml.__send__(:"#{k}_", to_str(vv), t: type_of(vv))
               end
             end
           end

data/lib/factbase/to_yaml.rb

@@ -28,6 +28,6 @@ class Factbase::ToYAML
   # Convert the entire factbase into YAML.
   # @return [String] The factbase in YAML format
   def yaml
-    YAML.dump(Factbase::Flatten.new(Marshal.load(@fb.export), @sorter).it)
+    YAML.dump(Factbase::Flatten.new(@fb.each.to_a, @sorter).it)
   end
 end

data/lib/factbase/version.rb

@@ -8,6 +8,5 @@
 # Copyright:: Copyright (c) 2024-2026 Yegor Bugayenko
 # License:: MIT
 class Factbase
-  # Current version of the gem (changed by .rultor.yml on every release)
-  VERSION = '0.19.10' unless const_defined?(:VERSION)
+  VERSION = '0.19.12' unless const_defined?(:VERSION)
 end

data/lib/factbase.rb

@@ -98,18 +98,22 @@ class Factbase
     @maps.size
   end
 
+  # Iterate over all facts yielding plain hashes.
+  # @yieldparam [Hash] fact Each fact as a plain Hash
+  # @return [Integer, Enumerator] Total number of facts or Enumerator
+  def each(&)
+    @maps.each(&)
+  end
+
   # Insert a new fact and return it.
   #
   # A fact, when inserted, is empty. It doesn't contain any properties.
   #
-  # The operation is thread-safe, meaning that different threads may
-  # insert facts in parallel without breaking the consistency of the factbase.
-  #
   # @return [Factbase::Fact] The fact just inserted
   def insert
     map = {}
     @maps << map
-    require_relative 'factbase/fact'
+    require_relative('factbase/fact')
     Factbase::Fact.new(map)
   end
 
@@ -135,7 +139,7 @@ class Factbase
   def query(term, maps = nil)
     maps ||= @maps
     term = to_term(term) if term.is_a?(String)
-    require_relative 'factbase/query'
+    require_relative('factbase/query')
     Factbase::Query.new(maps, term, self)
   end
 
@@ -143,7 +147,7 @@ class Factbase
   # @param [String] query The query to convert
   # @return [Factbase::Term] The term
   def to_term(query)
-    require_relative 'factbase/syntax'
+    require_relative('factbase/syntax')
     Factbase::Syntax.new(query).to_term
   end
 
@@ -164,15 +168,15 @@ class Factbase
   #
   # @return [Factbase::Churn] How many facts have been changed (zero if rolled back)
   def txn
-    require_relative 'factbase/lazy_taped'
+    require_relative('factbase/lazy_taped')
     taped = Factbase::LazyTaped.new(@maps)
-    require_relative 'factbase/churn'
+    require_relative('factbase/churn')
     churn = Factbase::Churn.new
-    catch :commit do
-      require_relative 'factbase/light'
+    catch(:commit) do
+      require_relative('factbase/light')
       commit = false
-      catch :rollback do
-        yield Factbase::Light.new(Factbase.new(taped))
+      catch(:rollback) do
+        yield(Factbase::Light.new(Factbase.new(taped)))
         commit = true
       end
       return churn unless commit
@@ -236,9 +240,19 @@ class Factbase
   # This method supports both the original format (Array of maps) and
   # the IndexedFactbase format (Hash with :maps and :idx keys).
   #
+  # SECURITY: the input must come from a source you trust, because it is
+  # deserialized with +Marshal.load+. Loading a +Marshal+ stream crafted
+  # by an attacker can execute arbitrary code in the calling process,
+  # so never call +import+ on bytes received over the network, read from
+  # a user-supplied path, or pulled from any other untrusted channel
+  # without an out-of-band integrity check. See the official Ruby
+  # security notes for +Marshal.load+ at
+  # https://docs.ruby-lang.org/en/3.3/security_rdoc.html#label-Marshal.load
+  # for details.
+  #
   # @param [String] bytes Binary string to import
   def import(bytes)
-    raise 'Empty input, cannot load a factbase' if bytes.empty?
+    raise(StandardError, 'Empty input, cannot load a factbase') if bytes.empty?
     data = Marshal.load(bytes)
     @maps +=
       if data.is_a?(Hash) && data.key?(:maps)