spira 0.0.1.pre → 0.0.1

data/README

@@ -19,12 +19,12 @@ or to create a new store of RDF data based on simple defaults.
 
       base_uri "http://example.org/example/people"
     
-      property :name, :predicate => RDF::FOAF.name, :type => String
-      property :age,  :predicate => RDF::FOAF.age,  :type => Integer
+      property :name, :predicate => FOAF.name, :type => String
+      property :age,  :predicate => FOAF.age,  :type => Integer
 
     end
 
-    bob = Person.create 'bob'
+    bob = RDF::URI("http://example.org/people/bob").as(Person)
     bob.age  = 15
     bob.name = "Bob Smith"
     bob.save!
@@ -36,19 +36,21 @@ or to create a new store of RDF data based on simple defaults.
 ### Features
 
  * Extensible validations system
+ * Extensible types system
  * Easy to use multiple data sources
  * Easy to adapt models to existing data
+ * Open-world semantics
  * Objects are still RDF.rb-compatible enumerable objects
  * No need to put everything about an object into Spira
  * Easy to use a resource as multiple models
 
 ## Getting Started
 
-By far the easiest way to work with Spira is to install it via Rubygems:
+The easiest way to work with Spira is to install it via Rubygems:
 
     $ sudo gem install spira
 
-Nonetheless, downloads are available at the Github project page.
+Downloads will be available on the github project page, as well as on Rubyforge.
 
 ## Defining Model Classes
 
@@ -74,9 +76,9 @@ without the `RDF::` prefix.  For example:
 
 Then use your model classes, in a way more or less similar to any number of ORMs:
 
-    cd = CD.create "queens-greatest-hits"
+    cd = CD.for("queens-greatest-hits")
     cd.name = "Queen's greatest hits"
-    artist = Artist.create "queen"
+    artist = Artist.for("queen")
     artist.name = "Queen"
     
     cd.artist = artist
@@ -84,21 +86,30 @@ Then use your model classes, in a way more or less similar to any number of ORMs
     artist.cds = [cd]
     artist.save!
 
-    queen = Arist.find 'queen'
-    hits = CD.find 'queens-greatest-hits'
+    queen = Arist.for('queen')
+    hits = CD.for 'queens-greatest-hits'
     hits.artist == artist == queen
 
 ### Absolute and Relative URIs
 
 A class with a base URI can reference objects by a short name:
 
-    Artist.find 'queen'
+    Artist.for('queen')
 
 However, a class is not required to have a base URI, and even if it does, it
 can always access classes with a full URI:
 
-    nk = Artist.find RDF::URI.new('http://example.org/my-hidden-cds/new-kids')
-    
+    nk = Artist.for(RDF::URI.new('http://example.org/my-hidden-cds/new-kids'))
+
+If you have a URI that you would like to look at as a Spira resource, you can instantiate it from the URI:
+
+    RDF::URI.new('http://example.org/my-hidden-cds/new-kids').as(Artist)
+    # => <Artist @uri=http://example.org/my-hidden-cds/new-kids>
+
+Any call to 'for' with a valid identifier will always return an object with nil
+fields.  It's a way of looking at a given resource, not a closed-world mapping
+to one.
+
 ### Class Options
 
 A number of options are available for Spira classes.
@@ -106,11 +117,11 @@ A number of options are available for Spira classes.
 #### base_uri
 
 A class with a `base_uri` set (either an `RDF::URI` or a `String`) will
-use that URI as a base URI for non-absolute `create` and `find` calls.
+use that URI as a base URI for non-absolute `for` calls.
 
 Example
-    CD.find 'queens-greatest-hits' # is the same as...
-    CD.find RDF::URI.new('http://example.org/cds/queens-greatest-hits')
+    CD.for 'queens-greatest-hits' # is the same as...
+    CD.for RDF::URI.new('http://example.org/cds/queens-greatest-hits')
 
 #### type
 
@@ -118,12 +129,12 @@ A class with a `type` set is assigned an `RDF.type` on creation and saving.
 
     class Album
       include Spira::Resource
-      type RDF::URI.new('http://example.org/types/album')
+      type URI.new('http://example.org/types/album')
       property :name,   :predicate => DC.title
     end
 
