Class: Dbd::Fact

Inherits:
Object
  • Object
show all
Defined in:
lib/dbd/fact.rb,
lib/dbd/fact/id.rb,
lib/dbd/fact/factory.rb,
lib/dbd/fact/subject.rb,
lib/dbd/fact/collection.rb

Overview

Basic Fact of knowledge.

The database is built as an ordered sequence of facts, a “fact stream”.

This is somewhat similar to a “triple” in the RDF (Resource Description Framework) concept, but with different and extended functionality.

Each basic fact has:

  • a time_stamp (time with nanosecond granularity)

    To allow verifying that the order in a fact stream is correct.

    A time_stamp does not need to represent the exact time of the creation of the fact, but it has to increase in strictly monotic order in a fact stream.

  • a unique and invariant id (a uuid)

    To allow referencing back to it (e.g. to invalidate it later in a fact stream).

  • a context_subject (a uuid)

    The subject of the Context (a set of Contexts with the same subject) about this fact. Each Fact, points back to a Context (the Context must have been fully defined, earlier in a fact stream).

  • a subject (a uuid)

    “About which Resource is this fact?”.

    Similar to the subject of an RDF triple, except that this subject is not a URI, but an abstract uuid (that is world-wide unique and invariant).

    Links to “real-world” URI’s and URL’s can be added later as separate facts (this also allows linking multiple “real-world” URI’s to a single Resource).

  • a predicate (a string)

    “Which property of the resource are we describing?”.

    Currently this is a string, but I suggest modeling this similar to predicate in RDF. Probably more detailed modeling using RDF predicate will follow.

  • an object (a string)

    “What is the value of the property of the resource we are describing?”.

    Currently this is a string, but I suggest modeling this similar to object in RDF. Probably more detailed modeling using RDF object will follow.

Direct Known Subclasses

ContextFact

Defined Under Namespace

Modules: Collection, Factory, ID, Subject

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options) ⇒ Fact

Builds a new Fact.

Parameters:

  • options (Hash{Symbol => Object})

