rdf 0.2.3 → 0.3.0.pre

data/lib/rdf/reader.rb

@@ -1,14 +1,17 @@
 module RDF
   ##
-  # An RDF parser.
+  # The base class for RDF parsers.
+  #
+  # @example Loading an RDF reader implementation
+  #   require 'rdf/ntriples'
   #
   # @example Iterating over known RDF reader classes
   #   RDF::Reader.each { |klass| puts klass.name }
   #
   # @example Obtaining an RDF reader class
   #   RDF::Reader.for(:ntriples)     #=> RDF::NTriples::Reader
-  #   RDF::Reader.for("spec/data/test.nt")
-  #   RDF::Reader.for(:file_name      => "spec/data/test.nt")
+  #   RDF::Reader.for("etc/doap.nt")
+  #   RDF::Reader.for(:file_name      => "etc/doap.nt")
   #   RDF::Reader.for(:file_extension => "nt")
   #   RDF::Reader.for(:content_type   => "text/plain")
   #
@@ -16,14 +19,14 @@ module RDF
   #   RDF::Reader.for(:ntriples).new($stdin) { |reader| ... }
   #
   # @example Parsing RDF statements from a file
-  #   RDF::Reader.open("spec/data/test.nt") do |reader|
+  #   RDF::Reader.open("etc/doap.nt") do |reader|
   #     reader.each_statement do |statement|
   #       puts statement.inspect
   #     end
   #   end
   #
   # @example Parsing RDF statements from a string
-  #   data = StringIO.new(File.read("spec/data/test.nt"))
+  #   data = StringIO.new(File.read("etc/doap.nt"))
   #   RDF::Reader.for(:ntriples).new(data) do |reader|
   #     reader.each_statement do |statement|
   #       puts statement.inspect
@@ -35,14 +38,15 @@ module RDF
   # @see RDF::Writer
   class Reader
     extend  ::Enumerable
+    extend  RDF::Util::Aliasing::LateBound
     include RDF::Readable
-    include ::Enumerable
+    include RDF::Enumerable # @since 0.3.0
 
     ##
     # Enumerates known RDF reader classes.
     #
     # @yield  [klass]
-    # @yieldparam [Class]
+    # @yieldparam [Class] klass
     # @return [Enumerator]
     def self.each(&block)
       @@subclasses.each(&block)
@@ -99,63 +103,192 @@ module RDF
     end
 
     ##