-    rolling_stones = Album.create RDF::URI.new('http://example.org/cds/rolling-stones-hits')
-    # See RDF.rb for more information about #has_predicate?
+    rolling_stones = Album.for RDF::URI.new('http://example.org/cds/rolling-stones-hits')
+    # See RDF.rb at http://rdf.rubyforge.org/RDF/Enumerable.html for more information about #has_predicate?
     rolling_stones.has_predicate?(RDF.type) #=> true
     Album.type #=> RDF::URI('http://example.org/types/album')
 
@@ -145,15 +156,16 @@ A class with a `default_vocabulary` set will transparently create predicates for
 
     class Song
       include Spira::Resource
-      default_vocabulary RDF::URI.new('http://example.org/vocab')
+      default_vocabulary URI.new('http://example.org/vocab')
       base_uri 'http://example.org/songs'
       property :title
       property :author, :type => :artist
     end
 
-    dancing_queen = Song.create 'dancing-queen'
+    dancing_queen = Song.for 'dancing-queen'
     dancing_queen.title = "Dancing Queen"
     dancing_queen.artist = abba
+    # See RDF::Enumerable for #has_predicate?
     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
 
@@ -168,6 +180,11 @@ repository if one is not set.
 
 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
@@ -182,11 +199,17 @@ for `property` work for `has_many`.
 Property always takes a symbol name as a name, and a variable list of options.  The supported options are:
 
  * `:type`: The type for this property.  This can be a Ruby base class, an 
-   RDF::XSD entry, or another Spira model class, referenced as a symbol. Default: `String`
+   RDF::XSD entry, or another Spira model class, referenced as a symbol.  See
+   **Types** below.  Default: `Any`
  * `:predicate`: The predicate to use for this type.  This can be any RDF URI.
    This option is required unless the `default_vocabulary` has been used.
 
-### Relations
+### Types
+
+A property's type can be either a class which includes Spira::Type or a
+reference to another Spira model class, given as a symbol.
+
+#### Relations
 
 If the `:type` of a spira class is the name of another Spira class as a symbol,
 such as `:artist` for `Artist`, Spira will attempt to load the referenced
@@ -194,6 +217,71 @@ object when the appropriate property is accessed.
 
 In the RDF store, this will be represented by the URI of the referenced object.
 
+#### Type Classes
+
+A type class includes Spira::Type, and can implement serialization and
+deserialization functions, and register aliases to themselves if their datatype
+is usually expressed as a URI.  Here is the built-in Spira Integer class:
+
+    module Spira::Types
+      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
+    end
+
+Classes can now use this particular type like so:
+
+    class Test
+      include Spira::Resource
+      property :test1, :type => Integer
+      property :test2, :type => XSD.integer
+    end
+
+Spira classes include the Spira::Types namespace, where several default types
+are implemented:
+
+  * `Integer`
+  * `Float`
+  * `Boolean`
+  * `String`
+  * `Any`
+
+The default type for a Spira property is `Spira::Types::Any`, which uses
+`RDF::Literal`'s automatic boxing/unboxing of XSD types as best it can.  See
+`[RDF::Literal](http://rdf.rubyforge.org/RDF/Literal.html)` for more information.
+
+You can implement your own types as well.  Your class' serialize method should
+turn an RDF::Value into a ruby object, and vice versa.
+
+    module MyModule
+      class MyType
+        include Spira::Type
+        def self.serialize(value)
+          ...
+        end
+
+        def self.unserialize(value)
+          ...
+        end
+      end
+    end
+
+    class MyClass
+      include Spira::Resource
+      property :property1, :type => MyModule::MyType
+    end
+
 ## Defining Repositories
 
 You can define multiple repositories with Spira, and use more than one at a time:
@@ -225,24 +313,55 @@ Classes can specify a default repository to use other than `:default` with the
 
 ## Validations
 
-Before saving, each object will run a `validate` function, if one exists.  You
-can use the built in `assert` and assert helpers such as `assert_set` and
+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
-      def validate
-        # the only valid CDs are ABBA CD's!
-        assert(artist.name == "Abba","Could not save a CD made by #{artist.name}")
+      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 = nil
+    dancing-queen.artist = nickelback
     dancing-queen.save!  #=> ValidationError
+    dancing-queen.errors.each => ["artist cannot be Nickelback"]
 
     dancing-queen.artist = abba
     dancing-queen.save!  #=> true
 
+
+## 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
+
+
 ## Using Model Objects as RDF.rb Objects
 
 All model objects are fully-functional as `RDF::Enumerable`, `RDF::Queryable`,
@@ -251,9 +370,10 @@ level.  You can also access attributes that are not defined as properties.
 
 ## Support
 
