factbase 0.19.9 → 0.19.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c7c832590816ff7438ea62c6692d2567775088ab27567d407b2294b8caafced7
-  data.tar.gz: 3c4b7313117776731de9b91cca81c472cd6dfe9dd64e7390381e54194b912b77
+  metadata.gz: 712cd682bc9457b563afc7a855e56cad191d2a302406e0e4e9f886ce7fa83af3
+  data.tar.gz: cd3a312b78a152b7c9631777473e7465648e6b57d31d713d37d93c63834048ed
 SHA512:
-  metadata.gz: b7569a94be51517bb2860cf368849aaa22f89f96b04a16a29fafba294c6ad72c8b03e359f35024a482a82f657edfb36710ec7f60504ff4422663a96cc0a3ebc8
-  data.tar.gz: 7991d24eae8705444c781b35e00fe74b3f3087e015b3ac2cc1d59d250e0afddd70b7c23006dabf85d4d14dbc2c920a78f1e7e6068edc235c0b45dbdb4af5c17b
+  metadata.gz: 013ff487bbd8d2379224361b7794d5219d3235c9c66f645ebe1d6dd928d2298f1a411240328839ea48e08f7dd4c1161cde173530c52f5f8a5afdab52c66cce98
+  data.tar.gz: cf57ff6a8f881224a2124306871d245cab380331905fd0ec1acecd381a46d636a7877867a8f1ef27611f1dafe4f1e777c1a01aa57f08b35eb3486682aef22ad3

data/Gemfile.lock

@@ -16,7 +16,7 @@ PATH
 GEM
   remote: https://rubygems.org/
   specs:
-    ansi (1.5.0)
+    ansi (1.6.0)
     ast (2.4.3)
     backtrace (0.4.1)
     benchmark (0.5.0)
@@ -38,13 +38,13 @@ GEM
     loog (0.8.0)
       ellipsized
       logger (~> 1.0)
-    minitest (6.0.2)
+    minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
-    minitest-reporters (1.7.1)
+    minitest-reporters (1.8.0)
       ansi
       builder
-      minitest (>= 5.0)
+      minitest (>= 5.0, < 7)
       ruby-progressbar
     nokogiri (1.19.0-arm64-darwin)
       racc (~> 1.4)
@@ -64,14 +64,14 @@ GEM
     psych (5.3.1)
       date
       stringio
-    qbash (0.8.0)
+    qbash (0.8.4)
       backtrace (> 0)
       elapsed (> 0)
       loog (> 0)
       tago (> 0)
     racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.3.1)
+    rake (13.4.2)
     rdoc (7.1.0)
       erb
       psych (>= 4.0.0)

data/README.md

@@ -129,8 +129,7 @@ There are some boolean terms available in a query
 * `(not b)` is the inverse of `b`
 * `(or b1 b2 ...)` is `true` if at least one argument is `true`
 * `(and b1 b2 ...)` — if all arguments are `true`
-* `(when b1 b2)` — if `b1` is `true` and `b2` is `true`
-or `b1` is `false`
+* `(when b1 b2)` — true if `b1` is `false`, or if both `b1` and `b2` are `true`
 * `(exists p)` — if `p` property exists
 * `(absent p)` — if `p` property is absent
 * `(zero v)` — if any `v` equals to zero
@@ -145,6 +144,9 @@ There are string manipulators:
 * `(concat v1 v2 v3 ...)` — concatenates all `v`
 * `(sprintf v v1 v2 ...)` — creates a string by `v` format with params
 * `(matches v s)` — if any `v` matches the `s` regular expression
+* `(contains v s)` — if any value of `v` contains any value of `s` (substring match)
+* `(starts_with v s)` — if any `v` starts with `s`
+* `(ends_with v s)` — if any `v` ends with `s`
 
 There are a few terms that return non-boolean values:
 
@@ -152,7 +154,7 @@ There are a few terms that return non-boolean values:
 * `(size v)` is the cardinality of `v` (zero if `v` is `nil`)
 * `(type v)` is the type of `v`
 (`"String"`, `"Integer"`, `"Float"`, `"Time"`, or `"Array"`)
-* `(either v1 v1)` is `v2` if `v1` is `nil`
+* `(either v1 v2)` is `v2` if `v1` is `nil`
 
 It's possible to modify the facts retrieved, on fly:
 
@@ -227,6 +229,80 @@ There are some system-level terms:
 * `(env v1 v2)` returns the value of environment variable `v1` or the string
 `v2` if it's not set
 
