tripod 0.0.10 → 0.2

data/README.md

@@ -6,10 +6,12 @@ ActiveModel-style Ruby ORM for RDF Linked Data. Works with SPARQL 1.1 HTTP endpo
 * Inspired by [Durran Jordan's](https://github.com/durran) [Mongoid](http://mongoid.org/en/mongoid/) ORM for [MongoDB](http://www.mongodb.org/), and [Ben Lavender's](https://github.com/bhuga) RDF ORM, [Spira](https://github.com/ruby-rdf/spira).
 * Uses [Ruby-RDF](https://github.com/ruby-rdf/rdf) to manage the data internally.
 
-__Warning: Work still in progress / experimental. Not production ready!__
+__Warning: Some features are still experimental.__
 
 ## Quick start, for using in a rails app.
 
+Note: Tripod doesn't supply a database. You need to install one. I recommend [Fuseki](http://jena.apache.org/documentation/serving_data/index.html), which runs on port 3030 by default.
+
 1. Install the gem:
 
         gem install tripod
@@ -32,7 +34,11 @@ __Warning: Work still in progress / experimental. Not production ready!__
         class Person
           include Tripod::Resource
 
+          rdf_type 'http://person'
+          graph_uri 'http://people'
+
           field :name, 'http://name'
+          field :knows, 'http://knows', :multivalued => true
           field :aliases, 'http://alias', :multivalued => true
           field :age, 'http://age', :datatype => RDF::XSD.integer
           field :important_dates, 'http://importantdates', :datatype => RDF::XSD.date, :multivalued => true
@@ -43,15 +49,15 @@ __Warning: Work still in progress / experimental. Not production ready!__
 5. Use it
 
         uri = 'http://ric'
-        graph = 'http://people'
-        p = Person.new(uri, graph)
+        p = Person.new(uri)
         p.name = 'Ric'
         p.age = 31
         p.aliases = ['Rich', 'Richard']
         p.important_dates = [Date.new(2011,1,1)]
-        p[RDF::type] = RDF::URI('http://person')
         p.save!
 
+        # Note: queries supplied to the where method should return the uris of the resource,
+        # and what graph they're in.
         people = Person.where("
           SELECT ?person ?graph
           WHERE {
@@ -60,7 +66,7 @@ __Warning: Work still in progress / experimental. Not production ready!__
               ?person a <http://person> .
             }
           }",
-        :uri_variable => 'person' )
+        :uri_variable => 'person' ) # optionally, set a different name for the uri parameter (default: uri)
         # => returns an array of Person objects, containing all data we know about them.
 
         ric = Person.find('http://ric')

data/lib/tripod.rb

@@ -33,6 +33,7 @@ require 'rdf'
 require 'rdf/rdfxml'
 require 'rdf/n3'
 require 'rdf/json'
+require 'json/ld'
 
 require 'rest_client'
 
@@ -64,12 +65,14 @@ end
 require "tripod/extensions"
 require "tripod/sparql_client"
 
+require "tripod/predicates"
 require "tripod/attributes"
 require "tripod/errors"
 require "tripod/fields"
 require "tripod/finders"
 require "tripod/persistence"
 require "tripod/repository"
+require "tripod/serialization"
 require "tripod/state"
 require "tripod/version"
 

data/lib/tripod/attributes.rb

@@ -5,77 +5,69 @@ module Tripod::Attributes
 
   extend ActiveSupport::Concern
 
-  # Reads values from this respource's in-memory statement repository, where the predicate matches that of the uri passed in.
-  # Returns an Array of RDF::Terms object.
+  # Reads an attribute from this resource, based on a defined field
+  # Returns the value(s) for the named (or given) field
   #
-  # @example Read an attribute.
-  #   person.read_attribute('http://foo')
-  #   person.read_attribute(RDF::URI.new('http://foo'))
+  # @example Read the value associated with a predicate.
+  #   class Person
+  #     field :name, 'http://name'
+  #   end
   #
-  # @example Read an attribute (alternate syntax.)
-  #   person['http://foo']
-  #   person[RDF::URI.new('http://foo')]
+  #   person.read_attribute(:name)
   #
-  # @param [ String, RDF::URI ] uri The uri of the attribute to get.
+  # @param [ String ] name The name of the field for which to get the value.
+  # @param [ Field ] field An optional Field object
   #