Options Hash (options):

  • :object (#to_s) —

    Required : the object for this Fact (required)

  • :predicate (#to_s) —

    Required : the predicate for this Fact

  • :subject (String (uuid)) —

    Optional : the subject for this Fact

  • :context_subject (String (uuid)) —

    Optional : the subject of the Context

  • :id (String (uuid)) —

    Optional : set the id

  • :time_stamp (TimeStamp) —

    Optional : the time_stamp for this Fact

Raises:



123
124
125
126
127
128
129
130
131
132
133
 
# File 'lib/dbd/fact.rb', line 123

def initialize(options)
  @time_stamp = options[:time_stamp]
  @id = options[:id] || self.class.factory.new_id
  @context_subject = options[:context_subject]
  @subject = options[:subject]
  @predicate = options[:predicate]
  @object = options[:object]
  validate_time_stamp_class(@time_stamp)
  raise PredicateError, "predicate cannot be nil" if predicate.nil?
  raise ObjectError, "object cannot be nil" if object.nil?
end

Class Method Details

.attributes ⇒ Array

Returns The 6 attributes of a Fact.

Returns:

  • (Array) —

    The 6 attributes of a Fact.



69
70
71
72
73
74
75
76
 
# File 'lib/dbd/fact.rb', line 69

def self.attributes
  [:time_stamp,
   :id,
   :context_subject,
   :subject,
   :predicate,
   :object]
end

.factory ⇒ Module

Returns The module that has the factories for Fact.

Returns:

  • (Module) —

    The module that has the factories for Fact



63
64
65
 
# File 'lib/dbd/fact.rb', line 63

def self.factory
  self::Factory
end

Instance Method Details

#context_fact? ⇒ trueish

Confirms this is not a ContextFact.

Needed for validations that depend on different behavior for a context_fact (mainly, no context_subject).

Returns:

  • (trueish) —

    false in the Fact implementation



215
216
217
 
# File 'lib/dbd/fact.rb', line 215

def context_fact?
  false
end

#context_subject=(context_subject) ⇒ Object

A set_once setter for context_subject.

Parameters:

  • context_subject (String) —

    a string representation of the uuid



101
102
103
 
# File 'lib/dbd/fact.rb', line 101

def context_subject=(context_subject)
  set_once(:context_subject, context_subject)
end

#context_subject_error(context_subject) ⇒ Object

Validates the presence or absence of context_subject.

Here, in (base) Fact, context_subject must be present.

In the derived ContextFact it must NOT be present. This is how the difference is encoded between Fact and ContextFact in the fact stream.

Return [nil, String] nil or an error message

Parameters:

  • context_subject (Object) 


204
205
206
 
# File 'lib/dbd/fact.rb', line 204

def context_subject_error(context_subject)
  "ContextFact subject is missing" unless context_subject
end

#equivalent?(other) ⇒ trueish

Equivalent facts (have all same values, except time_stamp which is near?).

For “equality” only a test on the id is used. If the id (which is a uuid) is the same, we assume that is the “same” fact. This equivalent? method is used to test is equal methods are “really” equivalent.

The time_stamp may be slightly different (because shifts of a few nanoseconds will be required to resolve collisions on merge).

Parameters:

  • other (Fact) —

    the other fact to compare with

Returns:

  • (trueish) 


165
166
167
168
169
 
# File 'lib/dbd/fact.rb', line 165

def equivalent?(other)
  (self.class.attributes - [:time_stamp]).
    all?{ |attribute| self.send(attribute) == other.send(attribute) } &&
    self.time_stamp.near?(other.time_stamp)
end

#errors ⇒ Array

Checks if a fact has errors for storing in the graph.

Returns:

  • (Array) —

    an Array of error messages



184
185
186
187
188
189
190
191
 
# File 'lib/dbd/fact.rb', line 184

def errors
  # * id not validated, is set automatically upon creation
  # * time_stamp not validated, is set automatically later
  # * predicate not validated, is validated upon creation
  # * object not validated, is validated upon creation
  [context_subject_error(context_subject),
   subject ? nil : "Subject is missing"].compact
end

#short ⇒ String

Returns a short string representation of a Fact.

Returns:

  • (String) —

    a short string representation of a Fact



173
174
175
176
177
178
 
# File 'lib/dbd/fact.rb', line 173

def short
  "#{context_subject_short} : " \
  "#{subject.to_s[0...8]} : " \
  "#{predicate.to_s.ljust(24, ' ').truncate_utf8(24)} : " \
  "#{object.to_s.truncate_utf8(80).gsub(/\n/, '_')}"
end

#string_values ⇒ Array

The individual strings are escaped:

  • newlines are escaped to ‘n’

This is used for the 6 entries in the to_CSV mapping.

Returns:

  • (Array) —

    The 6 values of a Fact converted to a string.



147
148
149
 
# File 'lib/dbd/fact.rb', line 147

def string_values
  values.map{ |value| escaped_string(value.to_s) }
end

#subject=(subject) ⇒ Object

A set_once setter for subject.

Parameters:

  • subject (String) —

    a string representation of the uuid



109
110
111
 
# File 'lib/dbd/fact.rb', line 109

def subject=(subject)
  set_once(:subject, subject)
end

#time_stamp=(time_stamp) ⇒ Object

These “set once” setters implement a form of immutable behavior. The value can be set once (after initial creation the object), but can never be changed after that.

A set_once setter for time_stamp.

The input class is validated (easy confusion with String or Time).

Parameters:

  • time_stamp (TimeStamp) —

    a time_stamp (not a Time or a String)



92
93
94
95
 
# File 'lib/dbd/fact.rb', line 92

def time_stamp=(time_stamp)
  validate_time_stamp_class(time_stamp)
  set_once(:time_stamp, time_stamp)
end

#values ⇒ Array

Returns The 6 values of a Fact.

Returns:

  • (Array) —

    The 6 values of a Fact.



137
138
139
 
# File 'lib/dbd/fact.rb', line 137

def values
  self.class.attributes.map{ |attribute| self.send(attribute) }
end