spira 0.0.12 → 0.5.0

data/AUTHORS

@@ -1,3 +1,5 @@
 * Ben Lavender <blavender@gmail.com>
 * Arto Bendiken <arto@bendiken.net>
 * Nicholas J Humfrey <njh@aelius.com>
+* Slava Kravchenko <https://github.com/cordawyn>
+* Aymeric Brisse <https://github.com/abrisse>

data/CHANGES.md

@@ -1,4 +1,7 @@
-# Changelog for Spira <http://github.com/datagraph/spira>
+# Changelog for Spira <http://github.com/rdf-ruby/spira>
+
+## 0.3.0
+ * General updates to bring up to date.
 
 ## 0.0.12
  * Implemented #validate, #validate! (refactored from #save!)
@@ -33,7 +36,7 @@
 ## 0.0.8
  * Remove type checking for repository addition.  More power in return for 
    slightly more difficult error messages.
- * Repositories added via klass, *arg are now only instantiated on first use
+ * Repositories added via klass, \*arg are now only instantiated on first use
    instead of immediately.
  * RDF::URI#as, RDF::Node#as, Resource.for, and Resource#new can now all accept
    a block, which yields the new instance and saves it after the block.
@@ -46,7 +49,7 @@
    permitted.
 
 ## 0.0.7
- * Added Resource.[], an alias for Resource.for
+ * Added Resource.\[\], an alias for Resource.for
  * Resource.each now correctly raises an exception when a repository isn't found
 
 ## 0.0.6

data/{README → README.md}

@@ -1,9 +1,7 @@
-# Spira
+# Spira [![Build Status](https://travis-ci.org/ruby-rdf/spira.png?branch=master)](http://travis-ci.org/ruby-rdf/spira)
 
 It's time to breathe life into your linked data.
 
----
-
 ## Synopsis
 Spira is a framework for using the information in [RDF.rb][] repositories as model
 objects.  It gives you the ability to work in a resource-oriented way without
@@ -17,11 +15,9 @@ A changelog is available in the {file:CHANGES.md} file.
 
 ### Example
 
-    class Person
-    
-      include Spira::Resource
+    class Person < Spira::Base
 
-      base_uri "http://example.org/example/people"
+      configure :base_uri => "http://example.org/example/people"
     
       property :name, :predicate => FOAF.name, :type => String
       property :age,  :predicate => FOAF.age,  :type => Integer
@@ -48,6 +44,49 @@ A changelog is available in the {file:CHANGES.md} file.
  * No need to put everything about an object into Spira
  * Easy to use a resource as multiple models
 
+## ActiveModel integration
+
+This is a version of Spira that makes use of ActiveModel. The goal of this version is
+to replace all the internals of Spira with ActiveModel hooks, and thus get rid of
+superfluous code and increase compatibility with Rails stack. I want it to be
+a drop-in replacement for ActiveRecord or any other mature ORM solution they use
+with Ruby on Rails.
+
+Although I've been trying to make the impact of this transition to be as little
+as possible, there are a few changes that you should be aware of:
+
+ * Read the comments on "new_record?" and "reload" methods. They are key methods in
+   understanding how Spira is working with the repository. Basically, a Spira record
+   is new, if the repository has no statements with this record as subject. This means,
+   that *the repository is queried every time you invoke "new_record?"*.
+   Also note that if Spira.repository is not set, your Spira resource will always be "new".
+   Also note that instantiating a new Spira resource sends a query to the repository,
+   if it is set, but should work just fine even if it's not (until you try to "save" it).
+ * Customary Rails' record manipulation methods are preferred now.
+   This means, you should use more habitual "save", "destroy", "update_attributes", etc.
+   instead of the "save!", "destroy!", "update", "update!" and others, as introduced
+   by the original Spira gem.
+ * Callbacks are now handled by ActiveModel. Previous ways of defining them are
+   no longer valid. This also introduces the "before_", "after_" and "around_" callbacks
+   as well as their "_validation", "_save", "_update" and "_create" companions for you to enjoy.
+ * Validations are also handled by ActiveModel. With all the helper methods you have in
+   ActiveRecord.
+ * A spira resource (class) must be defined by *inheriting* it from Spira::Base.
+   Using "include Spira::Resource" is *temporarily* broken, but will be back at some point,
+   with improvements and stuff.
+ * "after/before_create" callbacks are *not* called when only the properties of your
+   Spira resource are getting persisted. That is, you may create a "type"-less Spira resource,
+   assign properties to it, then #save it -- "_create" callbacks will not be triggered,
+   because Spira cannot infer a resource definition ("resource - RDF.type - type")
+   for such resource and will only persist its properties.
+   Although this is how the original Spira behaves too, I thought I'd state it
+   explicitly here before you start freaking out.
+ * Configuration options "base_uri", "default_vocabulary" and "repository_name" are
+   now configured via "configure" method (see the examples below).
+ * A couple of (not so) subtle changes:
+   1) Global caching is gone. This means that "artist.works.first.artist" (reverse lookup)
+   does not return the original artist, but its copy retrieved from the database.
+
 ## Getting Started
 
 The easiest way to work with Spira is to install it via Rubygems:
