ro-bundle 0.1.0 → 0.2.0

data/lib/ro-bundle/ro/annotation.rb

@@ -1,5 +1,5 @@
 #------------------------------------------------------------------------------
-# Copyright (c) 2014 The University of Manchester, UK.
+# Copyright (c) 2014, 2015 The University of Manchester, UK.
 #
 # BSD Licenced. See LICENCE.rdoc for details.
 #
@@ -10,8 +10,7 @@
 module ROBundle
 
   # A class to represent an Annotation in a Research Object.
-  class Annotation
-    include Provenance
+  class Annotation < ManifestEntry
 
     # :call-seq:
     #   new(target, content = nil)
@@ -24,25 +23,67 @@ module ROBundle
     # An annotation id is a UUID prefixed with "urn:uuid" as per
     # {RFC4122}[http://www.ietf.org/rfc/rfc4122.txt].
     def initialize(object, content = nil)
+      super()
+
       if object.instance_of?(Hash)
         @structure = object
+        @structure[:about] = [*@structure[:about]]
         init_provenance_defaults(@structure)
       else
         @structure = {}
-        @structure[:about] = object
-        @structure[:annotation] = UUID.generate(:urn)
+        @structure[:about] = [*object]
+        @structure[:uri] = UUID.generate(:urn)
         @structure[:content] = content
       end
     end
 
     # :call-seq:
-    #   target
+    #   annotates?(target) -> true or false
+    #
+    # Does this annotation object annotate the supplied target?
+    def annotates?(target)
+      @structure[:about].include?(target)
+    end
+
+    # :call-seq:
+    #   target -> String or Array
+    #
+    # The identifier(s) for the annotated resource. This is considered the
+    # target of the annotation, that is the resource (or resources) the
+    # annotation content is "somewhat about".
     #
-    # The identifier for the annotated resource. This is considered the target
-    # of the annotation, that is the resource the annotation content is
-    # "somewhat about".
+    # The target can either be a singleton or a list of targets.
     def target
-      @structure[:about]
+      about = @structure[:about]
+      about.length == 1 ? about[0] : about.dup
+    end
+
+    # :call-seq:
+    #   add_target(new_target, ...) -> added target(s)
+    #
+    # Add a new target, or targets, to this annotation.
+    #
+    # The target(s) added are returned.
+    def add_target(add)
+      @structure[:about] += [*add]
+
+      @edited = true
+      add
+    end
+
+    # :call-seq:
+    #   remove_target(target) -> target or nil
+    #
+    # Remove a target from this annotation. An annotation must always have a
+    # target so this method will do nothing if it already has only one target.
+    #
+    # If the target can be removed then it is returned, otherwise nil is
+    # returned.
+    def remove_target(remove)
+      return if @structure[:about].length == 1
+
+      @edited = true
+      @structure[:about].delete(remove)
     end
 
     # :call-seq:
@@ -58,15 +99,16 @@ module ROBundle
     #
     # Set the content of this annotation.
     def content=(new_content)
+      @edited = true
       @structure[:content] = new_content
     end
 
     # :call-seq:
-    #   annotation_id -> String
+    #   uri -> String in the form of a urn:uuid URI.
     #
     # Return the annotation id of this Annotation.
-    def annotation_id
-      @structure[:annotation]
+    def uri
+      @structure[:uri]
     end
 
     # :call-seq:
@@ -75,13 +117,9 @@ module ROBundle
     # Write this Annotation out as a json string. Takes the same options as
     # JSON#generate.
     def to_json(*a)
-      Util.clean_json(@structure).to_json(*a)
-    end
-
-    private
-
-    def structure
-      @structure
+      cleaned = Util.clean_json(@structure)
+      cleaned[:about] = target
+      JSON.generate(cleaned,*a)
     end
 
   end

data/lib/ro-bundle/ro/manifest-entry.rb

