Class: Factbase

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

Overview

Just version.

Author

Yegor Bugayenko ([email protected])

Copyright

Copyright © 2024-2025 Yegor Bugayenko

License

MIT

Defined Under Namespace

Modules: Aggregates, Aliases, CachedTerm, Casting, Debug, Defn, IndexedTerm, Logical, Math, Meta, Ordering, Strings, System Classes: Accum, CachedFact, CachedFactbase, CachedQuery, Churn, Fact, FactAsYaml, Flatten, Impatient, IndexedFact, IndexedFactbase, IndexedQuery, Inv, Light, Logged, Pre, Query, Rollback, Rules, SyncFactbase, SyncQuery, Syntax, Tallied, Taped, Tee, Term, ToJSON, ToXML, ToYAML

Constant Summary collapse

VERSION =

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

'0.15.8'

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



224
225
226
 
# File 'lib/factbase.rb', line 224

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.

Parameters:

  • bytes (String) —

    Binary string to import



239
240
241
242
 
# File 'lib/factbase.rb', line 239

def import(bytes)
  raise 'Empty input, cannot load a factbase' if bytes.empty?
  @maps += Marshal.load(bytes)
end

#insert ⇒ Factbase::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 different threads may insert facts in parallel without breaking the consistency of the factbase.

Returns:



109
110
111
112
113
114
 
# File 'lib/factbase.rb', line 109

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)



135
136
137
138
139
140
 
# File 'lib/factbase.rb', line 135

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:



145
146
147
148
 
# File 'lib/factbase.rb', line 145

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)



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
207
208
209
210
211
 
# File 'lib/factbase.rb', line 166

def txn
  pairs = {}
  before =
    @maps.map do |m|
      n = m.transform_values(&:dup)
      # rubocop:disable Lint/HashCompareByIdentity
      pairs[n.object_id] = m.object_id
      # rubocop:enable Lint/HashCompareByIdentity
      n
    end
  require_relative 'factbase/taped'
  taped = Factbase::Taped.new(before)
  catch :commit do
    require_relative 'factbase/light'
    commit = false
    catch :rollback do
      yield Factbase::Light.new(Factbase.new(taped))
      commit = true
    end
    return 0 unless commit
  rescue Factbase::Rollback
    return 0
  end
  require_relative 'factbase/churn'
  churn = Factbase::Churn.new
  taped.inserted.each do |oid|
    b = taped.find_by_object_id(oid)
    next if b.nil?
    @maps << b
    churn.append(1, 0, 0)
  end
  garbage = []
  taped.added.each do |oid|
    b = taped.find_by_object_id(oid)
    next if b.nil?
    garbage << pairs[oid]
    @maps << b
    churn.append(0, 0, 1)
  end
  taped.deleted.each do |oid|
    garbage << pairs[oid]
    churn.append(0, 1, 0)
  end
  @maps.delete_if { |m| garbage.include?(m.object_id) }
  churn
end