@@ -64,16 +103,14 @@ without the `RDF::` prefix.  For example:
 
     require 'spira'
     
-    class CD
-      include Spira::Resource
-      base_uri 'http://example.org/cds'
+    class CD < Spira::Base
+      configure :base_uri => 'http://example.org/cds'
       property :name,   :predicate => DC.title,   :type => XSD.string
       property :artist, :predicate => URI.new('http://example.org/vocab/artist'), :type => :artist
     end
     
-    class Artist
-      include Spira::Resource
-      base_uri 'http://example.org/artists'
+    class Artist < Spira::Base
+      configure :base_uri => 'http://example.org/artists'
       property :name, :predicate => DC.title, :type => XSD.string
       has_many :cds,  :predicate => URI.new('http://example.org/vocab/published_cd'), :type => XSD.string
     end
@@ -147,8 +184,7 @@ Example
 
 A class with a `type` set is assigned an `RDF.type` on creation and saving.
 
-    class Album
-      include Spira::Resource
+    class Album < Spira::Base
       type URI.new('http://example.org/types/album')
       property :name,   :predicate => DC.title
     end
@@ -162,6 +198,21 @@ In addition, one can count the members of a class with a `type` defined:
 
     Album.count  #=> 1 
 
+
+It is possible to assign multiple types to a Spira class:
+
+    class Man < Spira::Base
+      type RDF::URI.new('http://example.org/people/father')
+      type RDF::URI.new('http://example.org/people/cop')
+    end
+
+All assigned types are accessible via "types":
+
+    Man.types #=> #<Set: {#<RDF::URI:0xd5ebc0(http://example.org/people/father)>, #<RDF::URI:0xd5e4b8(http://example.org/people/cop)>}>
+
+Also note that "type" actually returns a first type from the list of types.
+
+
 #### property
 
 A class declares property members with the `property` function.  See `Property Options` for more information.
