openlogic-rdf 0.3.6

data/lib/rdf/mixin/mutable.rb

@@ -0,0 +1,191 @@
+module RDF
+  ##
+  # Classes that include this module must implement the methods
+  # `#insert_statement`, `#delete_statement` and `#each_statement`.
+  #
+  # @see RDF::Graph
+  # @see RDF::Repository
+  module Mutable
+    extend  RDF::Util::Aliasing::LateBound
+    include RDF::Readable
+    include RDF::Writable
+
+    ##
+    # Returns `true` if `self` is mutable.
+    #
+    # @return [Boolean]
+    # @see    #immutable?
+    def mutable?
+      writable?
+    end
+
+    ##
+    # Returns `true` if `self` is immutable.
+    #
+    # @return [Boolean]
+    # @see    #mutable?
+    def immutable?
+      !mutable?
+    end
+
+    ##
+    # Loads RDF statements from the given file or URL into `self`.
+    #
+    # @param  [String, #to_s]          filename
+    # @param  [Hash{Symbol => Object}] options
+    # @return [void]
+    def load(filename, options = {})
+      raise TypeError.new("#{self} is immutable") if immutable?
+
+      Reader.open(filename, {:base_uri => filename}.merge(options)) do |reader|
+        if options[:context]
+          statements = []
+          reader.each_statement do |statement|
+            statement.context = options[:context]
+            statements << statement
+          end
+          insert_statements(statements)
+          statements.size
+        else
+          insert_statements(reader)
+          nil
+        end
+      end
+    end
+
+    alias_method :load!, :load
+
+    ##
+    # Inserts RDF data into `self`.
+    #
+    # @param  [RDF::Enumerable, RDF::Statement, #to_rdf] data
+    # @raise  [TypeError] if `self` is immutable
+    # @return [Mutable]
+    # @see    RDF::Writable#<<
+    def <<(data)
+      raise TypeError.new("#{self} is immutable") if immutable?
+
+      super # RDF::Writable#<<
+    end
+
+    ##
+    # Inserts RDF statements into `self`.
+    #
+    # @param  [Array<RDF::Statement>] statements
+    # @raise  [TypeError] if `self` is immutable
+    # @return [Mutable]
+    # @see    RDF::Writable#insert
+    def insert(*statements)
+      raise TypeError.new("#{self} is immutable") if immutable?
+
+      super # RDF::Writable#insert
+    end
+
+    ##
+    # Updates RDF statements in `self`.
+    #
+    # `#update([subject, predicate, object])` is equivalent to
+    # `#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]
+    def update(*statements)
+      raise TypeError.new("#{self} is immutable") if immutable?
+
+      statements.each do |statement|
+        if (statement = Statement.from(statement))
+          delete([statement.subject, statement.predicate, nil])
+          insert(statement) if statement.has_object?
+        end
+      end
+    end
+
+    alias_method :update!, :update
+
+    ##
+    # Deletes RDF statements from `self`.
+    #
+    # @param  [Enumerable<RDF::Statement>] statements
+    # @raise  [TypeError] if `self` is immutable
+    # @return [Mutable]
+    def delete(*statements)
+      raise TypeError.new("#{self} is immutable") if immutable?
+
+      statements.map! do |value|
+        case
+          when value.respond_to?(:each_statement)
+            delete_statements(value)
+            nil
+          when (statement = Statement.from(value)).valid?
+            statement
+          else
+            delete_statements(query(value))
+            nil
+        end
+      end
+      statements.compact!
+      delete_statements(statements) unless statements.empty?
+
+      return self
+    end
+
+    alias_method :delete!, :delete
+
+    ##
+    # Deletes all RDF statements from `self`.
+    #
+    # @raise  [TypeError] if `self` is immutable
+    # @return [Mutable]
+    def clear
+      raise TypeError.new("#{self} is immutable") if immutable?
+
+      if respond_to?(:clear_statements)
+        clear_statements
+      else
+        delete_statements(self)
+      end
+
+      return self
+    end
+
+    alias_method :clear!, :clear
+
+  protected
+
+    ##
+    # Deletes the given RDF statements from the underlying storage.
+    #
+    # Defaults to invoking {#delete_statement} for each given statement.
+    #
+    # Subclasses of {RDF::Repository} may wish to override this method if
+    # they are capable of more efficiently deleting multiple statements at
+    # once.
+    #
+    # @param  [RDF::Enumerable] statements
+    # @return [void]
+    def delete_statements(statements)
+      each = statements.respond_to?(:each_statement) ? :each_statement : :each
+      statements.__send__(each) do |statement|
+        delete_statement(statement)
+      end
+    end
+
+    ##
+    # Deletes an RDF statement from the underlying storage.
+    #
+    # Subclasses of {RDF::Repository} must implement this method, except if
+    # they are immutable.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [void]
+    # @abstract
+    def delete_statement(statement)
+      raise NotImplementedError.new("#{self.class}#delete_statement")
+    end
+
+    protected :delete_statements
+    protected :delete_statement
+  end
+end

