factbase 0.0.35 → 0.0.37

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc97bfbf967aa07fa189c2d3c696eb8d963f4647c06fb5d97ca4b0e2b4edb4db
-  data.tar.gz: b38987779b663f76cbf9876b4e117cd1fabb3e1c2ef07bd6ab433be0dede9a44
+  metadata.gz: a464f6fa40a3aef098e4ab4a58b6f6905ac101421f22fb806b63c4fb624aa610
+  data.tar.gz: ad19a0147890d8b4ff8fff96f7e9f47b09ecb264b3cb52fa606be892278fa380
 SHA512:
-  metadata.gz: 97cdc3269d4fbfea8d7246f6cee197be5bdf8b1e463573940b9be2384cbc2718a454e7f1291c5efc11554fc59c84a97c9349def6413d0ee54192118820cdb252
-  data.tar.gz: '049a1b2ae928bae38e1079f4e67d4f29a3efe3201e27c28c92f58bf4a2eda519a62a9a18095d857792337b19775e319921f8494643718a406bf6c377e36eefa6'
+  metadata.gz: 6abb74b759ef7eea421e8a7f4f1ebdbf7ae46836dfefcd324286508fbb82e207a787265c0cf9f8931b43b00d50e5df983266fa9442f9c277111dfa9ea3a778de
+  data.tar.gz: b0ed97f83f59230bafce810488f3e720d098a748149f7fbd58b7f1c25425b2fba6b742ce16b18692df34607eb3c42f9f11196ca212bc0273d7bdffe15e759efe

data/.github/workflows/rake.yml

@@ -32,7 +32,7 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-20.04, macos-12, windows-2022]
-        ruby: [3.2]
+        ruby: [3.2, 3.3]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4

data/Gemfile.lock

@@ -101,7 +101,7 @@ GEM
       zeitwerk (~> 2.6)
     rainbow (3.1.1)
     rake (13.2.1)
-    rdoc (6.6.3.1)
+    rdoc (6.7.0)
       psych (>= 4.0.0)
     regexp_parser (2.9.2)
     reline (0.5.7)
@@ -171,7 +171,7 @@ GEM
     webrick (1.8.1)
     yaml (0.3.0)
     yard (0.9.36)
-    zeitwerk (2.6.14)
+    zeitwerk (2.6.15)
 
 PLATFORMS
   arm64-darwin-22

data/README.md

