factbase 0.0.38 → 0.0.40

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3c7e0abf7bec6e53f050b4eeaeddd2b9954ee77b2a5f9a0332394c995d91ba9
-  data.tar.gz: 5da4b8574d7b1a93fd67f3d833bf51952eb5b3d9c303b9e20a084dc5953d71bc
+  metadata.gz: 129d17fba6d19bc5131f853d6b90c2e963187e84626270be4f7766e926d4c2c9
+  data.tar.gz: 4196611d541b81bdc1a73bf31f4b1fe15077ad702d8d1ec558f0f61d5e530396
 SHA512:
-  metadata.gz: f472603e32966c098979c2a461d94cd60f1f6213c4cea4abae225694d59ae88df252bbd42dcfb3292efb97352618cfa35fe56bef86bf87310dc74b4dbce65a20
-  data.tar.gz: fb91b271a5d57c59268dd386f8960e1c3c3c1577ea80e5c9bc3b623eaa6c559b15ce326f23ec9035e795d08ce647af353f4ae12aef5a34a124286f41fdf79130
+  metadata.gz: 1d87ddb11c2252043c963c6e086a617f216bc15a79441cfa121a0e3de3157f31705cfd1bfea7b6b89996488c76805ee27152f4be00627c7d3f3e1d506636c303
+  data.tar.gz: 5e913f0d675f19fc03cc83c80301af5fd390de8cdaf730a0ea2612768ae0056286be7f5f42686616ee0b1fc69cf22adc0009e9df5315251971e9c948da5ee739

data/README.md

