spira 0.0.12 → 0.5.0

data/lib/spira/reflections.rb

@@ -0,0 +1,19 @@
+require "spira/association_reflection"
+
+module Spira
+  module Reflections
+    # Returns a hash containing all AssociationReflection objects for the current class
+    # Example:
+    #
+    #   Invoice.reflections
+    #   Account.reflections
+    #
+    def reflections
+      read_inheritable_attribute(:reflections) || write_inheritable_attribute(:reflections, {})
+    end
+
+    def reflect_on_association(association)
+      reflections[association].is_a?(AssociationReflection) ? reflections[association] : nil
+    end
+  end
+end

data/lib/spira/resource.rb

@@ -1,72 +1,177 @@
-module Spira
+require "active_support/core_ext/class"
+require "spira/association_reflection"
 
-  ##
-  # 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 Spira
   module Resource
- 
-    autoload :DSL,              'spira/resource/dsl'
-    autoload :ClassMethods,     'spira/resource/class_methods'
-    autoload :InstanceMethods,  'spira/resource/instance_methods'
-    autoload :Validations,      'spira/resource/validations'
+    ##
+    # Configuration options for the Spira::Resource:
+    #
+    # @params[Hash] options
+    #   :repository_name    :: name of the repository to use
+    #   :base_uri           :: base URI to be used for the resource
+    #   :default_vocabulary :: default vocabulary to use for the properties
+    #                          defined for this resource
+    # All these configuration options are readable via
+    # their respectively named Spira resource methods.
+    #
+    def configure(options = {})
+      singleton_class.class_eval do
+        { :repository_name => options[:repository_name],
+          :base_uri => options[:base_uri],
+          :default_vocabulary => options[:default_vocabulary]
+        }.each do |name, value|
+          # redefine reader methods only when required,
+          # otherwise, use the ancestor methods
+          if value
+            define_method name do
+              value
+            end
+          end
+        end
+      end
+    end
 
     ##
-    # When a child class includes Spira::Resource, this does the magic to make
-    # it a Spira resource.
+    # Declare a type for the Spira::Resource.
+    # You can declare multiple types for a resource
+    # with multiple "type" assignments.
+    # If no types are declared for a resource,
+    # they are inherited from the parent resource.
     #
-    # @private
-    def self.included(child)
-      # 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
+    # @params[RDF::URI] uri
+    #
+    def type(uri = nil)
+      if uri
+        if uri.is_a?(RDF::URI)
+          ts = @types ? types : Set.new
+          singleton_class.class_eval do
+            define_method :types do
+              ts
+            end
           end
-          @properties = {}
-          @lists      = {}
+          @types = ts << uri
+        else
+          raise TypeError, "Type must be a RDF::URI"
         end
