openlogic-rdf 0.3.6

data/lib/rdf/repository.rb

@@ -0,0 +1,389 @@
+module RDF
+  ##
+  # An RDF repository.
+  #
+  # @example Creating a transient in-memory repository
+  #   repository = RDF::Repository.new
+  #
+  # @example Checking whether a repository is readable/writable
+  #   repository.readable?
+  #   repository.writable?
+  #
+  # @example Checking whether a repository is persistent or transient
+  #   repository.persistent?
+  #   repository.transient?
+  #
+  # @example Checking whether a repository is empty
+  #   repository.empty?
+  #
+  # @example Checking how many statements a repository contains
+  #   repository.count
+  #
+  # @example Checking whether a repository contains a specific statement
+  #   repository.has_statement?(statement)
+  #
+  # @example Enumerating statements in a repository
+  #   repository.each_statement { |statement| statement.inspect! }
+  #
+  # @example Inserting statements into a repository
+  #   repository.insert(*statements)
+  #   repository.insert(statement)
+  #   repository.insert([subject, predicate, object])
+  #   repository << statement
+  #   repository << [subject, predicate, object]
+  #
+  # @example Deleting statements from a repository
+  #   repository.delete(*statements)
+  #   repository.delete(statement)
+  #   repository.delete([subject, predicate, object])
+  #
+  # @example Deleting all statements from a repository
+  #   repository.clear!
+  #
+  class Repository
+    include RDF::Countable
+    include RDF::Enumerable
+    include RDF::Queryable
+    include RDF::Mutable
+    include RDF::Durable
+
+    ##
+    # Returns the options passed to this repository when it was constructed.
+    #
+    # @return [Hash{Symbol => Object}]
+    attr_reader :options
+
+    ##
+    # Returns the {URI} of this repository.
+    #
+    # @return [URI]
+    attr_reader :uri
+    alias_method :url, :uri
+
+    ##
+    # Returns the title of this repository.
+    #
+    # @return [String]
+    attr_reader :title
+
+    ##
+    # Loads one or more RDF files into a new transient in-memory repository.
+    #
+    # @param  [String, Array<String>] filenames
+    # @param  [Hash{Symbol => Object}] options
+    #   Options from {RDF::Reader#initialize}, {RDF::Format.for} and {RDF::Repository#initialize}
+    # @yield  [repository]
+    # @yieldparam [Repository]
+    # @return [void]
+    def self.load(filenames, options = {}, &block)
+      self.new(options) do |repository|
+        [filenames].flatten.each do |filename|
+          repository.load(filename, options)
+        end
+
+        if block_given?
+          case block.arity
+            when 1 then block.call(repository)
+            else repository.instance_eval(&block)
+          end
+        end
+      end
+    end
+
+    ##
+    # Initializes this repository instance.
+    #
+    # @param  [Hash{Symbol => Object}] options
+    # @option options [URI, #to_s]    :uri (nil)
+    # @option options [String, #to_s] :title (nil)
+    # @yield  [repository]
+    # @yieldparam [Repository] repository
+    def initialize(options = {}, &block)
+      @options = options.dup
+      @uri     = @options.delete(:uri)
+      @title   = @options.delete(:title)
+
+      # Provide a default in-memory implementation:
+      send(:extend, Implementation) if self.class.equal?(RDF::Repository)
+
+      if block_given?
+        case block.arity
+          when 1 then block.call(self)
+          else instance_eval(&block)
+        end
+      end
+    end
+
+    ##
+    # Returns a developer-friendly representation of this object.
+    #
+    # @return [String]
+    def inspect
+      sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, uri.to_s)
+    end
+
+    ##
+    # Outputs a developer-friendly representation of this object to
+    # `stderr`.
+    #
+    # @return [void]
+    def inspect!
+      each_statement { |statement| statement.inspect! }
+      nil
+    end
+
+    ##
+    # Executes the given block in a transaction.
+    #
+    # @example
+    #   repository.transaction do |tx|
+    #     tx.insert [RDF::URI("http://rdf.rubyforge.org/"), RDF::DC.title, "RDF.rb"]
+    #   end
+    #
+    # @param  [RDF::Resource] context
+    # @yield  [tx]
+    # @yieldparam  [RDF::Transaction] tx
+    # @yieldreturn [void] ignored
+    # @return [void] `self`
+    # @see    RDF::Transaction
+    # @since  0.3.0
+    def transaction(context = nil, &block)
+      tx = begin_transaction(context)
+      begin
+        case block.arity
+          when 1 then block.call(tx)
+          else tx.instance_eval(&block)
+        end
+      rescue => error
+        rollback_transaction(tx)
+        raise error
+      end
+      commit_transaction(tx)
+      self
+    end
+    alias_method :transact, :transaction
+
+  protected
+
+    ##
+    # Begins a new transaction.
+    #
+    # Subclasses implementing transaction-capable storage adapters may wish
+    # to override this method in order to begin a transaction against the
+    # underlying storage.
+    #
+    # @param  [RDF::Resource] context
+    # @return [RDF::Transaction]
+    # @since  0.3.0
+    def begin_transaction(context)
+      RDF::Transaction.new(:context => context)
+    end
+
+    ##
+    # Rolls back the given transaction.
+    #
+    # Subclasses implementing transaction-capable storage adapters may wish
+    # to override this method in order to roll back the given transaction in
+    # the underlying storage.
+    #
+    # @param  [RDF::Transaction] tx
+    # @return [void] ignored
+    # @since  0.3.0
+    def rollback_transaction(tx)
+      # nothing to do
+    end
+
+    ##
+    # Commits the given transaction.
+    #
+    # Subclasses implementing transaction-capable storage adapters may wish
+    # to override this method in order to commit the given transaction to
+    # the underlying storage.
+    #
+    # @param  [RDF::Transaction] tx
+    # @return [void] ignored
+    # @since  0.3.0
+    def commit_transaction(tx)
+      tx.execute(self)
+    end
+
+    ##
+    # @see RDF::Repository
+    module Implementation
+      DEFAULT_CONTEXT = false
+
+      ##
+      # @private
+      def self.extend_object(obj)
+        obj.instance_variable_set(:@data, obj.options.delete(:data) || {})
+        super
+      end
+
+      ##
+      # @private
+      # @see RDF::Readable#supports?
+      def supports?(feature)
+        case feature.to_sym
+          when :context   then true   # statement contexts / named graphs
+          when :inference then false  # forward-chaining inference
+          else false
+        end
+      end
+
+      ##
+      # @private
+      # @see RDF::Durable#durable?
+      def durable?
+        false
+      end
+
+      ##
+      # @private
+      # @see RDF::Countable#empty?
+      def empty?
+        @data.empty?
+      end
+
+      ##
+      # @private
+      # @see RDF::Countable#count
+      def count
+        count = 0
+        @data.each do |c, ss|
+          ss.each do |s, ps|
+            ps.each do |p, os|
+              count += os.size
+            end
+          end
+        end
+        count
+      end
+
+      ##
+      # @private
+      # @see RDF::Enumerable#has_statement?
+      def has_statement?(statement)
+        s, p, o, c = statement.to_quad
+        c ||= DEFAULT_CONTEXT
+        @data.has_key?(c) &&
+          @data[c].has_key?(s) &&
+          @data[c][s].has_key?(p) &&
+          @data[c][s][p].include?(o)
+      end
+
+      ##
+      # @private
+      # @see RDF::Enumerable#each_statement
+      def each_statement(&block)
+        if block_given?
+          # Note that to iterate in a more consistent fashion despite
+          # possible concurrent mutations to `@data`, we use `#dup` to make
+          # shallow copies of the nested hashes before beginning the
+          # iteration over their keys and values.
+          @data.dup.each do |c, ss|
+            ss.dup.each do |s, ps|
+              ps.dup.each do |p, os|
+                os.dup.each do |o|
+                  block.call(RDF::Statement.new(s, p, o, :context => c.equal?(DEFAULT_CONTEXT) ? nil : c))
+                end
+              end
+            end
+          end
+        end
+        enum_statement
+      end
+      alias_method :each, :each_statement
+
+      ##
+      # @private
+      # @see RDF::Enumerable#has_context?
+      def has_context?(value)
+        @data.keys.include?(value)
+      end
+
+      ##
+      # @private
+      # @see RDF::Enumerable#each_context
+      def each_context(&block)
+        if block_given?
+          contexts = @data.keys
+          contexts.delete(DEFAULT_CONTEXT)
+          contexts.each(&block)
+        end
+        enum_context
+      end
+
+    protected
+
+      ##
+      # Match elements with eql?, not ==
+      # Context of `false` matches default context. Unbound variable matches non-false context
+      # @private
+      # @see RDF::Queryable#query
+      def query_pattern(pattern, &block)
+        context   = pattern.context
+        subject   = pattern.subject
+        predicate = pattern.predicate
+        object    = pattern.object
+
+        cs = @data.has_key?(context) ? {context => @data[context]} : @data.dup
+        cs.each do |c, ss|
+          next unless context.nil? || context == false && !c || context.eql?(c)
+          ss = ss.has_key?(subject) ? {subject => ss[subject]} : ss.dup
+          ss.each do |s, ps|
+            next unless subject.nil? || subject.eql?(s)
+            ps = ps.has_key?(predicate) ? {predicate => ps[predicate]} : ps.dup
+            ps.each do |p, os|
+              next unless predicate.nil? || predicate.eql?(p)
+              os = os.dup # TODO: is this really needed?
+              os.each do |o|
+                next unless object.nil? || object.eql?(o)
+                block.call(RDF::Statement.new(s, p, o, :context => c.equal?(DEFAULT_CONTEXT) ? nil : c))
+              end
+            end
+          end
+        end
+      end
+
+      ##
+      # @private
+      # @see RDF::Mutable#insert
+      def insert_statement(statement)
+        unless has_statement?(statement)
+          s, p, o, c = statement.to_quad
+          c ||= DEFAULT_CONTEXT
+          @data[c] ||= {}
+          @data[c][s] ||= {}
+          @data[c][s][p] ||= []
+          @data[c][s][p] << o
+        end
+      end
+
+      ##
+      # @private
+      # @see RDF::Mutable#delete
+      def delete_statement(statement)
+        if has_statement?(statement)
+          s, p, o, c = statement.to_quad
+          c ||= DEFAULT_CONTEXT
+          @data[c][s][p].delete(o)
+          @data[c][s].delete(p) if @data[c][s][p].empty?
+          @data[c].delete(s) if @data[c][s].empty?
+          @data.delete(c) if @data[c].empty?
+        end
+      end
+
+      ##
+      # @private
+      # @see RDF::Mutable#clear
+      def clear_statements
+        @data.clear
+      end
+
+      protected :query_pattern
+      protected :insert_statement
+      protected :delete_statement
+      protected :clear_statements
+    end # Implementation
+  end # Repository
+end # RDF

