factbase 0.0.37 → 0.0.39

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a464f6fa40a3aef098e4ab4a58b6f6905ac101421f22fb806b63c4fb624aa610
-  data.tar.gz: ad19a0147890d8b4ff8fff96f7e9f47b09ecb264b3cb52fa606be892278fa380
+  metadata.gz: 8ff1db55d5a25e5036d3a98423caedc960f8323681e2227c82e0a397727067c0
+  data.tar.gz: b3000b708bd2eb69005998a722011a296384d5cea66641b975471e611b93e4d0
 SHA512:
-  metadata.gz: 6abb74b759ef7eea421e8a7f4f1ebdbf7ae46836dfefcd324286508fbb82e207a787265c0cf9f8931b43b00d50e5df983266fa9442f9c277111dfa9ea3a778de
-  data.tar.gz: b0ed97f83f59230bafce810488f3e720d098a748149f7fbd58b7f1c25425b2fba6b742ce16b18692df34607eb3c42f9f11196ca212bc0273d7bdffe15e759efe
+  metadata.gz: a377a359a877b1f50c83f13c451e095036b4087cf88e39c04a0e5d64e86337bfef458883646009daff4b2b90446abbdbd563a4921b3ed275b88b7408b69ef0de
+  data.tar.gz: 26a5ca088df353e0c526080213aa4d87b23805dd522617d52d2d738b1881c40ae4c659fa886db4fbe19a30a131ff6b5a7e19aadf5dbafcbd0f6b81954386bd65

data/.rubocop.yml

@@ -43,7 +43,7 @@ Metrics/BlockLength:
 Metrics/CyclomaticComplexity:
   Max: 25
 Metrics/PerceivedComplexity:
-  Max: 25
+  Max: 30
 Metrics/ClassLength:
   Enabled: false
 Layout/EmptyLineAfterGuardClause:

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
-* `(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 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`
 
 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/syntax.rb

@@ -44,7 +44,9 @@ class Factbase::Syntax
   def to_term
     build.simplify
   rescue StandardError => e
-    raise "#{e.message} in \"#{@query}\""
+    err = "#{e.message} in #{@query}"
+    err = "#{err}, tokens: #{@tokens}" unless @tokens.nil?
+    raise err
   end
 
   private
@@ -95,7 +97,11 @@ class Factbase::Syntax
     list = []
     acc = ''
     string = false
-    @query.to_s.gsub(/#.*$/, '').chars.each do |c|
+    comment = false
+    @query.to_s.chars.each do |c|
+      comment = true if !string && c == '#'
+      comment = false if comment && c == "\n"
+      next if comment
       if ['\'', '"'].include?(c)
         if string && acc[acc.length - 1] == '\\'
           acc = acc[0..-2]

data/lib/factbase/term.rb

@@ -158,7 +158,7 @@ class Factbase::Term
     by_symbol(0, fact).nil?
   end
 
-  def nonil(fact, maps)
+  def either(fact, maps)
     assert_args(2)
     v = the_values(0, fact, maps)
     return v unless v.nil?

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.37'
+  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_query.rb

@@ -59,7 +59,7 @@ class TestQuery < Minitest::Test
       '(when (eq num 0) (exists time))' => 2,
       '(many num)' => 1,
       '(one num)' => 2,
-      '(gt num (minus 1 (nonil (at 0 (prev num)) 0)))' => 3,
+      '(gt num (minus 1 (either (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,

data/test/factbase/test_syntax.rb

@@ -42,10 +42,12 @@ class TestSyntax < Minitest::Test
   def test_simple_parsing
     [
       '(foo)',
-      '(foo (bar) (zz 77)   )',
+      '(foo (bar) (zz 77)   ) # hey',
+      "# hello\n\n\n(foo (bar))",
       "(eq foo   \n\n 'Hello, world!'\n)\n",
       "(eq x 'Hello, \\' \n) \\' ( world!')",
       "# this is a comment\n(eq foo # test\n 42)\n\n# another comment\n",
+      "(foo 'Hello,\n\nworld!\r\t\n')\n",
       "(or ( a 4) (b 5) (always) (and (always) (c 5) \t\t(r 7 w8s w8is 'Foo')))"
     ].each do |q|
       Factbase::Syntax.new(q).to_term
@@ -60,7 +62,7 @@ class TestSyntax < Minitest::Test
       "(r 'Dude\\'s Friend')",
       "(r 'I\\'m \\\"good\\\"')",
       '(foo x y z)',
-      "(foo x y z t f 42 'Hi!' 33)",
+      "(foo x y z t f 42 'Hi!# you' 33)",
       '(foo (x) y z)',
       '(eq t 2024-05-25T19:43:48Z)',
       '(eq t 2024-05-25T19:43:48Z)',
@@ -106,11 +108,10 @@ class TestSyntax < Minitest::Test
       ')',
       '"'
     ].each do |q|
-      assert(
-        assert_raises(q) do
-          Factbase::Syntax.new(q).to_term
-        end.message.include?(q)
-      )
+      msg = assert_raises(q) do
+        Factbase::Syntax.new(q).to_term
+      end.message
+      assert(msg.include?(q), msg)
     end
   end
 

data/test/factbase/test_term.rb

@@ -178,8 +178,8 @@ class TestTerm < Minitest::Test
     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])
+  def test_either
+    t = Factbase::Term.new(:either, [Factbase::Term.new(:at, [5, :foo]), 42])
     assert_equal([42], t.evaluate(fact('foo' => 4), []))
   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.37
+  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