spira 0.0.1.pre → 0.0.1

data/lib/spira/resource/instance_methods.rb

@@ -2,128 +2,216 @@ require 'rdf/isomorphic'
 
 module Spira
   module Resource
+
+    ##
+    # This module contains instance methods for Spira resources.  See
+    # {Spira::Resource} for more information.
+    #
+    # @see Spira::Resource
+    # @see Spira::Resource::ClassMethods
+    # @see Spira::Resource::DSL
+    # @see Spira::Resource::Validations
     module InstanceMethods 
-  
+ 
+      ##
+      # This instance's URI.
+      #
+      # @return [RDF::URI]
       attr_reader :uri
 
-      # Initialize a new instance of a spira resource.
-      # The new instance can be instantiated with an opts[:statements] or opts[:attributes], but not both.
+      ## 
+      # 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 [Hash] opts Default attributes for this instance
+      # @see Spira::Resource::ClassMethods#for
       def initialize(identifier, opts = {})
-       
-        @attributes = {}
-
-        if identifier.is_a? RDF::URI
-          @uri = identifier
-        else
-          if (self.class.base_uri)
-            separator = self.class.base_uri.to_s[-1,1] == "/" ? '' : '/'
-            @uri = RDF::URI.parse(self.class.base_uri.to_s + separator + identifier)
-          else
-            raise ArgumentError, "#{self.class} has no base URI configured, and can thus only be created using RDF::URIs (got #{identifier.inspect})"
-          end
+        @uri = self.class.uri_for(identifier)
+        reload(opts)
+      end
+  
+      ##
+      # Reload all attributes for this instance, overwriting or setting
+      # defaults with the given opts.  This resource will block if the
+      # underlying repository blocks the next time it accesses attributes.
+      #
+      # @param   [Hash{Symbol => Any}] opts
+      # @option opts [Symbol] :any A property name.  Sets the given property to the given value.
+      def reload(opts = {})
+        @attributes = promise { reload_attributes }
+        @original_attributes = promise { @attributes.force ; @original_attributes }
+        self.class.properties.each do |name, predicate|
+          attribute_set(name, opts[name]) unless opts[name].nil?
         end
+      end
 
-        #@repo = RDF::Repository.new
-        #@repo.insert(*(opts[:statements])) unless opts[:statements].nil?
-        #@repo.insert(*[RDF::Statement.new(@uri, RDF.type, opts[:type])]) if opts[:type]
+      ##
+      # Load this instance's attributes.  Overwrite loaded values with attributes in the given options.
+      #
+      # @param [Hash] opts
+      # @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)
+        @attributes = {}
 
-        #  If we got statements, we are being loaded, not created
-        if opts[:statements]
+        unless statements.empty?
           # Set attributes for each statement corresponding to a predicate
           self.class.properties.each do |name, property|
             if self.class.is_list?(name)
+              # FIXME: This should not be an Array, but a Set.  However, a set
+              # must compare its values to see if they already exist.  This
+              # means any referenced relations will check their attributes and
+              # execute the promises to load those classes.  Need an identity
+              # map of some sort to fix that.
               values = []
-              statements = opts[:statements].query(:subject => @uri, :predicate => property[:predicate])
-              unless statements.nil?
-                statements.each do |statement|
+              collection = statements.query(:subject => @uri, :predicate => property[:predicate])
+              unless collection.nil?
+                collection.each do |statement|
                   values << self.class.build_value(statement,property[:type])
                 end
               end
               attribute_set(name, values)
             else
-              statement = opts[:statements].query(:subject => @uri, :predicate => property[:predicate]).first
+              statement = statements.query(:subject => @uri, :predicate => property[:predicate]).first
               attribute_set(name, self.class.build_value(statement, property[:type]))
             end
           end
-        else
-          self.class.properties.each do |name, predicate|
-            attribute_set(name, opts[name]) unless opts[name].nil?
-          end
-
         end
 
-
-        #@repo = RDF::Repository.new
-        #@repo.insert(*(opts[:statements])) unless opts[:statements].nil?
-        #@repo.insert(*[RDF::Statement.new(@uri, RDF.type, opts[:type])]) if opts[:type]
-  
-        #self.class.properties.each do |name, predicate|
-        #  send(((name.to_s)+"=").to_sym, opts[name]) unless opts[name].nil?
-        #end
+        # We need to load and save the original attributes so we can remove
+        # them from the repository on save, since RDF will happily let us add
+        # as many triples for a subject and predicate as we want.
+        @original_attributes = {}
         @original_attributes = @attributes.dup
         @original_attributes.each do | name, value |
           @original_attributes[name] = value.dup if value.is_a?(Array)
         end
+
+        @attributes
       end