data/lib/rdf/transaction.rb

@@ -0,0 +1,161 @@
+module RDF
+  ##
+  # An RDF transaction.
+  #
+  # Transactions consist of a sequence of RDF statements to delete from and
+  # a sequence of RDF statements to insert into a given named graph.
+  #
+  # @example Executing a transaction against a repository
+  #   repository = ...
+  #   RDF::Transaction.execute(repository) do |tx|
+  #     subject = RDF::URI("http://example.org/article")
+  #     tx.delete [subject, RDF::DC.title, "Old title"]
+  #     tx.insert [subject, RDF::DC.title, "New title"]
+  #   end
+  #
+  # @since 0.3.0
+  class Transaction
+    include RDF::Mutable
+
+    ##
+    # Executes a transaction against the given RDF repository.
+    #
+    # @param  [RDF::Repository]         repository
+    # @param  [Hash{Symbol => Object}]  options
+    # @yield  [tx]
+    # @yieldparam [RDF::Transaction] tx
+    # @return [void]
+    def self.execute(repository, options = {}, &block)
+      self.new(&block).execute(repository, options)
+    end
+
+    ##
+    # RDF graph to modify when executed.
+    #
+    # @return [RDF::Resource]
+    attr_reader :graph
+
+    ##
+    # RDF statements to delete when executed.
+    #
+    # @return [RDF::Enumerable]
+    attr_reader :deletes
+
+    ##
+    # RDF statements to insert when executed.
+    #
+    # @return [RDF::Enumerable]
+    attr_reader :inserts
+
+    ##
+    # Any additional options for this transaction.
+    #
+    # @return [Hash{Symbol => Object}]
+    attr_reader :options
+
+    ##
+    # Initializes this transaction.
+    #
+    # @param  [Hash{Symbol => Object}]  options
+    # @option options [RDF::Resource]   :graph  (nil)
+    # @option options [RDF::Enumerable] :insert (RDF::Graph.new)
+    # @option options [RDF::Enumerable] :delete (RDF::Graph.new)
+    # @yield  [tx]
+    # @yieldparam [RDF::Transaction] tx
+    def initialize(options = {}, &block)
+      @options = options.dup
+      @graph   = @options.delete(:graph)  || @options.delete(:context)
+      @inserts = @options.delete(:insert) || RDF::Graph.new
+      @deletes = @options.delete(:delete) || RDF::Graph.new
+      @inserts.extend(RDF::Enumerable) unless @inserts.kind_of?(RDF::Enumerable)
+      @deletes.extend(RDF::Enumerable) unless @deletes.kind_of?(RDF::Enumerable)
+
+      if block_given?
+        case block.arity
+          when 1 then block.call(self)
+          else instance_eval(&block)
+        end
+      end
+    end
+
+    ##
+    # Returns `false` to indicate that this transaction is append-only.
+    #
+    # Transactions do not support the `RDF::Enumerable` protocol directly.
+    # To enumerate the RDF statements to be inserted or deleted, use the
+    # {#inserts} and {#deletes} accessors.
+    #
+    # @return [Boolean]
+    # @see    RDF::Readable#readable?
+    def readable?
+      false
+    end
+
+    ##
+    # Executes this transaction against the given RDF repository.
+    #
+    # @param  [RDF::Repository]         repository
+    # @param  [Hash{Symbol => Object}]  options
+    # @return [void]
+    def execute(repository, options = {})
+      before_execute(repository, options) if respond_to?(:before_execute)
+
+      deletes.each_statement do |statement|
+        statement = statement.dup
+        statement.context = graph
+        repository.delete(statement)
+      end
+
+      inserts.each_statement do |statement|
+        statement = statement.dup
+        statement.context = graph
+        repository.insert(statement)
+      end
+
+      after_execute(repository, options) if respond_to?(:after_execute)
+      self
+    end
+
+    ##
+    # Returns a developer-friendly representation of this transaction.
+    #
+    # @return [String]
+    def inspect
+      sprintf("#<%s:%#0x(graph: %s, deletes: %d, inserts: %d)>", self.class.name, __id__,
+        graph ? graph.to_s : 'nil', deletes.count, inserts.count)
+    end
+
+    ##
+    # Outputs a developer-friendly representation of this transaction to
+    # `stderr`.
+    #
+    # @return [void]
+    def inspect!
+      warn(inspect)
+    end
+
+    ##
+    # Appends an RDF statement to the sequence to insert when executed.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [void]
+    # @see    RDF::Writable#insert_statement
+    def insert_statement(statement)
+      inserts << statement
+    end
+
+    ##
+    # Appends an RDF statement to the sequence to delete when executed.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [void]
+    # @see    RDF::Mutable#delete_statement
+    def delete_statement(statement)
+      deletes << statement
+    end
+
+    undef_method :load, :update, :clear
+    protected :insert_statement
+    protected :delete_statement
+  end # Transaction
+end # RDF