-  # @return [ Array ] An array of RDF::Terms.
-  def read_attribute(predicate_uri)
-    values = []
-    @repository.query( [:subject, RDF::URI.new(predicate_uri.to_s), :object] ) do |statement|
-      values << statement.object
+  # @return Either a string or an Array of strings, depending on whether the field is multivalued or not
+  def read_attribute(name, field=nil)
+    field ||= self.fields[name]
+    raise Tripod::Errors::FieldNotPresent.new unless field
+
+    attr_values = read_predicate(field.predicate)
+    # We always return strings on way out.
+    # If the field is multivalued, return an array of the results
+    # If it's not multivalued, return the first (should be only) result.
+    if field.multivalued
+      attr_values.map do |v|
+        v.nil? ? nil : v.to_s
+      end
+    else
+      first_val = attr_values.first
+      first_val.nil? ? nil : first_val.to_s
     end
-    values
   end
   alias :[] :read_attribute
 
-  # Replace the statement-values for a single predicate in this resource's in-memory repository.
+  # Writes an attribute to the resource, based on a defined field
   #
-  # @example Write the attribute.
-  #   person.write_attribute('http://title', "Mr.")
-  #   person.write_attribute('http://title', ["Mrs.", "Ms."])
+  # @example Write the value associated with a predicate.
+  #   class Person
+  #     field :name, 'http://name'
+  #   end
   #
-  # @example Write the attribute (alternate syntax.)
-  #   person['http://title'] = "Mr."
-  #   person['http://title'] = ["Mrs.", "Ms."]
+  #   person.write_attribute(:name, 'Bob')
   #
-  # @param [ String, RDF::URI ] predicate_uri The name of the attribute to update.
-  # @param [ Object, Array ] value The values to set for the attribute. Can be an array, or single item. They should compatible with RDF::Terms
-  def write_attribute(predicate_uri, objects)
-    raise Tripod::Errors::UriNotSet.new() unless @uri
-
-    # remove existing
-    remove_attribute(predicate_uri)
+  # @param [ String ] name The name of the field for which to set the value.
+  # @param [ String ] value The value to set it to
+  # @param [ Field ] field An optional Field object
+  def write_attribute(name, value, field=nil)
+    field ||= self.fields[name]
+    raise Tripod::Errors::FieldNotPresent.new unless field
 
-    # ... and replace
-    objects = [objects] unless objects.kind_of?(Array)
-    objects.each do |object|
-      @repository << RDF::Statement.new( @uri, RDF::URI.new(predicate_uri.to_s), object )
+    if value.kind_of?(Array)
+      if field.multivalued
+        new_val = []
+        value.each do |v|
+          new_val << self.class.new_value_for_field(v, field)
+        end
+      else
+        new_val = self.class.new_value_for_field(value.first, field)
+      end
+    else
+      new_val = self.class.new_value_for_field(value, field)
     end
 
-    # returns the new values
-    read_attribute(predicate_uri)
+    write_predicate(field.predicate, new_val)
   end
   alias :[]= :write_attribute
-
-  # Append the statement-values for a single predicate in this resource's in-memory repository. Basically just adds a new statement for this ((resource's uri)+predicate)
-  #
-  # @example Write the attribute.
-  #   person.append_to_attribute('http://title', "Mrs.")
-  #   person.append_to_attribute('http://title', "Ms.")
-  #
-  # @param [ String, RDF::URI ] predicate_uri The uri of the attribute to update.
-  # @param [ Object ] value The values to append for the attribute. Should compatible with RDF::Terms
-  def append_to_attribute(predicate_uri, object )
-    raise Tripod::Errors::UriNotSet.new() unless @uri
-
-    @repository << RDF::Statement.new(@uri, RDF::URI.new(predicate_uri.to_s), object)
-  end
-
-  def remove_attribute(predicate_uri)
-    @repository.query( [:subject, RDF::URI.new(predicate_uri.to_s), :object] ) do |statement|
-      @repository.delete( statement )
-    end
-  end
-  alias :delete :remove_attribute
-
 end

data/lib/tripod/components.rb

@@ -13,11 +13,13 @@ module Tripod::Components
   include ActiveModel::Naming
   include ActiveModel::Validations
 