data/lib/rdf/mixin/queryable.rb

@@ -0,0 +1,265 @@
+module RDF
+  ##
+  # An RDF query mixin.
+  #
+  # Classes that include this module should implement a `#query_pattern` method that
+  # yields {RDF::Statement RDF statements}. Classes may also implement an optimized
+  # `#query_execute` method that yields {RDF::Statement RDF statements}.
+  #
+  # @see RDF::Graph
+  # @see RDF::Repository
+  module Queryable
+    include ::Enumerable
+
+    ##
+    # Queries `self` for RDF statements matching the given `pattern`.
+    #
+    # This method delegates to the protected {#query_pattern} method for the
+    # actual lower-level query pattern matching implementation.
+    #
+    # @example
+    #     queryable.query([nil, RDF::DOAP.developer, nil])
+    #     queryable.query(:predicate => RDF::DOAP.developer)
+    #
+    # @param  [RDF::Query, RDF::Statement, Array(RDF::Term), Hash] pattern
+    # @yield  [statement]
+    #   each matching statement
+    # @yieldparam  [RDF::Statement] statement
+    # @yieldreturn [void] ignored
+    # @return [Enumerator]
+    # @see    RDF::Queryable#query_pattern
+    def query(pattern, &block)
+      raise TypeError, "#{self} is not readable" if respond_to?(:readable?) && !readable?
+
+      case pattern
+        # A basic graph pattern (BGP) query:
+        when Query
+          if block_given?
+            before_query(pattern) if respond_to?(:before_query)
+            query_execute(pattern, &block)
+            after_query(pattern) if respond_to?(:after_query)
+          end
+          enum_for(:query_execute, pattern)
+
+        # A simple triple/quad pattern query:
+        else
+          pattern = Query::Pattern.from(pattern)
+          before_query(pattern) if block_given? && 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)
+
+            # 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?
+              query_pattern(pattern, &block) if block_given?
+              enum_for(:query_pattern, pattern)
+          end
+          after_query(pattern) if block_given? && respond_to?(:after_query)
+          enum.extend(RDF::Queryable, RDF::Enumerable, RDF::Countable)
+          def enum.to_a
+            super.extend(RDF::Queryable, RDF::Enumerable, RDF::Countable)
+          end
+          enum
+      end
+    end
+
+    ##
+    # Queries `self` using the given basic graph pattern (BGP) query,
+    # yielding each matched solution to the given block.
+    #
+    # Since RDF.rb 0.3.0, repository implementations can override this
+    # method in order to provide for storage-specific optimized graph
+    # pattern query execution.
+    #
+    # @param  [RDF::Query] query
+    #   the query to execute
+    # @yield  [solution]
+    # @yieldparam  [RDF::Query::Solution] solution
+    # @yieldreturn [void] ignored
+    # @return [void] ignored
+    # @see    RDF::Queryable#query
+    # @see    RDF::Query#execute
+    # @since  0.3.0
+    def query_execute(query, &block)
+      # By default, we let RDF.rb's built-in `RDF::Query#execute` handle BGP
+      # query execution by breaking down the query into its constituent
+      # triple patterns and invoking `RDF::Query::Pattern#execute` on each
+      # pattern.
+      query.execute(self).each(&block)
+    end
+    protected :query_execute
+
+    ##
+    # Queries `self` for RDF statements matching the given `pattern`,
+    # yielding each matched statement to the given block.
+    #
+    # Since RDF.rb 0.2.0, repository implementations should override this
+    # method in order to provide for storage-specific optimized triple
+    # pattern matching.
+    #
+    # @param  [RDF::Query::Pattern] pattern
+    #   the query pattern to match
+    # @yield  [statement]
+    # @yieldparam  [RDF::Statement] statement
+    # @yieldreturn [void] ignored
+    # @return [void] ignored
+    # @see    RDF::Queryable#query
+    # @see    RDF::Query::Pattern#execute
+    # @since  0.2.0
+    def query_pattern(pattern, &block)
+      # By default, we let Ruby's built-in `Enumerable#grep` handle the
+      # matching of statements by iterating over all statements and calling
+      # `RDF::Query::Pattern#===` on each statement.
+      # @see http://ruby-doc.org/core/classes/Enumerable.html#M003121
+      grep(pattern, &block)
+    end
+    protected :query_pattern
+
+    ##
+    # Queries `self` for an RDF statement matching the given `pattern` and
+    # returns that statement if found.
+    #
+    # Returns `nil` if no statements match `pattern`.
+    #
+    # @overload first
+    #   @return [RDF::Statement]
+    #
+    # @overload first(pattern)
+    #   @param  [RDF::Query, RDF::Statement, Array(RDF::Term), Hash] pattern
+    #   @return [RDF::Statement]
+    #
+    # @return [RDF::Statement]
+    # @since  0.1.9
+    def first(pattern = nil)
+      if pattern
+        query(pattern) do |statement|
+          return statement
+        end
+        return nil
+      else
+        super()
+      end
+    end
+
+    ##
+    # Queries `self` for an RDF statement matching the given `pattern` and
+    # returns the statement's subject term.
+    #
+    # Returns `nil` if no statements match `pattern`.
+    #
+    # @overload first_subject
+    #   @return [RDF::Resource]
+    #
+    # @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|
+        return statement.subject
+      end
+      return nil
+    end
+
+    ##
+    # Queries `self` for an RDF statement matching the given `pattern` and
+    # returns the statement's predicate term.
+    #
+    # Returns `nil` if no statements match `pattern`.
+    #
+    # @overload first_predicate
+    #   @return [RDF::URI]
+    #
+    # @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|
+        return statement.predicate
+      end
+      return nil
+    end
+
+    ##
+    # Queries `self` for an RDF statement matching the given `pattern` and
+    # returns the statement's object term.
+    #
+    # Returns `nil` if no statements match `pattern`.
+    #
+    # @overload first_object
+    #   @return [RDF::Term]
+    #
+    # @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|
+        return statement.object
+      end
+      return nil
+    end
+
+    ##
+    # Queries `self` for RDF statements matching the given `pattern` and
+    # returns the first found object literal.
+    #
+    # Returns `nil` if no statements match `pattern` or if none of the found
+    # statements have a literal as their object term.
+    #
+    # @overload first_literal
+    #   @return [RDF::Literal]
+    #
+    # @overload first_literal(pattern)
+    #   @param  [RDF::Query, RDF::Statement, Array(RDF::Term), Hash] pattern
+    #   @return [RDF::Literal]
+    #
+    # @return [RDF::Literal]
+    # @since  0.1.9
+    def first_literal(pattern = nil)
+      __send__(*(pattern ? [:query, pattern] : [:each])) do |statement|
+        return statement.object if statement.object.is_a?(RDF::Literal)
+      end
+      return nil
+    end
+
+    ##
+    # Queries `self` for RDF statements matching the given `pattern` and
+    # returns the value of the first found object literal.
+    #
+    # Returns `nil` if no statements match `pattern` or if none of the found
+    # statements have a literal as their object term.
+    #
+    # @overload first_value
+    #   @return [Object]
+    #
+    # @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
+    end
+  end # Queryable
+end # RDF