@@ -174,10 +225,9 @@ A class declares list members with the `has_many` function.  See `Property Optio
 
 A class with a `default_vocabulary` set will transparently create predicates for defined properties:
 
-    class Song
-      include Spira::Resource
-      default_vocabulary URI.new('http://example.org/vocab')
-      base_uri 'http://example.org/songs'
+    class Song < Spira::Base
+      configure :default_vocabulary => URI.new('http://example.org/vocab'),
+                :base_uri => 'http://example.org/songs'
       property :title
       property :author, :type => :artist
     end
@@ -189,22 +239,17 @@ A class with a `default_vocabulary` set will transparently create predicates for
     dancing_queen.has_predicate?(RDF::URI.new('http://example.org/vocab/title'))  #=> true
     dancing_queen.has_predicate?(RDF::URI.new('http://example.org/vocab/artist')) #=> true
 
-#### default_source
+#### repository_name
 
 Provides this class with a default repository to use instead of the `:default`
 repository if one is not set.
 
-    class Song
-      default_source :songs
+    class Song < Spira::Base
+      configure :repository_name => :songs
     end
 
 See 'Defining Repositories' for more information.
 
-#### validate
-
-Provides the name of a function which does some sort of validation.  See
-'Validations' for more information.
-
 ### Property Options
 
 Spira classes can have properties that are either singular or a list.  For a
@@ -256,16 +301,15 @@ is usually expressed as a URI.  Here is the built-in Spira Integer class:
           RDF::Literal.new(value)
         end
     
-        register_alias XSD.integer
+        register_alias RDF::XSD.integer
       end
     end
 
 Classes can now use this particular type like so:
 
-    class Test
-      include Spira::Resource
+    class Test < Spira::Base
       property :test1, :type => Integer
-      property :test2, :type => XSD.integer
+      property :test2, :type => RDF::XSD.integer
     end
 
 Spira classes include the Spira::Types namespace, where several default types
@@ -297,8 +341,7 @@ turn an RDF::Value into a ruby object, and vice versa.
       end
     end
 
-    class MyClass
-      include Spira::Resource
+    class MyClass < Spira::Base
       property :property1, :type => MyModule::MyType
     end
 
@@ -311,8 +354,12 @@ You can define multiple repositories with Spira, and use more than one at a time
     Spira.add_repository! :cds,    RDF::Sesame::Repository.new 'some_server'
     Spira.add_repository! :albums, RDF::Repository.load('some_file.nt')
 
-    CD.repository = :cds
-    Album.repository = :albums
+    class CD < Spira::Base
+      configure :repository_name => :cds
+    end
+    class Album < Spira::Base
+      configure :repository_name => :albums
+    end
 
 Objects can reference each other cross-repository.
 
@@ -323,94 +370,23 @@ If no repository has been specified, the `:default` repository will be used.
     Artist.repository == repo #=> true
 
 Classes can specify a default repository to use other than `:default` with the
-`default_source` function:
+`repository_name` function:
 
-    class Song
-      default_source :songs
+    class Song < Spira::Base
+      configure :repository_name => :songs
     end
 
     Song.repository #=> nil, won't use :default
 
 ## Validations
 
-You may declare any number of validation functions with the `validate` function. 
-Before saving, each referenced validation will be run, and the instance's
-{Spira::Errors} object will be populated with any errors.  You can use the
-built in `assert` and assert helpers such as `assert_set` and
-`asssert_numeric`.
-
-
-    class CD
-      validate :is_real_music
-      def is_real_music
-        assert(artist.name != "Nickelback", :artist, "cannot be Nickelback")
-      end
-
-      validate :track_count_numeric
-      def track_count_numeric
-        assert_numeric(track_count)
-      end
-    end
-
-    dancing_queen.artist = nickelback
-    dancing_queen.save!  #=> ValidationError
-    dancing_queen.errors.each #=> ["artist cannot be Nickelback"]
-
-    dancing_queen.artist = abba
-    dancing_queen.save!  #=> true
+[removed]
+See the description of ActiveModel::Validations.
 
 ## Hooks
 
-Spira supports `before_create`, `after_create`, `after_update`, `before_save`,
-`after_save`, and `before_destroy` hooks:
-
-    class CD
-      def before_save
-        self.publisher = 'No publisher set' if self.publisher.nil?
-      end
-    end
-
-The `after_update` hook only fires on the `update` method, not simple property
-accessors (to allow you to easily set properties in these without going into a
-recursive loop):
-
-    class CD
-      def after_update
-        self.artist = 'Queen' # every artist should be Queen!
-      end
-    end
-    
-    # ...snip ...
-    dancing_queen.artist
-    #=> "ABBA"
-    dancing_queen.name = "Dancing Queen"
-    dancing_queen.artist
-    #=> "ABBA"
-    dancing_queen.update(:name => "Dancing Queen")
-    dancing_queen.artist
-    #=> "Queen"
-
-## Inheritance
-
-You can extend Spira resources without a problem:
-
-    class BoxedSet < CD
-      include Spira::Resource
-      property cd_count, :predicate => CD.count, :type => Integer
-    end
-
-You can also make Spira modules and include them into other classes:
-
-    module Media
-      include Spira::Resource
-      property :format, :predicate => Media.format
-    end
-
-    class CD
-      include Spira::Resource
-      include Media
-    end
-
+[removed]
+See the description of ActiveModel::Callbacks.
 
 ## Using Model Objects as RDF.rb Objects
 
@@ -427,16 +403,11 @@ There are a number of ways to ask for help.  In declining order of preference:
  * You can post issues to the Github issue queue
  * (there might one day be a google group or other such support channel, but not yet)
 
-## Authors, Development, and License
-
-#### Authors
- * Ben Lavender <blavender@gmail.com>
-
-#### 'License'
+## 'License'
 Spira is free and unemcumbered software released into the public
 domain.  For more information, see the included UNLICENSE file.
 
-#### Contributing
+## Contributing
 Fork it on Github and go.  Please make sure you're kosher with the UNLICENSE
 file before contributing.
 

data/lib/rdf/ext/uri.rb

@@ -0,0 +1,37 @@
+module RDF
+  class URI
+    ##
+    # Create a projection of this URI as the given Spira::Resource class.
+    # Equivalent to `klass.for(self, *args)`
+    #
+    # @example Instantiating a URI as a Spira Resource
+    #     RDF::URI('http://example.org/person/bob').as(Person)
+    # @param [Class] klass
+    # @param [*Any] args Any arguments to pass to klass.for
+    # @yield [self] Executes a given block and calls `#save!`
+    # @yieldparam [self] self The newly created instance
+    # @return [Klass] An instance of klass
+    def as(klass, *args, &block)
+      raise ArgumentError, "#{klass} is not a Spira resource" unless klass.is_a?(Class) && klass.ancestors.include?(Spira::Base)
+      klass.for(self, *args, &block)
+    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
+    # @yield [self] Executes a given block and calls `#save!`
+    # @yieldparam [self] self The newly created instance
+    # @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::Base)
+      klass.for(self, *args)
+    end
+  end
+end