-    # @param  [String] filename
+    # Parses input from the given file name or URL.
+    #
+    # @param  [String, #to_s] filename
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options (see {RDF::Reader#initialize})
     # @option options [Symbol] :format (:ntriples)
     # @yield  [reader]
-    # @yieldparam [Reader]
-    # @raise  [FormatError] if no reader available for the specified format
+    # @yieldparam  [RDF::Reader] reader
+    # @yieldreturn [void] ignored
+    # @raise  [RDF::FormatError] if no reader found for the specified format
     def self.open(filename, options = {}, &block)
-      if reader = self.for(options[:format] || filename)
-        Kernel.open(filename, 'rb') do |file|
+      Util::File.open_file(filename, options) do |file|
+        reader = self.for(options[:format]) if options[:format]
+        content_type = file.content_type if file.respond_to?(:content_type)
+        reader ||= self.for(options.merge(:file_name => filename, :content_type => content_type))
+        if reader
           reader.new(file, options, &block)
+        else
+          raise FormatError, "unknown RDF format: #{options[:format] || {:file_name => filename, :content_type => content_type}.inspect}"
         end
-      else
-        raise FormatError.new("unknown RDF format: #{options[:format] || filename}")
       end
     end
 
     ##
+    # Initializes the reader.
+    #
     # @param  [IO, File, String] input
-    # @yield  [reader]
-    # @yieldparam [Reader] reader
+    #   the input stream to read
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options
+    # @option options [Encoding] :encoding     (Encoding::UTF_8)
+    #   the encoding of the input stream (Ruby 1.9+)
+    # @option options [Boolean]  :validate     (false)
+    #   whether to validate the parsed statements and values
+    # @option options [Boolean]  :canonicalize (false)
+    #   whether to canonicalize parsed literals
+    # @option options [Boolean]  :intern       (true)
+    #   whether to intern all parsed URIs
+    # @option options [Hash]     :prefixes     (Hash.new)
+    #   the prefix mappings to use (not supported by all readers)
+    # @option options [#to_s]    :base_uri     (nil)
+    #   the base URI to use when resolving relative URIs (not supported by
+    #   all readers)
+    # @yield  [reader] `self`
+    # @yieldparam  [RDF::Reader] reader
+    # @yieldreturn [void] ignored
     def initialize(input = $stdin, options = {}, &block)
-      @options = options
-      @nodes   = {}
-      @input   = case input
+      @options = options.dup
+      @options[:validate]     ||= false
+      @options[:canonicalize] ||= false
+      @options[:intern]       ||= true
+      @options[:prefixes]     ||= Hash.new
+
+      @input = case input
         when String then StringIO.new(input)
         else input
       end
-      block.call(self) if block_given?
+
+      if block_given?
+        case block.arity
+          when 0 then instance_eval(&block)
+          else block.call(self)
+        end
+      end
     end
 
     ##
-    # @yield  [statement]
-    # @yieldparam [Statement]
-    # @return [Reader]
-    def each(&block)
-      each_statement(&block)
+    # Any additional options for this reader.
+    #
+    # @return [Hash]
+    # @since  0.3.0
+    attr_reader :options
+
+    ##
+    # Returns the URI prefixes currently defined for this reader.
+    #
+    # @example
+    #   reader.prefixes[:dc]  #=> RDF::URI('http://purl.org/dc/terms/')
+    #
+    # @return [Hash{Symbol => RDF::URI}]
+    # @since  0.3.0
+    def prefixes
+      @options[:prefixes] ||= {}
     end
 
     ##
-    # @yield  [statement]
-    # @yieldparam [Statement]
-    # @return [Enumerator]
+    # Defines the given URI prefixes for this reader.
+    #
+    # @example
+    #   reader.prefixes = {
+    #     :dc => RDF::URI('http://purl.org/dc/terms/'),
+    #   }
+    #
+    # @param  [Hash{Symbol => RDF::URI}] prefixes
+    # @return [Hash{Symbol => RDF::URI}]
+    # @since  0.3.0
+    def prefixes=(prefixes)
+      @options[:prefixes] = prefixes
+    end
+
+    ##
+    # Defines the given named URI prefix for this reader.
+    #
+    # @example Defining a URI prefix
+    #   reader.prefix :dc, RDF::URI('http://purl.org/dc/terms/')
+    #
+    # @example Returning a URI prefix
+    #   reader.prefix(:dc)    #=> RDF::URI('http://purl.org/dc/terms/')
+    #
+    # @overload prefix(name, uri)
+    #   @param  [Symbol, #to_s]   name
+    #   @param  [RDF::URI, #to_s] uri
+    #
+    # @overload prefix(name)
+    #   @param  [Symbol, #to_s]   name
+    #
+    # @return [RDF::URI]
+    def prefix(name, uri = nil)
+      name = name.respond_to?(:to_sym) ? name.to_sym : name.to_s.to_sym
+      uri.nil? ? prefixes[name] : prefixes[name] = RDF::URI(uri)
+    end
+    alias_method :prefix!, :prefix
+
+    ##
+    # Iterates the given block for each RDF statement.
+    #
+    # If no block was given, returns an enumerator.
+    #
+    # Statements are yielded in the order that they are read from the input
+    # stream.
+    #
+    # @overload each_statement
+    #   @yield  [statement]
+    #     each statement
+    #   @yieldparam  [RDF::Statement] statement
+    #   @yieldreturn [void] ignored
+    #   @return [void]
+    #
+    # @overload each_statement
+    #   @return [Enumerator]
+    #
+    # @return [void]
+    # @see    RDF::Enumerable#each_statement
     def each_statement(&block)
-      begin
-        loop { block.call(read_statement) }
-      rescue EOFError => e
+      if block_given?
+        begin
+          loop { block.call(read_statement) }
+        rescue EOFError => e
+          rewind rescue nil
+        end
       end
+      enum_for(:each_statement)
     end
+    alias_method :each, :each_statement
 
     ##
-    # @yield  [triple]
-    # @yieldparam [Array(RDF::Value)]
-    # @return [Enumerator]
+    # Iterates the given block for each RDF triple.
+    #
+    # If no block was given, returns an enumerator.
+    #
+    # Triples are yielded in the order that they are read from the input
+    # stream.
+    #
+    # @overload each_triple
+    #   @yield  [subject, predicate, object]
+    #     each triple
+    #   @yieldparam  [RDF::Resource] subject
+    #   @yieldparam  [RDF::URI]      predicate
+    #   @yieldparam  [RDF::Value]    object
+    #   @yieldreturn [void] ignored
+    #   @return [void]
+    #
+    # @overload each_triple
+    #   @return [Enumerator]
+    #
+    # @return [void]
+    # @see    RDF::Enumerable#each_triple
     def each_triple(&block)
-      begin
-        loop { block.call(*read_triple) }
-      rescue EOFError => e
+      if block_given?
+        begin
+          loop { block.call(*read_triple) }
+        rescue EOFError => e
+          rewind rescue nil
+        end
       end
+      enum_for(:each_triple)
     end
 
     ##
@@ -167,10 +300,13 @@ module RDF
     def rewind
       @input.rewind
     end
+    alias_method :rewind!, :rewind
 
     ##
-    # Closes the input stream. An `IOError` is raised for further read
-    # attempts.
+    # Closes the input stream, after which an `IOError` will be raised for
+    # further read attempts.
+    #
+    # If the input stream is already closed, does nothing.
     #
     # @return [void]
     # @since  0.2.2
@@ -178,93 +314,145 @@ module RDF
     def close
       @input.close unless @input.closed?
     end
+    alias_method :close!, :close
 
-    protected
+  protected
 
-      ##
-      # @raise [NotImplementedError] unless implemented in subclass
-      def read_statement
-        Statement.new(*read_triple)
-      end
+    ##
+    # Reads a statement from the input stream.
+    #
+    # @return [RDF::Statement] a statement
+    # @raise  [NotImplementedError] unless implemented in subclass
+    # @abstract
+    def read_statement
+      Statement.new(*read_triple)
+    end
 
-      ##
-      # @raise [NotImplementedError] unless implemented in subclass
-      def read_triple
-        raise NotImplementedError.new("#{self.class}#read_triple") # override in subclasses
-      end
+    ##
+    # Reads a triple from the input stream.
+    #
+    # @return [Array(RDF::Value)] a triple
+    # @raise  [NotImplementedError] unless implemented in subclass
+    # @abstract
+    def read_triple
+      raise NotImplementedError, "#{self.class}#read_triple" # override in subclasses
+    end
 
-      ##
-      # @raise [ReaderError]
-      def fail_subject
-        raise RDF::ReaderError, "expected subject in #{@input.inspect} line #{lineno}"
-      end
+    ##
+    # Raises an "expected subject" parsing error on the current line.
+    #
+    # @return [void]
+    # @raise  [RDF::ReaderError]
+    def fail_subject
+      raise RDF::ReaderError, "expected subject in #{@input.inspect} line #{lineno}"
+    end
 
-      ##
-      # @raise [ReaderError]
-      def fail_predicate
-        raise RDF::ReaderError, "expected predicate in #{@input.inspect} line #{lineno}"
-      end
+    ##
+    # Raises an "expected predicate" parsing error on the current line.
+    #
+    # @return [void]
+    # @raise  [RDF::ReaderError]
+    def fail_predicate
+      raise RDF::ReaderError, "expected predicate in #{@input.inspect} line #{lineno}"
+    end
 
-      ##
-      # @raise [ReaderError]
-      def fail_object
-        raise RDF::ReaderError, "expected object in #{@input.inspect} line #{lineno}"
-      end
+    ##
+    # Raises an "expected object" parsing error on the current line.
+    #
+    # @return [void]
+    # @raise  [RDF::ReaderError]
+    def fail_object
+      raise RDF::ReaderError, "expected object in #{@input.inspect} line #{lineno}"
+    end
 
-    private
+    ##
+    # Returns the encoding of the input stream.
+    #
+    # _Note: this method requires Ruby 1.9 or newer._
+    #
+    # @return [Encoding]
+    def encoding
+      @options[:encoding] ||= Encoding::UTF_8
+    end
 
-      @@subclasses = [] # @private
+    ##
+    # Returns `true` if parsed statements and values should be validated.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def validate?
+      @options[:validate]
+    end
 
-      ##
-      # @private
-      def self.inherited(child)
-        @@subclasses << child
-        super
-      end
+    ##
+    # Returns `true` if parsed values should be canonicalized.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def canonicalize?
+      @options[:canonicalize]
+    end
 
-      ##
-      # @return [Integer]
-      def lineno
-        @input.lineno
-      end
+    ##
+    # Returns `true` if parsed URIs should be interned.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def intern?
+      @options[:intern]
+    end
 
-      ##
-      # @return [String]
-      def readline
-        @line = @input.readline.chomp
-        @line.force_encoding(encoding) if @line.respond_to?(:force_encoding) # for Ruby 1.9+
-        @line
-      end
+  private
 
-      ##
-      # @return [Encoding]
-      def encoding
-        @encoding ||= ::Encoding::UTF_8
-      end
+    @@subclasses = [] # @private
 
-      ##
-      # @return [void]
-      def strip!
-        @line.strip!
-      end
+    ##
+    # @private
+    # @return [void]
+    def self.inherited(child)
+      @@subclasses << child
+      super
+    end
 
-      ##
-      # @return [Boolean]
-      def blank?
-        @line.nil? || @line.empty?
-      end
+    ##
+    # @return [Integer]
+    def lineno
+      @input.lineno
+    end
 
-      ##
-      # @param  [Regexp] pattern
-      # @return [Object]
-      def match(pattern)
-        if @line =~ pattern
-          result, @line = $1, $'.lstrip
-          result || true
-        end
-      end
+    ##
+    # @return [String]
+    def readline
+      @line = @input.readline.chomp
+      @line.force_encoding(encoding) if @line.respond_to?(:force_encoding) # for Ruby 1.9+
+      @line
+    end
 
-  end
+    ##
+    # @return [void]
+    def strip!
+      @line.strip!
+    end
 
-  class ReaderError < IOError; end
-end
+    ##
+    # @return [Boolean]
+    def blank?
+      @line.nil? || @line.empty?
+    end
+
+    ##
+    # @param  [Regexp] pattern
+    # @return [Object]
+    def match(pattern)
+      if @line =~ pattern
+        result, @line = $1, $'.lstrip
+        result || true
+      end
+    end
+  end # Reader
+
+  ##
+  # The base class for RDF parsing errors.
+  class ReaderError < IOError
+  end # ReaderError
+end # RDF

data/lib/rdf/repository.rb

@@ -111,6 +111,16 @@ module RDF
       end
     end
 
+    ##
+    # Returns `true` if this repository supports the given `feature`.
+    #
+    # @param  [Symbol, #to_sym] feature
+    # @return [Boolean]
+    # @since  0.1.10
+    def supports?(feature)
+      false
+    end
+
     ##
     # Returns a developer-friendly representation of this object.
     #
@@ -129,6 +139,80 @@ module RDF
       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
+    # @return [void]
+    # @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]
+    # @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]
+    # @since  0.3.0
+    def commit_transaction(tx)
+      tx.execute(self)
+    end
+
     ##
     # @see RDF::Repository
     module Implementation
@@ -140,11 +224,8 @@ module RDF
       end
 
       ##
-      # Returns `true` if this repository supports `feature`.
-      #
-      # @param  [Symbol, #to_sym] feature
-      # @return [Boolean]
-      # @since  0.1.10
+      # @private
+      # @see RDF::Repository#supports?
       def supports?(feature)
         case feature.to_sym
           when :context   then true   # statement contexts / named graphs
@@ -229,7 +310,8 @@ module RDF
       # @private
       # @see RDF::Enumerable#each_context
       def each_context(&block)
-        block_given? ? @data.keys.compact.each(&block) : enum_context
+        @data.keys.compact.each(&block) if block_given?
+        enum_context
       end
 
     protected