rdf 1.99.1 → 2.0.0.beta1

data/lib/rdf/mixin/enumerator.rb

@@ -7,6 +7,10 @@ module RDF
       include Queryable
       include Enumerable
 
+      def method_missing(method, *args)
+        self.to_a if method.to_sym == :to_ary
+      end
+
       # Make sure returned arrays are also queryable
       def to_a
         return super.to_a.extend(RDF::Queryable, RDF::Enumerable)
@@ -27,6 +31,10 @@ module RDF
       include Queryable
       include Enumerable
 
+      def method_missing(method, *args)
+        self.to_a if method.to_sym == :to_ary
+      end
+
       # Make sure returned arrays are also queryable
       def to_a
         return super.to_a.extend(RDF::Queryable, RDF::Enumerable)

data/lib/rdf/mixin/indexable.rb

@@ -18,7 +18,7 @@ module RDF
     # Indexes `self`.
     #
     # @abstract
-    # @return [void]
+    # @return [self]
     def index!
       raise NotImplementedError, "#{self.class}#index!"
     end

data/lib/rdf/mixin/mutable.rb

@@ -31,26 +31,20 @@ module RDF
     ##
     # Loads RDF statements from the given file or URL into `self`.
     #
-    # @param  [String, #to_s]          filename
+    # @param  [String, #to_s]          url
     # @param  [Hash{Symbol => Object}] options
     #   Options from {RDF::Reader.open}
-    # @option options [RDF::Resource] :context
-    #   Set set context of each loaded statement. This option is deprecated in RDF.rb 2.0.
     # @option options [RDF::Resource] :graph_name
     #   Set set graph name of each loaded statement
     # @return [void]
-    def load(filename, options = {})
-      if options.has_key?(:context)
-        warn "[DEPRECATION] the :contexts option to Mutable#load is deprecated in RDF.rb 2.0, use :graph_name instead. Called from #{Gem.location_of_caller.join(':')}"
-        options[:graph_name] ||= options.delete(:context)
-      end
+     def load(url, graph_name: nil, **options)
       raise TypeError.new("#{self} is immutable") if immutable?
 
-      Reader.open(filename, {base_uri: filename}.merge(options)) do |reader|
-        if options[:graph_name]
+      Reader.open(url, {base_uri: url}.merge(options)) do |reader|
+        if graph_name
           statements = []
           reader.each_statement do |statement|
-            statement.graph_name = options[:graph_name]
+            statement.graph_name = graph_name
             statements << statement
           end
           insert_statements(statements)
@@ -80,9 +74,20 @@ module RDF
     ##
     # Inserts RDF statements into `self`.
     #
-    # @param  [Array<RDF::Statement>] statements
-    # @raise  [TypeError] if `self` is immutable
-    # @return [Mutable]
+    # @note using splat argument syntax with excessive arguments provided
+    # significantly affects performance. Use Enumerator form for large
+    # numbers of statements.
+    #
+    # @overload insert(*statements)
+    #   @param  [Array<RDF::Statement>] statements
+    #   @raise  [TypeError] if `self` is immutable
+    #   @return [self]
+    #
+    # @overload insert(statements)
+    #   @param  [Enumerable<RDF::Statement>] statements
+    #   @raise  [TypeError] if `self` is immutable
+    #   @return [self]
+    #
     # @see    RDF::Writable#insert
     def insert(*statements)
       raise TypeError.new("#{self} is immutable") if immutable?
@@ -97,16 +102,30 @@ module RDF
     # `#delete([subject, predicate, nil])` followed by
     # `#insert([subject, predicate, object])` unless `object` is `nil`.
     #
-    # @param  [Enumerable<RDF::Statement>] statements
-    # @raise  [TypeError] if `self` is immutable
-    # @return [Mutable]
+    # @note using splat argument syntax with excessive arguments provided
+    # significantly affects performance. Use Enumerator form for large
+    # numbers of statements.
+    #
+    # @overload update(*statements)
+    #   @param  [Array<RDF::Statement>] statements
+    #   @raise  [TypeError] if `self` is immutable
+    #   @return [self]
+    #
+    # @overload update(statements)
+    #   @param  [Enumerable<RDF::Statement>] statements
+    #   @raise  [TypeError] if `self` is immutable
+    #   @return [self]
     def update(*statements)
       raise TypeError.new("#{self} is immutable") if immutable?