data/lib/rdf/util/aliasing.rb

@@ -0,0 +1,63 @@
+module RDF; module Util
+  module Aliasing
+    ##
+    # Helpers for late-bound instance method aliasing.
+    #
+    # Anything that extends this module will obtain an `alias_method` class
+    # method that creates late-bound instance method aliases instead of the
+    # default early-bound aliases created by Ruby's `Module#alias_method`.
+    #
+    # This is useful because RDF.rb mixins typically alias a number of
+    # overridable methods. For example, `RDF::Enumerable#count` has the
+    # aliases `#size` and `#length`. Normally if implementing classes were
+    # to override the default method, the aliased methods would still be
+    # bound to the mixin's original reference implementation rather than the
+    # new overridden method. Mixing in this module into the implementing
+    # class fixes this problem.
+    #
+    # @example Using late-bound aliasing in a module
+    #   module MyModule
+    #     extend RDF::Util::Aliasing::LateBound
+    #   end
+    #
+    # @example Using late-bound aliasing in a class
+    #   class MyClass
+    #     extend RDF::Util::Aliasing::LateBound
+    #   end
+    #
+    # @see   http://en.wikipedia.org/wiki/Name_binding
+    # @since 0.2.0
+    module LateBound
+      ##
+      # Makes `new_name` a late-bound alias of the method `old_name`.
+      #
+      # @example Aliasing the `#count` method to `#size` and `#length`
+      #   alias_method :size,   :count
+      #   alias_method :length, :count
+      #
+      # @param  [Symbol, #to_sym] new_name
+      # @param  [Symbol, #to_sym] old_name
+      # @return [void]
+      # @see    http://ruby-doc.org/core/classes/Module.html#M001653
+      def alias_method(new_name, old_name)
+        new_name, old_name = new_name.to_sym, old_name.to_sym
+
+        class_eval(<<-EOF)
+          def #{new_name}(*args, &block)
+            #{old_name}(*args, &block)
+          end
+        EOF
+
+        # NOTE: the following eval-less (and hence slightly less evil)
+        # implementation only works on Ruby 1.8.7+ due to the |&block|
+        # syntax that was introduced in 1.9 and then backported to 1.8.7;
+        # it is a syntax error in earlier versions of Ruby:
+        #self.__send__(:define_method, new_name) do |*args, &block|
+        #  __send__(old_name, *args, &block)
+        #end
+
+        return self
+      end
+    end # LateBound
+  end # Aliasing
+end; end # RDF::Util