-There are a number of ways to ask for help.  In declining order of likelihood of response:
+There are a number of ways to ask for help.  In declining order of preference:
 
  * Fork the project and write a failing test, or a pending test for a feature request
+ * Ask on the [public-rdf-ruby w3c mailing list][]
  * 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)
 
@@ -269,3 +389,5 @@ domain.  For more information, see the included UNLICENSE file.
 #### Contributing
 Fork it on Github and go.  Please make sure you're kosher with the UNLICENSE
 file before contributing.
+
+[public-rdf-ruby w3c mailing list]:         http://lists.w3.org/Archives/Public/public-rdf-ruby/

data/VERSION

@@ -1 +1 @@
-0.0.1.pre
+0.0.1

data/lib/spira.rb

@@ -1,18 +1,62 @@
 require 'rdf'
 
+##
+# Spira is a framework for building projections of RDF data into Ruby classes.
+# It is built on top of RDF.rb.
+#
+# @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] ||= {}
   end
   module_function :repositories
 
+  ##
+  # The list of all property types available for Spira resources
+  # 
+  # @see Spira::Types
+  # @return [Hash{Symbol => Spira::Type}]
+  def types
+    settings[: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
+  # @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
+  # @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
       when RDF::Repository
@@ -29,12 +73,53 @@ module Spira
   alias_method :add_repository!, :add_repository
   module_function :add_repository, :add_repository!
 
+  ##
+  # The RDF::Repository for the named repository
+  #
+  # @param [Symbol] name The name of the repository
+  # @return [RDF::Repository]
+  # @see RDF::Repository
   def repository(name)
     repositories[name]
   end
   module_function :repository
 
+  ##
+  # 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
+  #
+  # @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 
+  end
+  module_function :type_alias
+
   autoload :Resource,         'spira/resource'
+  autoload :Type,             'spira/type'
+  autoload :Types,            'spira/types'
+  autoload :Errors,           'spira/errors'
+  autoload :VERSION,          'spira/version'
 
   class ValidationError < StandardError; end
 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
+    # @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/errors.rb

@@ -0,0 +1,94 @@
+module Spira
+
+  ##
+  # Spira::Errors represents a collection of validation errors for a Spira
+  # resource.  It tracks a list of errors for each field.
+  #
+  # This class does not perform validations.  It only tracks the results of
+  # them.
+  class Errors
+
+    ##
+    # Creates a new Spira::Errors
+    #
+    # @return [Spira::Errors]
+    def initialize
+      @errors = {}
+    end
+
+    ##
+    # Returns true if there are no errors, false otherwise
+    #
+    # @return [true, false]
+    def empty?
+      @errors.all? do |field, errors| errors.empty? end
+    end
+
+    ##
+    # Returns true if there are errors, false otherwise
+    #
+    # @return [true, false]
+    def any?
+      !empty?
+    end
+
+    ##
+    # Returns true if the given property or list has any errors
+    #
+    # @param [Symbol] name The name of the property or list
+    # @return [true, false]
+    def any_for?(property)
+      !(@errors[property].nil?) && !(@errors[property].empty?)
+    end
+ 
+    ##
+    # Add an error to a given property or list
+    #
+    # @example Add an error to a property
+    #     errors.add(:username, "cannot be nil")
+    # @param [Symbol] property The property or list to add the error to
+    # @param [String] problem The error
+    # @return [Void]
+    def add(property, problem)
+      @errors[property] ||= []
+      @errors[property].push problem
+    end
+
+    ##
+    # The list of errors for a given property or list
+    #
+    # @example Get the errors for the `:username` field
+    #     errors.add(:username, "cannot be nil")
+    #     errors.for(:username) #=> ["cannot be nil"]
+    # @param [Symbol] property The property or list to check
+    # @return [Array<String>] The list of errors
+    def for(property)
+      @errors[property]
+    end
+
+    ##
+    # Clear all errors
+    # 
+    # @return [Void]
+    def clear
+      @errors = {}
+    end
+
+    ##
+    # Return all errors as strings
+    #
+    # @example Get all errors
+    #     errors.add(:username, "cannot be nil")
+    #     errors.each #=> ["username cannot be nil"]
+    # @return [Array<String>]
+    def each
+      @errors.map do |property, problems|
+        problems.map do |problem|
+          property.to_s + " " + problem  
+        end
+      end.flatten
+    end
+
+
+  end
+end