rdf-raptor 0.4.0 → 0.4.1

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

@@ -0,0 +1,130 @@
+module RDF::Raptor::FFI
+  ##
+  # A foreign-function interface (FFI) to `libraptor` 1.4.x.
+  #
+  # @see http://librdf.org/raptor/libraptor.html
+  module V1
+    autoload :IOStream,        'rdf/raptor/ffi/v1/iostream'
+    autoload :IOStreamHandler, 'rdf/raptor/ffi/v1/iostream_handler'
+    autoload :Parser,          'rdf/raptor/ffi/v1/parser'
+    autoload :Serializer,      'rdf/raptor/ffi/v1/serializer'
+    autoload :Statement,       'rdf/raptor/ffi/v1/statement'
+    autoload :URI,             'rdf/raptor/ffi/v1/uri'
+
+    extend ::FFI::Library
+    ffi_lib RDF::Raptor::LIBRAPTOR
+
+    # TODO: Ideally this would be an enum, but the JRuby FFI (as of
+    # version 1.4.0) has problems with enums as part of structs:
+    #   `Unknown field type: #<FFI::Enum> (ArgumentError)`
+    RAPTOR_IDENTIFIER_TYPE_UNKNOWN   = 0
+    RAPTOR_IDENTIFIER_TYPE_RESOURCE  = 1
+    RAPTOR_IDENTIFIER_TYPE_ANONYMOUS = 2
+    RAPTOR_IDENTIFIER_TYPE_LITERAL   = 5
+
+    # @see http://librdf.org/raptor/api-1.4/tutorial-initialising-finishing.html
+    attach_function :raptor_init, [], :void
+    attach_function :raptor_finish, [], :void
+    attach_function :raptor_alloc_memory, [:size_t], :pointer
+    attach_function :raptor_calloc_memory, [:size_t, :size_t], :pointer
+    attach_function :raptor_free_memory, [:pointer], :void
+
+    # @see http://librdf.org/raptor/api-1.4/raptor-section-locator.html
+    typedef :pointer, :raptor_locator
+    attach_function :raptor_locator_line, [:raptor_locator], :int
+    attach_function :raptor_locator_column, [:raptor_locator], :int
+    attach_function :raptor_locator_byte, [:raptor_locator], :int
+
+    # @see http://librdf.org/raptor/api-1.4/raptor-section-general.html
+    attach_variable :raptor_version_major, :int
+    attach_variable :raptor_version_minor, :int
+    attach_variable :raptor_version_release, :int
+    attach_variable :raptor_version_decimal, :int
+    callback        :raptor_message_handler, [:pointer, :raptor_locator, :string], :void
+
+    # @see http://librdf.org/raptor/api-1.4/raptor-section-uri.html
+    typedef :pointer, :raptor_uri
+    attach_function :raptor_new_uri, [:string], :raptor_uri
+    attach_function :raptor_uri_copy, [:raptor_uri], :raptor_uri
+    attach_function :raptor_uri_equals, [:raptor_uri, :raptor_uri], :int
+    attach_function :raptor_uri_as_string, [:raptor_uri], :string
+    attach_function :raptor_uri_to_string, [:raptor_uri], :string
+    attach_function :raptor_uri_print, [:raptor_uri, :pointer], :void
+    attach_function :raptor_free_uri, [:raptor_uri], :void
+
+    # @see http://librdf.org/raptor/api-1.4/raptor-section-triples.html
+    typedef :int,     :raptor_identifier_type
+    typedef :pointer, :raptor_identifier
+    typedef :pointer, :raptor_statement
+    attach_function :raptor_statement_compare, [:raptor_statement, :raptor_statement], :int
+    attach_function :raptor_print_statement, [:raptor_statement, :pointer], :void
+    attach_function :raptor_print_statement_as_ntriples, [:pointer, :pointer], :void
+    attach_function :raptor_statement_part_as_string, [:pointer, :raptor_identifier_type, :raptor_uri, :pointer], :string
+
+    # @see http://librdf.org/raptor/api-1.4/raptor-section-parser.html
+    callback :raptor_statement_handler, [:pointer, :raptor_statement], :void
+    typedef :pointer, :raptor_parser
+    attach_function :raptor_new_parser, [:string], :raptor_parser
+    attach_function :raptor_set_error_handler, [:raptor_parser, :pointer, :raptor_message_handler], :void
+    attach_function :raptor_set_warning_handler, [:raptor_parser, :pointer, :raptor_message_handler], :void
+    attach_function :raptor_set_statement_handler, [:raptor_parser, :pointer, :raptor_statement_handler], :void
+    attach_function :raptor_parse_file, [:raptor_parser, :raptor_uri, :raptor_uri], :int
+    attach_function :raptor_parse_file_stream, [:raptor_parser, :pointer, :string, :raptor_uri], :int
+    attach_function :raptor_parse_uri, [:raptor_parser, :raptor_uri, :raptor_uri], :int
+    attach_function :raptor_start_parse, [:raptor_parser, :string], :int
+    attach_function :raptor_parse_chunk, [:raptor_parser, :string, :size_t, :int], :int
+    attach_function :raptor_get_mime_type, [:raptor_parser], :string
+    attach_function :raptor_set_parser_strict, [:raptor_parser, :int], :void
+    attach_function :raptor_get_need_base_uri, [:raptor_parser], :int
+    attach_function :raptor_free_parser, [:raptor_parser], :void
+
+    # @see http://librdf.org/raptor/api-1.4/raptor-section-iostream.html
+    typedef :pointer, :raptor_iostream
+    attach_function :raptor_new_iostream_from_handler2, [:pointer, :pointer], :raptor_iostream
+    attach_function :raptor_free_iostream, [:raptor_iostream], :void
+    callback        :raptor_iostream_init_func, [:pointer], :int
+    callback        :raptor_iostream_finish_func, [:pointer], :void
+    callback        :raptor_iostream_write_byte_func, [:pointer, :int], :int
+    callback        :raptor_iostream_write_bytes_func, [:pointer, :pointer, :size_t, :size_t], :int
+    callback        :raptor_iostream_write_end_func, [:pointer], :void
+    callback        :raptor_iostream_read_bytes_func, [:pointer, :pointer, :size_t, :size_t], :int
+    callback        :raptor_iostream_read_eof_func, [:pointer], :int
+
+    # @see http://librdf.org/raptor/api-1.4/raptor-section-xml-namespace.html
+    typedef :pointer, :raptor_namespace
+
+    # @see http://librdf.org/raptor/api-1.4/raptor-section-serializer.html
+    typedef :pointer, :raptor_serializer
+    attach_function :raptor_new_serializer, [:string], :raptor_serializer
+    attach_function :raptor_free_serializer, [:raptor_serializer], :void
+    attach_function :raptor_serialize_start_to_iostream, [:raptor_serializer, :raptor_uri, :raptor_iostream], :int
+    attach_function :raptor_serialize_start_to_filename, [:raptor_serializer, :string], :int
+    attach_function :raptor_serialize_statement, [:raptor_serializer, :raptor_statement], :int
+    attach_function :raptor_serialize_end, [:raptor_serializer], :int
+    attach_function :raptor_serializer_set_error_handler, [:raptor_serializer, :pointer, :raptor_message_handler], :void
+    attach_function :raptor_serializer_set_warning_handler, [:raptor_serializer, :pointer, :raptor_message_handler], :void
+
+    # Initialize the world.
+    # We do this exactly once and never release because we can't delegate
+    # any memory management to the Ruby GC.
+    # Internally `raptor_init`/`raptor_finish` work with reference counts.
+    raptor_init
+
+    ##
+    # Allocates memory for the string `str` inside `libraptor`, copying the
+    # string into the newly-allocated buffer.
+    #
+    # The buffer should later be deallocated using `raptor_free_string`.
+    #
+    # @return [FFI::Pointer]
+    def raptor_new_string(str)
+      ptr = V1.raptor_alloc_memory(str.bytesize + 1)
+      ptr.put_string(0, str)
+      ptr
+    end
+    module_function :raptor_new_string
+
+    alias_method :raptor_free_string, :raptor_free_memory
+    module_function :raptor_free_string
+  end # V1
+end # RDF::Raptor::FFI

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