data/lib/rdf/mixin/readable.rb

@@ -0,0 +1,15 @@
+module RDF
+  ##
+  module Readable
+    extend RDF::Util::Aliasing::LateBound
+
+    ##
+    # Returns `true` if `self` is readable.
+    #
+    # @return [Boolean]
+    # @see    RDF::Writable#writable?
+    def readable?
+      true
+    end
+  end
+end

data/lib/rdf/mixin/type_check.rb

@@ -0,0 +1,21 @@
+module RDF
+  ##
+  # An RDF type check mixin.
+  #
+  # This module implements #raise_error, which will raise TypeError.
+  #
+  # @see RDF::Value
+  # @see RDF::Literal
+  # @see RDF::Literal
+  module TypeCheck
+    ##
+    # Default implementation of type_error, which returns false.
+    # Classes including RDF::TypeCheck will raise TypeError
+    # instead.
+    #
+    # @raise [TypeError]
+    def type_error(message)
+      raise TypeError, message
+    end
+  end # TypeCheck
+end # RDF

data/lib/rdf/mixin/writable.rb

@@ -0,0 +1,152 @@
+module RDF
+  ##
+  # Classes that include this module must implement the methods
+  # `#insert_statement`.
+  #
+  # @see RDF::Graph
+  # @see RDF::Repository
+  module Writable
+    extend RDF::Util::Aliasing::LateBound
+
+    ##
+    # Returns `true` if `self` is writable.
+    #
+    # @return [Boolean] `true` or `false`
+    # @see    RDF::Readable#readable?
+    def writable?
+      true
+    end
+
+    ##
+    # Inserts RDF data into `self`.
+    #
+    # @param  [RDF::Enumerable, RDF::Statement, #to_rdf] data
+    # @return [RDF::Writable] `self`
+    def <<(data)
+      case data
+        when RDF::Reader
+          insert_reader(data)
+        when RDF::Graph
+          insert_graph(data)
+        when RDF::Enumerable
+          insert_statements(data)
+        when RDF::Statement
+          insert_statement(data)
+        else case
+          when data.respond_to?(:to_rdf) && !data.equal?(rdf = data.to_rdf)
+            self << rdf
+          else
+            insert_statement(Statement.from(data))
+        end
+      end
+
+      return self
+    end
+
+    ##
+    # Inserts RDF statements into `self`.
+    #
+    # @param  [Array<RDF::Statement>] statements
+    # @return [RDF::Writable] `self`
+    def insert(*statements)
+      statements.map! do |value|
+        case
+          when value.respond_to?(:each_statement)
+            insert_statements(value)
+            nil
+          when (statement = Statement.from(value)).valid?
+            statement
+          else
+            raise ArgumentError.new("not a valid statement: #{value.inspect}")
+        end
+      end
+      statements.compact!
+      insert_statements(statements) unless statements.empty?
+
+      return self
+    end
+    alias_method :insert!, :insert
+
+  protected
+
+    ##
+    # Inserts statements from the given RDF reader into the underlying
+    # storage or output stream.
+    #
+    # Defaults to passing the reader to the {#insert_statements} method.
+    #
+    # Subclasses of {RDF::Repository} may wish to override this method in
+    # case their underlying storage can efficiently import RDF data directly
+    # in particular serialization formats, thus avoiding the intermediate
+    # parsing overhead.
+    #
+    # @param  [RDF::Reader] reader
+    # @return [void]
+    # @since  0.2.3
+    def insert_reader(reader)
+      insert_statements(reader)
+    end
+
+    ##
+    # Inserts the given RDF graph into the underlying storage or output
+    # stream.
+    #
+    # Defaults to passing the graph to the {#insert_statements} method.
+    #
+    # Subclasses of {RDF::Repository} may wish to override this method in
+    # case their underlying storage architecture is graph-centric rather
+    # than statement-oriented.
+    #
+    # Subclasses of {RDF::Writer} may wish to override this method if the
+    # output format they implement supports named graphs, in which case
+    # implementing this method may help in producing prettier and more
+    # concise output.
+    #
+    # @param  [RDF::Graph] graph
+    # @return [void]
+    def insert_graph(graph)
+      insert_statements(graph)
+    end
+
+    ##
+    # Inserts the given RDF statements into the underlying storage or output
+    # stream.
+    #
+    # Defaults to invoking {#insert_statement} for each given statement.
+    #
+    # Subclasses of {RDF::Repository} may wish to override this method if
+    # they are capable of more efficiently inserting multiple statements at
+    # once.
+    #
+    # Subclasses of {RDF::Writer} don't generally need to implement this
+    # method.
+    #
+    # @param  [RDF::Enumerable] statements
+    # @return [void]
+    # @since  0.1.6
+    def insert_statements(statements)
+      each = statements.respond_to?(:each_statement) ? :each_statement : :each
+      statements.__send__(each) do |statement|
+        insert_statement(statement)
+      end
+    end
+
+    ##
+    # Inserts an RDF statement into the underlying storage or output stream.
+    #
+    # Subclasses of {RDF::Repository} must implement this method, except if
+    # they are immutable.
+    #
+    # Subclasses of {RDF::Writer} must implement this method.
+    #
+    # @param  [RDF::Statement] statement
+    # @return [void]
+    # @abstract
+    def insert_statement(statement)
+      raise NotImplementedError.new("#{self.class}#insert_statement")
+    end
+
+    protected :insert_statements
+    protected :insert_statement
+  end # Writable
+end # RDF