active-triples 0.11.0 → 1.0.0.rc1

data/lib/active_triples/rdf_source.rb

@@ -2,6 +2,7 @@
 require 'active_model'
 require 'active_support/core_ext/hash'
 require 'active_support/core_ext/array/wrap'
+require 'set'
 
 module ActiveTriples
   ##
@@ -75,7 +76,26 @@ module ActiveTriples
       define_model_callbacks :persist
     end
 
+    ##
+    # @!method count
+    #   @return (see RDF::Graph#count)
+    # @!method each
+    #   @return (see RDF::Graph#each)
+    # @!method load!
+    #   @return (see RDF::Graph#load!)
+    # @!method has_statement?
+    #   @return (see RDF::Graph#has_statement?)
+    # @!method query
+    #   @return (see RDF::Graph#query)
     delegate :query, :each, :load!, :count, :has_statement?, to: :graph
+
+    ##
+    # @!method to_base
+    #   @return (see RDF::Term#to_base)
+    # @!method term?
+    #   @return (see RDF::Term#term?)
+    # @!method escape
+    #   @return (see RDF::Term#escape)
     delegate :to_base, :term?, :escape, to: :to_term
 
     ##
@@ -90,6 +110,8 @@ module ActiveTriples
     # @see RDF::Graph
     # @todo move this logic out to a Builder?
     def initialize(*args, &block)
+      @observers   = Set.new
+
       resource_uri = args.shift unless args.first.is_a?(Hash)
       @rdf_subject = get_uri(resource_uri) if resource_uri
 
@@ -189,6 +211,16 @@ module ActiveTriples
       end
     end
 
+    ##
+    # @return [Array<RDF::URI>] a group of properties to use for default labels.
+    def default_labels
+      [RDF::Vocab::SKOS.prefLabel,
+       RDF::Vocab::DC.title,
+       RDF::RDFS.label,
+       RDF::Vocab::SKOS.altLabel,
+       RDF::Vocab::SKOS.hiddenLabel]
+    end
+
     ##
     # @return [Hash]
     def serializable_hash(*)
@@ -287,6 +319,14 @@ module ActiveTriples
       node? ? rdf_subject.id : rdf_subject.to_s
     end
 
+    ##
+    # @return [String]
+    #
+    # @note Without a custom #inspect, we inherit from RDF::Value.
+    def inspect
+      sprintf("#<%s:%#0x ID:%s>", self.class.to_s, self.object_id, self.to_base)
+    end
+
     ##
     # @return [Boolean] true if the Term is a node
     #
@@ -493,7 +533,7 @@ module ActiveTriples
     end
 
     ##
-    # @deprecated for removal in 1.0; use `#get_values` instead.
+    # @deprecated for removal in 1.0; use `#get_values` insctead.
     # @see #get_values
     def get_relation(args)
       warn 'DEPRECATION: `ActiveTriples::RDFSource#get_relation` will be' \
@@ -543,18 +583,55 @@ module ActiveTriples
       @marked_for_destruction
     end
 
-    private
+    ##
+    # @param observer [#notify]
+    #
+    # @retern [#notify] the added observer
+    def add_observer(observer)
+      @observers.add(observer)
+    end
 
     ##
-    # @return [Array<RDF::URI>] a group of properties to use for default labels.
-    def default_labels
-      [RDF::Vocab::SKOS.prefLabel,
-       RDF::Vocab::DC.title,
-       RDF::RDFS.label,
-       RDF::Vocab::SKOS.altLabel,
-       RDF::Vocab::SKOS.hiddenLabel]
+    # @param observer [#notify] an observer to delete
+    #
+    # @return [#notify, nil] the deleted observer; nil if the observer was not
+    #   registered
+    def delete_observer(observer)
+      @observers.delete?(observer)
     end
 