+      statements = statements[0] if statements.length == 1 && statements[0].is_a?(Enumerable)
 
       statements.each do |statement|
         if (statement = Statement.from(statement))
-          delete([statement.subject, statement.predicate, nil])
-          insert(statement) if statement.has_object?
+          if statement.has_object?
+            delete_insert([[statement.subject, statement.predicate, nil]], [statement])
+          else
+            delete([statement.subject, statement.predicate, nil])
+          end
         end
       end
     end
@@ -119,9 +138,19 @@ module RDF
     # considered to be a pattern, and used to query
     # self to find matching statements to delete.
     #
-    # @param  [Enumerable<RDF::Statement>] statements
-    # @raise  [TypeError] if `self` is immutable
-    # @return [Mutable]
+    # @note using splat argument syntax with excessive arguments provided
+    # significantly affects performance. Use Enumerator form for large
+    # numbers of statements.
+    #
+    # @overload delete(*statements)
+    #   @param  [Array<RDF::Statement>] statements
+    #   @raise  [TypeError] if `self` is immutable
+    #   @return [self]
+    #
+    # @overload delete(statements)
+    #   @param  [Enumerable<RDF::Statement>] statements
+    #   @raise  [TypeError] if `self` is immutable
+    #   @return [self]
     def delete(*statements)
       raise TypeError.new("#{self} is immutable") if immutable?
 
@@ -145,6 +174,56 @@ module RDF
 
     alias_method :delete!, :delete
 
+    ##
+    # Performs a set of deletes and inserts as a combined operation.
+    #
+    # @note in the base implementation, this is equivalent to calling `#delete` 
+    #   and `#insert` sequentially. This method is preferred to take advantage 
+    #   of (e.g.) `RDF::Repositories` that can execute the operation in a single
+    #   request.
+    #
+    # @param  [Enumerable<RDF::Statement>, Array<RDF::Statement>] deletes
+    # @param  [Enumerable<RDF::Statement>, Array<RDF::Statement>] inserts
+    # @raise  [TypeError] if `self` is immutable
+    # @return [Mutable] self
+    #
+    # @see #delete
+    # @see #insert
+    def delete_insert(deletes, inserts)
+      deletes.respond_to?(:each_statement) ? delete(deletes) : delete(*deletes)
+      inserts.respond_to?(:each_statement) ? insert(inserts) : insert(*inserts)
+
+      self
+    end
+
+    alias_method :delete_insert!, :delete_insert
+
+    ##
+    # Applies the given changeset
+    #
+    # If `#supports?(:atomic_write)` is `true`, this must apply the changeset
+    # atomically. Otherwise, it should offer an efficient implementation of a 
+    # combined delete/insert of the changeset.
+    #
+    # @param changeset [RDF::Changeset] the changeset to apply
+    # @return [Boolean] true if the changeset has been applied
+    def apply_changeset(changeset)
+      delete_insert(changeset.deletes, changeset.inserts)
+    end
+
+    ##
+    # A readable & queryable snapshot of the repository for isolated reads. 
+    # 
+    # This method must be implemented when `#supports(:snapshots)` is `true`.
+    # 
+    # @return [Dataset] an immutable Dataset containing a current snapshot of
+    #   the Repository contents.
+    # @raise [NotImplementederror] when snapshots aren't implemented for the
+    #   class
+    def snapshot
+      raise NotImplementedError, "#{self.class} does not implement snapshots"
+    end
+
     ##
     # Deletes all RDF statements from `self`.
     #

data/lib/rdf/mixin/queryable.rb

@@ -15,8 +15,7 @@ module RDF
     ##
     # Queries `self` for RDF statements matching the given `pattern`.
     #
-    # This method delegates to the protected {RDF::Queryable#query_pattern} method for the
-    # actual lower-level query pattern matching implementation.
+    # This method delegates to the protected {RDF::Queryable#query_pattern} method for the actual lower-level query pattern matching implementation.
     #
     # @example Querying for statements having a given predicate
     #     queryable.query([nil, RDF::Vocab::DOAP.developer, nil])
