spira 0.0.2 → 0.0.3

data/CHANGES.md

@@ -0,0 +1,25 @@
+# Changelog for Spira <http://github.com/datagraph/spira>
+ 
+## untagged
+ * Bumped promise dependency to 0.1.1 to fix a Ruby 1.9 warning
+ * Rework error handling when a repository is not configured; this should
+   always now raise a Spira::NoRepositoryError regardless of what operation 
+   was attempted, and the error message was improved as well.
+ * A '/' is no longer appended to base URIs ending with a '#'
+ * Resources can now take a BNode as a subject.  Implemented #node?, #uri,
+   #to_uri, #to_node, and #to_subject in support of this; see the yardocs for
+   exact semantics.  RDF::Node is monkey patched with #as, just like RDF::URI,
+   for instantiation.   Old code should not break, but if you want to add
+   BNodes, you may be using #uri where you want to now be using #subject.
+
+## 0.0.2
+ * Implemented #each on resource classes, allowing classes with a defined RDF
+   type to be enumerated
+ * Fragment URIs are now used as strings, allowing i.e. Integers to be used as
+   the final portion of a URI for classes with a base_uri defined.
+ * Added an RDF::URI property type
+ * Implemented #to_rdf and #to_uri for increased compatibility with the RDF.rb 
+   ecosystem
+
+## 0.0.1
+ * Initial release

data/README

@@ -13,6 +13,8 @@ or to create a new store of RDF data based on simple defaults.
 
 An introductory blog post is at <http://blog.datagraph.org/2010/05/spira>
 
+A changelog is available in the {file:CHANGES.md} file.
+
 ### Example
 
     class Person

data/VERSION

@@ -1 +1 @@
-0.0.2
+0.0.3

data/lib/spira.rb

@@ -85,6 +85,17 @@ module Spira
   end
   module_function :repository
 
+  ##
+  # Clear all repositories from Spira's knowledge.  Use it if you want, but
+  # it's really here for testing.
+  #
+  # @return [Void]
+  # @private
+  def clear_repositories!
+    settings[:repositories] = {}
+  end
+  module_function :clear_repositories!
+
   ##
   # Alias a property type to another.  This allows a range of options to be
   # specified for a property type which all reference one Spira::Type
@@ -122,4 +133,20 @@ module RDF
       klass.for(self, *args)
     end
   end
+
+  class Node
+    ##
+    # Create a projection of this Node as the given Spira::Resource class.
+    # Equivalent to `klass.for(self, *args)`
+    #
+    # @example Instantiating a blank node as a Spira Resource
+    #     RDF::Node.new.as(Person)
+    # @param [Class] klass
+    # @param [*Any] args Any arguments to pass to klass.for
+    # @return [Klass] An instance of klass
+    def as(klass, *args)
+      raise ArgumentError, "#{klass} is not a Spira resource" unless klass.is_a?(Class) && klass.ancestors.include?(Spira::Resource)
+      klass.for(self, *args)
+    end
+  end
 end

data/lib/spira/exceptions.rb

@@ -7,5 +7,9 @@ module Spira
 
   ##
   # For cases when a projection fails a validation check
-  class ValidationError < StandardError; end
+  class ValidationError < StandardError ; end
+
+  ##
+  # For cases in which a repository is required but none has been given
+  class NoRepositoryError < StandardError ; end
 end

data/lib/spira/resource/class_methods.rb

@@ -10,19 +10,29 @@ module Spira
    # @see Spira::Resource::DSL
     module ClassMethods
 
+      ##
+      # A symbol name for the repository this class is currently using.
+      attr_reader :repository_name
+
       ##
       # The current repository for this class
       # 
-      # @param  [RDF::Repository] repo The repository
-      # @return [Void]
+      # @return [RDF::Repository, nil]
       # @private
       def repository
-        case @repository_name
-          when nil
-            Spira.repository(:default)
-          else
-            Spira.repository(@repository_name)
-        end
+        name = @repository_name || :default
+        Spira.repository(name)
+      end
+
+      ##
+      # Get the current repository for this class, and raise a
+      # Spira::NoRepositoryError if it is nil.
+      #
+      # @raise  [Spira::NoRepositoryError]
+      # @return [RDF::Repository]
+      # @private
+      def repository_or_fail
+        repository || (raise Spira::NoRepositoryError, "#{self} is configured to use #{@repository_name} as a repository, but it has not been set.")
       end
 
       ##