data/lib/spira.rb

@@ -1,6 +1,8 @@
-require 'rdf'
-require 'promise'
-require 'spira/exceptions'
+require "rdf"
+require "rdf/ext/uri"
+require "promise"
+require "spira/exceptions"
+require "spira/utils"
 
 ##
 # Spira is a framework for building projections of RDF data into Ruby classes.
@@ -9,66 +11,59 @@ require 'spira/exceptions'
 # @see http://rdf.rubyforge.org
 # @see http://github.com/bhuga/spira
 # @see Spira::Resource
-module Spira
 
-  ##
-  # The list of repositories available for Spira resources
-  #
-  # @see http://rdf.rubyforge.org/RDF/Repository.html
-  # @return [Hash{Symbol => RDF::Repository}]
-  # @private
-  def repositories
-    settings[:repositories] ||= {}
+module RDF
+  class Repository
   end
-  module_function :repositories
+end
+
+module Spira
+
+  autoload :Base,             'spira/base'
+  autoload :Type,             'spira/type'
+  autoload :Types,            'spira/types'
+  autoload :VERSION,          'spira/version'
 
   ##
   # The list of all property types available for Spira resources
-  # 
+  #
   # @see Spira::Types
   # @return [Hash{Symbol => Spira::Type}]
   def types
-    settings[:types] ||= {}
+    @types ||= {}
   end
   module_function :types
 
