rdf-raptor 0.4.2 → 1.0.0.beta1

data/README

@@ -2,8 +2,8 @@ Raptor RDF Parser Plugin for RDF.rb
 ===================================
 [![Build Status](https://secure.travis-ci.org/ruby-rdf/rdf-raptor.png?branch=master)](http://travis-ci.org/ruby-rdf/rdf-raptor)
 
-This is an [RDF.rb][] plugin that adds support for parsing/serializing
-[RDF/XML][], [Turtle][] and [RDFa][] data using the [Raptor RDF Parser][Raptor]
+This is an [RDF.rb][] plugin that adds support for parsing/serializing [NTriples][],
+[RDF/XML][], [Turtle][], [RDFa][], and [Graphviz][] data using the [Raptor RDF Parser][Raptor]
 library.
 
 * <http://github.com/ruby-rdf/rdf-raptor>
@@ -12,12 +12,13 @@ library.
 Features
 --------
 
-* Requires the [Raptor][] library and/or command-line utilities.
-* Parses and serializes RDF data from/into the RDF/XML or Turtle formats.
+* Uses the fast [Raptor][] C library.
+* Parses and serializes RDF data from/into the NTriples, RDF/XML, and Turtle formats.
 * Extracts RDF statements from XHTML+RDFa documents.
+* Serializes RDF statements into Graphviz format.
 * Provides serialization format autodetection for RDF/XML, Turtle and RDFa.
 * Compatible with any operating system supported by Raptor and Ruby.
-* Compatible with MRI 1.8.x, 1.9.x and JRuby (tested with JRuby 1.8 and 1.9 mode).
+* Compatible with MRI 1.8.x, 1.9.x, REE, JRuby and Rubinius (1.8 and 1.9 mode).
 
 Examples
 --------
@@ -27,7 +28,15 @@ Examples
 ### Ensuring Raptor is installed and obtaining the version number
 
     RDF::Raptor.available?         #=> true
-    RDF::Raptor.version            #=> "1.4.21"
+    RDF::Raptor.version            #=> "2.0.8"
+
+### Parsing RDF statements from an NTriples file
+
+    RDF::Reader.open("http://datagraph.org/jhacker/foaf.nt") do |reader|
+      reader.each_statement do |statement|
+        puts statement.inspect
+      end
+    end
 
 ### Parsing RDF statements from an RDF/XML file
 
@@ -105,6 +114,14 @@ Examples
     RDF::Format.for(:file_extension => "html")
     RDF::Format.for(:content_type   => "application/xhtml+xml")
 
+### Obtaining the Graphviz format specification class
+
+    RDF::Format.for(:graphviz)     #=> RDF::Raptor::Graphviz::Format
+    RDF::Format.for("output.dot")
+    RDF::Format.for(:file_name      => "output.dot")
+    RDF::Format.for(:file_extension => "")
+    RDF::Format.for(:content_type   => "text/vnd.graphviz")
+
 Documentation
 -------------
 
@@ -120,9 +137,9 @@ Documentation
 Dependencies
 ------------
 
-* [RDF.rb](http://rubygems.org/gems/rdf) (>= 0.3.0)
+* [RDF.rb](http://rubygems.org/gems/rdf) (>= 0.3.8)
 * [FFI](http://rubygems.org/gems/ffi) (>= 1.0.0)
-* [Raptor][] (>= 1.4.21), the `libraptor` library or the `rapper` binary
+* [Raptor][] (>= 2.0), the `libraptor` library or the `rapper` binary
 
 Installation
 ------------
@@ -140,7 +157,8 @@ Mac and the most common Linux and BSD distributions:
     % [sudo] port install raptor             # Mac OS X with MacPorts
     % [sudo] fink install raptor-bin         # Mac OS X with Fink
     % brew install raptor                    # Mac OS X with Homebrew
-    % [sudo] aptitude install raptor-utils   # Ubuntu / Debian
+    % [sudo] aptitude install raptor-utils   # Ubuntu / Debian with aptitude
+    % [sudo] apt-get install libraptor2-0    # Ubuntu / Debian with apt-get
     % [sudo] yum install raptor              # Fedora / CentOS / RHEL
     % [sudo] zypper install raptor           # openSUSE
     % [sudo] emerge raptor                   # Gentoo Linux
@@ -175,18 +193,21 @@ Contributors
 ------------
 
 * [Ben Lavender](http://github.com/bhuga) - <http://bhuga.net/>
-* [David Butler](http://github.com/dwbutler)
+* [David Butler](http://github.com/dwbutler) - <http://github.com/dwbutler>
 * [Gregg Kellogg](http://github.com/gkellogg) - <http://greggkellogg.net/>
 
 License
 -------
 
 This is free and unencumbered public domain software. For more information,
-see <http://unlicense.org/> or the accompanying {file:UNLICENSE} file.
+see <http://unlicense.org/> or the accompanying [UNLICENSE][] file.
 
 [RDF.rb]:   http://rdf.rubyforge.org/
+[NTriples]: http://en.wikipedia.org/wiki/N-Triples
 [RDF/XML]:  http://www.w3.org/TR/REC-rdf-syntax/
 [Turtle]:   http://en.wikipedia.org/wiki/Turtle_(syntax)
 [RDFa]:     http://rdfa.info/
+[Graphviz]: http://www.graphviz.org/
 [Raptor]:   http://librdf.org/raptor/
 [rapper]:   http://librdf.org/raptor/rapper.html
+[UNLICENSE]:https://github.com/ruby-rdf/rdf-raptor/blob/master/UNLICENSE

data/VERSION

@@ -1 +1 @@
-0.4.2
+1.0.0.beta1

data/lib/rdf/raptor/cli.rb

@@ -19,7 +19,6 @@ module RDF::Raptor
         [$1, $2, $3].join('.')
       end
     end
-    module_function :version
 
     ##
     # CLI reader implementation.

data/lib/rdf/raptor/ffi/v1/parser.rb

@@ -59,7 +59,7 @@ module RDF::Raptor::FFI::V1
     # @param  [Proc] handler
     # @return [void]
     def statement_handler=(handler)
-      V1.raptor_set_statement_handler(self, self, handler)
+      V1.raptor_parser_set_statement_handler(self, self, handler)
     end
 
     ##

data/lib/rdf/raptor/ffi/v2/iostream.rb

@@ -0,0 +1,56 @@
+module RDF::Raptor::FFI::V2
+  ##
+  # This class provides an I/O stream that can write to filenames, `FILE*`,
+  # strings and user-defined output via callbacks.
+  #
+  # @see http://librdf.org/raptor/api-1.4/raptor-section-iostream.html
+  class IOStream < ::FFI::ManagedStruct
+    include RDF::Raptor::FFI
+    layout  :world, :pointer,
+            :user_data, :pointer,
+            :handler, :pointer,
+            :offset, :size_t,
+            :mode, :int,
+            :flags, :int
+
+    ##
+    # @overload initialize(ptr)
+    #   @param  [FFI::Pointer] ptr
+    #
+    # @overload initialize(handler)
+    #   @param  [V2::IOStreamHandler] handler
+    #
+    # @overload initialize(file)
+    #   @param  [File, Tempfile] file
+    #
+    def initialize(ptr_or_obj, options = {})
+      ptr = case ptr_or_obj
+        when FFI::Pointer
+          ptr_or_obj
+        when V2::IOStreamHandler
+          @handler = ptr_or_obj # prevents premature GC
+          V2.raptor_new_iostream_from_handler(V2.world, self, @handler)
+        when File, Tempfile
+          V2.raptor_new_iostream_to_filename(V2.world, File.expand_path(ptr_or_obj.path))
+        when false
+          V2.raptor_new_iostream_to_sink(V2.world)
+        else nil
+      end
+      raise ArgumentError, "invalid argument: #{ptr_or_obj.inspect}" if ptr.nil? || ptr.null?
+      
+      @free_iostream = options[:free_iostream] || true
+      super(ptr)
+    end
+
+    ##
+    # Releases `libraptor` memory associated with this structure.
+    #
+    # @param  [FFI::Pointer] ptr
+    # @return [void]
+    def self.release(ptr)
+      if @free_iostream
+        V2.raptor_free_iostream(ptr)
+      end
+    end
+  end # IOStream
+end # RDF::Raptor::FFI::V2

data/lib/rdf/raptor/ffi/v2/iostream_handler.rb

@@ -0,0 +1,153 @@
+module RDF::Raptor::FFI::V2
+  ##
+  # @see http://librdf.org/raptor/api-1.4/raptor-section-iostream.html
+  class IOStreamHandler < ::FFI::Struct
+    include RDF::Raptor::FFI
+    layout :version, :int,
+           :init, :raptor_iostream_init_func,
+           :finish, :raptor_iostream_finish_func,
+           :write_byte, :raptor_iostream_write_byte_func,
+           :write_bytes, :raptor_iostream_write_bytes_func,
+           :write_end, :raptor_iostream_write_end_func,
+           :read_bytes, :raptor_iostream_read_bytes_func,
+           :read_eof, :raptor_iostream_read_eof_func
+
+    HANDLERS = [:init, :finish, :write_byte, :write_bytes, :read_bytes, :read_eof]
+
+    ##
+    # The IO object to operate upon.
+    #
+    # @return [IO]
+    attr_accessor :io
+
+    ##
+    # @overload initialize(ptr)
+    #   @param  [FFI::Pointer] ptr
+    #
+    # @overload initialize(io)
+    #   @param  [IO, StringIO] io
+    #
+    def initialize(ptr_or_io = nil)
+      if ptr_or_io.respond_to?(:write)
+        @io = ptr_or_io
+        super()
+      else
+        case ptr_or_io
+        when FFI::Pointer
+          super(ptr_or_io)
+        when nil
+          super()
+        else
+          raise ArgumentError, "invalid argument: #{ptr_or_io.inspect}"
+        end
+      end
+      initialize!
+    end
+
+    ##
+    # @return [void]
+    def initialize!
+      self[:version] = 2
+
+      #define_handler(:init) do |context|
+      #  $stderr.puts("#{self.class}: init")
+      #end
+      #define_handler(:finish) do |context|
+      #  $stderr.puts("#{self.class}: finish")
+      #end
+      define_handler(:write_byte) do |context, byte|
+        begin
+          @io.putc(byte)
+          0
+        rescue => e
+          $stderr.puts("#{e} in #{self.class}#write_byte")
+          1
+        end
+      end
+      define_handler(:write_bytes) do |context, data, size, nmemb|
+        begin
+          @io.write(data.read_string(size * nmemb))
+          0
+        rescue => e
+          $stderr.puts("#{e} in #{self.class}#write_bytes")
+          1
+        end
+      end
+      #define_handler(:write_end) do |context|
+      #  $stderr.puts("#{self.class}: write_end")
+      #end
+      #define_handler(:read_bytes) do |context, data, size, nmemb|
+      #  $stderr.puts("#{self.class}: read_bytes")
+      #end
+      #define_handler(:read_eof) do |context|
+      #  $stderr.puts("#{self.class}: read_eof")
+      #end
+    end
+
+    ##
+    # @param  [Proc] func
+    # @return [void]
+    def init_handler=(func)
+      define_handler(:init, &func)
+    end
+    alias_method :init=, :init_handler=
+
+    ##
+    # @param  [Proc] func
+    # @return [void]
+    def finish_handler=(func)
+      define_handler(:finish, &func)
+    end
+    alias_method :finish=, :finish_handler=
+
+    ##
+    # @param  [Proc] func
+    # @return [void]
+    def write_byte_handler=(func)
+      define_handler(:write_byte, &func)
+    end
+    alias_method :write_byte=, :write_byte_handler=
+
+    ##
+    # @param  [Proc] func
+    # @return [void]
+    def write_bytes_handler=(func)
+      define_handler(:write_bytes, &func)
+    end
+    alias_method :write_bytes=, :write_bytes_handler=
+
+    ##
+    # @param  [Proc] func
+    # @return [void]
+    def write_end_handler=(func)
+      define_handler(:write_end, &func)
+    end
+    alias_method :write_end=, :write_end_handler=
+
+    ##
+    # @param  [Proc] func
+    # @return [void]
+    def read_bytes_handler=(func)
+      define_handler(:read_bytes, &func)
+    end
+    alias_method :read_bytes=, :read_bytes_handler=
+
+    ##
+    # @param  [Proc] func
+    # @return [void]
+    def read_eof_handler=(func)
+      define_handler(:read_eof, &func)
+    end
+    alias_method :read_eof=, :read_eof_handler=
+
+    ##
+    # @param  [Symbol, #to_sym] name
+    # @return [void]
+    def define_handler(name, &block)
+      name = name.to_sym
+      raise ArgumentError, "invalid IOStreamHandler function name: #{name}" unless HANDLERS.include?(name)
+      @procs ||= {} # prevents premature GC of the procs
+      @procs[name] = self[name] = block
+    end
+  end # IOStreamHandler
+end # RDF::Raptor::FFI::V1

data/lib/rdf/raptor/ffi/v2/parser.rb

@@ -0,0 +1,205 @@
+module RDF::Raptor::FFI::V2
+  ##
+  # This class provides the functionality of turning syntaxes into RDF
+  # triples - RDF parsing.
+  #
+  # @see http://librdf.org/raptor/api-1.4/raptor-section-parser.html
+  class Parser < ::FFI::ManagedStruct
+    include RDF::Raptor::FFI
+    layout :world, :pointer # the actual layout is private
+
+    # The default base URI
+    BASE_URI    = 'file:///dev/stdin'
+
+    # The maximum chunk size for `#parse_stream`
+    BUFFER_SIZE = 64 * 1024
+
+    ##
+    # @overload initialize(ptr)
+    #   @param  [FFI::Pointer] ptr
+    #
+    # @overload initialize(name)
+    #   @param  [Symbol, String] name
+    #
+    def initialize(ptr_or_name)
+      ptr = case ptr_or_name
+        when FFI::Pointer then ptr_or_name
+        when Symbol       then V2.raptor_new_parser(V2.world, ptr_or_name.to_s)
+        when String       then V2.raptor_new_parser(V2.world, ptr_or_name)
+        else nil
+      end
+      raise ArgumentError, "invalid argument: #{ptr_or_name.inspect}" if ptr.nil? || ptr.null?
+      super(ptr)
+    end
+
+    ##
+    # Releases `libraptor` memory associated with this structure.
+    #
+    # @param  [FFI::Pointer] ptr
+    # @return [void]
+    def self.release(ptr)
+      V2.raptor_free_parser(ptr)
+    end
+
+    ##
+    # @param  [Proc] handler
+    # @return [void]
+    def error_handler=(handler)
+      #V2.raptor_set_error_handler(self, self, handler)
+    end
+
+    ##
+    # @param  [Proc] handler
+    # @return [void]
+    def warning_handler=(handler)
+      #V2.raptor_set_warning_handler(self, self, handler)
+    end
+
+    ##
+    # @param  [Proc] handler
+    # @return [void]
+    def statement_handler=(handler)
+      V2.raptor_parser_set_statement_handler(self, self, handler)
+    end
+
+    ##
+    # @param  [Object] input
+    #   the input to parse
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for parsing
+    # @option options [String, #to_s] :base_uri (nil)
+    #   the base URI to use when resolving relative URIs
+    # @yield  [parser, statement]
+    #   each statement in the input
+    # @yieldparam  [FFI::Pointer] parser
+    # @yieldparam  [FFI::Pointer] statement
+    # @yieldreturn [void] ignored
+    # @return [void]
+    def parse(input, options = {}, &block)
+      case input
+        when RDF::URI, URI, %r(^(file|https|http|ftp)://)
+          parse_url(input, options, &block)
+        when File, Tempfile
+          parse_file(input, options, &block)
+        when IO, StringIO
+          parse_stream(input, options, &block)
+        when String
+          parse_buffer(input, options, &block)
+        else
+          raise ArgumentError, "don't know how to parse #{input.inspect}"
+      end
+    end
+
+    ##
+    # @param  [RDF::URI, String, #to_s] url
+    #   the input URL to parse
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for parsing (see {#parse})
+    # @yield  [parser, statement]
+    #   each statement in the input
+    # @yieldparam  [FFI::Pointer] parser
+    # @yieldparam  [FFI::Pointer] statement
+    # @yieldreturn [void] ignored
+    # @return [void]
+    def parse_url(url, options = {}, &block)
+      self.statement_handler = block if block_given?
+
+      data_url = V2::URI.new((url.respond_to?(:to_uri) ? url.to_uri : url).to_s)
+      base_uri = options[:base_uri].to_s.empty? ? nil : V2::URI.new(options[:base_uri].to_s)
+
+      result = V2.raptor_parser_parse_uri(self, data_url, base_uri)
+      # TODO: error handling if result.nonzero?
+    end
+    alias_method :parse_uri, :parse_url
+
+    ##
+    # @param  [File, Tempfile, #path] file
+    #   the input file to parse
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for parsing (see {#parse})
+    # @yield  [parser, statement]
+    #   each statement in the input
+    # @yieldparam  [FFI::Pointer] parser
+    # @yieldparam  [FFI::Pointer] statement
+    # @yieldreturn [void] ignored
+    # @return [void]
+    def parse_file(file, options = {}, &block)
+      self.statement_handler = block if block_given?
+
+      data_url = V2::URI.new("file://#{File.expand_path(file.path)}")
+      base_uri = options[:base_uri].to_s.empty? ? nil : V2::URI.new(options[:base_uri].to_s)
+
+      result = V2.raptor_parser_parse_file(self, data_url, base_uri)
+      # TODO: error handling if result.nonzero?
+    end
+
+    ##
+    # @param  [IO, StringIO, #readpartial] stream
+    #   the input stream to parse
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for parsing (see {#parse})
+    # @yield  [parser, statement]
+    #   each statement in the input
+    # @yieldparam  [FFI::Pointer] parser
+    # @yieldparam  [FFI::Pointer] statement
+    # @yieldreturn [void] ignored
+    # @return [void]
+    def parse_stream(stream, options = {}, &block)
+      self.statement_handler = block if block_given?
+
+      begin
+        parse_start!(options[:base_uri] || BASE_URI)
+        loop do
+          parse_chunk(stream.sysread(BUFFER_SIZE))
+        end
+      rescue EOFError => e
+        parse_end!
+      end
+    end
+
+    ##
+    # @param  [String, #to_str] buffer
+    #   the input buffer to parse
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for parsing (see {#parse})
+    # @yield  [parser, statement]
+    #   each statement in the input
+    # @yieldparam  [FFI::Pointer] parser
+    # @yieldparam  [FFI::Pointer] statement
+    # @yieldreturn [void] ignored
+    # @return [void]
+    def parse_buffer(buffer, options = {}, &block)
+      self.statement_handler = block if block_given?
+
+      parse_start!((options[:base_uri] || BASE_URI).to_s)
+      parse_chunk(buffer.to_str)
+      parse_end!
+    end
+
+    ##
+    # @private
+    # @param  [String] base_uri
+    # @return [void]
+    def parse_start!(base_uri = BASE_URI)
+      result = V2.raptor_parser_parse_start(self, V2::URI.new(base_uri))
+      # TODO: error handling if result.nonzero?
+    end
+
+    ##
+    # @private
+    # @param  [String] buffer
+    #   the input chunk to parse
+    # @return [void]
+    def parse_chunk(buffer)
+      result = V2.raptor_parser_parse_chunk(self, buffer, buffer.bytesize, 0)
+      # TODO: error handling if result.nonzero?
+    end
+
+    ##
+    # @private
+    # @return [void]
+    def parse_end!
+      result = V2.raptor_parser_parse_chunk(self, nil, 0, 1) # EOF
+    end
+  end # Parser
+end # RDF::Raptor::FFI::V2

data/lib/rdf/raptor/ffi/v2/serializer.rb

@@ -0,0 +1,137 @@
+module RDF::Raptor::FFI::V2
+  ##
+  # This class provides the functionality of turning RDF triples into
+  # syntaxes - RDF serializing.
+  #
+  # @see http://librdf.org/raptor/api-1.4/raptor-section-serializer.html
+  class Serializer < ::FFI::ManagedStruct
+    include RDF::Raptor::FFI
+
+    # Note this layout is private
+    layout  :world, :pointer,
+            :locator, :pointer,
+            :failed, :bool,
+            :base_uri, :pointer,
+            :context, :pointer,
+            :iostream, :pointer,
+            :free_iostream_on_end, :bool,
+            :factory, :pointer,
+            :options, :pointer
+
+    ##
+    # @overload initialize(ptr)
+    #   @param  [FFI::Pointer] ptr
+    #
+    # @overload initialize(name)
+    #   @param  [Symbol, String] name
+    #
+    def initialize(ptr_or_name)
+      ptr = case ptr_or_name
+        when FFI::Pointer then ptr_or_name
+        when Symbol       then V2.raptor_new_serializer(V2.world, ptr_or_name.to_s)
+        when String       then V2.raptor_new_serializer(V2.world, ptr_or_name)
+        else nil
+      end
+      raise ArgumentError, "invalid argument: #{ptr_or_name.inspect}" if ptr.nil? || ptr.null?
+      super(ptr)
+    end
+
+    ##
+    # Releases `libraptor` memory associated with this structure.
+    #
+    # @param  [FFI::Pointer] ptr
+    # @return [void]
+    def self.release(ptr)
+      V2.raptor_free_serializer(ptr)
+    end
+
+    ##
+    # @param  [Proc] handler
+    # @return [void]
+    def error_handler=(handler)
+      V2.raptor_serializer_set_error_handler(self, self, handler)
+    end
+
+    ##
+    # @param  [Proc] handler
+    # @return [void]
+    def warning_handler=(handler)
+      V2.raptor_serializer_set_warning_handler(self, self, handler)
+    end
+
+    ##
+    # @param  [Object] output
+    #   where output should be written to
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for serializing
+    # @option options [String, #to_s] :base_uri (nil)
+    #   the base URI to use when resolving relative URIs
+    # @return [void]
+    def start_to(output, options = {})
+      if output.respond_to?(:write)
+        start_to_stream(output, options)
+       else
+        raise ArgumentError, "don't know how to serialize to #{output.inspect}"
+      end
+    end
+
+    ##
+    # @param  [IO, StringIO] stream
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for serializing (see {#start_to})
+    # @return [void]
+    def start_to_stream(stream, options = {})
+      iostream = V2::IOStream.new(V2::IOStreamHandler.new(stream), :free_iostream => self[:free_iostream_on_end])
+      start_to_iostream(iostream, options)
+    end
+
+    ##
+    # @param  [V2::IOStream] iostream
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for serializing (see {#start_to})
+    # @return [void]
+    def start_to_iostream(iostream, options = {})
+      @iostream = iostream # prevents premature GC
+      @base_uri = options[:base_uri].to_s.empty? ? nil : V2::URI.new(options[:base_uri].to_s)
+      if V2.raptor_serializer_start_to_iostream(self, @base_uri, @iostream).nonzero?
+        raise RDF::WriterError, "raptor_serialize_start_to_iostream() failed"
+      end
+    end
+
+    ##
+    # @return [void]
+    def finish
+      if V2.raptor_serializer_serialize_end(self).nonzero?
+        raise RDF::WriterError, "raptor_serialize_end() failed"
+      end
+      @iostream = @base_uri = nil # allows GC
+    end
+
+    ##
+    # @param  [RDF::Resource] subject
+    # @param  [RDF::URI]      predicate
+    # @param  [RDF::Term]     object
+    # @return [void]
+    def serialize_triple(subject, predicate, object)
+      raptor_statement = V2::Statement.new
+      raptor_statement.subject   = subject
+      raptor_statement.predicate = predicate
+      raptor_statement.object    = object
+      begin
+        serialize_raw_statement(raptor_statement)
+      ensure
+        raptor_statement.release
+        raptor_statement = nil
+      end
+    end
+
+    ##
+    # @param  [V2::Statement] statement
+    # @return [void]
+    def serialize_raw_statement(statement)
+      if V2.raptor_serializer_serialize_statement(self, statement).nonzero?
+        raise RDF::WriterError, "raptor_serialize_statement() failed"
+      end
+    end
+  end # Serializer
+end # RDF::Raptor::FFI::V2