+  include Tripod::Predicates
   include Tripod::Attributes
   include Tripod::Persistence
   include Tripod::Fields
   include Tripod::Finders
   include Tripod::Repository
+  include Tripod::Serialization
   include Tripod::State
 
 end

data/lib/tripod/errors.rb

@@ -1,4 +1,5 @@
 # encoding: utf-8
+require 'tripod/errors/field_not_present'
 require 'tripod/errors/resource_not_found'
 require 'tripod/errors/uri_not_set'
 require 'tripod/errors/validations'

data/lib/tripod/errors/field_not_present.rb

@@ -0,0 +1,8 @@
+# encoding: utf-8
+module Tripod::Errors
+
+  # field not present error.
+  class FieldNotPresent < StandardError
+  end
+
+end

data/lib/tripod/fields.rb

@@ -28,9 +28,8 @@ module Tripod::Fields
     #
     # @return [ Field ] The generated field
     def field(name, predicate, options = {})
-      named = name.to_s
       # TODO: validate the field params/options here..
-      add_field(named, predicate, options)
+      add_field(name, predicate, options)
     end
 
 
@@ -92,20 +91,7 @@ module Tripod::Fields
     def create_field_getter(name, meth, field)
       generated_methods.module_eval do
         re_define_method(meth) do
-
-          attr_values = read_attribute(field.predicate)
-
-          # We always return strings on way out.
-          # If the field is multivalued, return an array of the results
-          # If it's not multivalued, return the first (should be only) result.
-          if field.multivalued
-            attr_values.map do |v|
-              v.nil? ? nil : v.to_s
-            end
-          else
-            first_val = attr_values.first
-            first_val.nil? ? nil : first_val.to_s
-          end
+          read_attribute(name, field)
         end
       end
     end
@@ -121,20 +107,7 @@ module Tripod::Fields
     def create_field_setter(name, meth, field)
       generated_methods.module_eval do
         re_define_method("#{meth}=") do |value|
-          if value.kind_of?(Array)
-            if field.multivalued
-              new_val = []
-              value.each do |v|
-                new_val << self.class.new_value_for_field(v, field)
-              end
-            else
-              new_val = self.class.new_value_for_field(value.first, field)
-            end
-          else
-            new_val = self.class.new_value_for_field(value, field)
-          end
-
-          write_attribute(field.predicate, new_val)
+          write_attribute(name, value, field)
         end
       end
     end
@@ -149,7 +122,7 @@ module Tripod::Fields
     def create_field_check(name, meth, field)
       generated_methods.module_eval do
         re_define_method("#{meth}?") do
-          attr = read_attribute(field.predicate)
+          attr = read_attribute(name, field)
           attr == true || attr.present?
         end
       end

data/lib/tripod/finders.rb

@@ -6,30 +6,37 @@ module Tripod::Finders
 
   module ClassMethods
 
-    # Find a +Resource+ by its uri.
+    # Find a +Resource+ by its uri (and, optionally, by its graph if there are more than one).
     #
     # @example Find a single resource by a uri.
     #   Person.find('http://ric')
     #   Person.find(RDF::URI('http://ric'))
+    # @example Find a single resource by uri and graph
+    #   Person.find('http://ric', 'http://example.com/people')
+    #   Person.find(RDF::URI('http://ric'), Person.find(RDF::URI('http://example.com/people')))
     #
     # @param [ String, RDF::URI ] uri The uri of the resource to find
+    # @param [ String, RDF::URI ] graph_uri The uri of the graph from which to get the resource
     #
     # @raise [ Tripod::Errors::ResourceNotFound ] If no resource found.
     #
     # @return [ Resource ] A single resource
-    def find(uri)
-
-      # do a quick select to see what graph to use.
-      select_query = "SELECT ?g WHERE { GRAPH ?g {<#{uri.to_s}> ?p ?o } } LIMIT 1"
-      result = Tripod::SparqlClient::Query.select(select_query)
-      if result.length > 0
-        graph_uri_str = result[0]["g"]["value"]
-      else
-        raise Tripod::Errors::ResourceNotFound.new
+    def find(uri, graph_uri=nil)
+
+      unless graph_uri
+        # do a quick select to see what graph to use.
+        select_query = "SELECT ?g WHERE { GRAPH ?g {<#{uri.to_s}> ?p ?o } } LIMIT 1"
+        result = Tripod::SparqlClient::Query.select(select_query)
+        if result.length > 0
+          graph_uri = result[0]["g"]["value"]
+        else
+          raise Tripod::Errors::ResourceNotFound.new
+        end
       end
 
       # instantiate and hydrate the resource