-    
-      def _destroy_attributes(attributes)
+
+      ##
+      # Remove the given attributes from the repository
+      #
+      # @param [Hash] attributes The hash of attributes to delete
+      # @param [Hash{Symbol => Any}] opts Options for deletion
+      # @option opts [true] :destroy_type Destroys the `RDF.type` statement associated with this class as well
+      # @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)
       end
-  
+ 
+      ##
+      # Remove this instance from the repository.  Will not delete statements
+      # not associated with this model.
+      #
+      # @return [true, false] Whether or not the destroy was successful
       def destroy!
-        _destroy_attributes(@attributes)
+        _destroy_attributes(@attributes, :destroy_type => true)
+        reload
+      end
+
+      ##
+      # Remove all statements associated with this instance from the
+      # repository. This will delete statements unassociated with the current
+      # projection.
+      #
+      # @return [true, false] Whether or not the destroy was successful
+      def destroy_resource!
+        self.class.repository.delete([@uri,nil,nil])
       end
 
+      ##
+      # Save changes in this instance to the repository.
+      #
+      # @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
-        if respond_to?(:validate)
+        unless self.class.validators.empty?
           errors.clear
-          validate
+          self.class.validators.each do | validator | self.send(validator) end
           if errors.empty?
             _update!
           else
-            raise(ValidationError, "Could not save #{self.inspect} due to validation errors: " + errors.join(';'))
+            raise(ValidationError, "Could not save #{self.inspect} due to validation errors: " + errors.each.join(';'))
           end
         else
           _update!
         end
       end
 
+      ##
+      # Save changes to the repository
+      #
+      # @private
       def _update!
         _destroy_attributes(@original_attributes)
         self.class.repository.insert(*self)
         @original_attributes = @attributes.dup
       end
-  
+ 
+      ## 
+      # The `RDF.type` associated with this class.
+      #
+      # @return [nil,RDF::URI] The RDF type associated with this instance's class.
       def type
         self.class.type
       end
-  
+ 
+      ##
+      # `type` is a special property which is associated with the class and not
+      # the instance.  Always raises a TypeError to try and assign it.  
+      #
+      # @raise [TypeError] always
       def type=(type)
         raise TypeError, "Cannot reassign RDF.type for #{self}; consider appending to a has_many :types"
       end
-  
+ 
+      ##
+      # A developer-friendly view of this projection
+      #
+      # @private
       def inspect
         "<#{self.class}:#{self.object_id} uri: #{@uri}>"
       end
-  
+ 
+      ##
+      # Enumerate each RDF statement that makes up this projection.  This makes
+      # each instance an `RDF::Enumerable`, with all of the nifty benefits
+      # thereof.  See <http://rdf.rubyforge.org/RDF/Enumerable.html> for
+      # information on arguments.
+      #
+      # @see http://rdf.rubyforge.org/RDF/Enumerable.html
       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?
-        if block_given?
-          repository.each(*args, &block)
-        else
-          ::Enumerable::Enumerator.new(self, :each)
-        end
+        repository.each(*args, &block)
       end
 
+      ##
+      # Safely set a given attribute.  Currently not needed and marked as
+      # private.
+      #
+      # @private
       def attribute_set(name, value)
         @attributes[name] = value
       end
 
+      ##
+      # Safely get a given attribute. 
+      #
+      # @private
       def attribute_get(name)
         case self.class.is_list?(name)
           when true
@@ -133,12 +221,17 @@ module Spira
         end
       end
 
+      ##
+      # Create an RDF::Repository for the given attributes hash.  This could
+      # just as well be a class method but is only used here in #save! and
+      # #destroy!, so it is defined here for simplicity.  
+      #
+      # @param [Hash] attributes The attributes to create a repository for
+      # @private
       def repository_for_attributes(attributes)
         repo = RDF::Repository.new
         attributes.each do | name, attribute |
           if self.class.is_list?(name)
-            #old = @repo.query(:subject => @uri, :predicate => predicate)
-            #@repo.delete(*old.to_a) unless old.empty?
             new = []
             attribute.each do |value|
               value = self.class.build_rdf_value(value, self.class.properties[name][:type])
@@ -153,9 +246,15 @@ module Spira
         repo
       end
 
+      ##
+      # Compare this instance with another instance.  The comparison is done on
+      # an RDF level, and will work across subclasses as long as the attributes
+      # are the same.
+      # 
+      # @see http://rdf.rubyforge.org/isomorphic/
       def ==(other)
         case other
-          # TODO: define behavior for equality on subclasses.  also subclasses.
+          # TODO: define behavior for equality on subclasses.
           when self.class
             @uri == other.uri 
           when RDF::Enumerable