+## Architecture
+
+The entire database is a single flat [Ruby](https://www.ruby-lang.org/en/)
+  `Array` of `Hash` objects held in RAM (`Factbase#@maps`). There are no
+  tables, schemas, or type enforcement beyond four scalar types: `Integer`,
+  `Float`, `String`, and `Time`. This contrasts with
+  [SQLite](https://sqlite.org/) (fixed-column tables on disk) and
+  [MongoDB](https://www.mongodb.com/) (typed document collections). New
+  programmers must understand that all data vanishes on process exit unless
+  `export`/`import` is called explicitly.
+
+Each property of a fact is a non-empty ordered set of values rather than a
+  single value. Assigning `f.foo = 1` then `f.foo = 2` produces
+  `f['foo'] == [1, 2]`; each assignment appends. Reading `f.foo` returns
+  the first element; `f['foo']` returns the full array. This accumulative
+  semantics differs from [SQL](https://www.iso.org/standard/76583.html)
+  (one value per column) and most NoSQL stores where assignment overwrites.
+  New programmers must expect multi-element arrays on every property read.
+
+Queries use a custom Lisp-style
+  [S-expression](https://en.wikipedia.org/wiki/S-expression) language:
+  `(and (eq kind 'book') (gt age 10))`. `Factbase::Syntax` tokenizes and
+  parses a query string into an AST of `Factbase::Term` objects;
+  `Factbase::Query#each` evaluates that AST against every fact. This
+  differs from [SQL](https://www.iso.org/standard/76583.html),
+  [XPath](https://www.w3.org/TR/xpath-31/), and
+  [JSONPath](https://datatracker.ietf.org/doc/html/rfc9535). New
+  programmers add operators by implementing a term class, not by modifying
+  parser grammar.
+
+Each query operator (`eq`, `gt`, `agg`, `join`, etc.) is a separate class
+  under `lib/factbase/terms/`. `Factbase::Term` holds a dispatch hash
+  (`@terms`) mapping operator symbols to instances and delegates `evaluate`
+  and `predict` calls there. This is not a class hierarchy — adding a new
+  operator requires a new file in `terms/` and a registration line in the
+  `Factbase::Term` constructor. New programmers extending the query
+  language must follow this two-step pattern.
+
+Transactions are ACID and implemented via lazy copy-on-write journaling.
+  `Factbase#txn` wraps the array in `Factbase::LazyTaped`, which defers
+  physical duplication of hash objects until the first write. Inserts,
+  deletes, and property additions are tracked by Ruby `object_id`. On
+  commit the journal is replayed into the main array; raising
+  `Factbase::Rollback` discards it. Nesting transactions is explicitly
+  forbidden by `Factbase::Light`. This differs from SQLite's
+  [WAL](https://sqlite.org/wal.html) and PostgreSQL's
+  [MVCC](https://www.postgresql.org/docs/current/mvcc.html).
+
+Cross-cutting capabilities — thread safety, indexing, constraint
+  validation, logging, and change counting — are added via decorators:
+  `Factbase::SyncFactbase`, `Factbase::IndexedFactbase`,
+  `Factbase::Rules`, `Factbase::Logged`, and `Factbase::Tallied`. The
+  [`decoor`](https://github.com/yegor256/decoor) gem provides delegation
+  boilerplate. The bare `Factbase` class is not thread-safe; new
+  programmers must wrap it with `SyncFactbase` before sharing across
+  threads.
+
+Persistence uses Ruby's
+  [`Marshal`](https://ruby-doc.org/core/Marshal.html), serializing the
+  internal array of hashes to a binary blob via `Marshal.dump`. The format
+  is Ruby-version-specific and not portable across major Ruby versions or
+  platforms, unlike [JSON](https://www.json.org/json-en.html) or
+  [Protocol Buffers](https://protobuf.dev/). Output-only decorators
+  `Factbase::ToJSON`, `Factbase::ToXML`, and `Factbase::ToYAML` exist but
+  do not support round-trip import.
+
+`Factbase::IndexedFactbase` lazily builds a hash-based inverted index for
+  equality queries, keyed by array `object_id`, property name, and
+  operator. The index is built incrementally on each query and invalidated
+  entirely on any mutation (delete or property addition). Without this
+  decorator every `query#each` call performs a full linear scan over all
+  facts. New programmers should add `IndexedFactbase` whenever the
+  factbase holds more than a few thousand facts.
+
 ## How to contribute
 
 Read
@@ -249,91 +325,25 @@ This is the result of the benchmark:
 
 <!-- benchmark_begin -->
 ```text
-                                                                       
-query all facts from an empty factbase                             0.00
-insert 20000 facts                                                 0.66
-export 20000 facts                                                 0.02
-import 410996 bytes (20000 facts)                                  0.02
-insert 10 facts                                                    0.00
-query 10 times w/txn                                               2.13
-query 10 times w/o txn                                             0.12
-modify 10 attrs w/txn                                              1.62
-delete 10 facts w/txn                                             10.22
-build index on 5000 facts                                          0.03
-export 5000 facts with index                                       0.04
-import 5000 facts with persisted index                             0.03
-query 5000 facts using persisted index                             0.08
-export 5000 facts without index                                    0.02
-import 5000 facts without index                                    0.01
-query 5000 facts building index on-the-fly                         0.07
-query 15k facts  sel: 20%  card: 10  absent plain                  0.60
-query 15k facts  sel: 20%  card: 10  absent indexed(cold)          0.17
-query 15k facts  sel: 20%  card: 10  absent indexed(warm)          0.16
-query 15k facts  sel: 20%  card: 10  exists plain                  0.57
-query 15k facts  sel: 20%  card: 10  exists indexed(cold)          0.17
-query 15k facts  sel: 20%  card: 10  exists indexed(warm)          0.13
-query 15k facts  sel: 20%  card: 10  eq plain                      0.86
-query 15k facts  sel: 20%  card: 10  eq indexed(cold)              0.26
-query 15k facts  sel: 20%  card: 10  eq indexed(warm)              0.19
-query 15k facts  sel: 20%  card: 10  not plain                     1.16
-query 15k facts  sel: 20%  card: 10  not indexed(cold)             0.53
-query 15k facts  sel: 20%  card: 10  not indexed(warm)             0.51
-query 15k facts  sel: 20%  card: 10  gt plain                      0.88
-query 15k facts  sel: 20%  card: 10  gt indexed(cold)              0.29
-query 15k facts  sel: 20%  card: 10  gt indexed(warm)              0.24
-query 15k facts  sel: 20%  card: 10  lt plain                      0.87
-query 15k facts  sel: 20%  card: 10  lt indexed(cold)              0.29
-query 15k facts  sel: 20%  card: 10  lt indexed(warm)              0.20
-query 15k facts  sel: 20%  card: 10  and eq plain                  1.43
-query 15k facts  sel: 20%  card: 10  and eq indexed(cold)          0.91
-query 15k facts  sel: 20%  card: 10  and eq indexed(warm)          0.50
-query 15k facts  sel: 20%  card: 10  and complex plain             1.38
-query 15k facts  sel: 20%  card: 10  and complex indexed(cold)     0.51
-query 15k facts  sel: 20%  card: 10  and complex indexed(warm)     0.45
-query 15k facts  sel: 20%  card: 10  one plain                     0.75
-query 15k facts  sel: 20%  card: 10  one indexed(cold)             0.21
-query 15k facts  sel: 20%  card: 10  one indexed(warm)             0.16
-query 15k facts  sel: 20%  card: 10  or plain                      2.02
-query 15k facts  sel: 20%  card: 10  or indexed(cold)              0.46
-query 15k facts  sel: 20%  card: 10  or indexed(warm)              0.32
-query 15k facts  sel: 20%  card: 10  unique plain                  1.87
-query 15k facts  sel: 20%  card: 10  unique indexed(cold)          0.67
-query 15k facts  sel: 20%  card: 10  unique indexed(warm)          0.42
-(and (eq what 'issue-was-closed') (exists... -> 200                1.08
-(and (eq what 'issue-was-closed') (exists... -> 200/txn            1.24
-(and (eq what 'issue-was-closed') (exists... -> zero               1.08
-(and (eq what 'issue-was-closed') (exists... -> zero/txn           1.28
-transaction rollback on factbase with 100000 facts                 0.01
-(gt time '2024-03-23T03:21:43Z')                                   0.31
-(gt cost 50)                                                       0.14
-(eq title 'Object Thinking 5000')                                  0.02
-(and (eq foo 42.998) (or (gt bar 200) (absent z...                 0.03
-(and (exists foo) (not (exists blue)))                             1.23
-(eq id (agg (always) (max id)))                                    2.80
-(join "c<=cost,b<=bar" (eq id (agg (always) (ma...                 4.44
-(and (eq what "foo") (join "w<=what" (and (eq i...                 7.39
-delete!                                                            0.44
-(and (eq issue *) (eq repository *) (eq what '*') (eq where '*'))  0.41
-Taped.append() x50000                                              0.02
-Taped.each() x125                                                  1.10
-Taped.delete_if() x375                                             0.86
-50000 facts: plain read (no txn)                                   4.10
-50000 facts: read-only txn (no copy)                               5.33
-50000 facts: plain insert (no txn)                                 0.00
-50000 facts: insert in txn (no copy triggered)                     0.00
-50000 facts: plain modify (no txn)                                28.59
-50000 facts: modify in txn (copy triggered)                       37.78
-100000 facts: plain read (no txn)                                  8.33
-100000 facts: read-only txn (no copy)                             12.80
-100000 facts: plain insert (no txn)                                0.00
-100000 facts: insert in txn (no copy triggered)                    0.00
-100000 facts: plain modify (no txn)                               57.26
-100000 facts: modify in txn (copy triggered)                      75.84
+                                                                   user
+void scan                                                      0.001049
+20k facts: export: 2980KB                                      0.840193
+20k facts: import: 2980KB                                      1.033492
+50k facts: read                                                0.000179
+50k facts: read in txn                                         0.002282
+50k facts: insert                                              0.000082
+50k facts: insert in txn                                       0.000613
+50k facts: modify                                              1.427349
+50k facts: modify in txn                                       2.773065
+12k facts: large query: match 3k                              13.166170
+12k facts: large query: match 3k in txn                       18.502015
+12k facts: large query: match zero                            14.234812
+12k facts: large query: match zero in txn                     19.847547
 ```
 
 The results were calculated in [this GHA job][benchmark-gha]
-on 2026-02-26 at 06:08,
+on 2026-05-23 at 03:40,
 on Linux with 4 CPUs.
 <!-- benchmark_end -->
 
-[benchmark-gha]: https://github.com/yegor256/factbase/actions/runs/22430010182
+[benchmark-gha]: https://github.com/yegor256/factbase/actions/runs/26322478578

data/Rakefile

@@ -61,27 +61,30 @@ RuboCop::RakeTask.new(:rubocop) do |task|
 end
 
 desc 'Benchmark them all'
-task :benchmark, [:name] do |_t, args|
-  bname = args[:name] || 'all'
+task :benchmark, [:name, :cycles] do |_t, args|
+  bname = args[:name] || 'essential'
+  cycles = (args[:cycles] || 5).to_i
   require_relative 'lib/factbase'
   require_relative 'lib/factbase/cached/cached_factbase'
   require_relative 'lib/factbase/indexed/indexed_factbase'
   require_relative 'lib/factbase/sync/sync_factbase'
   require 'benchmark'
   Benchmark.bm(60) do |b|
-    fb = Factbase.new
-    fb = Factbase::CachedFactbase.new(fb)
-    fb = Factbase::IndexedFactbase.new(fb)
-    fb = Factbase::SyncFactbase.new(fb)
-    if bname == 'all'
-      Dir['benchmark/bench_*.rb'].each do |f|
-        require_relative f
-        Kernel.send(File.basename(f).gsub(/\.rb$/, '').to_sym, b, fb)
+    files =
+      case bname
+      when 'all'
+        Dir['benchmark/bench_*.rb']
+      when 'essential'
+        %w[empty serialization txns large_query].map { |f| "benchmark/bench_#{f}.rb" }
+      else
+        ["benchmark/#{bname}.rb"]
       end
-    else
-      f = "benchmark/#{bname}.rb"
+    files.each do |f|
       require_relative f
-      Kernel.send(File.basename(f).gsub(/\.rb$/, '').to_sym, b, fb)
+      fb = Factbase.new
+      fb = Factbase::IndexedFactbase.new(fb)
+      fb = Factbase::CachedFactbase.new(fb)
+      Kernel.send(File.basename(f).gsub(/\.rb$/, '').to_sym, b, fb, cycles)
     end
   end
 end

data/lib/factbase/indexed/indexed_factbase.rb

@@ -61,11 +61,12 @@ class Factbase::IndexedFactbase
   # Run an ACID transaction.
   # @return [Factbase::Churn] How many facts have been changed (zero if rolled back)
   def txn
+    inner_idx = {}
     result =
       @origin.txn do |fbt|
-        yield Factbase::IndexedFactbase.new(fbt, @idx, @fresh)
+        yield Factbase::IndexedFactbase.new(fbt, inner_idx, @fresh)
       end
-    @idx.clear
+    @idx.clear if result.deleted.positive? || result.added.positive?
     @fresh.clear
     result
   end

data/lib/factbase/syntax.rb

@@ -142,7 +142,7 @@ class Factbase::Syntax
         t[1..-2]
       elsif t.match?(/^(\+|-)?[0-9]+$/)
         t.to_i
-      elsif t.match?(/^(\+|-)?[0-9]+\.[0-9]+(e\+[0-9]+)?$/)
+      elsif t.match?(/^(\+|-)?[0-9]+\.[0-9]+(e(\+|-)[0-9]+)?$/)
         t.to_f
       elsif t.match?(/^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}Z$/)
         Time.parse(t)

data/lib/factbase/tallied.rb

@@ -8,7 +8,7 @@ require 'others'
 require_relative '../factbase'
 require_relative 'churn'
 
-# A decorator of a Factbase, that count all operations and then returns
+# A decorator of a Factbase, that counts all operations and then returns
 # an instance of Factbase::Churn.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)

data/lib/factbase/term.rb

@@ -12,6 +12,9 @@ require_relative 'terms/prev'
 require_relative 'terms/concat'
 require_relative 'terms/sprintf'
 require_relative 'terms/matches'
+require_relative 'terms/contains'
+require_relative 'terms/starts_with'
+require_relative 'terms/ends_with'
 require_relative 'terms/traced'
 require_relative 'terms/assert'
 require_relative 'terms/env'
@@ -108,6 +111,9 @@ class Factbase::Term < Factbase::TermBase
       concat: Factbase::Concat.new(operands),
       sprintf: Factbase::Sprintf.new(operands),
       matches: Factbase::Matches.new(operands),
+      contains: Factbase::Contains.new(operands),
+      starts_with: Factbase::StartsWith.new(operands),
+      ends_with: Factbase::EndsWith.new(operands),
       traced: Factbase::Traced.new(operands),
       assert: Factbase::Assert.new(operands),
       env: Factbase::Env.new(operands),

data/lib/factbase/terms/base.rb

@@ -3,12 +3,10 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024-2026 Yegor Bugayenko
 # SPDX-License-Identifier: MIT
 
-# Test for unique term.
+# Base class for all terms.
 # Author:: Volodya Lombrozo (volodya.lombrozo@gmail.com)
 # Copyright:: Copyright (c) 2024-2026 Yegor Bugayenko
 # License:: MIT
-
-# Base class for all terms.
 class Factbase::TermBase
   # Turns it into a string.
   # @return [String] The string of it

data/lib/factbase/terms/compare.rb

@@ -31,8 +31,23 @@ 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(
+      "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/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/matches.rb

@@ -14,6 +14,7 @@ class Factbase::Matches < Factbase::TermBase
   def initialize(operands)
     super()
     @operands = operands
+    @regexps = {}
   end
 
   # Evaluate term on a fact.
@@ -29,6 +30,15 @@ class Factbase::Matches < Factbase::TermBase
     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])
+    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 "Invalid regexp '#{key}': #{e.message}"
   end
 end

data/lib/factbase/terms/sprintf.rb

@@ -24,6 +24,14 @@ class Factbase::Sprintf < Factbase::TermBase
   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(fmt, ops)
+  end
+
+  private
+
+  def formatted(fmt, ops)
     format(*([fmt] + ops))
+  rescue ArgumentError => e
+    raise "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

data/lib/factbase/terms/to_time.rb

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

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

data/lib/factbase/version.rb

@@ -9,5 +9,5 @@
 # License:: MIT
 class Factbase
   # Current version of the gem (changed by .rultor.yml on every release)
-  VERSION = '0.19.9' unless const_defined?(:VERSION)
+  VERSION = '0.19.11' unless const_defined?(:VERSION)
 end

data/lib/factbase.rb

@@ -102,9 +102,6 @@ class Factbase
   #
   # 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 = {}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: factbase
 version: !ruby/object:Gem::Version
-  version: 0.19.9
+  version: 0.19.11
 platform: ruby
 authors:
 - Yegor Bugayenko
@@ -222,11 +222,13 @@ files:
 - lib/factbase/terms/boolean.rb
 - lib/factbase/terms/compare.rb
 - lib/factbase/terms/concat.rb
+- lib/factbase/terms/contains.rb
 - lib/factbase/terms/count.rb
 - lib/factbase/terms/defn.rb
 - lib/factbase/terms/div.rb
 - lib/factbase/terms/either.rb
 - lib/factbase/terms/empty.rb
+- lib/factbase/terms/ends_with.rb
 - lib/factbase/terms/env.rb
 - lib/factbase/terms/eq.rb
 - lib/factbase/terms/exists.rb
@@ -255,6 +257,7 @@ files:
 - lib/factbase/terms/size.rb
 - lib/factbase/terms/sorted.rb
 - lib/factbase/terms/sprintf.rb
+- lib/factbase/terms/starts_with.rb
 - lib/factbase/terms/sum.rb
 - lib/factbase/terms/times.rb
 - lib/factbase/terms/to_float.rb