rdf-do 0.2.0

data/README.md

@@ -0,0 +1,48 @@
+# RDF::DataObjects
+
+DataObjects-backed RDF.rb repository, aiming for a simple use case and
+currently targeting SQLite and Postgres.  It passes its specs with Heroku's
+database.
+
+This was written for a tutorial, and is thus a pretty naive implementation:
+RDF::DataObjects stores triples in a simple subject, predicate, object, context
+table.  Don't try to back a big website with it yet.  Nonetheless, it works.
+
+Example:
+    repository = RDF::DataObjects::Repository.new "sqlite3:test.db"
+    repository.insert(statement)
+    repository.count              #=> 1
+    repository.delete(statement)
+
+You can use any DataObjects compatible connection options, but only SQLite3 and
+Postgres are implemented for now.  The different databases are *just* different
+enough with their handling of unique constraints that some database-specific
+work is required, but it's not much.
+
+## Installation:
+
+The greatly preferred installation method is via RubyGems:
+
+    $ sudo gem install rdf-do
+
+Manual downloads are available at <http://github.com/bhuga/rdf-do/downloads>
+
+## Connecting:
+  
+    repo = RDF::DataObjects::Repository.new "postgres://localhost/database"
+    repo = RDF::DataObjects::Repository.new "sqlite3:test.db"
+
+
+## Using:
+
+Your repository is a fully-functional RDF.rb `RDF::Repository`.  As with any
+RDF.rb repository, this includes the mixins `RDF::Enumerable`, `RDF::Mutable`,
+`RDF::Durable`, and `RDF::Queryable`.  Please see <http://rdf.rubyforge.org> for
+more information.
+
+### Miscellany
+
+ * Author: Ben Lavender <blavender@gmail.com> <http://bhuga.net> <http://blog.datagraph.org>
+ * 'License':  RDF::DataObjects is free and unemcumbered software released into the public domain.  For more information, see the included UNLICENSE file.
+
+

data/UNLICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <http://unlicense.org/>

data/VERSION

@@ -0,0 +1 @@
+0.2.0

data/lib/rdf/do/adapters/defaults.rb

@@ -0,0 +1,68 @@
+require 'rdf/ntriples'
+
+module RDF::DataObjects
+  module Adapters
+
+    ## 
+    # Default SQL statements and methods for RDF::DataObjects::Repository::Adapters.
+    module Defaults
+
+      def count_sql
+        'select count(*) from quads'
+      end
+
+      def insert_sql
+        'REPLACE INTO `quads` (subject, predicate, object, context) VALUES (?, ?, ?, ?)'
+      end
+
+      def delete_sql
+        'DELETE FROM `quads` where (subject = ? AND predicate = ? AND object = ? AND context = ?)'
+      end
+
+      def each_sql
+        'select * from quads'
+      end
+
+      def each_subject_sql
+        'select subject from quads'
+      end
+
+      def each_predicate_sql
+        'select predicate from quads'
+      end
+
+      def each_object_sql
+        'select object from quads'
+      end
+
+      def each_context_sql
+        'select context from quads'
+      end
+
+      ##
+      # Perform a query on an RDF::DataObjects::Repository based on a hash of components.
+      #
+      # This is meant to be called by RDF::DataObjects::Repository.
+      #
+      # @example
+      #     adapter.query(repository, :predicate => predicate)
+      # @return [DataObjects::Result]
+      def query(repository, hash = {})
+        return repository.result(each_sql) if hash.empty?
+        conditions = []
+        params = []
+        [:subject, :predicate, :object, :context].each do |resource|
+          unless hash[resource].nil?
+            conditions << "#{resource.to_s} = ?"
+            params     << repository.serialize(hash[resource])
+          end
+        end
+        where = conditions.empty? ? "" : "WHERE "
+        where << conditions.join(' AND ')
+        repository.result('select * from quads ' + where, *params)
+      end
+
+    end
+  end
+end
+

