tripod 0.0.3 → 0.0.4

data/README.md

@@ -1,13 +1,69 @@
 # Tripod
 
-ActiveModel-style Ruby ORM for RDF data.
+ActiveModel-style Ruby ORM for RDF Linked Data. Works with SPARQL 1.1 HTTP endpoints.
 
-    gem install tripod
+## Quick start, for using in a rails app.
 
-[Documentation](http://rubydoc.info/github/Swirrl/tripod/master/frames)
+1. Install the gem:
+
+        gem install tripod
+
+2. Add it to your Gemfile
+
+        gem tripod
+
+3. Configure it (in application.rb, or development.rb/production.rb/test.rb)
+
+        # (values shown are the defaults)
+        Tripod.configure do |config|
+          config.update_endpoint = 'http://127.0.0.1:3030/tripod/update'
+          config.query_endpoint = 'http://127.0.0.1:3030/tripod/sparql'
+          config.timeout_seconds = 30
+        end
+
+4. Include it in your model classes.
+
+        class Person
+          include Tripod::Resource
+
+          field :name, 'http://name'
+          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
+        end
+
+        # Note: Active Model validations are supported
+
+5. Use it
+
+        uri = 'http://ric'
+        graph = 'http://people'
+        p = Person.new(uri, graph)
+        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!
+
+        people = Person.where("
+          SELECT ?person ?graph
+          WHERE {
+            GRAPH ?graph {
+              ?person ?p ?o .
+              ?person a <http://person> .
+            }
+          }",
+        :uri_variable => 'person' )
+        # => returns an array of Person objects, containing all data we know about them.
+
+        ric = Person.find('http://ric')
+        # => returns a single Person object.
+
+[Full Documentation](http://rubydoc.info/github/Swirrl/tripod/master/frames)
 
 __Warning: Work still in progress / experimental. Not production ready!__
 
-Heavily inspired by [Durran Jordan's](https://github.com/durran) excellent [Mongoid](http://mongoid.org/en/mongoid/) ORM for [MongoDB](http://www.mongodb.org/).
+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).
 
 Copyright (c) 2012 [Swirrl IT Limited](http://swirrl.com). Released under MIT License

data/lib/tripod/finders.rb

@@ -40,5 +40,57 @@ module Tripod::Finders
       resource
     end
 
+    # Find a collection of +Resource+s by a SPARQL select statement which returns their uris.
+    # Under the hood, this only executes two queries: a select, then a describe.
+    #
+    # @example
+    #   Person.where('SELECT ?uri ?graph WHERE { GRAPH ?graph { ?uri ?p ?o } } LIMIT 3')
+    #
+    # @param [ String ] criteria. A sparql query which returns a list of uris of the objects.
+    # @param [ Hash ] opts. A hash of options.
+    #
+    # @option options [ String ] uri_variable The name of the uri variable in thh query, if not 'uri'
+    # @option options [ String ] graph_variable The name of the uri variable in thh query, if not 'graph'
+    #
+    # @return [ Array ] An array of hydrated resources of this class's type.
+    def where(criteria, opts={})
+
+      # 1. Run the select.
+      select_results = Tripod::SparqlClient::Query.select(criteria)
+
+      data = {}
+
+      select_results.each do |r|
+        uri_variable = opts[:uri_variable] || 'uri'
+        graph_variable = opts[:graph_variable] || 'graph'
+        data[ r[uri_variable]["value"] ] = r[graph_variable]["value"]
+      end
+
+      uris_sparql_str = data.keys.map{ |u| "<#{u}>" }.join(" ")
+
+      # 2. Do a big describe statement, and read the results into an in-memory repo
+      triples = Tripod::SparqlClient::Query::describe("DESCRIBE #{uris_sparql_str}")
+      triples_repository = RDF::Repository.new()
+      RDF::Reader.for(:ntriples).new(triples) do |reader|
+        reader.each_statement do |statement|
+          triples_repository << statement
+        end
+      end
+
+      resources = []
+      # 3. for each of our uris, make a resource, with a graph of triples for that uri from the in-mem repo
+      data.each_pair do |u,g|
+        r = self.new(u,g)
+        data_graph = RDF::Graph.new
+        triples_repository.query( [RDF::URI.new(u), :predicate, :object] ) do |statement|
+          data_graph << statement
+        end
+        r.hydrate!(data_graph)
+        resources << r
+      end
+
+      resources
+
+    end
   end
 end

data/lib/tripod/version.rb

@@ -1,3 +1,3 @@
 module Tripod
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

data/spec/tripod/finders_spec.rb

@@ -68,4 +68,29 @@ describe Tripod::Finders do
 
   end
 
+  describe '.where' do
+
+    before do
+      # save these into the db
+      bill
+      ric
+    end
+
+    it 'returns an array of resources which match those in the db' do
+      res = Person.where('SELECT ?uri ?graph WHERE { GRAPH ?graph { ?uri ?p ?o } }')
+      res.length.should == 2
+      res.first.should == ric
+      res.last.should == bill
+
+      res.first.name.should == "ric"
+      res.first['http://knows'].should == [RDF::URI.new("http://bill")]
+    end
+
+    it 'uses the uri and graph variables if supplied' do
+      res = Person.where('SELECT ?bob ?geoff WHERE { GRAPH ?geoff { ?bob ?p ?o } }', :uri_variable => 'bob', :graph_variable => 'geoff')
+      res.length.should == 2
+    end
+
+  end
+
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tripod
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -13,7 +13,7 @@ date: 2012-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rest-client
-  requirement: &70124707968440 !ruby/object:Gem::Requirement
+  requirement: &70121805448680 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -21,10 +21,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70124707968440
+  version_requirements: *70121805448680
 - !ruby/object:Gem::Dependency
   name: activemodel
-  requirement: &70124707967900 !ruby/object:Gem::Requirement
+  requirement: &70121805448140 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -32,10 +32,10 @@ dependencies:
         version: '3.1'
   type: :runtime
   prerelease: false
-  version_requirements: *70124707967900
+  version_requirements: *70121805448140
 - !ruby/object:Gem::Dependency
   name: equivalent-xml
-  requirement: &70124707967480 !ruby/object:Gem::Requirement
+  requirement: &70121805447720 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -43,10 +43,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70124707967480
+  version_requirements: *70121805447720
 - !ruby/object:Gem::Dependency
   name: rdf
-  requirement: &70124707966940 !ruby/object:Gem::Requirement
+  requirement: &70121805447180 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ~>
@@ -54,10 +54,10 @@ dependencies:
         version: '0.3'
   type: :runtime
   prerelease: false
-  version_requirements: *70124707966940
+  version_requirements: *70121805447180
 - !ruby/object:Gem::Dependency
   name: rdf-rdfxml
-  requirement: &70124707966520 !ruby/object:Gem::Requirement
+  requirement: &70121805446760 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,10 +65,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70124707966520
+  version_requirements: *70121805446760
 - !ruby/object:Gem::Dependency
   name: rdf-n3
-  requirement: &70124707966060 !ruby/object:Gem::Requirement
+  requirement: &70121805446300 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -76,10 +76,10 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70124707966060
+  version_requirements: *70121805446300
 - !ruby/object:Gem::Dependency
   name: rdf-json
-  requirement: &70124707965640 !ruby/object:Gem::Requirement
+  requirement: &70121805445880 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -87,7 +87,7 @@ dependencies:
         version: '0'
   type: :runtime
   prerelease: false
-  version_requirements: *70124707965640
+  version_requirements: *70121805445880
 description: RDF ruby ORM
 email:
 - ric@swirrl.com