@@ -0,0 +1,47 @@
+module RDF::Raptor::FFI::V1
+  ##
+  # 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 :user_data, :pointer # the actual layout is private
+
+    ##
+    # @overload initialize(ptr)
+    #   @param  [FFI::Pointer] ptr
+    #
+    # @overload initialize(handler)
+    #   @param  [V1::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 V1::IOStreamHandler
+          @handler = ptr_or_obj # prevents premature GC
+          V1.raptor_new_iostream_from_handler2(self, @handler)
+        when File, Tempfile
+          V1.raptor_new_iostream_to_filename(File.expand_path(ptr_or_obj.path))
+        when false
+          V1.raptor_new_iostream_to_sink()
+        else nil
+      end
+      raise ArgumentError, "invalid argument: #{ptr_or_obj.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)
+      V1.raptor_free_iostream(ptr)
+    end
+  end # IOStream
+end # RDF::Raptor::FFI::V1

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

@@ -0,0 +1,151 @@
+module RDF::Raptor::FFI::V1
+  ##
+  # @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)
+      ptr = case ptr_or_io
+        when FFI::Pointer
+          ptr_or_io
+        when IO, StringIO
+          @io = ptr_or_io
+          nil
+        when nil then nil
+        else
+          raise ArgumentError, "invalid argument: #{ptr_or_io.inspect}"
+      end
+      super(ptr)
+      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/v1/parser.rb

@@ -0,0 +1,205 @@
+module RDF::Raptor::FFI::V1
+  ##
+  # 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 V1.raptor_new_parser(ptr_or_name.to_s)
+        when String       then V1.raptor_new_parser(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)
+      V1.raptor_free_parser(ptr)
+    end
+
+    ##
+    # @param  [Proc] handler
+    # @return [void]
+    def error_handler=(handler)
+      V1.raptor_set_error_handler(self, self, handler)
+    end
+
+    ##
+    # @param  [Proc] handler
+    # @return [void]
+    def warning_handler=(handler)
+      V1.raptor_set_warning_handler(self, self, handler)
+    end
+
+    ##
+    # @param  [Proc] handler
+    # @return [void]
+    def statement_handler=(handler)
+      V1.raptor_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, %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 = V1::URI.new((url.respond_to?(:to_uri) ? url.to_uri : url).to_s)
+      base_uri = options[:base_uri].to_s.empty? ? nil : V1::URI.new(options[:base_uri].to_s)
+
+      result = V1.raptor_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 = V1::URI.new("file://#{File.expand_path(file.path)}")
+      base_uri = options[:base_uri].to_s.empty? ? nil : V1::URI.new(options[:base_uri].to_s)
+
+      result = V1.raptor_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).to_s)
+        loop do
+          parse_chunk(stream.readpartial(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 = V1.raptor_start_parse(self, 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 = V1.raptor_parse_chunk(self, buffer, buffer.bytesize, 0)
+      # TODO: error handling if result.nonzero?
+    end
+
+    ##
+    # @private
+    # @return [void]
+    def parse_end!
+      result = V1.raptor_parse_chunk(self, nil, 0, 1) # EOF
+    end
+  end # Parser
+end # RDF::Raptor::FFI::V1