data/lib/rdf/do/adapters/postgres.rb

@@ -0,0 +1,44 @@
+require 'rdf/do/adapters/defaults'
+
+module RDF::DataObjects
+  module Adapters
+
+    ##
+    # Postgres Adapter for RDF::DataObjects.
+    #
+    class Postgres
+      
+      self.extend Defaults
+
+      ##
+      # Indempotently migrate this database.
+      #
+      # @param [RDF::DataObjects::Repository]
+      # @return [void]
+      def self.migrate?(do_repository, opts = {})
+        begin do_repository.exec('CREATE TABLE quads (subject varchar(255), predicate varchar(255), object varchar(255), context varchar(255), UNIQUE (subject, predicate, object, context))') rescue nil end
+        begin do_repository.exec('CREATE INDEX quads_context_index ON quads (context)') rescue nil end
+        begin do_repository.exec('CREATE INDEX quads_object_index ON quads (object)') rescue nil end
+        begin do_repository.exec('CREATE INDEX quads_predicate_index ON quads (predicate)') rescue nil end
+        begin do_repository.exec('CREATE INDEX quads_subject_index ON quads (subject)') rescue nil end
+        do_repository.exec('CREATE OR REPLACE RULE "insert_ignore" AS ON INSERT TO quads WHERE EXISTS(SELECT true FROM quads WHERE subject = NEW.subject AND predicate = NEW.predicate AND object = NEW.object AND context = NEW.context) DO INSTEAD NOTHING;')
+      end
+
+      # SQL prepared statement for insertions
+      #
+      # @return [String]
+      def self.insert_sql
+        'insert into quads (subject, predicate, object, context) VALUES (?, ?, ?, ?)'
+      end
+
+      # SQL prepared statement for deletions
+      #
+      # @return [String]
+      def self.delete_sql 
+        "DELETE FROM quads where (subject = ? AND predicate = ? AND object = ? AND context = ?)"
+      end
+
+    end
+  end
+end
+

data/lib/rdf/do/adapters/sqlite3.rb

@@ -0,0 +1,25 @@
+require 'rdf/do/adapters/defaults'
+
+module RDF::DataObjects
+  module Adapters
+    class Sqlite3
+
+      self.extend Defaults
+
+      ##
+      # Indempotently migrate this database
+      #
+      # @param [RDF::DataObjects::Repository]
+      # @return [void]
+      def self.migrate?(do_repository, opts = {})
+        do_repository.exec('CREATE TABLE IF NOT EXISTS quads (`subject` varchar(255), `predicate` varchar(255), `object` varchar(255), `context` varchar(255), UNIQUE (`subject`, `predicate`, `object`, `context`))')
+        begin do_repository.exec('CREATE INDEX `quads_context_index` ON `quads` (`context`)') rescue nil end
+        begin do_repository.exec('CREATE INDEX `quads_object_index` ON `quads` (`object`)') rescue nil end
+        begin do_repository.exec('CREATE INDEX `quads_predicate_index` ON `quads` (`predicate`)') rescue nil end
+        begin do_repository.exec('CREATE INDEX `quads_subject_index` ON `quads` (`subject`)') rescue nil end
+      end
+
+    end
+  end
+end
+

data/lib/rdf/do.rb