@@ -38,9 +37,10 @@ module RDF
     # @yieldparam  [RDF::Statement, RDF::Query::Solution] statement
     #   Statement or Solution
     # @yieldreturn [void] ignored
-    # @return [Enumerator, Query::Solutions]
-    #   Returns an enumerator over statements or query solutions, if passed an {RDF::Query}
+    # @return [Enumerator<RDF::Statement>, RDF::Enumerable, Query::Solutions]
+    #   Returns an enumerable of statements (may be an enumerator) or query solutions, if passed an {RDF::Query}
     # @see    RDF::Queryable#query_pattern
+    # @note   Since 2.0, this may return an Enumerable or an Enumerator in addition to Solutions
     def query(pattern, options = {}, &block)
       raise TypeError, "#{self} is not readable" if respond_to?(:readable?) && !readable?
 
@@ -50,11 +50,7 @@ module RDF
           solutions = RDF::Query::Solutions.new
           block = lambda {|solution| solutions << solution} unless block_given?
           before_query(pattern) if respond_to?(:before_query)
-          if method(:query_execute).arity == 1
-            query_execute(pattern, &block)
-          else
-            query_execute(pattern, options, &block)
-          end
+          query_execute(pattern, options, &block)
           after_query(pattern) if respond_to?(:after_query)
           # Returns the solutions, not an enumerator
           solutions
@@ -62,35 +58,36 @@ module RDF
         # A simple triple/quad pattern query:
         else
           pattern = Query::Pattern.from(pattern)
-          before_query(pattern) if block_given? && respond_to?(:before_query)
+          before_query(pattern) if respond_to?(:before_query)
           enum = case
             # Blank triple/quad patterns are equivalent to iterating over
             # every statement, so as a minor optimization we'll just do that
             # directly instead of bothering with `#query_pattern`:
             when pattern.blank?
-              each(&block) if block_given?
-              enum_for(:each)
+              if block_given?
+                each(&block)
+              else
+                to_a.extend(Queryable)
+              end
 
             # Constant triple/quad patterns are equivalent to looking up a
             # particular statement, so as a minor optimization we'll just do
             # that directly instead of bothering with `#query_pattern`:
             when pattern.constant?
               statement = Statement.from(pattern)
-              block.call(statement) if block_given? && include?(statement)
-              enum_for(:query, pattern)
-
-            # Otherwise, we delegate to `#query_pattern`:
-            else # pattern.variable?
-              if block_given?
-                if self.method(:query_pattern).arity == 1
-                  query_pattern(pattern, &block)
+              if include?(statement)
+                if block_given?
+                  yield statement
                 else
-                  query_pattern(pattern, options, &block)
+                  [statement]
                 end
               end
-              enum_for(:query_pattern, pattern)
+
+            # Otherwise, we delegate to `#query_pattern`:
+            else # pattern.variable?
+              query_pattern(pattern, options, &block)
           end
-          after_query(pattern) if block_given? && respond_to?(:after_query)
+          after_query(pattern) if respond_to?(:after_query)
           enum
       end
     end
@@ -193,8 +190,6 @@ module RDF
     # @overload first_subject(pattern)
     #   @param  [RDF::Query, RDF::Statement, Array(RDF::Term), Hash] pattern
     #   @return [RDF::Resource]
-    #
-    # @return [RDF::Resource]
     # @since  0.1.9
     def first_subject(pattern = nil)
       __send__(*(pattern ? [:query, pattern] : [:each])) do |statement|
@@ -215,8 +210,6 @@ module RDF
     # @overload first_predicate(pattern)
     #   @param  [RDF::Query, RDF::Statement, Array(RDF::Term), Hash] pattern
     #   @return [RDF::URI]
-    #
-    # @return [RDF::URI]
     # @since  0.1.9
     def first_predicate(pattern = nil)
       __send__(*(pattern ? [:query, pattern] : [:each])) do |statement|
@@ -237,8 +230,6 @@ module RDF
     # @overload first_object(pattern)
     #   @param  [RDF::Query, RDF::Statement, Array(RDF::Term), Hash] pattern
     #   @return [RDF::Term]