@@ -0,0 +1,52 @@
+#------------------------------------------------------------------------------
+# Copyright (c) 2014 The University of Manchester, UK.
+#
+# BSD Licenced. See LICENCE.rdoc for details.
+#
+# Author: Robert Haines
+#------------------------------------------------------------------------------
+
+#
+module ROBundle
+
+  # This is the bass class of things which can appear in the manifest:
+  # * Aggregate
+  # * Annotation
+  # * Proxy
+  class ManifestEntry
+    include Provenance
+
+    # :call-seq:
+    #   new
+    #
+    # Create a new ManifestEntry with an empty structure and the +edited+ flag
+    # set to false.
+    def initialize
+      @structure = {}
+      @edited = false
+    end
+
+    # :call-seq:
+    #   edited? -> true or false
+    #
+    # Has this ManifestEntry been edited?
+    def edited?
+      @edited
+    end
+
+    # :stopdoc:
+    # For internal use only!
+    def stored
+      @edited = false
+    end
+    # :startdoc:
+
+    private
+
+    def structure
+      @structure
+    end
+
+  end
+
+end

data/lib/ro-bundle/ro/manifest.rb

@@ -24,9 +24,19 @@ module ROBundle
     def initialize
       super(FILE_NAME, :required => true)
 
+      @structure = nil
+      @initialized = false
       @edited = false
     end
 
+    # :call-seq:
+    #   initialized? -> true or false
+    #
+    # Has this manifest been initialized?
+    def initialized?
+      @initialized
+    end
+
     # :call-seq:
     #   context -> List of context URIs
     #
@@ -93,7 +103,7 @@ module ROBundle
     #
     # Return a list of all the aggregated resources in this Research Object.
     def aggregates
-      structure[:aggregates].dup
+      structure[:aggregates]
     end
 
     # :call-seq:
@@ -134,12 +144,9 @@ module ROBundle
 
       if object.is_a?(Aggregate)
         removed = structure[:aggregates].delete(object)
-
-        unless removed.nil?
-          removed = removed.file.nil? ? removed.uri : removed.file
-        end
+        removed = removed.uri unless removed.nil?
       else
-        removed = remove_aggregate_by_file_or_uri(object)
+        removed = remove_aggregate_by_uri(object)
       end
 
       unless removed.nil?
@@ -165,7 +172,7 @@ module ROBundle
         # If the supplied Annotation object is already registered then it is
         # the annotation itself we are annotating!
         if container.annotation?(object)
-          object = Annotation.new(object.annotation_id, content)
+          object = Annotation.new(object.uri, content)
         end
       else
         object = Annotation.new(object, content)
@@ -200,7 +207,7 @@ module ROBundle
       end
 
       removed.each do |ann|
-        id = ann.annotation_id
+        id = ann.uri
         remove_annotation(id) unless id.nil?
       end
 
@@ -212,7 +219,7 @@ module ROBundle
     #
     # Return a list of all the annotations in this Research Object.
     def annotations
-      structure[:annotations].dup
+      structure[:annotations]
     end
 
     # :call-seq:
@@ -220,7 +227,11 @@ module ROBundle
     #
     # Has this manifest been altered in any way?
     def edited?
-      @edited
+      if @structure.nil?
+        @edited
+      else
+        @edited || edited(aggregates) || edited(annotations)
+      end
     end
 
     # :call-seq:
@@ -229,8 +240,39 @@ module ROBundle
     # Write this Manifest out as a json string. Takes the same options as
     # JSON#generate.
     def to_json(*a)
-      Util.clean_json(structure).to_json(*a)
+      JSON.generate(Util.clean_json(structure),*a)
+    end
+
+    # :call-seq:
+    #   write
+    #
+    # Write this manifest into the RO Bundle, overwriting the old version.
+    def write
+      container.file.open(full_name, "w") do |m|
+        m.puts JSON.pretty_generate(self)
+      end
+
+      stored
+    end
+
+    # :stopdoc:
+    # For internal use only!
+    def init(struct = {})
+      init_default_context(struct)
+      init_default_id(struct)
+      init_provenance_defaults(struct)
+      struct[:history] = [*struct.fetch(:history, [])]
+      struct[:aggregates] = [*struct.fetch(:aggregates, [])].map do |agg|
+        Aggregate.new(agg)
+      end
+      struct[:annotations] = [*struct.fetch(:annotations, [])].map do |ann|
+        Annotation.new(ann)
+      end
+
+      @initialized = true
+      @structure = struct
     end
+    # :startdoc:
 
     protected
 
@@ -250,12 +292,17 @@ module ROBundle
 
     private
 