@@ -0,0 +1,369 @@
+require 'data_objects'
+require 'rdf/ntriples'
+require 'enumerator'
+
+module RDF
+
+  ##
+  # RDF::DataObjects offers an RDF::Repository which is backed by a DataObjects
+  # connection.  All inserts and deletes to this repository are done in real
+  # time; no flushing is required.
+  #
+  # Each RDF::DataObjects::Repository includes an RDF::DataObjects::Adapter, such as
+  # RDF::DataObjects::Adapters::Sqlite3.
+  #
+  # @see RDF::DataObjects::Adapters
+  # @see RDF::Repository
+  module DataObjects
+
+    ##
+    # RDF::DataObjects::Repository is an RDF::Repository is backed by a
+    # DataObjects connection.
+    #
+    class Repository < RDF::Repository
+
+      ## Create a new RDF::DataObjects::Repository
+      # 
+      # The `options` parameter can be anything that
+      # DataObjects::Connection.new accepts.  The correct
+      # RDF::Repository::DataObjects adapter will be loaded based on the URI
+      # scheme of the created connection.
+      #
+      # @example
+      #     RDF::DataObjects::Repository.new  # => new Repository based on sqlite3://:memory:
+      #     RDF::DataObjects::Repository.new 'postgres://localhost/database'  # => New repository based on postgres adapter
+      # @param [Any] options
+      # @return [RDF::DataObjects::Repository]
+      def initialize(options = {})
+        begin
+          case options
+            when String
+              @db     = ::DataObjects::Connection.new(options)
+            when Hash
+              @db     = ::DataObjects::Connection.new(options[:db])
+              adapter = options[:adapter]
+            when nil
+              @db    = ::DataObjects::Connection.new('sqlite3://:memory:')
+          end
+          adapter = @db.instance_variable_get("@uri").scheme
+          require 'rdf/do/adapters/' + adapter.to_s
+        rescue Exception => e
+          raise LoadError, "Could not load a DataObjects adapter for #{options}.  You may need to add a 'require do_adapter', or you may be trying to use an unsupported adapter (Currently supporting postgres, sqlite3).  The error message was: #{e.message}"
+        end
+        @adapter = RDF::DataObjects::Adapters::const_get(adapter.to_s.capitalize)
+        @adapter.migrate? self
+      end
+
+      ##
+      # Close and dispose of this connection.
+      #
+      # @return [void]
+      def dispose
+        close
+        @db.dispose
+      end
+
+      ##
+      # Close this connection.
+      #
+      # @return [void]
+      def close
+        @db.close
+        @adapter = nil
+      end
+
+      ##
+      # Returns true if this repository is empty.
+      #
+      # @see RDF::Enumerable#empty
+      # @return [Boolean]
+      def empty?
+        count == 0
+      end
+
+      ##
+      # Insert a single statement into this repository.
+      #
+      # @see RDF::Mutable#insert_statement
+      # @param [RDF::Statement]
+      # @return [void]
+      def insert_statement(statement)
+        insert *[statement]
+      end
+
+      ##
+      # Delete a single statement from this repository.
+      #
+      # @see RDF::Mutable#delete_statement
+      # @param [RDF::Statement]
+      # @return [void]
+      def delete_statement(statement)
+        delete *[statement]
+      end
+
+      def insert(*statements)
+        query = @adapter.insert_sql
+        statements.each do |s|
+          exec(query,serialize(s. subject),serialize(s.predicate), serialize(s.object), serialize(s.context)) 
+        end
+      end
+
+      def delete(*statements)
+        query = @adapter.delete_sql
+        statements.each do |s|
+          exec(query,serialize(s. subject),serialize(s.predicate), serialize(s.object), serialize(s.context)) 
+        end
+      end
+
+      ## 
+      # Serialize an RDF::Value into N-triples format.
+      # Nil values will be encoded as 'nil' to avoid problems with SQL
+      # implementations considering null values as distinct from one another.
+      #
+      # @see RDF::DataObjects::Repository#unserialize
+      # @param [RDF::Value]
+      # @return [String]
+      def serialize(value)
+        value.nil? ? 'nil' : RDF::NTriples::Writer.serialize(value)
+      end
+
+      ##
+      # Unserialize an RDF::Value from N-triples format.
+      # Expects nil values to be encoded as 'nil'.
+      #
+      # @see RDF::DataObjects::Repository#serialize
+      # @param [String]
+      # @return [RDF::Value]
+      def unserialize(value)
+        value == 'nil' ? nil : RDF::NTriples::Reader.unserialize(value)
+      end
+     
+      ##
+      # Execute the given non-query SQL with the given arguments against this
+      # repository's DataObjects::Connection.
+      #
+      # If the given sql is in a prepared statement format, it will be executed
+      # with the given *args.
+      #
+      # @param [String] sql
+      # @param [*RDF::Value] args
+      def exec(sql, *args)
+        @db.create_command(sql).execute_non_query(*args)
+      end
+
+      ##
+      # Execute the given query SQL with the given arguments against this
+      # repository's DataObjects::Connection.
+      #
+      # If the given sql is in a prepared statement format, it will be executed
+      # with the given *args.
+      #
+      # @param [String] sql
+      # @param [*RDF::Value] args
+      def result(sql, *args)
+        @db.create_command(sql).execute_reader(*args)
+      end
+
+      ##
+      # Helper method to handle the block/enumerator handling for each/each_subject/each_object, etc.
+      #
+      # Will call the given method with the given block is one is given.
+      # Will return an enumerator with the given method called as a block if no block is given.
+      #
+      # @param [Symbol] method
+      # @param [Proc] &block
+      # @return [Enumerable::Enumerator, void]
+      # @nodoc
+      # @private
+      def each_or_enumerator(method, &block)
+        if block_given?
+          self.send(method, &block)
+        else
+          ::Enumerable::Enumerator.new(self,:each_or_enumerator)
+        end
+      end
+
+      ##
+      # Implementation of #each
+      #
+      # @nodoc
+      # @private
+      # @return [void]
+      # @see RDF::Enumerable#each
+      # @see RDF::DataObjects::Repository#each_or_enumerator
+      def each_block(&block)
+        reader = result(@adapter.each_sql)
+        while reader.next!
+          block.call(RDF::Statement.new(
+                      :subject   => unserialize(reader.values[0]),
+                      :predicate => unserialize(reader.values[1]),
+                      :object    => unserialize(reader.values[2]),
+                      :context   => unserialize(reader.values[3])))
+        end
+      end
+
+      ##
+      # Iterate over all RDF::Statements in this repository.
+      #
+      # @see RDF::Enumerable#each
+      # @param [Proc] &block
+      # @return [Enumerable::Enumerator, void]
+      def each(&block)
+        each_or_enumerator(:each_block, &block)
+      end
+
+      ##
+      # Iterate over all RDF::Resource subjects in this repository.
+      #
+      # @see RDF::Enumerable#each_subject
+      # @param [Proc] &block
+      # @return [Enumerable::Enumerator, void]
+      def each_subject(&block)
+        each_or_enumerator(:subject_block, &block)
+      end
+
+      ##
+      # Implementation of #each_subject
+      #
+      # @nodoc
+      # @private
+      # @return [void]
+      # @see RDF::Enumerable#each_subject
+      # @see RDF::DataObjects::Repository#each_or_enumerator
+      def subject_block(&block)
+        reader = result(@adapter.each_subject_sql)
+        while reader.next!
+          block.call(unserialize(reader.values[0]))
+        end
+      end
+
+      ##
+      # Iterate over all RDF::Resource predicates in this repository.
+      #
+      # @see RDF::Enumerable#each_predicate
+      # @param [Proc] &block
+      # @return [Enumerable::Enumerator, void]
+      def each_predicate(&block)
+        each_or_enumerator(:predicate_block, &block)
+      end
+
+      ##
+      # Implementation of #each_predicate
+      #
+      # @nodoc
+      # @private
+      # @return [void]
+      # @see RDF::Enumerable#each_predicate
+      # @see RDF::DataObjects::Repository#each_or_enumerator
+      def predicate_block(&block)
+        reader = result(@adapter.each_predicate_sql)
+        while reader.next!
+          block.call(unserialize(reader.values[0]))
+        end
+      end
+
+      ##
+      # Iterate over all RDF::Value objects in this repository.
+      #
+      # @see RDF::Enumerable#each_object
+      # @param [Proc] &block
+      # @return [Enumerable::Enumerator, void]
+      def each_object(&block)
+        each_or_enumerator(:object_block, &block)
+      end
+
+      ##
+      # Implementation of #each_object
+      #
+      # @nodoc
+      # @private
+      # @return [void]
+      # @see RDF::Enumerable#each_object
+      # @see RDF::DataObjects::Repository#each_or_enumerator
+      def object_block(&block)
+        reader = result(@adapter.each_object_sql)
+        while reader.next!
+          block.call(unserialize(reader.values[0]))
+        end
+      end
+
+      ##
+      # Iterate over all RDF::Resource contexts in this repository.
+      #
+      # @see RDF::Enumerable#each_context
+      # @param [Proc] &block
+      # @return [Enumerable::Enumerator, void]
+      def each_context(&block)
+        each_or_enumerator(:context_block, &block)
+      end
+
+      ##
+      # Implementation of #each_context
+      #
+      # @nodoc
+      # @private
+      # @return [void]
+      # @see RDF::Enumerable#each_context
+      # @see RDF::DataObjects::Repository#each_or_enumerator
+      def context_block(&block)
+        reader = result(@adapter.each_context_sql)
+        while reader.next!
+          context = unserialize(reader.values[0])
+          block.call(context) unless context.nil?
+        end
+      end
+
+      ## Implementation of RDF::Queryable#query
+      #  
+      # This implementation will do well for statements and hashes, and not so
+      # well for RDF::Query objects.
+      # 
+      # Accepts a query pattern argument as in RDF::Queryable.  See
+      # {RDF::Queryable} for more information.
+      #
+      # @param [RDF::Statement, Hash, Array] pattern
+      # @return [RDF::Enumerable, void]  
+      # @see RDF::Queryable#query
+      def query(pattern, &block)
+        case pattern
+          when RDF::Statement
+            query(pattern.to_hash)
+          when Array
+            query(RDF::Statement.new(*pattern))
+          when Hash
+            statements = []
+            reader = @adapter.query(self,pattern)
+            while reader.next!
+              statements << RDF::Statement.new(
+                      :subject   => unserialize(reader.values[0]),
+                      :predicate => unserialize(reader.values[1]),
+                      :object    => unserialize(reader.values[2]),
+                      :context   => unserialize(reader.values[3]))
+            end
+            case block_given?
+              when true
+                statements.each(&block)
+              else
+                statements.extend(RDF::Enumerable, RDF::Queryable)
+            end
+          else
+            super(pattern) 
+        end
+
+      end
+
+      ##
+      # The number of statements in this repository
+      # 
+      # @see RDF::Enumerable#count
+      # @return [Integer]
+      def count
+        result = result(@adapter.count_sql)
+        result.next!
+        result.values.first
+      end
+
+    end
+  end
+end
+

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification 
+name: rdf-do
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 2
+  - 0
+  version: 0.2.0
+platform: ruby
+authors: 
+- Ben Lavender
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-04-02 00:00:00 +02:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rdf
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 1
+        - 3
+        version: 0.1.3
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: rdf-spec
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 1
+        - 0
+        version: 0.1.0
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 3
+        - 0
+        version: 1.3.0
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: yard
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        - 5
+        - 3
+        version: 0.5.3
+  type: :development
+  version_requirements: *id004
+description: RDF.rb plugin for DataObjects-backed repositories
+email: blavender@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- UNLICENSE
+- VERSION
+- lib/rdf/do/adapters/defaults.rb
+- lib/rdf/do/adapters/postgres.rb
+- lib/rdf/do/adapters/sqlite3.rb
+- lib/rdf/do.rb
+has_rdoc: false
+homepage: http://rdf.rubyforge.org/
+licenses: 
+- Public Domain
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 1
+      - 8
+      - 2
+      version: 1.8.2
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: rdf
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: RDF.rb plugin for DataObjects-backed repositories
+test_files: []
+