spira 0.0.1.pre → 0.0.1

data/lib/spira/resource.rb

@@ -1,4 +1,37 @@
 module Spira
+
+  ##
+  # Spira::Resource is the main interface to Spira.  Classes and modules
+  # include Spira::Resource to create projections of RDF data as a class.  For
+  # an overview, see the {file:README}.
+  #
+  # Projections are a mapping of RDF predicates to fields.
+  #
+  #     class Person
+  #       include Spira::Resource
+  #
+  #       property :name, :predicate => FOAF.name
+  #       property :age, :predicate => FOAF.age, :type => Integer
+  #     end
+  #
+  #     RDF::URI('http://example.org/people/bob').as(Person) #=> <#Person @uri=http://example.org/people/bob>
+  #
+  # Spira resources include the RDF namespace, and can thus reference all of
+  # the default RDF.rb vocabularies without the RDF:: prefix:
+  #
+  #     property :name, :predicate => FOAF.name
+  #
+  # The Spira::Resource documentation is broken into several parts, vaguely
+  # related by functionality:
+  #  * {Spira::Resource::DSL} contains methods used during the declaration of a class or module
+  #  * {Spira::Resource::ClassMethods} contains class methods for use by declared classes
+  #  * {Spira::Resource::InstanceMethods} contains methods for use by instances of Spira resource classes
+  #  * {Spira::Resource::Validations} contains some default validation functions
+  #
+  # @see Spira::Resource::DSL
+  # @see Spira::Resource::ClassMethods
+  # @see Spira::Resource::InstanceMethods
+  # @see Spira::Resource::Validations
   module Resource
  
     autoload :DSL,              'spira/resource/dsl'
@@ -6,20 +39,33 @@ module Spira
     autoload :InstanceMethods,  'spira/resource/instance_methods'
     autoload :Validations,      'spira/resource/validations'
 
+    ##
+    # When a child class includes Spira::Resource, this does the magic to make
+    # it a Spira resource.
+    #
+    # @private
     def self.included(child)
-      child.extend DSL
-      child.extend ClassMethods
-      child.instance_eval do
-        class << self
-          attr_accessor :properties, :lists
+      # Don't do inclusion work twice.  Checking for the properties accessor is
+      # a proxy for a proper check to see if this is a resource already.  Ruby
+      # has already extended the child class' ancestors to include
+      # Spira::Resource by the time we get here.
+      # FIXME: Find a 'more correct' check.
+      unless child.respond_to?(:properties)
+        child.extend DSL
+        child.extend ClassMethods
+        child.instance_eval do
+          class << self
+            attr_accessor :properties, :lists
+          end
+          @properties = {}
+          @lists      = {}
         end
-        @properties = {}
-        @lists      = {}
       end
     end
     
     # This lets including classes reference vocabularies without the RDF:: prefix
     include RDF
+    include Spira::Types
     include InstanceMethods
 
   end

data/lib/spira/resource/class_methods.rb

@@ -1,14 +1,21 @@
 module Spira
  module Resource
 
-   # This module contains all class methods available to a Spira::Resource class
-   #
+   ##
+   # This module contains all class methods available to a declared Spira::Resource class.
+   # {Spira::Resource} contains more information about Spira resources.
    #
+   # @see Spira::Resource
+   # @see Spira::Resource::InstanceMethods
+   # @see Spira::Resource::DSL
     module ClassMethods
-      def repository=(repo)
-        @repository = repo
-      end
 
+      ##
+      # The current repository for this class
+      # 
+      # @param  [RDF::Repository] repo The repository
+      # @return [Void]
+      # @private
       def repository
         case @repository_name
           when nil
@@ -18,68 +25,127 @@ module Spira
         end
       end
 