+    ##
+    # Sends `#notify` messages with the property symbol and the current values
+    # for the property to each observer.
+    #
+    # @note We short circuit to avoid query costs if no observers are present.
+    #   If there are regisetred observers, values are returned as an array.
+    #   This means that we incur query costs immediately and only once.
+    #
+    # @example Setting up observers
+    #    class MyObserver
+    #      def notify(property, values)
+    #        # do something
+    #      end
+    #    end
+    #
+    #    observer = MyObserver.new
+    #    my_source.add_observer(observer)
+    #
+    #    my_source.creator = 'Moomin'
+    #    # the observer recieves a #notify(:creator, ['Moomin']) message here.
+    #
+    # @param property [Symbol]
+    #
+    # @return [void]
+    def notify_observers(property)
+      return if @observers.empty?
+      values = get_values(property).to_a
+      @observers.each { |o| o.notify(property, values) }
+    end
+
+    private
+
     ##
     # Rewrites the subject and object of each statement containing
     # `old_subject` in either position. Used when setting the subject to

data/lib/active_triples/relation.rb

@@ -4,19 +4,17 @@ require 'active_support/core_ext/module/delegation'
 module ActiveTriples
   ##
   # A `Relation` represents the values of a specific property/predicate on an
-  # {RDFSource}. Each relation is a set ({Array}) of {RDF::Terms} that are
-  # objects in the of source's triples of the form:
+  # `RDFSource`. Each relation is a set (`Enumerable` of the `RDF::Term`s that 
+  # are objects in the of source's triples of the form:
   #
-  #   <{#parent}> <{#predicate}> [term] .
+  #     <{#parent}> <{#predicate}> [term] .
   #
-  # Relations express a set of binary relationships (on a predicate) between
-  # the parent node and a term.
-  #
-  # When the term is a URI or Blank Node, it is represented in the results
-  # {Array} as an {RDFSource} with a graph selected as a subgraph of the
-  # parent's. The triples in this subgraph are: (a) those whose subject is the
-  # term; (b) ...
+  # Relations express a binary relationships (over a predicate) between the 
+  # parent node and a set of terms.
   #
+  # When the term is a URI or Blank Node, it is represented in the results as an
+  # `RDFSource`. Literal values are cast to strings, Ruby native types, or 
+  # remain as an `RDF::Literal` as documented in `#each`.
   #
   # @see RDF::Term
   class Relation
@@ -29,12 +27,12 @@ module ActiveTriples
     #   @return [RDFSource] the resource that is the domain of this relation
     # @!attribute [rw] value_arguments
     #   @return [Array<Object>]
-    # @!attribute [rw] rel_args
+    # @!attribute [r] rel_args
     #   @return [Hash]
     # @!attribute [r] reflections
     #   @return [Class]
-    attr_accessor :parent, :value_arguments, :rel_args
-    attr_reader :reflections
+    attr_accessor :parent, :value_arguments
+    attr_reader :reflections, :rel_args
 
     delegate :[], :inspect, :last, :size, :join, to: :to_a
 
@@ -45,11 +43,11 @@ module ActiveTriples
     def initialize(parent_source, value_arguments)
       self.parent = parent_source
       @reflections = parent_source.reflections
-      self.rel_args ||= {}
-      self.rel_args = value_arguments.pop if
+      @rel_args ||= {}
+      @rel_args = value_arguments.pop if
         value_arguments.is_a?(Array) && value_arguments.last.is_a?(Hash)
 
-      self.value_arguments = value_arguments
+      @value_arguments = value_arguments
     end
 
     ##
@@ -105,6 +103,7 @@ module ActiveTriples
     def <=>(other)
       return nil unless other.respond_to?(:each)
 
+      # If we're empty, avoid calling `#to_a` on other.
       if empty?
         return 0 if other.each.first.nil?
         return nil
@@ -113,20 +112,24 @@ module ActiveTriples
       # We'll need to traverse `other` repeatedly, so we get a stable `Array`
       # representation. This avoids any repeated query cost if `other` is a
       # `Relation`.
-      length = 0
-      other  = other.to_a
-      this   = each
+      length       = 0
+      other        = other.to_a
+      other_length = other.length
+      this         = each
 
       loop do
         begin
