dbd 0.0.5 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9ad1bee3c2518a24358318cfda3b6931321911a2
-  data.tar.gz: 2b7ffc84e350ce65c526e8cfc2246713e02cd7a6
+  metadata.gz: cc144cf2ae12eb90508d2da68006a9cc5ac247dd
+  data.tar.gz: 7bac3b578951f4a3a610aa988d5f06c180095368
 SHA512:
-  metadata.gz: a2b09154cd4c1482f08d7233964343c9b02ac70293358e9928b6b46fe30f04650b1a118506ab0fe98d6ce8a46143563ac5f09a0e3233f5c3196ab95b26e97b81
-  data.tar.gz: a25149c6e0288ce1cd9ae0f7f769fbcd067b5db6dfc52b8128cd4f6d53cfd31c1e607e62e2ef020735cef027447de56711f754bcfcf8cef55005d241ae7e2ca6
+  metadata.gz: 0e0f6fa90ad08943e62780b350a058e4d27286eb0396e3524222cd4d488ca81ac3764b58076bdb5331a91cd851fa710440a3e1b7060e81d2734c2f069f56a8ed
+  data.tar.gz: fb95d9bb0d1ecb5f13d297fa69ab01d661e460653d80333967583c46e843412ea46324fa025330d59f1dfcbf19c4dd5fa53a51099fe39db9d972a0e5339b1595

data/Guardfile

@@ -1,8 +1,9 @@
 guard 'rspec' do
   watch(%r{^spec/.+_spec\.rb$})
   watch(%r{^spec/factories})    { "spec" }
-  watch(%r{^lib/dbd/helpers})       { "spec" }
-  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{^lib/dbd/helpers})   { "spec" }
+#  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}/" }
   watch('spec/spec_helper.rb')  { "spec" }
   watch('lib/dbd.rb')           { "spec" }
 end

data/HISTORY.txt

@@ -27,3 +27,8 @@
 =====
 
 * use ruby_peter_v 0.0.8 which does not have max_with_nil
+
+0.0.6 (17 June 2013)
+=====
+
+* Fact.from_CSV reads from a CSV stream (file or stringIO)

data/dbd.gemspec

@@ -26,5 +26,5 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'yard'
   spec.add_runtime_dependency 'neography'
   spec.add_runtime_dependency 'rdf', '~> 1.0.6'
-  spec.add_runtime_dependency 'ruby_peter_v', '>= 0.0.8'
+  spec.add_runtime_dependency 'ruby_peter_v', '>= 0.0.9'
 end

data/docs/stories/013_read_graph_from_CSV.txt

@@ -0,0 +1,10 @@
+013_read_graph_from_CSV
+
+As a client
+I can read a graph from a CSV file
+
+* read a CSV file
+* with some special characters
+* with comma, new line and escape double quote
+* without double quotes
+* checks that each Fact has 6 valid fields

data/lib/dbd.rb

@@ -10,5 +10,5 @@ require 'dbd/resource'
 require 'dbd/provenance_resource'
 require 'dbd/graph'
 
-require 'dbd/rdf'
+require 'dbd/rdf_base'
 require 'dbd/repo'

data/lib/dbd/fact.rb

@@ -123,8 +123,11 @@ module Dbd
     # @option options [#to_s] :object Required :  the object for this Fact (required)
     # @option options [Subject] :provenance_subject (nil) Optional: the subject of the provenance(resource|fact)
     # @option options [Subject] :subject (nil) Optional: the subject for this Fact
+    # @option options [TimeStamp] :time_stamp (nil) Optional: the time_stamp for this Fact
+    # @option options [ID] :id Optional : set the id
     def initialize(options)
-      @id = self.class.new_id
+      @id = options[:id] || self.class.new_id
+      @time_stamp = options[:time_stamp]
       @provenance_subject = options[:provenance_subject]
       @subject = options[:subject]
       @predicate = options[:predicate]
@@ -139,6 +142,16 @@ module Dbd
       self.class.attributes.map{ |attribute| self.send(attribute) }
     end
 