+    def stored
+      @edited = false
+      (aggregates + annotations).each { |a| a.stored }
+    end
+
     # The internal structure of this class cannot be setup at construction
     # time in the initializer as there is no route to its data on disk at that
     # point. Once loaded, parts of the structure are converted to local
     # objects where appropriate.
     def structure
-      return @structure if @structure
+      return @structure if initialized?
 
       begin
         struct ||= JSON.parse(contents, :symbolize_names => true)
@@ -263,22 +310,7 @@ module ROBundle
         struct = {}
       end
 
-      @structure = init_defaults(struct)
-    end
-
-    def init_defaults(struct)
-      init_default_context(struct)
-      init_default_id(struct)
-      init_provenance_defaults(struct)
-      struct[:history] = [*struct.fetch(:history, [])]
-      struct[:aggregates] = [*struct.fetch(:aggregates, [])].map do |agg|
-        Aggregate.new(agg)
-      end
-      struct[:annotations] = [*struct.fetch(:annotations, [])].map do |ann|
-        Annotation.new(ann)
-      end
-
-      struct
+      init(struct)
     end
 
     def init_default_context(struct)
@@ -303,14 +335,10 @@ module ROBundle
       struct
     end
 
-    def remove_aggregate_by_file_or_uri(object)
-      aggregates.each do |agg|
-        if Util.is_absolute_uri?(object)
-          return structure[:aggregates].delete(agg).uri if object == agg.uri
-        else
-          if object == agg.file || object == agg.file_entry
-            return structure[:aggregates].delete(agg).file
-          end
+    def remove_aggregate_by_uri(object)
+      structure[:aggregates].each do |agg|
+        if object == agg.uri || object == agg.file_entry
+          return structure[:aggregates].delete(agg).uri
         end
       end
 
@@ -321,8 +349,10 @@ module ROBundle
     def remove_annotation_by_field(object)
       removed = []
 
-      annotations.each do |ann|
-        if ann.annotation_id == object ||
+      # Need to dup the list here so we don't break it when deleting things.
+      # We can't use delete_if because we want to know what we've deleted!
+      structure[:annotations].dup.each do |ann|
+        if ann.uri == object ||
           ann.target == object ||
           ann.content == object
 
@@ -333,6 +363,14 @@ module ROBundle
       removed
     end
 
+    def edited(resource)
+      resource.each do |res|
+        return true if res.edited?
+      end
+
+      false
+    end
+
   end
 
 end

data/lib/ro-bundle/ro/provenance.rb

@@ -10,8 +10,7 @@
 module ROBundle
 
   # This module is a mixin for Research Object
-  # {provenance}[http://wf4ever.github.io/ro/bundle/draft/#provenance]
-  # information.
+  # {provenance}[https://w3id.org/bundle/#provenance] information.
   #
   # To use this module simply provide an (optionally private) method named
   # 'structure' which returns the internal fields of the object as a Hash.
@@ -21,16 +20,19 @@ module ROBundle
   # * <tt>:authoredOn</tt>
   # * <tt>:createdBy</tt>
   # * <tt>:createdOn</tt>
+  # * <tt>:retrievedBy</tt>
+  # * <tt>:retrievedFrom</tt>
+  # * <tt>:retrievedOn</tt>
   module Provenance
 
     # :call-seq:
     #   add_author(author) -> Agent
     #
-    # Add an author to the list of authors for this Research Object. The
+    # Add an author to the list of authors for this resource. The
     # supplied parameter can either be an Agent or the name of an author as a
     # String.
     #
-    # The Agent object added to the Research Object is returned.
+    # The Agent object that is added is returned.
     def add_author(author)
       unless author.is_a?(Agent)
         author = Agent.new(author.to_s)
@@ -44,7 +46,7 @@ module ROBundle
     # :call-seq:
     #   authored_by -> Agents
     #
-    # Return the list of Agents that authored this Research Object.
+    # Return the list of Agents that authored this resource.
     def authored_by
       structure.fetch(:authoredBy, []).dup
     end
@@ -52,7 +54,7 @@ module ROBundle
     # :call-seq:
     #   authored_on -> Time
     #
