Class: Factbase

Inherits:
Object
  • Object
show all
Defined in:
lib/factbase.rb,
lib/factbase/version.rb

Overview

Just version.

Author

Yegor Bugayenko (yegor256@gmail.com)

Copyright

Copyright © 2024-2026 Yegor Bugayenko

License

MIT

Defined Under Namespace

Modules: CachedTerm, IndexedTerm Classes: Absent, Accum, Agg, Always, And, Arithmetic, As, Assert, Best, Boolean, CachedFact, CachedFactbase, CachedQuery, Churn, Compare, Concat, Contains, Count, Defn, Div, Either, Empty, EndsWith, Env, Eq, Exists, Fact, FactAsYaml, First, Flatten, Fuzz, Gt, Gte, Head, Impatient, IndexedAbsent, IndexedAnd, IndexedEq, IndexedExists, IndexedFact, IndexedFactbase, IndexedGt, IndexedLt, IndexedNot, IndexedOne, IndexedOr, IndexedQuery, IndexedUnique, Inv, Inverted, Join, LazyTaped, Light, Logged, Lt, Lte, Many, Matches, Max, Min, Minus, Never, Nil, Not, Nth, One, Or, Plus, Pre, Prev, Query, Rollback, Rules, Simplified, Size, Sorted, Sprintf, StartsWith, Sum, SyncFactbase, SyncQuery, Syntax, Tallied, Taped, Tee, Term, TermBase, Times, ToFloat, ToInteger, ToJSON, ToString, ToTime, ToXML, ToYAML, Traced, Type, Undef, Unique, When, Zero

Constant Summary collapse

VERSION =

Current version of the gem (changed by .rultor.yml on every release)

'0.19.11'

Instance Method Summary collapse

Constructor Details

#initialize(maps = []) ⇒ Factbase

Constructor.

Parameters:

  • maps (Array<Hash>) (defaults to: []) —

    Array of facts to start with



91
92
93
 
# File 'lib/factbase.rb', line 91

def initialize(maps = [])
  @maps = maps
end

Instance Method Details

#export ⇒ String

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!

Returns:

  • (String) —

    Binary string containing serialized data



219
220
221
 
# File 'lib/factbase.rb', line 219

def export
  Marshal.dump(@maps)
end

#import(bytes) ⇒ Object

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 be added to them.

This method supports both the original format (Array of maps) and the IndexedFactbase format (Hash with :maps and :idx keys).

Parameters:

  • bytes (String) —

    Binary string to import



237
238
239
240
241
242
243
244
245
246
 
# File 'lib/factbase.rb', line 237

def import(bytes)
  raise 'Empty input, cannot load a factbase' if bytes.empty?
  data = Marshal.load(bytes)
  @maps +=
    if data.is_a?(Hash) && data.key?(:maps)
      Marshal.load(data[:maps])
    else
      data
    end
end

#insert ⇒ Factbase::Fact

Insert a new fact and return it.

A fact, when inserted, is empty. It doesn’t contain any properties.

Returns:



106
107
108
109
110
111
 
# File 'lib/factbase.rb', line 106

def insert
  map = {}
  @maps << map
  require_relative 'factbase/fact'
  Factbase::Fact.new(map)
end

#query(term, maps = nil) ⇒ Object

Create a query capable of iterating.

There is a Lisp-like syntax, for example:

(eq title 'Object Thinking')
(gt time 2024-03-23T03:21:43Z)
(gt cost 42)
(exists seenBy)
(and
  (eq foo 42.998)
  (or
    (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.

Parameters:

  • term (String|Factbase::Term) —

    The query to use for selections

  • maps (Array<Hash>|nil) (defaults to: nil) —

    The subset of maps (if provided)



132
133
134
135
136
137
 
# File 'lib/factbase.rb', line 132

def query(term, maps = nil)
  maps ||= @maps
  term = to_term(term) if term.is_a?(String)
  require_relative 'factbase/query'
  Factbase::Query.new(maps, term, self)
end

#size ⇒ Integer

Size, the total number of facts in the factbase.

Returns:

  • (Integer) —

    How many facts are in there



97
98
99
 
# File 'lib/factbase.rb', line 97

def size
  @maps.size
end

#to_term(query) ⇒ Factbase::Term

Convert a query to a term.

Parameters:

  • query (String) —

    The query to convert

Returns:



142
143
144
145
 
# File 'lib/factbase.rb', line 142

def to_term(query)
  require_relative 'factbase/syntax'
  Factbase::Syntax.new(query).to_term
end

#txn ⇒ Factbase::Churn

Run an ACID transaction, which will either modify the factbase or rollback in case of an error.

If necessary to terminate a transaction and rollback all changes, you should raise the Factbase::Rollback exception:

fb = Factbase.new
fb.txn do |fbt|
  fbt.insert.bar = 42
  raise Factbase::Rollback
end

At the end of this script, the factbase will be empty. No facts will be inserted and all changes that happened in the block will be rolled back.

Returns:

  • (Factbase::Churn) —

    How many facts have been changed (zero if rolled back)



163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
 
# File 'lib/factbase.rb', line 163

def txn
  require_relative 'factbase/lazy_taped'
  taped = Factbase::LazyTaped.new(@maps)
  require_relative 'factbase/churn'
  churn = Factbase::Churn.new
  catch :commit do
    require_relative 'factbase/light'
    commit = false
    catch :rollback do
      yield Factbase::Light.new(Factbase.new(taped))
      commit = true
    end
    return churn unless commit
  rescue Factbase::Rollback
    return churn
  end
  seen = {}.compare_by_identity
  garbage = {}.compare_by_identity
  taped.deleted.each do |oid|
    original = @maps.find { |m| m.object_id == oid }
    next if original.nil?
    garbage[original] = true
    churn.append(0, 1, 0)
  end
  taped.inserted.each do |oid|
    b = taped.find_by_object_id(oid)
    next if b.nil?
    next if seen.key?(b)
    seen[b] = true
    @maps << b
    churn.append(1, 0, 0)
  end
  taped.added.each do |oid|
    b = taped.find_by_object_id(oid)
    next if b.nil?
    next if seen.key?(b)
    original = taped.source_of(b)
    garbage[original] = true if original
    @maps << b
    churn.append(0, 0, 1)
  end
  @maps.delete_if { |m| garbage.key?(m) } unless garbage.empty?
  churn
end