+    ##
+    # Constructs a Fact from a values array
+    # (e.g. pulled from a CSV row).
+    #
+    # @param [Array] values Required : the array with values, organized as in attributes
+    # @return [Fact] the constructed fact
+    def self.from_values(values)
+      new(Hash[[self.attributes, values].transpose])
+    end
+
     ##
     # @return [String] a short string representation of a Fact
     def short
@@ -190,6 +203,15 @@ module Dbd
       "Provenance subject is missing" unless provenance_subject
     end
 
+    ##
+    # Confirms this is not a ProvenanceFact
+    #
+    # Needed for validations that depend on different behavior for
+    # a provenance_fact (mainly, no provenance_subject).
+    def provenance_fact?
+      false
+    end
+
   private
 
     def provenance_subject_short

data/lib/dbd/fact/id.rb

@@ -2,12 +2,12 @@ module Dbd
   class Fact
     class ID
 
-      def initialize
-        @uuid = Helpers::UUID.new
+      def initialize(options = {})
+        @uuid = options[:uuid] || Helpers::UUID.new.to_s
       end
 
       def to_s
-        @uuid.to_s
+        @uuid
       end
 
       def self.regexp

data/lib/dbd/fact/subject.rb

@@ -4,12 +4,12 @@ module Dbd
   class Fact
     class Subject
 
-      def initialize
-        @uuid = Helpers::UUID.new
+      def initialize(options = {})
+        @uuid = options[:uuid] || Helpers::UUID.new.to_s
       end
 
       def to_s
-        @uuid.to_s
+        @uuid
       end
 
       def self.regexp

data/lib/dbd/graph.rb

@@ -5,19 +5,26 @@ module Dbd
   ##
   # The Graph stores the Facts and ProvenanceFacts in an in-memory
   # collection structure.
+  #
+  # On the other hand, it acts as an "interface" that can be
+  # re-implemented by other persistence mechanisms (duck typing).
   class Graph
 
     include Fact::Collection
 
     ##
-    # Add a Fact or Resource or any set recursively.
+    # Add a Fact, Resource or other recursive collection of facts.
     #
-    # This will add a time_stamp to the Facts.
-    def <<(recursive_fact_collection)
-      recursive_fact_collection.each_recursively do |fact|
+    # Side effect: this will set the time_stamp of the facts.
+    #
+    # @param [#time_stamp, #time_stamp=, #each] fact_collection a recursive collection of facts
+    # @return [Graph] self
+    def <<(fact_collection)
+      fact_collection.each_recursively do |fact|
         enforce_strictly_monotonic_time(fact)
         super(fact)
       end
+      self
     end
 
     ##
@@ -32,6 +39,20 @@ module Dbd
       end.encode("utf-8")
     end
 
+    ##
+    # Import a graph from a CSV string.
+    #
+    # @param [String] csv a string that contains the CSV serialization
+    # @return [Graph] the imported graph
+    def self.from_CSV(csv)
+      Graph.new.tap do |graph|
+        CSV.new(csv).each do |row|
+          # TODO validate the input formats (e.g. invalid uuid codes)
+          graph << Fact.from_values(row)
+        end
+      end
+    end
+
   private
 
     ##

data/lib/dbd/provenance_fact.rb

@@ -53,15 +53,12 @@ module Dbd
     end
 
     ##
-    # Builds duplicate with the subject set.
+    # Confirms this is a ProvenanceFact
     #
-    # @param [Subject] subject_arg
-    # @return [ProvenanceFact] the duplicate fact
-    def dup_with_subject(subject_arg)
-      self.class.new(
-       subject: subject_arg, # from arg
-       predicate: predicate,
-       object: object)
+    # Needed for validations that depend on different behavior for
+    # a provenance_fact (mainly, no provenance_subject).
+    def provenance_fact?
+      true
     end
 
   private

data/lib/dbd/provenance_resource.rb