-          cur = this.next
+          current = this.next
         rescue StopIteration
-          return other.length == length ? 0 : nil
+          # If we die, we are equal to other so far, check length and walk away.
+          return other_length == length ? 0 : nil
         end
 
         length += 1
-
-        return nil if other.length < length || !other.include?(cur)
+        
+        # Return as not comparable if we have seen more terms than are in other,
+        # or if other does not include the current term.
+        return nil if other_length < length || !other.include?(current)
       end
     end
 
@@ -207,7 +210,9 @@ module ActiveTriples
     #
     # @return [Relation] self; a now empty relation
     def clear
+      return self if empty?
       parent.delete([rdf_subject, predicate, nil])
+      parent.notify_observers(property)
 
       self
     end
@@ -242,8 +247,11 @@ module ActiveTriples
     # @return [ActiveTriples::Relation] self
     def delete(value)
       value = RDF::Literal(value) if value.is_a? Symbol
-      parent.delete([rdf_subject, predicate, value])
 
+      return self if parent.query([rdf_subject, predicate, value]).nil?
+
+      parent.delete([rdf_subject, predicate, value])
+      parent.notify_observers(property)
       self
     end
 
@@ -367,20 +375,20 @@ module ActiveTriples
     end
 
     ##
-    # Adds values to the relation
+    # Set the values of the Relation
     #
     # @param [Array<RDF::Resource>, RDF::Resource] values  an array of values
-    #   or a single value. If not an {RDF::Resource}, the values will be
-    #   coerced to an {RDF::Literal} or {RDF::Node} by {RDF::Statement}
+    #   or a single value. If not an `RDF::Resource`, the values will be
+    #   coerced to an `RDF::Literal` or `RDF::Node` by `RDF::Statement`
     #
     # @return [Relation] a relation containing the set values; i.e. `self`
     #
     # @raise [ActiveTriples::UndefinedPropertyError] if the property is not
-    #   already an {RDF::Term} and is not defined in `#property_config`
+    #   already an `RDF::Term` and is not defined in `#property_config`
     #
     # @see http://www.rubydoc.info/github/ruby-rdf/rdf/RDF/Statement For
-    #   documentation on {RDF::Statement} and the handling of
-    #   non-{RDF::Resource} values.
+    #   documentation on `RDF::Statement` and the handling of
+    #   non-`RDF::Resource` values.
     def set(values)
       raise UndefinedPropertyError.new(property, reflections) if predicate.nil?
 
@@ -389,8 +397,11 @@ module ActiveTriples
 
       clear
       values.each { |val| set_value(val) }
+      parent.notify_observers(property)
+      
+      parent.persist! if parent.persistence_strategy.respond_to?(:ancestors) &&
+                         parent.persistence_strategy.ancestors.any? { |r| r.is_a?(ActiveTriples::List::ListResource) }
 
-      parent.persist! if parent.persistence_strategy.is_a? ParentStrategy
       self
     end
 
@@ -406,6 +417,9 @@ module ActiveTriples
     #
     # @note This casts symbols to a literals, which gets us symmetric behavior
     #   with `#set(:sym)`.
+    #
+    # @note This method treats all calls as changes for the purpose of observer
+    #   notifications
     # @see #delete
     def subtract(*values)
       values = values.first if values.first.is_a? Enumerable
@@ -415,6 +429,7 @@ module ActiveTriples
       end
 
       parent.delete(*statements)
+      parent.notify_observers(property)
       self
     end
 
@@ -451,7 +466,7 @@ module ActiveTriples
             value
           end
         when RDF::Resource
-          make_node(value)
+          cast? ? make_node(value) : value
         else
           value
         end
@@ -538,7 +553,6 @@ module ActiveTriples
                 parent.persistence_strategy.ancestors.find { |a| a == new_resource })
           new_resource.set_persistence_strategy(ParentStrategy)
           new_resource.parent = parent
-          new_resource.persist!
         end
 
         self.node_cache[resource.rdf_subject] = (resource == object ? new_resource : object)