@@ -57,26 +67,37 @@ module Spira
         if !self.type.nil? && attributes[:type]
           raise TypeError, "#{self} has an RDF type, #{self.type}, and cannot accept one as an argument."
         end
-        uri = uri_for(identifier)
+        uri = id_for(identifier)
         self.new(uri, attributes)
       end
 
       ##
-      # Creates a URI based on a base_uri and string or URI
+      # Creates a URI or RDF::Node based on a potential base_uri and string,
+      # URI, or Node, or Addressable::URI.  If not a URI or Node, the given
+      # identifier should be a string representing an absolute URI, or
+      # something responding to to_s which can be appended to a base URI, which
+      # this class must have.
       #
       # @param  [Any] Identifier
-      # @return [RDF::URI]
-      # @raise  [ArgumentError] If this class cannot create an identifier from the given string
+      # @return [RDF::URI, RDF::Node]
+      # @raise  [ArgumentError] If this class cannot create an identifier from the given argument
       # @see http://rdf.rubyforge.org/RDF/URI.html
-      def uri_for(identifier)
-        case identifier
-          when RDF::URI
+      def id_for(identifier)
+        case 
+          # Catches RDF::URI and implementing subclasses
+          when identifier.respond_to?(:to_uri)
+            identifier.to_uri
+          # Catches RDF::Nodes
+          when identifier.respond_to?(:node?) && identifier.node?
             identifier
+          when identifier.is_a?(Addressable::URI)
+            RDF::URI.new(identifier)
+          # Treat identifier as a string, and create a URI out of it.
           else
             uri = RDF::URI.new(identifier.to_s)
             return uri if uri.absolute?
             raise ArgumentError, "Cannot create identifier for #{self} by String without base_uri; RDF::URI required" if self.base_uri.nil?