+      else
+        types.first
+      end
+    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::Base class name (Strings are
+    # used to prevent issues with load order).
+    # @see Spira::Types
+    # @see Spira::Type
+    # @return [Void]
+    def property(name, opts = {})
+      unset_has_many(name)
+      predicate = predicate_for(opts[:predicate], name)
+      type = type_for(opts[:type])
+      properties[name] = HashWithIndifferentAccess.new(:predicate => predicate, :type => type)
+
+      define_attribute_method name
+      define_method "#{name}=" do |arg|
+        write_attribute name, arg
+      end
+      define_method name do
+        read_attribute name
+      end
+    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.
+    #
+    # has_many corresponds to an RDF subject with several triples of the same
+    # predicate. This corresponds to a Ruby Array, which will be returned when
+    # the property is accessed. Arrays will be accepted for new values, but
+    # ordering and duplicate values will be lost on save.
+    #
+    # @see Spira::Base::DSL#property
+    def has_many(name, opts = {})
+      property(name, opts)
+
+      reflections[name] = AssociationReflection.new(:has_many, name, opts)
+
+      define_method "#{name.to_s.singularize}_ids" do
+        records = send(name) || []
+        records.map(&:id).compact
+      end
+      define_method "#{name.to_s.singularize}_ids=" do |ids|
+        records = ids.map {|id| self.class.reflect_on_association(name).klass.unserialize(id) }.compact
+        send "#{name}=", records
+      end
+    end
+
+
+    private
+
+    # Unset a has_many relation if it exists. Allow to redefine the cardinality of a relation in a subClass
+    #
+    # @private
+    def unset_has_many(name)
+      if reflections[name]
+        reflections.delete(name)
+        undef_method "#{name.to_s.singularize}_ids"
+        undef_method "#{name.to_s.singularize}_ids="
+      end
+    end
+
+    ##
+    # Determine the predicate for a property based on the given predicate, name, and default vocabulary
+    #
+    # @param  [#to_s, #to_uri] predicate
+    # @param  [Symbol] name
+    # @return [RDF::URI]
+    # @private
+    def predicate_for(predicate, name)
+      case
+      when predicate.respond_to?(:to_uri) && predicate.to_uri.absolute?
+        predicate
+      when default_vocabulary.nil?
+        raise ResourceDeclarationError, "A :predicate option is required for types without a default vocabulary"
+      else
+        # FIXME: use rdf.rb smart separator after 0.3.0 release
+        separator = default_vocabulary.to_s[-1,1] =~ /(\/|#)/ ? '' : '/'
+        RDF::URI.intern(default_vocabulary.to_s + separator + name.to_s)
+      end
+    end
+
+    ##
+    # Determine the type for a property based on the given type option
+    #
+    # @param [nil, Spira::Type, Constant] type
+    # @return Spira::Type
+    # @private
+    def type_for(type)
+      case
+      when type.nil?
+        Spira::Types::Any
+      when type.is_a?(Symbol) || type.is_a?(String)
+        type
+      when Spira.types[type]
+        Spira.types[type]
+      else
+        raise TypeError, "Unrecognized type: #{type}"
       end
     end
-    
-    # This lets including classes reference vocabularies without the RDF:: prefix
-    include Spira::Types
-    include ::RDF
-    include InstanceMethods
 
   end
 end

data/lib/spira/serialization.rb

@@ -0,0 +1,27 @@
+module Spira
+  module Serialization
+    ##
+    # Support for Psych (YAML) custom serializer.
+    #
+    # This causes the subject and all attributes to be saved to a YAML or JSON serialization
+    # in such a way that they can be restored in the future.
+    #
+    # @param [Psych::Coder] coder
+    def encode_with(coder)
+      coder["subject"] = subject
+      attributes.each {|p,v| coder[p.to_s] = v if v}
+    end
+
+    ##
+    # Support for Psych (YAML) custom de-serializer.
+    #
+    # Updates a previously allocated Spira::Base instance to that of a previously
+    # serialized instance.
+    #
+    # @param [Psych::Coder] coder
+    def init_with(coder)
+      instance_variable_set(:"@subject", coder["subject"])
+      assign_attributes coder.map.except("subject")
+    end
+  end
+end

data/lib/spira/type.rb

@@ -8,17 +8,17 @@ module Spira
   # 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
   #
@@ -27,7 +27,7 @@ module Spira
   # integer property on a Spira resource:
   #
   #     property :age, :predicate => FOAF.age, :type => Integer
-  #     property :age, :predicate => FOAF.age, :type => XSD.integer
+  #     property :age, :predicate => FOAF.age, :type => RDF::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.
@@ -55,8 +55,8 @@ module Spira
       #
       # @param [Any] identifier The new alias in property declarations for this class
       # @return [Void]
-      def register_alias(any)
-        Spira.type_alias(any, self)
+      def register_alias(identifier)
+        Spira.type_alias(identifier, self)
       end
 
       ##

data/lib/spira/types.rb

@@ -4,25 +4,22 @@ module Spira
   # Spira::Types is a set of default Spira::Type classes.
   #
   # @see Spira::Type
-  # @see Spira::Types::Integer
+  # @see Spira::Types::Int
+  # @see Spira::Types::Integer  
   # @see Spira::Types::Boolean
   # @see Spira::Types::String
+  # @see Spira::Types::GYear
+  # @see Spira::Types::Date
+  # @see Spira::Types::DateTime
   # @see Spira::Types::Float
   # @see Spira::Types::Any
   module Types
 
     # No autoloading here--the associations to XSD types are made by the
-    # classes themselves, so we need to explicitly require them or XSD types
+    # classes themselves, so we need to require them or XSD types
     # will show up as not found.
-    require 'spira/types/integer'
-    require 'spira/types/boolean'
-    require 'spira/types/any'
-    require 'spira/types/string'
-    require 'spira/types/float'
-    require 'spira/types/uri'
-    require 'spira/types/decimal'
-    require 'spira/types/native'
-
+    
+    Dir.glob(File.join(File.dirname(__FILE__), 'types', '*.rb')).each { |file| require file }
 
   end
 end

data/lib/spira/types/boolean.rb

@@ -19,13 +19,13 @@ module Spira::Types
 
     def self.serialize(value)
       if value
-        RDF::Literal.new(true, :datatype => XSD.boolean)
+        RDF::Literal.new(true, :datatype => RDF::XSD.boolean)
       else 
-        RDF::Literal.new(false, :datatype => XSD.boolean)
+        RDF::Literal.new(false, :datatype => RDF::XSD.boolean)
       end
     end
 
-    register_alias XSD.boolean
+    register_alias RDF::XSD.boolean
 
   end
 end

data/lib/spira/types/date.rb

@@ -1,24 +1,23 @@
 module Spira::Types
 
   ##
-  # A {Spira::Type} for Date values.  Values will be associated with the
+  # A {Spira::Type} for dates.  Values will be associated with the
   # `XSD.date` type.
   #
   # A {Spira::Resource} property can reference this type as
-  # `Spira::Types::Date`, `Date`, or `XSD.Date`.
+  # `Spira::Types::Date`, `Date`, or `XSD.date`.
   #
   # @see Spira::Type
   # @see http://rdf.rubyforge.org/RDF/Literal.html
   class Date
-
     include Spira::Type
 
     def self.unserialize(value)
-      value.object
+      object = value.object
     end
 
     def self.serialize(value)
-      RDF::Literal::Date.new(value)
+      RDF::Literal.new(value, :datatype => XSD.date)
     end
 
     register_alias XSD.date

data/lib/spira/types/dateTime.rb

@@ -0,0 +1,26 @@
+module Spira::Types
+
+  ##
+  # A {Spira::Type} for dateTimes.  Values will be associated with the
+  # `XSD.dateTime` type.
+  #
+  # A {Spira::Resource} property can reference this type as
+  # `Spira::Types::DateTime`, `DateTime`, or `XSD.dateTime`.
+  #
+  # @see Spira::Type
+  # @see http://rdf.rubyforge.org/RDF/Literal.html
+  class DateTime
+    include Spira::Type
+
+    def self.unserialize(value)
+      object = value.object
+    end
+
+    def self.serialize(value)
+      RDF::Literal.new(value, :datatype => XSD.dateTime)
+    end
+
+    register_alias XSD.dateTime
+
+  end
+end

data/lib/spira/types/decimal.rb

@@ -20,10 +20,10 @@ module Spira::Types
     end
 
     def self.serialize(value)
-      RDF::Literal.new(value.is_a?(BigDecimal) ? value.to_s('F') : value.to_s, :datatype => XSD.decimal)
+      RDF::Literal.new(value.is_a?(BigDecimal) ? value.to_s('F') : value.to_s, :datatype => RDF::XSD.decimal)
     end
 
-    register_alias XSD.decimal
+    register_alias RDF::XSD.decimal
 
   end
 end