@@ -561,22 +575,27 @@ module ActiveTriples
       #
       # @private
       def make_node(value)
-        return value unless cast?
         klass = class_for_value(value)
         value = RDF::Node.new if value.nil?
-        node = node_cache[value] if node_cache[value]
-        node ||= klass.from_uri(value,parent)
-        node.set_persistence_strategy(property_config[:persist_to]) if
-          is_property? && property_config[:persist_to]
-        return nil if (is_property? && property_config[:class_name]) && (class_for_value(value) != class_for_property)
+
+        return node_cache[value] if node_cache[value]
+
+        node = klass.from_uri(value, parent)
+
+        if is_property? && property_config[:persist_to]
+          node.set_persistence_strategy(property_config[:persist_to])
+
+          node.persistence_strategy.parent = parent if
+            node.persistence_strategy.is_a?(ParentStrategy)
+        end
+
         self.node_cache[value] ||= node
-        node
       end
 
       ##
       # @private
       def cast?
-        return true unless is_property? || (rel_args && rel_args[:cast])
+        return true unless is_property? || rel_args[:cast]
         return rel_args[:cast] if rel_args.has_key?(:cast)
         !!property_config[:cast]
       end
@@ -605,7 +624,7 @@ module ActiveTriples
       def uri_class(v)
         v = RDF::URI.intern(v) if v.kind_of? String
         type_uri = parent.query([v, RDF.type, nil]).to_a.first.try(:object)
-        Resource.type_registry[type_uri]
+        RDFSource.type_registry[type_uri]
       end
 
       ##

data/lib/active_triples/schema.rb

@@ -3,16 +3,35 @@ module ActiveTriples
   ##
   # Super class which provides a simple property DSL for defining property ->
   # predicate mappings.
+  # 
+  # @example defining and applying a custom schema
+  #   class MySchema < ActiveTriples::Schema
+  #     property :title,   predicate: RDF::Vocab::DC.title
+  #     property :creator, predicate: RDF::Vocab::DC.creator, other: :options
+  #   end
+  #
+  #   resource = Class.new { include ActiveTriples::RDFSource }
+  #   resource.apply_schema(MySchema)
+  #
   class Schema
     class << self
+      ##
+      # Define a property.
+      #
       # @param [Symbol] property The property name on the object.
       # @param [Hash] options Options for the property.
+      # @option options [Boolean] :cast
+      # @option options [String, Class] :class_name 
       # @option options [RDF::URI] :predicate The predicate to map the property
       #   to.
+      #
+      # @see ActiveTriples::Property for more about options
       def property(property, options)
         properties << Property.new(options.merge(:name => property))
       end
-
+      
+      ##
+      # @return [Array<ActiveTriples::Property>]
       def properties
         @properties ||= []
       end

data/lib/active_triples/version.rb

@@ -1,4 +1,4 @@
 # frozen_string_literal: true
 module ActiveTriples
-  VERSION = '0.11.0'.freeze
+  VERSION = '1.0.0.rc1'.freeze
 end

data/spec/active_triples/extension_strategy_spec.rb

@@ -14,14 +14,25 @@ RSpec.describe ActiveTriples::ExtensionStrategy do
       expect(asset).to have_received(:property).with(property.name, property.to_h)
     end
 
+    it 'execute the block' do
+      block = Proc.new {}
+      asset = build_asset
+      property = build_property("name", {:predicate => RDF::Vocab::DC.title}, &block)
+
+      subject.apply(asset, property)
+
+      expect(asset).to have_received(:property).with(property.name, property.to_h, &block)
+    end
+
     def build_asset
       object_double(ActiveTriples::Resource, :property => nil)
     end
 
-    def build_property(name, options)
+    def build_property(name, options, &block)
       property = object_double(ActiveTriples::Property.new(:name => nil))
       allow(property).to receive(:name).and_return(name)
       allow(property).to receive(:to_h).and_return(options)
+      allow(property).to receive(:config).and_return(block)
       property
     end
   end