-            separator = self.base_uri.to_s[-1,1] == "/" ? '' : '/'
+            separator = self.base_uri.to_s[-1,1] =~ /(\/|#)/ ? '' : '/'
             RDF::URI.new(self.base_uri.to_s + separator + identifier.to_s)
         end
       end

data/lib/spira/resource/dsl.rb

@@ -132,7 +132,7 @@ module Spira
       # Build a Ruby value from an RDF value.
       #
       # @private
-      def build_value(statement, type, existing_relation = nil)
+      def build_value(statement, type)
         case
           when statement == nil
             nil
@@ -146,15 +146,9 @@ module Spira
                 raise TypeError, "#{type} is not a Spira Resource (referenced as #{type} by #{self}"
               end
             end
-            case
-              when false && existing_relation && (existing_relation.uri == statement.object.to_uri)
-                existing_relation
-              else
-                promise { klass.for(statement.object) || 
-                          klass.create(statement.object) }
-            end
+            promise { klass.for(statement.object) }
           else
-            raise TypeError, "Unable to unserialize #{statement.object} for #{type}"
+            raise TypeError, "Unable to unserialize #{statement.object} as #{type}"
         end
       end
 
@@ -165,11 +159,9 @@ module Spira
           when type.is_a?(Class) && type.ancestors.include?(Spira::Type)
             type.serialize(value)
           when value && value.class.ancestors.include?(Spira::Resource)
-            value.uri
-          when type == RDF::URI && value.is_a?(RDF::URI)
-            value
+            value.subject
           else
-            raise TypeError, "Unable to serialize #{value} for #{type}"
+            raise TypeError, "Unable to serialize #{value} as #{type}"
         end
       end
 

data/lib/spira/resource/instance_methods.rb

@@ -17,18 +17,18 @@ module Spira
       # This instance's URI.
       #
       # @return [RDF::URI]
-      attr_reader :uri
+      attr_reader :subject
 
       ## 
       # Initialize a new Spira::Resource instance of this resource class.  This
       # method should not be called directly, use
       # {Spira::Resource::ClassMethods#for} instead.
       #
-      # @param [Any] identifier The URI or URI fragment for this instance
+      # @param [RDF::URI, RDF::Node] identifier The URI or URI fragment for this instance
       # @param [Hash] opts Default attributes for this instance
       # @see Spira::Resource::ClassMethods#for
       def initialize(identifier, opts = {})
-        @uri = self.class.uri_for(identifier)
+        @subject = identifier
         reload(opts)
       end
   
@@ -54,10 +54,7 @@ module Spira
       # @return [Hash] @attributes
       # @private
       def reload_attributes()
-        if self.class.repository.nil?
-          raise RuntimeError, "#{self} is configured to use #{@repository_name} as a repository, but was unable to find it." 
-        end
-        statements = self.class.repository.query(:subject => @uri)
+        statements = self.class.repository_or_fail.query(:subject => @subject)
         @attributes = {}
 
         unless statements.empty?
@@ -70,7 +67,7 @@ module Spira
               # execute the promises to load those classes.  Need an identity
               # map of some sort to fix that.
               values = []
-              collection = statements.query(:subject => @uri, :predicate => property[:predicate])
+              collection = statements.query(:subject => @subject, :predicate => property[:predicate])
               unless collection.nil?
                 collection.each do |statement|
                   values << self.class.build_value(statement,property[:type])
@@ -78,7 +75,7 @@ module Spira
               end
               attribute_set(name, values)
             else
-              statement = statements.query(:subject => @uri, :predicate => property[:predicate]).first
+              statement = statements.query(:subject => @subject, :predicate => property[:predicate]).first
               attribute_set(name, self.class.build_value(statement, property[:type]))
             end
           end
@@ -105,8 +102,8 @@ module Spira
       # @private
       def _destroy_attributes(attributes, opts = {})
         repository = repository_for_attributes(attributes)
-        repository.insert([@uri, RDF.type, self.class.type]) if (self.class.type && opts[:destroy_type])
-        self.class.repository.delete(*repository)
+        repository.insert([@subject, RDF.type, self.class.type]) if (self.class.type && opts[:destroy_type])
+        self.class.repository_or_fail.delete(*repository)
       end
  
       ##
@@ -126,7 +123,7 @@ module Spira
       #
       # @return [true, false] Whether or not the destroy was successful
       def destroy_resource!
-        self.class.repository.delete([@uri,nil,nil])
+        self.class.repository_or_fail.delete([@subject,nil,nil])
       end
 
       ##
@@ -134,9 +131,6 @@ module Spira
       #
       # @return [true, false] Whether or not the save was successful
       def save!
-        if self.class.repository.nil?
-          raise RuntimeError, "#{self} is configured to use #{@repository_name} as a repository, but was unable to find it." 
-        end
         unless self.class.validators.empty?
           errors.clear
           self.class.validators.each do | validator | self.send(validator) end
@@ -156,7 +150,7 @@ module Spira
       # @private
       def _update!
         _destroy_attributes(@original_attributes)
-        self.class.repository.insert(*self)
+        self.class.repository_or_fail.insert(*self)
         @original_attributes = @attributes.dup
       end
  
@@ -185,20 +179,12 @@ module Spira
         self
       end
       
-      ##
-      # Returns the URI representation of this resource.
-      #
-      # @return [RDF::URI]
-      def to_uri
-        uri
-      end
-
       ##
       # A developer-friendly view of this projection
       #
       # @private
       def inspect
-        "<#{self.class}:#{self.object_id} uri: #{@uri}>"
+        "<#{self.class}:#{self.object_id} uri: #{@subject}>"
       end
  
       ##
@@ -211,13 +197,12 @@ module Spira
       def each(*args, &block)
         return RDF::Enumerator.new(self, :each) unless block_given?
         repository = repository_for_attributes(@attributes)
-        repository.insert(RDF::Statement.new(@uri, RDF.type, type)) unless type.nil?
+        repository.insert(RDF::Statement.new(@subject, RDF.type, type)) unless type.nil?
         repository.each(*args, &block)
       end
 
       ##
-      # Safely set a given attribute.  Currently not needed and marked as
-      # private.
+      # Sets the given attribute to the given value.
       #
       # @private
       def attribute_set(name, value)
@@ -225,7 +210,7 @@ module Spira
       end
 
       ##
-      # Safely get a given attribute. 
+      # Get the current value for the given attribute
       #
       # @private
       def attribute_get(name)
@@ -251,12 +236,12 @@ module Spira
             new = []
             attribute.each do |value|
               value = self.class.build_rdf_value(value, self.class.properties[name][:type])
-              new << RDF::Statement.new(@uri, self.class.properties[name][:predicate], value)
+              new << RDF::Statement.new(@subject, self.class.properties[name][:predicate], value)
             end
             repo.insert(*new)
           else
             value = self.class.build_rdf_value(attribute, self.class.properties[name][:type])
-            repo.insert(RDF::Statement.new(@uri, self.class.properties[name][:predicate], value))
+            repo.insert(RDF::Statement.new(@subject, self.class.properties[name][:predicate], value))
           end
         end
         repo
@@ -273,7 +258,7 @@ module Spira
           # TODO: define behavior for equality on subclasses.
           # TODO: should we compare attributes here?
           when self.class
-            @uri == other.uri 
+            @subject == other.uri 
           when RDF::Enumerable
             self.isomorphic_with?(other)
           else
@@ -281,6 +266,60 @@ module Spira
         end
       end
 
+      ##
+      # Returns true for :to_uri if this instance's subject is a URI, and false if it is not.
+      # Returns true for :to_node if this instance's subject is a Node, and false if it is not.
+      # Calls super otherwise.
+      #
+      # @private
+      def respond_to?(*args)
+        case args[0]
+          when :to_uri
+            @subject.respond_to?(:to_uri)
+          when :to_node
+            @subject.node?
+          else
+            super(*args)
+        end
+      end
+
+      ##
+      # Returns the RDF::URI associated with this instance if this instance's
+      # subject is an RDF::URI, and nil otherwise.
+      #
+      # @return [RDF::URI,nil]
+      def uri
+        @subject.respond_to?(:to_uri) ? @subject : nil
+      end
+
+      ##
+      # Returns the URI representation of this resource, if available.  If this
+      # resource's subject is a BNode, raises a NoMethodError.
+      #
+      # @return [RDF::URI]
+      # @raise [NoMethodError]
+      def to_uri
+        uri || (raise NoMethodError, "No such method: :to_uri (this instance's subject is not a URI")
+      end
+
+      ##
+      # Returns true if the subject associated with this instance is a blank node.
+      #
+      # @return [true, false]
+      def node?
+        @subject.node?
+      end
+
+      ##
+      # Returns the Node subject of this resource, if available.  If this
+      # resource's subject is a URI, raises a NoMethodError.
+      #
+      # @return [RDF::Node]
+      # @raise [NoMethodError]
+      def to_node
+        @subject.node? ? @subject : (raise NoMethodError, "No such method: :to_uri (this instance's subject is not a URI")
+      end
+
       ##
       # The validation errors collection associated with this instance.
       #

data/lib/spira/version.rb

@@ -2,7 +2,7 @@ module Spira
   module VERSION
     MAJOR = 0
     MINOR = 0
-    TINY  = 2
+    TINY  = 3
     EXTRA = nil
 
     STRING = [MAJOR, MINOR, TINY].join('.')

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 2
-  version: 0.0.2
+  - 3
+  version: 0.0.3
 platform: ruby
 authors: 
 - Ben Lavender
@@ -15,7 +15,7 @@ bindir:
 - bin
 cert_chain: []
 
-date: 2010-06-04 00:00:00 +02:00
+date: 2010-06-07 00:00:00 +02:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -28,8 +28,8 @@ dependencies:
         segments: 
         - 0
         - 1
-        - 0
-        version: 0.1.0
+        - 10
+        version: 0.1.10
   type: :development
   version_requirements: *id001
 - !ruby/object:Gem::Dependency 
@@ -70,8 +70,8 @@ dependencies:
         segments: 
         - 0
         - 1
-        - 0
-        version: 0.1.0
+        - 10
+        version: 0.1.10
   type: :runtime
   version_requirements: *id004
 - !ruby/object:Gem::Dependency 
@@ -98,8 +98,8 @@ dependencies:
         segments: 
         - 0
         - 1
-        - 0
-        version: 0.1.0
+        - 1
+        version: 0.1.1
   type: :runtime
   version_requirements: *id006
 description: Spira is a framework for using the information in RDF.rb repositories as model objects.
@@ -111,6 +111,7 @@ extensions: []
 extra_rdoc_files: []
 
 files: 
+- CHANGES.md
 - AUTHORS
 - README
 - UNLICENSE