-      def oldrepo
-        case
-          #when !@repository.nil?
-          #  @repository
-          when !@repository_name.nil?
-            Spira.repository(@repository_name) || raise(RuntimeError, "#{self} is configured to use #{@repository_name} as a repository, but was unable to find it.")
-            #@repository = Spira.repository(@repository_name)
-            #if @repository.nil?
-            #  raise RuntimeError, "#{self} is configured to use #{@repository_name} as a repository, but was unable to find it."
-            #end
-            #@repository
-          else
-            @repository = Spira.repository(:default)
-            if @repository.nil? 
-              raise RuntimeError, "#{self} has no configured repository and was unable to find a default repository."
-            end
-            @repository
+      ##
+      # Create a new projection instance of this class for the given URI.  If a
+      # class has a base_uri given, and the argument is not an `RDF::URI`, the
+      # given identifier will be appended to the base URI.
+      #
+      # Spira does not have 'find' or 'create' functions.  As RDF identifiers
+      # are globally unique, they all simply 'are'.
+      #
+      # On calling `for`, a new instance is created for the given URI.  The
+      # first time access is attempted on a field, the repository will be
+      # queried for existing attributes, which will be used for the given URI.
+      # Underlying repositories are not accessed at the time of calling `for`.
+      # 
+      # A class with a base URI may still be projected for any URI, whether or
+      # not it uses the given resource class' base URI.
+      #
+      # @raise [TypeError] if an RDF type is given in the attributes and one is
+      # given in the attributes.  
+      # @raise [ArgumentError] if a non-URI is given and the class does not
+      # have a base URI.  
+      # @overload for(uri, attributes = {})
+      #   @param [RDF::URI] uri The URI to create an instance for
+      #   @param [Hash{Symbol => Any}] attributes Initial attributes
+      # @overload for(identifier, attributes = {})
+      #   @param [Any] uri The identifier to append to the base URI for this class
+      #   @param [Hash{Symbol => Any}] attributes Initial attributes
+      # @return  [Spira::Resource] The newly created instance
+      # @see http://rdf.rubyforge.org/RDF/URI.html
+      def for(identifier, attributes = {})
+        if !self.type.nil? && attributes[:type]
+          raise TypeError, "#{self} has an RDF type, #{self.type}, and cannot accept one as an argument."
         end
-        #@repository
+        uri = uri_for(identifier)
+        self.new(uri, attributes)
       end
 
-      def find(identifier)
-        if repository.nil?
-          raise RuntimeError, "#{self} is configured to use #{@repository_name} as a repository, but was unable to find it." 
-        end
-        uri = case identifier
+      ##
+      # Creates a URI based on a base_uri and string or URI
+      #
+      # @param  [Any] Identifier
+      # @return [RDF::URI]
+      # @raise  [ArgumentError] If this class cannot create an identifier from the given string
+      # @see http://rdf.rubyforge.org/RDF/URI.html
+      def uri_for(identifier)
+        case identifier
           when RDF::URI
             identifier
           when String
-            raise ArgumentError, "Cannot find #{self} by String without base_uri; RDF::URI required" if self.base_uri.nil?
+            uri = RDF::URI.new(identifier)
+            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] == "/" ? '' : '/'
-            RDF::URI.parse(self.base_uri.to_s + separator + identifier)
+            RDF::URI.new(self.base_uri.to_s + separator + identifier)
           else
-            raise ArgumentError, "Cannot instantiate #{self} from #{identifier}, expected RDF::URI or String"
-        end
-        statements = self.repository.query(:subject => uri)
-        if statements.empty?
-          nil
-        else
-          self.new(identifier, :statements => statements) 
+            raise ArgumentError, "Cannot create an identifier for #{self} from #{identifier}, expected RDF::URI or String"
         end
       end
- 
+
+
+      ##
+      # The number of URIs projectable as a given class in the repository.
+      # This method is only valid for classes which declare a `type` with the
+      # `type` method in the DSL.
+      #
+      # @raise  [TypeError] if the resource class does not have an RDF type declared
+      # @return [Integer] the count
+      # @see Spira::Resource::DSL
       def count
         raise TypeError, "Cannot count a #{self} without a reference type URI." if @type.nil?
         result = repository.query(:predicate => RDF.type, :object => @type)
         result.count
       end
 
-      def create(name, attributes = {})
-        # TODO: validate attributes
-        unless @type.nil?
-          if attributes[:type]
-            raise TypeError, "Cannot assign type to new instance of #{self}; this class is associated with #{@type}"
+      ##
+      # Returns true if the given property is a has_many property, false otherwise
+      #
+      # @return [true, false]
+      def is_list?(property)
+        @lists.has_key?(property)
+      end
+
+      ##
+      # Handling inheritance
+      #
+      # @private
+      def inherited(child)
+        child.instance_eval do
+          include Spira::Resource
+        end
+        # FIXME: This is clearly brittle and ugly.
+        [:@base_uri, :@default_vocabulary, :@repository_name, :@type].each do |variable|
+          value = instance_variable_get(variable).nil? ? nil : instance_variable_get(variable).dup
+          child.instance_variable_set(variable, value)
+        end
+        [:@properties, :@lists, :@validators].each do |variable|
+          if child.instance_variable_get(variable).nil?
+            if instance_variable_get(variable).nil?
+              child.instance_variable_set(variable, nil)
+            else
+              child.instance_variable_set(variable, instance_variable_get(variable).dup)
+            end
+          elsif !(instance_variable_get(variable).nil?)
+            child.instance_variable_set(variable, instance_variable_get(variable).dup.merge(child.instance_variable_get(variable)))
           end
-          attributes[:type] = @type
         end