@@ -165,9 +264,19 @@ module Spira
         end
       end
 
+      ##
+      # The validation errors collection associated with this instance.
+      #
+      # @return [Spira::Errors]
+      # @see Spira::Errors
+      def errors
+        @errors ||= Spira::Errors.new
+      end
 
+      ## We have defined #each and can do this fun RDF stuff by default
       include ::RDF::Enumerable, ::RDF::Queryable
 
+      ## Include the base validation functions
       include Spira::Resource::Validations
 
     end  

data/lib/spira/resource/validations.rb

@@ -1,21 +1,45 @@
 module Spira
   module Resource
-    module Validations
 
-      def errors
-        @errors ||= []
-      end
+    ##
+    # Instance methods relating to validations for a Spira resource.  This
+    # includes the default assertions.
+    #
+    # @see Spira::Resource::InstanceMethods
+    # @see Spira::Resource::ClassMethods
+    # @see Spira::Resource::DSL
+    module Validations
 
-      def assert(boolean, message)
-        errors.push(message) unless boolean
+      ##
+      # Assert a fact about this instance.  If the given expression is false,
+      # an error will be noted.
+      #
+      # @example Assert that a title is correct
+      #     assert(title == 'xyz', :title, 'bad title')
+      # @param  [Any] boolean The expression to evaluate
+      # @param  [Symbol] property The property or has_many to mark as incorrect on failure
+      # @param  [String] message The message to record if this assertion fails
+      # @return [Void]
+      def assert(boolean, property, message)
+        errors.add(property, message) unless boolean
       end
 
+      ##
+      # A default helper assertion.  Asserts that a given property is set.
+      #
+      # @param  [Symbol] name The property to check
+      # @return [Void]
       def assert_set(name)
-        assert(!(self.send(name).nil?), "#{name.to_s} cannot be nil")
+        assert(!(self.send(name).nil?), name, "#{name.to_s} cannot be nil")
       end
 
+      ##
+      # A default helper assertion.  Asserts that a given property is numeric.
+      #
+      # @param  [Symbol] name The property to check
+      # @return [Void]
       def assert_numeric(name)
-        assert(self.send(name).is_a?(Numeric), "#{name.to_s} must be numeric (was #{self.send(name)})")
+        assert(self.send(name).is_a?(Numeric), name, "#{name.to_s} must be numeric (was #{self.send(name)})")
       end
 
     end

data/lib/spira/type.rb

@@ -0,0 +1,82 @@
+module Spira
+
+  ##
+  # Spira::Type can be included by classes to create new property types for
+  # Spira.  These types are responsible for serialization a Ruby value into an
+  # `RDF::Value`, and deserialization of an `RDF::Value` into a Ruby value.
+  #
+  # A simple example:
+  #
+  #     class Integer
+  #       
+  #       include Spira::Type
+  #       
+  #       def self.unserialize(value)
+  #         value.object
+  #       end
+  #       
+  #       def self.serialize(value)
+  #         RDF::Literal.new(value)
+  #       end
+  #       
+  #       register_alias XSD.integer
+  #     end
+  #
+  # This example will serialize and deserialize integers.  It's included with
+  # Spira by default.  It allows either of the following forms to declare an
+  # integer property on a Spira resource:
+  #
+  #     property :age, :predicate => FOAF.age, :type => Integer
+  #     property :age, :predicate => FOAF.age, :type => XSD.integer
+  #
+  # `Spira::Type`s include the RDF namespace and thus have all of the base RDF
+  # vocabularies available to them without the `RDF::` prefix.
+  #
+  # @see http://rdf.rubyforge.org/RDF/Value.html
+  # @see Spira::Resource
+  module Type
+
+    ##
+    # Make the DSL available to a child class.
+    #
+    # @private
+    def self.included(child)
+      child.extend(ClassMethods)
+      Spira.type_alias(child,child)
+    end
+
+    include RDF
+
+    module ClassMethods
+
+      ##
+      # Register an alias that this type can be referred to as, such as an RDF
+      # URI.  The alias can be any object, symbol, or constant.
+      #
+      # @param [Any] identifier The new alias in property declarations for this class
+      # @return [Void]
+      def register_alias(any)
+        Spira.type_alias(any, self)
+      end
+
+      ##
+      # Serialize a given value to RDF.
+      #
+      # @param [Any] value The Ruby value to be serialized
+      # @return [RDF::Value] The RDF form of this value
+      def serialize(value)
+        value
+      end
+
+      ##
+      # Unserialize a given RDF value to Ruby
+      #
+      # @param [RDF::Value] value The RDF form of this value
+      # @return [Any] The Ruby form of this value
+      def unserialize(value)
+        value
+      end
+    end
+
+  end
+end