@@ -54,7 +54,7 @@ f2.import(File.read(file))
 assert(f2.query('(eq foo 42)').each.to_a.size == 1)
 ```
 
-All terms available in a query:
+There are some terms available in a query:
 
 * `(always)` and `(never)` are "true" and "false"
 * `(not t)` inverses the `t` if it's boolean (exception otherwise)
@@ -68,14 +68,39 @@ All terms available in a query:
 * `(gt a b)` returns true if `a` is greater than `b`
 * `(size k)` returns cardinality of `k` property (zero if property is absent)
 * `(type a)` returns type of `a` ("String", "Integer", "Float", or "Time")
+* `(many a)` return true if there are many values in the `a` property
+* `(one a)` returns true if there is only one value in the `a` property
+* `(at i a)` returns the `i`-th value of the `a` property
+* `(nonil a b)` returns `b` if `a` is `nil`
 * `(matches a re)` returns true when `a` matches regular expression `re`
 * `(defn foo "self.to_s")` defines a new term using Ruby syntax and returns true
 
-There are also terms that match the entire factbase:
+Also, some simple arithmetic:
 
-* `(max k)` returns true if the value of `k` property
-is the largest in the entire factbase
-* `(min k)` returns true if the value of `k` is the smallest
+* `(plus a b)` is a sum of `a` and `b`
+* `(minus a b)` is a deducation of `b` from `a`
+* `(times a b)` is a multiplication of `a` and `b`
+* `(div a b)` is a division of `a` by `b`
+
+There are terms that are history of search aware:
+
+* `(prev a)` returns the value of `a` in the previously seen fact
+
+There are also terms that match the entire factbase
+and must be used inside the `(agg ..)` term:
+
+* `(count)` returns the tally of facts
+* `(max k)` returns the maximum value of the `k` property in all facts
+* `(min k)` returns the minimum
+* `(sum k)` returns the arithmetic sum of all values of the `k` property
+
+The `agg` term enables sub-queries by evaluating the first argument (term)
+over all available facts, passing the entire subset to the second argument,
+and then returning the result as an atomic value:
+
+* `(lt age (agg (eq gender 'F') (max age)))` selects all facts where
+the `age` is smaller than the maximum `age` of all women
+* `(eq id (agg (always) (max id)))` selects the fact with the largest `id`
 
 ## How to contribute
 

data/factbase.gemspec

@@ -25,17 +25,21 @@ require_relative 'lib/factbase'
 
 Gem::Specification.new do |s|
   s.required_rubygems_version = Gem::Requirement.new('>= 0') if s.respond_to? :required_rubygems_version=
-  s.required_ruby_version = '>=2.3'
+  s.required_ruby_version = '>=3.0'
   s.name = 'factbase'
   s.version = Factbase::VERSION
   s.license = 'MIT'
   s.summary = 'Factbase'
-  s.description = 'Fact base in memory and on disc'
+  s.description =
+    'A primitive in-memory collection of key-value records ' \
+    'known as "facts," with an ability to insert facts, add properties ' \
+    'to facts, and delete facts. There is no ability to modify facts. ' \
+    'It is also possible to find facts using Lisp-alike query predicates. ' \
+    'An entire factbase may be exported to a binary file and imported back.'
   s.authors = ['Yegor Bugayenko']
   s.email = 'yegor256@gmail.com'
   s.homepage = 'http://github.com/yegor256/factbase.rb'
   s.files = `git ls-files`.split($RS)
-  s.executables = s.files.grep(%r{^bin/}) { |f| File.basename(f) }
   s.rdoc_options = ['--charset=UTF-8']
   s.extra_rdoc_files = ['README.md', 'LICENSE.txt']
   s.add_runtime_dependency 'json', '~> 2.7'

data/lib/factbase/fact.rb

@@ -28,10 +28,20 @@ require_relative '../factbase'
 #
 # This is an internal class, it is not supposed to be instantiated directly.
 #
+# It is possible to use for testing directly, for example to make a
+# fact with a single key/value pair inside:
+#
+#  require 'factbase/fact'
+#  f = Factbase::Fact.new(Mutex.new, { 'foo' => [42, 256, 'Hello, world!'] })
+#  assert_equal(42, f.foo)
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024 Yegor Bugayenko
 # License:: MIT
 class Factbase::Fact
+  # Ctor.
+  # @param [Mutex] mutex A mutex to use for maps synchronization
+  # @param [Hash] map A map of key/value pairs
   def initialize(mutex, map)
     @mutex = mutex
     @map = map
@@ -48,7 +58,7 @@ class Factbase::Fact
     k = args[0].to_s
     if k.end_with?('=')
       kk = k[0..-2]
-      raise "Invalid prop name '#{kk}'" unless kk.match?(/^[a-z][_a-zA-Z0-9]*$/)
+      raise "Invalid prop name '#{kk}'" unless kk.match?(/^[a-z_][_a-zA-Z0-9]*$/)
       raise "Prohibited prop name '#{kk}'" if kk == 'to_s'
       v = args[1]
       raise "Prop value can't be nil" if v.nil?

data/lib/factbase/syntax.rb

@@ -129,14 +129,14 @@ class Factbase::Syntax
       elsif t.start_with?('\'', '"')
         raise 'String literal can\'t be empty' if t.length <= 2
         t[1..-2]
-      elsif t.match?(/^[0-9]+$/)
+      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)
       else
-        raise "Wrong symbol format (#{t})" unless t.match?(/^[a-z][a-zA-Z0-9_]*$/)
+        raise "Wrong symbol format (#{t})" unless t.match?(/^[_a-z][a-zA-Z0-9_]*$/)
         t.to_sym
       end
     end

data/lib/factbase/term.rb

@@ -27,6 +27,15 @@ require_relative 'fact'
 #
 # This is an internal class, it is not supposed to be instantiated directly.
 #
+# It is possible to use for testing directly, for example to make a
+# term with two arguments:
+#
+#  require 'factbase/fact'
+#  require 'factbase/term'
+#  f = Factbase::Fact.new(Mutex.new, { 'foo' => [42, 256, 'Hello, world!'] })
+#  t = Factbase::Term.new(:lt, [:foo, 50])
+#  assert(t.evaluate(f))
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024 Yegor Bugayenko
 # License:: MIT
@@ -93,19 +102,19 @@ class Factbase::Term
 
   def not(fact, maps)
     assert_args(1)
-    !only_bool(the_value(0, fact, maps))
+    !only_bool(the_values(0, fact, maps))
   end
 
   def or(fact, maps)
     (0..@operands.size - 1).each do |i|
-      return true if only_bool(the_value(i, fact, maps))
+      return true if only_bool(the_values(i, fact, maps))
     end
     false
   end
 
   def and(fact, maps)
     (0..@operands.size - 1).each do |i|
-      return false unless only_bool(the_value(i, fact, maps))
+      return false unless only_bool(the_values(i, fact, maps))
     end
     true
   end
@@ -149,16 +158,70 @@ class Factbase::Term
     by_symbol(0, fact).nil?
   end
 
+  def nonil(fact, maps)
+    assert_args(2)
+    v = the_values(0, fact, maps)
+    return v unless v.nil?
+    the_values(1, fact, maps)
+  end
+
+  def at(fact, maps)
+    assert_args(2)
+    i = the_values(0, fact, maps)
+    raise 'Too many values at first position, one expected' unless i.size == 1
+    i = i[0]
+    return nil if i.nil?
+    v = the_values(1, fact, maps)
+    return nil if v.nil?
+    v[i]
+  end
+
+  def prev(fact, maps)
+    assert_args(1)
+    before = @prev
+    v = the_values(0, fact, maps)
+    @prev = v
+    before
+  end
+
+  def many(fact, maps)
+    assert_args(1)
+    v = the_values(0, fact, maps)
+    !v.nil? && v.size > 1
+  end
+
+  def one(fact, maps)
+    assert_args(1)
+    v = the_values(0, fact, maps)
+    !v.nil? && v.size == 1
+  end
+
+  def plus(fact, maps)
+    arithmetic(:+, fact, maps)
+  end
+
+  def minus(fact, maps)
+    arithmetic(:-, fact, maps)
+  end
+
+  def times(fact, maps)
+    arithmetic(:*, fact, maps)
+  end
+
+  def div(fact, maps)
+    arithmetic(:/, fact, maps)
+  end
+
   def eq(fact, maps)
-    arithmetic(:==, fact, maps)
+    cmp(:==, fact, maps)
   end
 
   def lt(fact, maps)
-    arithmetic(:<, fact, maps)
+    cmp(:<, fact, maps)
   end
 
   def gt(fact, maps)
-    arithmetic(:>, fact, maps)
+    cmp(:>, fact, maps)
   end
 
   def size(fact, _maps)
@@ -178,20 +241,20 @@ class Factbase::Term
 
   def matches(fact, maps)
     assert_args(2)
-    str = the_value(0, fact, maps)
+    str = the_values(0, fact, maps)
     return false if str.nil?
     raise 'Exactly one string expected' unless str.size == 1
-    re = the_value(1, fact, maps)
+    re = the_values(1, fact, maps)
     raise 'Regexp is nil' if re.nil?
     raise 'Exactly one regexp expected' unless re.size == 1
     str[0].to_s.match?(re[0])
   end
 
-  def arithmetic(op, fact, maps)
+  def cmp(op, fact, maps)
     assert_args(2)
-    lefts = the_value(0, fact, maps)
+    lefts = the_values(0, fact, maps)
     return false if lefts.nil?
-    rights = the_value(1, fact, maps)
+    rights = the_values(1, fact, maps)
     return false if rights.nil?
     lefts.any? do |l|
       l = l.floor if l.is_a?(Time) && op == :==
@@ -202,6 +265,17 @@ class Factbase::Term
     end
   end
 
+  def arithmetic(op, fact, maps)
+    assert_args(2)
+    lefts = the_values(0, fact, maps)
+    raise 'The first argument is NIL, while literal expected' if lefts.nil?
+    raise 'Too many values at first position, one expected' unless lefts.size == 1
+    rights = the_values(1, fact, maps)
+    raise 'The second argument is NIL, while literal expected' if rights.nil?
+    raise 'Too many values at second position, one expected' unless rights.size == 1
+    lefts[0].send(op, rights[0])
+  end
+
   def defn(_fact, _maps)
     fn = @operands[0]
     raise 'A symbol expected as first argument of defn' unless fn.is_a?(Symbol)
@@ -269,7 +343,7 @@ class Factbase::Term
     fact[k]
   end
 
-  def the_value(pos, fact, maps)
+  def the_values(pos, fact, maps)
     v = @operands[pos]
     v = v.evaluate(fact, maps) if v.is_a?(Factbase::Term)
     v = fact[v.to_s] if v.is_a?(Symbol)

data/lib/factbase.rb

@@ -24,12 +24,32 @@ require 'json'
 require 'yaml'
 
 # Factbase.
+#
+# This is an entry point to a factbase:
+#
+#  fb = Factbase.new
+#  f = fb.insert # new fact created
+#  f.name = 'Jeff Lebowski'
+#  f.age = 42
+#  found = f.query('(gt 20 age)').each.to_a[0]
+#  assert(found.age == 42)
+#
+# A factbase may be exported to a file and then imported back:
+#
+#  fb1 = Factbase.new
+#  File.writebin(file, fb1.export)
+#  fb2 = Factbase.new # it's empty
+#  fb2.import(File.readbin(file))
+#
+# It's important to use +writebin+ and +readbin+, because the content is
+# a chain of bytes, not a text.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024 Yegor Bugayenko
 # License:: MIT
 class Factbase
   # Current version of the gem (changed by .rultor.yml on every release)
-  VERSION = '0.0.35'
+  VERSION = '0.0.37'
 
   # Constructor.
   def initialize(facts = [])

data/test/factbase/test_fact.rb

@@ -80,8 +80,8 @@ class TestFact < Minitest::Test
 
   def test_set_by_name
     f = Factbase::Fact.new(Mutex.new, {})
-    f.send('foo_bar=', 42)
-    assert_equal(42, f.foo_bar, f.to_s)
+    f.send('_foo_bar=', 42)
+    assert_equal(42, f._foo_bar, f.to_s)
   end
 
   def test_set_twice_same_value

data/test/factbase/test_query.rb

@@ -53,13 +53,21 @@ class TestQuery < Minitest::Test
       '(gt num 60)' => 1,
       "(and (lt pi 100) \n\n (gt num 1000))" => 0,
       '(exists pi)' => 1,
+      '(eq pi +3.14)' => 1,
       '(not (exists hello))' => 3,
       '(eq "Integer" (type num))' => 2,
       '(when (eq num 0) (exists time))' => 2,
+      '(many num)' => 1,
+      '(one num)' => 2,
+      '(gt num (minus 1 (nonil (at 0 (prev num)) 0)))' => 3,
+      '(and (not (many num)) (eq num (plus 21 +21)))' => 1,
+      '(and (not (many num)) (eq num (minus -100 -142)))' => 1,
+      '(and (one num) (eq num (times 7 6)))' => 1,
+      '(and (one pi) (eq pi (div -6.28 -2)))' => 1,
       '(gt (size num) 2)' => 1,
       '(matches name "^[a-z]+$")' => 1,
       '(lt (size num) 2)' => 2,
-      '(eq (size hello) 0)' => 3,
+      '(eq (size _hello) 0)' => 3,
       '(eq num pi)' => 0,
       '(absent time)' => 2,
       '(eq pi (agg (eq num 0) (sum pi)))' => 1,
@@ -68,7 +76,7 @@ class TestQuery < Minitest::Test
       '(eq time (min time))' => 1,
       '(and (absent time) (exists pi))' => 1,
       "(and (exists time) (not (\t\texists pi)))" => 1,
-      "(or (eq num 66) (lt time #{(Time.now - 200).utc.iso8601}))" => 1
+      "(or (eq num +66) (lt time #{(Time.now - 200).utc.iso8601}))" => 1
     }.each do |q, r|
       assert_equal(r, Factbase::Query.new(maps, Mutex.new, q).each.to_a.size, q)
     end

data/test/factbase/test_term.rb

@@ -166,6 +166,23 @@ class TestTerm < Minitest::Test
     assert_equal('(foo \'hello, world!\')', t1.evaluate(fact, []))
   end
 
+  def test_past
+    t = Factbase::Term.new(:prev, [:foo])
+    assert_nil(t.evaluate(fact('foo' => 4), []))
+    assert_equal([4], t.evaluate(fact('foo' => 5), []))
+  end
+
+  def test_at
+    t = Factbase::Term.new(:at, [1, :foo])
+    assert_nil(t.evaluate(fact('foo' => 4), []))
+    assert_equal(5, t.evaluate(fact('foo' => [4, 5]), []))
+  end
+
+  def test_nonil
+    t = Factbase::Term.new(:nonil, [Factbase::Term.new(:at, [5, :foo]), 42])
+    assert_equal([42], t.evaluate(fact('foo' => 4), []))
+  end
+
   private
 
   def fact(map = {})

data/test/test_factbase.rb

@@ -49,8 +49,8 @@ class TestFactbase < Minitest::Test
     f2 = Factbase.new
     f1.insert.foo = 42
     Tempfile.open do |f|
-      File.write(f.path, f1.export)
-      f2.import(File.read(f.path))
+      File.binwrite(f.path, f1.export)
+      f2.import(File.binread(f.path))
     end
     assert_equal(1, f2.query('(eq foo 42)').each.to_a.count)
   end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factbase
 version: !ruby/object:Gem::Version
-  version: 0.0.35
+  version: 0.0.37
 platform: ruby
 authors:
 - Yegor Bugayenko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-26 00:00:00.000000000 Z
+date: 2024-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json
@@ -66,7 +66,11 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.3'
-description: Fact base in memory and on disc
+description: A primitive in-memory collection of key-value records known as "facts,"
+  with an ability to insert facts, add properties to facts, and delete facts. There
+  is no ability to modify facts. It is also possible to find facts using Lisp-alike
+  query predicates. An entire factbase may be exported to a binary file and imported
+  back.
 email: yegor256@gmail.com
 executables: []
 extensions: []
@@ -138,7 +142,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.3'
+      version: '3.0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="