-        resource = self.new(name, attributes)
       end
 
-      def is_list?(property)
-        @lists.has_key?(property)
+      ## 
+      # Handling module inclusions
+      #
+      # @private
+      def included(child)
+        inherited(child)
+      end
+
+      ## 
+      # The list of validation functions for this projection
+      #
+      # @return [Array<Symbol>]
+      def validators
+        @validators ||= []
       end
 
     end

data/lib/spira/resource/dsl.rb

@@ -1,41 +1,122 @@
 require 'promise'
 
 module Spira
- module Resource
-
-   # This module contains all user-exposed methods for use in building a model class.
-   # It is used to extend classes that include Spira::Resource.
-   # @see a little bit of magic in Spira::Resource#included as well--some
-   # tricks need class_eval before this module is included.
-   # @see Spira::Resource::ClassMethods for class methods available after class
-   # definition 
-   # @see Spira::Resource::InstanceMethods for instance methods available after
-   # class definition
+  module Resource
+
+    ##
+    # This module consists of Spira::Resource class methods which correspond to
+    # the Spira resource class declaration DSL.  See {Spira::Resource} for more
+    # information.
+    #
+    # @see Spira::Resource
+    # @see Spira::Resource::ClassMethods
+    # @see Spira::Resource::InstanceMethods
+    # @see Spira::Resource::Validations
     module DSL  
 
+      ##
+      # The name of the default repository to use for this class.  This
+      # repository will be queried and written to instead of the :default
+      # repository.
+      #
+      # @param  [Symbol] name
+      # @return [Void]
       def default_source(name)
         @repository_name = name
         @repository = Spira.repository(name)
       end
-  
+ 
+      ##
+      # The base URI for this class.  Attempts to create instances for non-URI
+      # objects will be appended to this base URI.
+      #
+      # @param  [String, RDF::URI] base uri
+      # @return [Void]
       def base_uri(uri = nil)
         @base_uri = uri unless uri.nil?
         @base_uri
       end
-      
+     
+      ##
+      # The default vocabulary for this class.  Setting a default vocabulary
+      # will allow properties to be defined without a `:predicate` option.
+      # Predicates will instead be created by appending the property name to
+      # the given string.
+      #
+      # @param  [String, RDF::URI] base uri
+      # @return [Void]
       def default_vocabulary(uri)
         @default_vocabulary = uri
       end
 
+
+      ## 
+      # Add a property to this class.  A property is an accessor field that
+      # represents an RDF predicate.
+      #
+      # @example A simple string property
+      #     property :name, :predicate => FOAF.name, :type => String
+      # @example A property which defaults to {Spira::Types::Any}
+      #     property :name, :predicate => FOAF.name
+      # @example An integer property
+      #     property :age,  :predicate => FOAF.age, :type => Integer
+      # @param  [Symbol] name The name of this property
+      # @param  [Hash{Symbol => Any}] opts property options
+      # @option opts [RDF::URI]            :predicate The RDF predicate which will refer to this property
+      # @option opts [Spira::Type, String] :type      (Spira::Types::Any) The
+      # type for this property.  If a Spira::Type is given, that class will be
+      # used to serialize and unserialize values.  If a String is given, it
+      # should be the String form of a Spira::Resource class name (Strings are
+      # used to prevent issues with load order).  
+      # @see Spira::Types
+      # @see Spira::Type
+      # @return [Void]
       def property(name, opts = {} )
         add_accessors(name,opts,:hash_accessors)
       end
 
+      ##
+      # The plural form of `property`.  `Has_many` has the same options as
+      # `property`, but instead of a single value, a Ruby Array of objects will
+      # be created instead.  Be warned that this should be a Set to match RDF
+      # semantics, but this is not currently implemented.  Duplicate values of
+      # an array will be lost on save.  
+      #
+      # @see Spira::Resource::DSL#property
       def has_many(name, opts = {})
         add_accessors(name,opts,:hash_accessors)
         @lists[name] = true
       end
 
+      ##
+      # Validate this model with the given validator function name.
+      #
+      # @example
+      #     class Person
+      #       include Spira::Resource
+      #       property :name, :predicate => FOAF.name
+      #       validate :is_awesome
+      #       def is_awesome
+      #         assert(name =~ /Thor/, :name, "not awesome")
+      #       end
+      #     end
+      # @param  [Symbol] validator
+      # @return [Void]
+      def validate(validator)
+        validators << validator unless validators.include?(validator)
+      end
+
+
+      ##
+      # Associate an RDF type with this class.  RDF resources can be multiple
+      # types at once, but if they have an `RDF.type` statement for the given
+      # URI, this class can #count them.
+      #
+      # @param  [RDF::URI] uri The URI object of the `RDF.type` triple
+      # @return [Void]
+      # @see http://rdf.rubyforge.net/RDF/URI.html
+      # @see http://rdf.rubyforge.org/RDF.html#type-class_method
+      # @see Spira::Resource::ClassMethods#count 
       def type(uri = nil)
         unless uri.nil?
           @type = case uri