-  ##
-  # A thread-local hash for storing settings.  Used by Resource classes.
-  #
-  # @see Spira::Resource
-  # @see Spira.repositories
-  # @see Spira.types
-  def settings
-    Thread.current[:spira] ||= {}
-  end
-  module_function :settings
-
   ##
   # Add a repository to Spira's list of repositories.
   #
   # @overload add_repository(name, repo)
-  #     @param [Symbol] name The name of this repository
-  #     @param [RDF::Repository] repo An RDF::Repository
+  #   @param [Symbol] name The name of this repository
+  #   @param [RDF::Repository] repo
+  #
   # @overload add_repository(name, klass, *args)
-  #     @param [Symbol] name The name of this repository
-  #     @param [RDF::Repository, Class] repo A Class that inherits from RDF::Repository
-  #     @param [*Object] The list of arguments to instantiate the class
+  #   @param [Symbol] name The name of this repository
+  #   @param [Class] klass
+  #     A Class that inherits from `RDF::Repository`
+  #   @param [Array] args
+  #     The list of arguments to instantiate the class
+  #
   # @example Adding an ntriples file as a repository
   #     Spira.add_repository(:default, RDF::Repository.load('http://datagraph.org/jhacker/foaf.nt'))
   # @example Adding an empty repository to be instantiated on use
   #     Spira.add_repository(:default, RDF::Repository)
   # @return [Void]
-  # @see RDF::Repository
   def add_repository(name, klass, *args)
-    repositories[name] = case klass
+    repositories[name] =
+      case klass
       when Class
         promise { klass.new(*args) }
       else
         klass
-     end
-     if (name == :default) && settings[:repositories][name].nil?
-        warn "WARNING: Adding nil default repository"
-     end
+      end
+    if (name == :default) && repository(name).nil?
+      warn "WARNING: Adding nil default repository"
+    end
   end
   alias_method :add_repository!, :add_repository
   module_function :add_repository, :add_repository!
@@ -91,10 +86,23 @@ module Spira
   # @return [Void]
   # @private
   def clear_repositories!
-    settings[:repositories] = {}
+    @repositories = {}
   end
   module_function :clear_repositories!
 
+
+  private
+
+  ##
+  # The list of repositories available for Spira resources
+  #
+  # @see http://rdf.rubyforge.org/RDF/Repository.html
+  # @return [Hash{Symbol => RDF::Repository}]
+  def repositories
+    @repositories ||= {}
+  end
+  module_function :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
@@ -102,55 +110,8 @@ module Spira
   # @param [Any] new The new symbol or reference
   # @param [Any] original The type the new symbol should refer to
   # @return [Void]
-  # @private
   def type_alias(new, original)
-    types[new] = original 
+    types[new] = original
   end
   module_function :type_alias
-
-  autoload :Resource,         'spira/resource'
-  autoload :Base,             'spira/base'
-  autoload :Type,             'spira/type'
-  autoload :Types,            'spira/types'
-  autoload :Errors,           'spira/errors'
-  autoload :VERSION,          'spira/version'
-
-end
-
-module RDF
-  class URI
-    ##
-    # Create a projection of this URI as the given Spira::Resource class.
-    # Equivalent to `klass.for(self, *args)`
-    #
-    # @example Instantiating a URI as a Spira Resource
-    #     RDF::URI('http://example.org/person/bob').as(Person)
-    # @param [Class] klass
-    # @param [*Any] args Any arguments to pass to klass.for
-    # @yield [self] Executes a given block and calls `#save!`
-    # @yieldparam [self] self The newly created instance
-    # @return [Klass] An instance of klass
-    def as(klass, *args, &block)
-      raise ArgumentError, "#{klass} is not a Spira resource" unless klass.is_a?(Class) && klass.ancestors.include?(Spira::Resource)
-      klass.for(self, *args, &block)
-    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
-    # @yield [self] Executes a given block and calls `#save!`
-    # @yieldparam [self] self The newly created instance
-    # @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