factbase 0.0.38 → 0.0.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3c7e0abf7bec6e53f050b4eeaeddd2b9954ee77b2a5f9a0332394c995d91ba9
-  data.tar.gz: 5da4b8574d7b1a93fd67f3d833bf51952eb5b3d9c303b9e20a084dc5953d71bc
+  metadata.gz: 8ff1db55d5a25e5036d3a98423caedc960f8323681e2227c82e0a397727067c0
+  data.tar.gz: b3000b708bd2eb69005998a722011a296384d5cea66641b975471e611b93e4d0
 SHA512:
-  metadata.gz: f472603e32966c098979c2a461d94cd60f1f6213c4cea4abae225694d59ae88df252bbd42dcfb3292efb97352618cfa35fe56bef86bf87310dc74b4dbce65a20
-  data.tar.gz: fb91b271a5d57c59268dd386f8960e1c3c3c1577ea80e5c9bc3b623eaa6c559b15ce326f23ec9035e795d08ce647af353f4ae12aef5a34a124286f41fdf79130
+  metadata.gz: a377a359a877b1f50c83f13c451e095036b4087cf88e39c04a0e5d64e86337bfef458883646009daff4b2b90446abbdbd563a4921b3ed275b88b7408b69ef0de
+  data.tar.gz: 26a5ca088df353e0c526080213aa4d87b23805dd522617d52d2d738b1881c40ae4c659fa886db4fbe19a30a131ff6b5a7e19aadf5dbafcbd0f6b81954386bd65

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,6 +85,10 @@ 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

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.39'
+
+  # 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_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.39
 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