@@ -48,41 +129,55 @@ module Spira
         @type
       end
 
+      # Build a Ruby value from an RDF value.
       #
       # @private
-      def build_value(statement, type)
+      def build_value(statement, type, existing_relation = nil)
         case
           when statement == nil
             nil
-          when type == String
-            statement.object.object.to_s
-          when type == Integer
-            statement.object.object
-          when type.is_a?(Symbol)
-            klass = Kernel.const_get(type.to_s.capitalize)
-            raise TypeError, "#{klass} is not a Spira Resource (referenced as #{type} by #{self}" unless klass.ancestors.include? Spira::Resource
-            promise { klass.find(statement.object) || klass.create(statement.object) }
+          when type.is_a?(Class) && type.ancestors.include?(Spira::Type)
+            type.unserialize(statement.object)
+          when type.is_a?(Symbol) || type.is_a?(String)
+            klass = begin 
+              Kernel.const_get(type.to_s)
+            rescue NameError
+              unless klass.is_a?(Class) && klass.ancestors.include?(Spira::Resource)
+                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
+          else
+            raise TypeError, "Unable to unserialize #{statement.object} for #{type}"
         end
       end
 
+      # Build an RDF value from a Ruby value for a property
       # @private
       def build_rdf_value(value, type)
         case
-          when value.class.ancestors.include?(Spira::Resource)
+          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 == nil
-            value
           when type == RDF::URI && value.is_a?(RDF::URI)
             value
-          when type.is_a?(RDF::URI)
-            RDF::Literal.new(value, :datatype => type)
           else
-            RDF::Literal.new(value)
+            raise TypeError, "Unable to serialize #{value} for #{type}"
         end
       end
 
       private
 
+      ##
+      # Add getters and setters for a property or list.
+      # @private
       def add_accessors(name, opts, accessors_method)
         predicate = case
           when opts[:predicate]
@@ -93,8 +188,16 @@ module Spira
             separator = @default_vocabulary.to_s[-1,1] == "/" ? '' : '/'
             RDF::URI.new(@default_vocabulary.to_s + separator + name.to_s)
         end
-
-        type = opts[:type] || String
+        type = case
+            when opts[:type].nil?
+              Spira::Types::Any
+            when opts[:type].is_a?(Symbol) || opts[:type].is_a?(String)
+              opts[:type]
+            when !(Spira.types[opts[:type]].nil?)
+              Spira.types[opts[:type]]
+            else
+              raise TypeError, "Unrecognized type: #{opts[:type]}"
+          end
         @properties[name] = {}
         @properties[name][:predicate] = predicate
         @properties[name][:type] = type
@@ -106,6 +209,11 @@ module Spira
 
       end
 
+      ##
+      # Getter and Setter methods for predicates.
+      # FIXME: this and add_accessors are from an older version in which
+      # multiple versions of accessors existed, and can be refactored.
+      # @private
       def hash_accessors(name, predicate, type)
         setter = lambda do |arg|
           attribute_set(name,arg)
@@ -118,47 +226,6 @@ module Spira
         [getter, setter]
       end
 
-      def list_accessors(name, predicate, type)
-
-        setter = lambda do |arg|
-          old = @repo.query(:subject => @uri, :predicate => predicate)
-          @repo.delete(*old.to_a) unless old.empty?
-          new = []
-          arg.each do |value|
-            value = self.class.build_rdf_value(value, type)
-            new << RDF::Statement.new(@uri, predicate, value)
-          end
-          @repo.insert(*new)
-        end
-
-        getter = lambda do
-          values = []
-          statements = @repo.query(:subject => @uri, :predicate => predicate)
-          statements.each do |statement|
-            values << self.class.build_value(statement, type)
-          end
-          values
-        end
-
-        [getter, setter]
-      end
-
-      def single_accessors(name, predicate, type)
-        setter = lambda do |arg|
-          old = @repo.query(:subject => @uri, :predicate => predicate)
-          @repo.delete(*old.to_a) unless old.empty?
-          arg = self.class.build_rdf_value(arg, type)
-          @repo.insert(RDF::Statement.new(@uri, predicate, arg))
-        end
-
-        getter = lambda do
-          statement = @repo.query(:subject => @uri, :predicate => predicate).first
-          self.class.build_value(statement, type)
-        end
-
-        [getter, setter]
-      end
-
     end
   end
 end