@@ -1,7 +1,9 @@
 module Dbd
   ##
   # A ProvenanceResource is derived from a Resource, specifically
-  # for a Provenance (does not have and does need a provenance_subject)
+  # for a Provenance.
+  #
+  # The main difference is that it does not have a provenance_subject.
   class ProvenanceResource < Resource
 
     ##
@@ -17,38 +19,44 @@ module Dbd
     end
 
     ##
-    # Add a ProvenanceFact.
+    # Add a ProvenanceFact (strictly only a ProvenanceFact).
     #
+    # Side effect on subject:
     # * if it has no subject, the subject is set in a duplicate provenance_fact
     # * if is has the same subject as the resource, added unchanged.
     # * if it has a different subject, a SubjectError is raised.
     def <<(provenance_fact)
-      # TODO: check the type of the provenance_fact (ProvenanceFact)
       super
     end
 
   private
 
-    ##
     # Should not be called in ProvenanceResource subclass.
     def provenance_subject
-      raise RuntimeError, "provenance_subject should not be called in ProvenanceResource."
+      raise NoMethodError, "provenance_subject should not be called in ProvenanceResource."
     end
 
-    ##
-    # Validate that provenance_subject is not set here.
+    def set_provenance_subject(options)
+      raise ArgumentError, "provenance_subject must not be in the options" if options[:provenance_subject]
+    end
+
+    # Validate that provenance_subject is not present here.
+    # This should never raise as the setter was blocked above.
     def validate_provenance_subject
       raise ProvenanceError if @provenance_subject
     end
 
     ##
-    # Check provenance_subject, which should be nil here
+    # Assert _only_ ProvenanceFacts here
+    def assert_fact_provenance_fact(fact)
+      raise ArgumentError, "Trying to add a non-ProvenanceFact to a ProvenanceResource." unless fact.provenance_fact?
+    end
+
+    ##
+    # A noop for ProvenanceResource.
     # @param [ProvenanceFact] provenance_fact
-    def set_provenance!(provenance_fact)
-      if provenance_fact.provenance_subject
-        raise ProvenanceError,
-          "trying to set provenance_subject to#{provenance_fact.provenance_subject}"
-      end
+    def set_fact_provenance!(provenance_fact)
+      # Do nothing
     end
 
   end

data/lib/dbd/resource.rb

@@ -2,12 +2,12 @@ require 'dbd/helpers/ordered_set_collection'
 
 module Dbd
   ##
-  # A Resource is a collection of facts that have the same subject.
+  # A Resource is a collection of Facts that have the same subject.
   #
   # In the real-world this is a mainly an "instance" about which all
   # facts are giving information (e.g. a conference, a person, a
   # bicycle, ...). More generally this can also be used to describe
-  # classes and other concepts in the software system.
+  # classes and other concepts in the system.
   #
   # A new (random) subject is generated for a resource. In Dbd,
   # a subject is a random uuid (like a oid), not a meaningful URI
@@ -25,15 +25,7 @@ module Dbd
 
     include Helpers::OrderedSetCollection
 
-    attr_reader :subject
-
-    ##
-    # Getter for provenance_subject.
-    #
-    # Will be overridden in the ProvenanceResource subclass.
-    def provenance_subject
-      @provenance_subject
-    end
+    attr_reader :subject, :provenance_subject
 
     ##
     # @return [Fact::Subject] a new (random) Resource subject
@@ -51,19 +43,20 @@ module Dbd
     #
     # The provenance_subject argument is required. This will typically be
     # taken from an earlier created ProvenanceResource.
+    #
     # @param [Hash{Symbol => Object}] options
     # @option options [Fact::Subject] :provenance_subject (required) the subject of the provenance resource for this resource
     # @option options [Fact::Subject] :subject (new_subject) Optional: the subject for the resource
     def initialize(options)
-      @subject = options[:subject] || self.class.new_subject
-      @provenance_subject = options[:provenance_subject]
-      validate_provenance_subject
+      set_subject(options)
+      set_provenance_subject(options)
       super()
     end
 
     ##