-    #
-    # @return [RDF::Term]
     # @since  0.1.9
     def first_object(pattern = nil)
       __send__(*(pattern ? [:query, pattern] : [:each])) do |statement|
@@ -283,8 +274,6 @@ module RDF
     # @overload first_value(pattern)
     #   @param  [RDF::Query, RDF::Statement, Array(RDF::Term), Hash] pattern
     #   @return [Object]
-    #
-    # @return [Object]
     # @since  0.1.9
     def first_value(pattern = nil)
       (literal = first_literal(pattern)) ? literal.value : nil
@@ -293,7 +282,7 @@ module RDF
     ##
     # @private
     # @param  [Symbol, #to_sym] method
-    # @return [Enumerator]
+    # @return [Enumerator<RDF::Statement, RDF::Query::Pattern>]
     # @see    Object#enum_for
     def enum_for(method = :each, *args)
       # Ensure that enumerators are, themselves, queryable

data/lib/rdf/mixin/transactable.rb

@@ -0,0 +1,94 @@
+module RDF
+  ##
+  # A transaction application mixin.
+  # 
+  # Classes that include this module must provide a `#begin_transaction` method
+  # returning an {RDF::Transaction}.
+  #
+  # @example running a read/write transaction with block syntax
+  #   repository = RDF::Repository.new # or other transactable
+  #
+  #   repository.transaction(mutable: true) do |tx|
+  #     tx.insert [:node, RDF.type, RDF::OWL.Thing]
+  #     # ...
+  #   end
+  #
+  # @see RDF::Transaction
+  # @since 2.0.0
+  module Transactable
+    ##
+    # Executes the given block in a transaction.
+    #
+    # @example running a transaction
+    #   repository.transaction do |tx|
+    #     tx.insert [RDF::URI("http://rubygems.org/gems/rdf"), RDF::RDFS.label, "RDF.rb"]
+    #   end
+    #
+    # Raising an error within the transaction block causes automatic rollback.
+    #
+    # @param mutable [Boolean] 
+    #   allows changes to the transaction, otherwise it is a read-only snapshot of the underlying repository.
+    # @yield  [tx]
+    # @yieldparam  [RDF::Transaction] tx
+    # @yieldreturn [void] ignored
+    # @return [self]
+    # @see    RDF::Transaction
+    # @since  0.3.0
+    def transaction(mutable: false, &block)
+      tx = begin_transaction(mutable: mutable)
+      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 mutable [Boolean] Create a mutable or immutable transaction.
+    # @param graph_name [Boolean] A default graph name for statements inserted
+    #   or deleted (default: nil)
+    # @return [RDF::Transaction]
+    def begin_transaction(mutable: false, graph_name: nil)
+      raise NotImplementedError
+    end
+
+    ##
+    # Rolls back the given transaction.
+    #
+    # @param  [RDF::Transaction] tx
+    # @return [void] ignored
+    # @since  0.3.0
+    def rollback_transaction(tx)
+      tx.rollback
+    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
+    end
+  end
+end

data/lib/rdf/mixin/writable.rb

@@ -21,7 +21,7 @@ module RDF
     # Inserts RDF data into `self`.
     #
     # @param  [RDF::Enumerable, RDF::Statement, #to_rdf] data
-    # @return [RDF::Writable] `self`
+    # @return [self]
     def <<(data)
       case data
         when RDF::Reader
@@ -46,8 +46,17 @@ module RDF
     ##
     # Inserts RDF statements into `self`.
     #
-    # @param  [Array<RDF::Statement>] statements
-    # @return [RDF::Writable] `self`
+    # @note using splat argument syntax with excessive arguments provided
+    # significantly affects performance. Use Enumerator form for large
+    # numbers of statements.
+    #
+    # @overload insert(*statements)
+    #   @param  [Array<RDF::Statement>] statements
+    #   @return [self]
+    #
+    # @overload insert(statements)
+    #   @param  [Enumerable<RDF::Statement>] statements
+    #   @return [self]
     def insert(*statements)
       statements.map! do |value|
         case