-    # Return the time that this RO Bundle was edited as a Time object, or
+    # Return the time that this resource was edited as a Time object, or
     # +nil+ if not present in the manifest.
     def authored_on
       Util.parse_time(structure[:authoredOn])
@@ -61,7 +63,7 @@ module ROBundle
     # :call-seq:
     #   authored_on = new_time
     #
-    # Set a new authoredOn time for this Manifest. Anything that Ruby can
+    # Set a new authoredOn time for this resource. Anything that Ruby can
     # interpret as a time is accepted and converted to ISO8601 format on
     # serialization.
     def authored_on=(new_time)
@@ -72,7 +74,7 @@ module ROBundle
     # :call-seq:
     #   created_by -> Agent
     #
-    # Return the Agent that created this Research Object.
+    # Return the Agent that created this resource.
     def created_by
       structure[:createdBy]
     end
@@ -80,7 +82,7 @@ module ROBundle
     # :call-seq:
     #   created_by = new_creator
     #
-    # Set the Agent that has created this RO Bundle. Anything passed to this
+    # Set the Agent that has created this resource. Anything passed to this
     # method that is not an Agent will be converted to an Agent before setting
     # the value.
     def created_by=(new_creator)
@@ -95,7 +97,7 @@ module ROBundle
     # :call-seq:
     #   created_on -> Time
     #
-    # Return the time that this RO Bundle was created as a Time object, or
+    # Return the time that this resource was created as a Time object, or
     # +nil+ if not present in the manifest.
     def created_on
       Util.parse_time(structure[:createdOn])
@@ -104,7 +106,7 @@ module ROBundle
     # :call-seq:
     #   created_on = new_time
     #
-    # Set a new createdOn time for this Manifest. Anything that Ruby can
+    # Set a new createdOn time for this resource. Anything that Ruby can
     # interpret as a time is accepted and converted to ISO8601 format on
     # serialization.
     def created_on=(new_time)
@@ -128,6 +130,69 @@ module ROBundle
       end
     end
 
+    # :call-seq:
+    #   retrieved_by -> Agent
+    #
+    # Return the Agent that retrieved this resource.
+    def retrieved_by
+      structure[:retrievedBy]
+    end
+
+    # :call-seq:
+    #   retrieved_by = new_retrievor
+    #
+    # Set the Agent that has retrieved this resource. Anything passed to this
+    # method that is not an Agent will be converted to an Agent before setting
+    # the value.
+    def retrieved_by=(new_retrievor)
+      unless new_retrievor.instance_of?(Agent)
+        new_retrievor = Agent.new(new_retrievor.to_s)
+      end
+
+      @edited = true
+      structure[:retrievedBy] = new_retrievor
+    end
+
+    # :call-seq:
+    #   retrieved_from -> String URI
+    #
+    # Return the URI from which this resource was retrieved.
+    def retrieved_from
+      structure[:retrievedFrom]
+    end
+
+    # :call-seq:
+    #   retrieved_from = uri
+    #
+    # Set the URI from which this resource was retrieved. If a URI object is
+    # given it is converted to a String first.
+    def retrieved_from=(uri)
+      return unless Util.is_absolute_uri?(uri)
+
+      @edited = true
+      structure[:retrievedFrom] = uri.to_s
+    end
+
+    # :call-seq:
+    #   retrieved_on -> Time
+    #
+    # Return the time that this resource was retrieved as a Time object, or
+    # +nil+ if not present in the manifest.
+    def retrieved_on
+      Util.parse_time(structure[:retrievedOn])
+    end
+
+    # :call-seq:
+    #   retrieved_on = new_time
+    #
+    # Set a new retrievedOn time for this resource. Anything that Ruby can
+    # interpret as a time is accepted and converted to ISO8601 format on
+    # serialization.
+    def retrieved_on=(new_time)
+      @edited = true
+      set_time(:retrievedOn, new_time)
+    end
+
     private
 
     def init_provenance_defaults(struct)
@@ -136,6 +201,8 @@ module ROBundle
       struct[:authoredBy] = [*struct.fetch(:authoredBy, [])].map do |agent|
         Agent.new(agent)
       end
+      retrievor = struct[:retrievedBy]
+      struct[:retrievedBy] = Agent.new(retrievor) unless retrievor.nil?
 
       struct
     end