-      resource = self.new(uri, graph_uri_str)
+      resource = self.new(uri, graph_uri.to_s)
+
       resource.hydrate!
       resource.new_record = false
 
@@ -90,7 +97,7 @@ module Tripod::Finders
           triples_repository.query( [RDF::URI.new(u), :predicate, :object] ) do |statement|
             data_graph << statement
           end
-          r.hydrate!(data_graph)
+          r.hydrate!(:graph => data_graph)
           r.new_record = false
           resources << r
         end

data/lib/tripod/persistence.rb

@@ -144,6 +144,18 @@ module Tripod::Persistence
     true
   end
 
+  def update_attribute(name, value)
+    write_attribute(name, value)
+    save
+  end
+
+  def update_attributes(attributes={})
+    attributes.each_pair do |name, value|
+      send "#{name}=", value
+    end
+    save
+  end
+
   module ClassMethods #:nodoc:
 
     # Raise an error if validation failed.

data/lib/tripod/predicates.rb

@@ -0,0 +1,78 @@
+# encoding: utf-8
+
+# This module defines behaviour for predicates.
+module Tripod::Predicates
+
+  extend ActiveSupport::Concern
+
+  # returns a list of predicates (as RDF::URIs) for this resource
+  def predicates
+    pred_uris = []
+    @repository.statements.each do |s|
+      pred_uris << s.predicate unless pred_uris.include?(s.predicate)
+    end
+    pred_uris
+  end
+
+  # Reads values from this resource's in-memory statement repository, where the predicate matches that of the uri passed in.
+  # Returns an Array of RDF::Terms object.
+  #
+  # @example Read the value associated with a predicate.
+  #   person.read_predicate('http://foo')
+  #   person.read_predicate(RDF::URI.new('http://foo'))
+  #
+  # @param [ String, RDF::URI ] uri The uri of the predicate to get.
+  #
+  # @return [ Array ] An array of RDF::Terms.
+  def read_predicate(predicate_uri)
+    values = []
+    @repository.query( [:subject, RDF::URI.new(predicate_uri.to_s), :object] ) do |statement|
+      values << statement.object
+    end
+    values
+  end
+
+  # Replace the statement-values for a single predicate in this resource's in-memory repository.
+  #
+  # @example Write the predicate.
+  #   person.write_predicate('http://title', "Mr.")
+  #   person.write_predicate('http://title', ["Mrs.", "Ms."])
+  #
+  # @param [ String, RDF::URI ] predicate_uri The name of the attribute to update.
+  # @param [ Object, Array ] value The values to set for the attribute. Can be an array, or single item. They should be compatible with RDF::Terms
+  def write_predicate(predicate_uri, objects)
+    # remove existing
+    remove_predicate(predicate_uri)
+
+    # ... and replace
+    objects = [objects] unless objects.kind_of?(Array)
+    objects.each do |object|
+      @repository << RDF::Statement.new( @uri, RDF::URI.new(predicate_uri.to_s), object )
+    end
+
+    # returns the new values
+    read_predicate(predicate_uri)
+  end
+
+  # Append the statement-values for a single predicate in this resource's in-memory repository. Basically just adds a new statement for this ((resource's uri)+predicate)
+  #
+  # @example Write the attribute.
+  #   person.append_to_predicate('http://title', "Mrs.")
+  #   person.append_to_predicate('http://title', "Ms.")
+  #
+  # @param [ String, RDF::URI ] predicate_uri The uri of the attribute to update.
+  # @param [ Object ] value The values to append for the attribute. Should compatible with RDF::Terms
+  def append_to_predicate(predicate_uri, object )
+    raise Tripod::Errors::UriNotSet.new() unless @uri
+
+    @repository << RDF::Statement.new(@uri, RDF::URI.new(predicate_uri.to_s), object)
+  end
+
+  def remove_predicate(predicate_uri)
+    @repository.query( [:subject, RDF::URI.new(predicate_uri.to_s), :object] ) do |statement|
+      @repository.delete( statement )
+    end
+  end
+  alias :delete :remove_predicate
+
+end