@@ -54,7 +54,8 @@ f2.import(File.read(file))
 assert(f2.query('(eq foo 42)').each.to_a.size == 1)
 ```
 
-There are some terms available in a query:
+There are some boolean terms available in a query
+(they return either TRUE or FALSE):
 
 * `(always)` and `(never)` are "true" and "false"
 * `(not t)` inverses the `t` if it's boolean (exception otherwise)
@@ -66,14 +67,16 @@ There are some terms available in a query:
 * `(eq a b)` returns true if `a` equals to `b`
 * `(lt a b)` returns true if `a` is less than `b`
 * `(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
+* `(matches a re)` returns true when `a` matches regular expression `re`
+
+There are a few terms that return non-boolean values:
+
 * `(at i a)` returns the `i`-th value of the `a` property
+* `(size k)` returns cardinality of `k` property (zero if property is absent)
+* `(type a)` returns type of `a` ("String", "Integer", "Float", or "Time")
 * `(either 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
 
 Also, some simple arithmetic:
 
@@ -82,9 +85,14 @@ Also, some simple arithmetic:
 * `(times a b)` is a multiplication of `a` and `b`
 * `(div a b)` is a division of `a` by `b`
 
+One term is for meta-programming:
+
+* `(defn foo "self.to_s")` defines a new term using Ruby syntax and returns true
+
 There are terms that are history of search aware:
 
 * `(prev a)` returns the value of `a` in the previously seen fact
+* `(unique k)` returns true if the value of `k` property hasn't been seen yet
 
 There are also terms that match the entire factbase
 and must be used inside the `(agg ..)` term:

data/lib/factbase/fact.rb

@@ -24,17 +24,20 @@ require 'json'
 require 'time'
 require_relative '../factbase'
 
-# Fact.
+# A single fact in a 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
+# This is an internal class, it is not supposed to be instantiated directly,
+# by the +Factbase+ class.
+# However, it is possible to use it 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)
 #
+# A fact is basically a key/value hash map, where values are non-empty
+# sets of values.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024 Yegor Bugayenko
 # License:: MIT

data/lib/factbase/looged.rb

@@ -20,6 +20,7 @@
 # OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 # SOFTWARE.
 
+require 'time'
 require 'loog'
 
 # A decorator of a Factbase, that logs all operations.
@@ -114,39 +115,51 @@ class Factbase::Looged
     def each(&)
       q = Factbase::Syntax.new(@expr).to_term.to_s
       if block_given?
-        r = @query.each(&)
+        r = nil
+        tail = Factbase::Looged.elapsed do
+          r = @query.each(&)
+        end
         raise ".each of #{@query.class} returned #{r.class}" unless r.is_a?(Integer)
         if r.zero?
-          @loog.debug("Nothing found by '#{q}'")
+          @loog.debug("Nothing found by '#{q}' #{tail}")
         else
-          @loog.debug("Found #{r} fact(s) by '#{q}'")
+          @loog.debug("Found #{r} fact(s) by '#{q}' #{tail}")
         end
         r
       else
         array = []
-        # rubocop:disable Style/MapIntoArray
-        @query.each do |f|
-          array << f
+        tail = Factbase::Looged.elapsed do
+          @query.each do |f|
+            array << f
+          end
         end
-        # rubocop:enable Style/MapIntoArray
         if array.empty?
-          @loog.debug("Nothing found by '#{q}'")
+          @loog.debug("Nothing found by '#{q}' #{tail}")
         else
-          @loog.debug("Found #{array.size} fact(s) by '#{q}'")
+          @loog.debug("Found #{array.size} fact(s) by '#{q}' #{tail}")
         end
         array
       end
     end
 
     def delete!
-      r = @query.delete!
+      r = nil
+      tail = Factbase::Looged.elapsed do
+        r = @query.delete!
+      end
       raise ".delete! of #{@query.class} returned #{r.class}" unless r.is_a?(Integer)
       if r.zero?
-        @loog.debug("Nothing deleted by '#{@expr}'")
+        @loog.debug("Nothing deleted by '#{@expr}' #{tail}")
       else
-        @loog.debug("Deleted #{r} fact(s) by '#{@expr}'")
+        @loog.debug("Deleted #{r} fact(s) by '#{@expr}' #{tail}")
       end
       r
     end
   end
+
+  def self.elapsed
+    start = Time.now
+    yield
+    "in #{format('%.2f', (Time.now - start) * 1000)}ms"
+  end
 end

data/lib/factbase/term.rb

@@ -36,6 +36,15 @@ require_relative 'fact'
 #  t = Factbase::Term.new(:lt, [:foo, 50])
 #  assert(t.evaluate(f))
 #
+# The design of this class may look ugly, since it has a large number of
+# methods, each of which corresponds to a different type of a +Term+. A much
+# better design would definitely involve many classes, one per each type
+# of a term. It's not done this way because of an experimental nature of
+# the project. Most probably we should keep current design intact, since it
+# works well and is rather simple to extend (by adding new term types).
+# Moreover, it looks like the number of possible term types is rather limited
+# and currently we implement most of them.
+#
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
 # Copyright:: Copyright (c) 2024 Yegor Bugayenko
 # License:: MIT
@@ -184,6 +193,19 @@ class Factbase::Term
     before
   end
 
+  def unique(fact, _maps)
+    @uniques = [] if @uniques.nil?
+    assert_args(1)
+    vv = by_symbol(0, fact)
+    return false if vv.nil?
+    vv = [vv] unless vv.is_a?(Array)
+    vv.each do |v|
+      return false if @uniques.include?(v)
+      @uniques << v
+    end
+    true
+  end
+
   def many(fact, maps)
     assert_args(1)
     v = the_values(0, fact, maps)

data/lib/factbase.rb

@@ -23,9 +23,12 @@
 require 'json'
 require 'yaml'
 
-# Factbase.
+# A factbase, which essentially is a NoSQL one-table in-memory database
+# with a Lisp-ish query interface.
 #
-# This is an entry point to a factbase:
+# This class is an entry point to a factbase. For example, this is how you
+# add a new "fact" to a factbase, then put two properties into it, and then
+# find this fact with a simple search.
 #
 #  fb = Factbase.new
 #  f = fb.insert # new fact created
@@ -34,14 +37,41 @@ require 'yaml'
 #  found = f.query('(gt 20 age)').each.to_a[0]
 #  assert(found.age == 42)
 #
+# Every fact is a key-value hash map. Every value is a non-empty set of values.
+# Consider this example of creating a factbase with a single fact inside:
+#
+#  fb = Factbase.new
+#  f = fb.insert
+#  f.name = 'Jeff'
+#  f.name = 'Walter'
+#  f.age = 42
+#  f.age = 'unknown'
+#  f.place = 'LA'
+#  puts f.to_json
+#
+# This will print the following JSON:
+#
+#  {
+#    'name': ['Jeff', 'Walter'],
+#    'age': [42, 'unknown'],
+#    'place: 'LA'
+#  }
+#
+# Value sets, as you can see, allow data of different types. However, there
+# are only four types are allowed: Integer, Float, String, and Time.
+#
 # A factbase may be exported to a file and then imported back:
 #
 #  fb1 = Factbase.new
-#  File.writebin(file, fb1.export)
+#  File.binwrite(file, fb1.export)
 #  fb2 = Factbase.new # it's empty
-#  fb2.import(File.readbin(file))
+#  fb2.import(File.binread(file))
 #
-# It's important to use +writebin+ and +readbin+, because the content is
+# It's impossible to delete properties of a fact. It is however possible to
+# delete the entire fact, with the help of the +query()+ and then +delete!()+
+# methods.
+#
+# It's important to use +binwrite+ and +binread+, because the content is
 # a chain of bytes, not a text.
 #
 # Author:: Yegor Bugayenko (yegor256@gmail.com)
@@ -49,7 +79,10 @@ require 'yaml'
 # License:: MIT
 class Factbase
   # Current version of the gem (changed by .rultor.yml on every release)
-  VERSION = '0.0.38'
+  VERSION = '0.0.40'
+
+  # An exception that may be thrown in a transaction, to roll it back.
+  class Rollback < StandardError; end
 
   # Constructor.
   def initialize(facts = [])
@@ -69,7 +102,13 @@ class Factbase
     @maps.size
   end
 
-  # Insert a new fact.
+  # 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 you different threads may
+  # insert facts parallel without breaking the consistency of the factbase.
+  #
   # @return [Factbase::Fact] The fact just inserted
   def insert
     require_relative 'factbase/fact'
@@ -94,6 +133,9 @@ class Factbase
   #      (gt bar 200)
   #      (absent zzz)))
   #
+  # The full list of terms available in the query you can find in the
+  # +README.md+ file of the repository.
+  #
   # @param [String] query The query to use for selections
   def query(query)
     require_relative 'factbase/query'
@@ -102,9 +144,27 @@ class Factbase
 
   # Run an ACID transaction, which will either modify the factbase
   # or rollback in case of an error.
+  #
+  # If necessary to terminate a transaction and roolback all changes,
+  # you should raise the +Factbase::Rollback+ exception:
+  #
+  #  fb = Factbase.new
+  #  fb.txn do |fbt|
+  #    fbt.insert.bar = 42
+  #    raise Factbase::Rollback
+  #  end
+  #
+  # A the end of this script, the factbase will be empty. No facts will
+  # inserted and all changes that happened in the block will be rolled back.
+  #
+  # @param [Factbase] this The factbase to use (don't provide this param)
   def txn(this = self)
     copy = this.dup
-    yield copy
+    begin
+      yield copy
+    rescue Factbase::Rollback
+      return
+    end
     @mutex.synchronize do
       after = Marshal.load(copy.export)
       after.each_with_index do |m, i|
@@ -117,11 +177,31 @@ class Factbase
   end
 
   # Export it into a chain of bytes.
+  #
+  # Here is how you can export it to a file, for example:
+  #
+  #  fb = Factbase.new
+  #  fb.insert.foo = 42
+  #  File.binwrite("foo.fb", fb.export)
+  #
+  # The data is binary, it's not a text!
+  #
+  # @return [Bytes] The chain of bytes
   def export
     Marshal.dump(@maps)
   end
 
   # Import from a chain of bytes.
+  #
+  # Here is how you can read it from a file, for example:
+  #
+  #  fb = Factbase.new
+  #  fb.import(File.binread("foo.fb"))
+  #
+  # The facts that existed in the factbase before importing will remain there.
+  # The facts from the incoming byte stream will added to them.
+  #
+  # @param [Bytes] bytes Byte array to import
   def import(bytes)
     @maps += Marshal.load(bytes)
   end

data/test/factbase/test_looged.rb

@@ -94,7 +94,7 @@ class TestLooged < Minitest::Test
       'Found 1 fact(s) by \'(exists bar)\'',
       'Deleted 3 fact(s) by \'(not (exists bar))\''
     ].each do |s|
-      assert(log.to_s.include?("#{s}\n"), "#{log}\n")
+      assert(log.to_s.include?(s), "#{log}\n")
     end
   end
 end

data/test/factbase/test_query.rb

@@ -57,6 +57,9 @@ class TestQuery < Minitest::Test
       '(not (exists hello))' => 3,
       '(eq "Integer" (type num))' => 2,
       '(when (eq num 0) (exists time))' => 2,
+      '(unique num)' => 2,
+      '(unique name)' => 2,
+      '(unique pi)' => 1,
       '(many num)' => 1,
       '(one num)' => 2,
       '(gt num (minus 1 (either (at 0 (prev num)) 0)))' => 3,

data/test/factbase/test_tuples.rb

@@ -82,4 +82,25 @@ class TestTuples < Minitest::Test
     assert_equal(1, fb.query('(exists bar)').each.to_a.size)
     assert_equal(1, fb.query('(exists xyz)').each.to_a.size)
   end
+
+  def test_with_chaining
+    fb = Factbase.new
+    f1 = fb.insert
+    f1.name = 'Jeff'
+    f1.friend = 'Walter'
+    f2 = fb.insert
+    f2.name = 'Walter'
+    f2.group = 1
+    f3 = fb.insert
+    f3.name = 'Donny'
+    f3.group = 1
+    tuples = Factbase::Tuples.new(
+      fb, ['(eq name "Jeff")', '(eq name "{f0.friend}")', '(eq group {f1.group})']
+    )
+    tuples.each do |fs|
+      assert_equal('Walter', fs[1].name)
+      assert(%w[Walter Donny].include?(fs[2].name))
+    end
+    assert_equal(2, tuples.each.to_a.size)
+  end
 end

data/test/test_factbase.rb

@@ -140,4 +140,13 @@ class TestFactbase < Minitest::Test
     end
     assert_equal(1, fb.query('(exists xyz)').each.to_a.size)
   end
+
+  def test_txn_with_rollback
+    fb = Factbase.new
+    fb.txn do |fbt|
+      fbt.insert.bar = 33
+      raise Factbase::Rollback
+    end
+    assert_equal(0, fb.query('(always)').each.to_a.size)
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: factbase
 version: !ruby/object:Gem::Version
-  version: 0.0.38
+  version: 0.0.40
 platform: ruby
 authors:
 - Yegor Bugayenko
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-05-27 00:00:00.000000000 Z
+date: 2024-05-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: json