-    # Add a fact.
+    # Add a Fact (strictly not a ProvenanceFact)
     #
+    # Side effects on subject and provenance_subject:
     # * if it has no subject, the subject is set (this modifies the fact !)
     # * if is has the same subject as the resource, added unchanged.
     # * if it has a different subject, a SubjectError is raised.
@@ -71,25 +64,34 @@ module Dbd
     # * if is has the same provenance_subject as the resource, added unchanged.
     # * if it has a different provenance_subject, a ProvenanceError is raised.
     def <<(fact)
-      # TODO: check the type of the fact (Fact)
-      set_subject!(fact)
-      set_provenance!(fact)
+      assert_fact_provenance_fact(fact)
+      set_fact_subject!(fact)
+      set_fact_provenance!(fact)
       super(fact)
     end
 
   private
 
-    def set_subject!(fact)
+    def set_subject(options)
+      @subject = options[:subject] || self.class.new_subject
+    end
+
+    def set_provenance_subject(options)
+      @provenance_subject = options[:provenance_subject]
+      raise ProvenanceError, "provenance_subject cannot be nil" if @provenance_subject.nil?
+    end
+
+    def set_fact_subject!(fact)
       fact.subject = subject
     end
 
-    # this will be overriden in the ProvenanceResource sub_class
-    def set_provenance!(fact)
+    def set_fact_provenance!(fact)
       fact.provenance_subject = provenance_subject
     end
 
-    def validate_provenance_subject
-      raise ProvenanceError if @provenance_subject.nil?
+    # Assert _no_ ProvenanceFacts here
+    def assert_fact_provenance_fact(fact)
+      raise ArgumentError, "Trying to add a ProvenanceFact to a Resource." if fact.provenance_fact?
     end
 
   end

data/lib/dbd/time_stamp.rb

@@ -66,12 +66,23 @@ module Dbd
       Rational("#{1+rand(999)}/1_000_000_000")
     end
 
+    def self.time_format
+      '%F %T.%N %Z'
+    end
+
   public
 
     ##
-    # to a nanosecond granularity and in UTC
+    # with a nanosecond granularity and in UTC
     def to_s
-      @time.strftime('%F %T.%N %Z')
+      @time.strftime(self.class.time_format)
+    end
+
+    ##
+    # with a nanosecond granularity and in UTC
+    def self.from_s(time_string)
+      date_time = DateTime.strptime(time_string, time_format)
+      TimeStamp.new(time: date_time.to_time.utc)
     end
 
     def >(other)

data/lib/dbd/version.rb

@@ -1,3 +1,3 @@
 module Dbd
-  VERSION = "0.0.5"
+  VERSION = "0.0.6"
 end

data/spec/factories/fact.rb

@@ -16,6 +16,20 @@ module Factories
         object: "Gandhi")
     end
 
+    def self.fact_with_forced_id(forced_id)
+      factory_for.new(
+        id: forced_id,
+        predicate: "http://example.org/test/name",
+        object: "Gandhi")
+    end
+
+    def self.fact_with_time_stamp(time_stamp)
+      factory_for.new(
+        time_stamp: time_stamp,
+        predicate: "http://example.org/test/name",
+        object: "Gandhi")
+    end
+
     def self.fact_2_with_subject(provenance_subject = nil)
       factory_for.new(
         provenance_subject: provenance_subject,
@@ -56,6 +70,15 @@ module Factories
         object: "A long story\nreally.")
     end
 
+    def self.full_fact
+      fixed_id = Factories::Fact::ID.fixed_id
+      fact_with_forced_id(fixed_id).tap do |fact|
+        fact.time_stamp = Factories::TimeStamp.fixed_time_stamp
+        fact.subject = Factories::Fact::Subject.fixed_subject
+        fact.provenance_subject = Factories::Fact::Subject.fixed_provenance_subject
+      end
+    end
+
     module Collection
 
       def self.factory_for_instance