redlander 0.2.1

data/lib/redlander.rb

@@ -0,0 +1,61 @@
+$:.unshift(File.dirname(__FILE__)) unless
+  $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
+
+require 'uri'
+require 'xml_schema'
+
+module Redlander
+  require 'redland'
+  require 'redlander/version'
+
+  class RedlandError < RuntimeError; end
+
+  class << self
+
+    def rdf_world
+      unless @rdf_world
+        @rdf_world = Redland.librdf_new_world
+        raise RedlandError.new("Could not create a new RDF world") unless @rdf_world
+        ObjectSpace.define_finalizer(@rdf_world, proc { Redland.librdf_free_world(@rdf_world) })
+        Redland.librdf_world_open(@rdf_world)
+      end
+      @rdf_world
+    end
+
+    # Convert options hash into a string for librdf.
+    # What it does:
+    #   1) Convert boolean values into 'yes/no' values
+    #   2) Change underscores in key names into dashes ('dhar_ma' => 'dhar-ma')
+    #   3) Join all options as "key='value'" pairs in a comma-separated string
+    def to_rdf_options(options = {})
+      options.inject([]){|opts, option_pair|
+        key = option_pair[0].to_s.gsub(/_/, '-')
+        value = if [TrueClass, FalseClass].include?(option_pair[1].class)
+                  option_pair[1] ? 'yes' : 'no'
+                else
+                  option_pair[1]
+                end
+        opts << "#{key}='#{value}'"
+      }.join(',')
+    end
+
+    # Helper method to create an instance of rdfuri.
+    # For internal use only!
+    def to_rdf_uri(uri)
+      return nil if uri.nil?
+      uri = uri.is_a?(URI) ? uri.to_s : uri
+      rdf_uri = Redland.librdf_new_uri(rdf_world, uri)
+      raise RedlandError.new("Failed to create URI from '#{uri}'") unless rdf_uri
+      ObjectSpace.define_finalizer(rdf_uri, proc { Redland.librdf_free_uri(rdf_uri) })
+      rdf_uri
+    end
+
+  end
+
+  require 'redlander/error_container'
+  require 'redlander/statement_iterator'
+  require 'redlander/parser'
+  require 'redlander/serializer'
+  require 'redlander/model'
+  require 'redlander/node'
+end

data/lib/redlander/error_container.rb

@@ -0,0 +1,41 @@
+module ErrorContainer
+
+  class Errors
+    include Enumerable
+
+    def initialize
+      @container = []
+    end
+
+    def add(error_message)
+      if @container.include?(error_message)
+        @container
+      else
+        @container << error_message
+      end
+    end
+
+    def each
+      @container.each do |err|
+        yield err
+      end
+    end
+
+    def empty?
+      @container.empty?
+    end
+
+    def clear
+      @container.clear
+    end
+
+    def size
+      @container.size
+    end
+  end
+
+  def errors
+    @errors ||= Errors.new
+  end
+
+end

data/lib/redlander/model.rb

@@ -0,0 +1,33 @@
+require 'redlander/storage'
+require 'redlander/model_proxy'
+
+module Redlander
+
+  class Model
+
+    include Redlander::ParsingInstanceMethods
+    include Redlander::SerializingInstanceMethods
+
+    attr_reader :rdf_model
+
+    # Create a new RDF model.
+    # For explanation of options, read Storage.initialize_storage
+    def initialize(options = {})
+      @rdf_storage = Storage.initialize_storage(options)
+
+      @rdf_model = Redland.librdf_new_model(Redlander.rdf_world, @rdf_storage, "")
+      raise RedlandError.new("Failed to create a new model") unless @rdf_model
+      ObjectSpace.define_finalizer(@rdf_model, proc { Redland.librdf_free_model(@rdf_model) })
+    end
+
+    # Statements contained in the model.
+    #
+    # Similar to Ruby on Rails, a proxy object is actually returned,
+    # which delegates methods to Statement class.
+    def statements
+      ModelProxy.new(self)
+    end
+
+  end
+
+end

data/lib/redlander/model_proxy.rb

@@ -0,0 +1,85 @@
+require 'redlander/statement'
+
+module Redlander
+
+  class ModelProxy
+
+    include StatementIterator
+
+    def initialize(model, rdf_stream = nil)
+      @model = model
+      @rdf_stream = if rdf_stream
+                      rdf_stream
+                    else
+                      Redland.librdf_model_as_stream(@model.rdf_model)
+                    end
+      raise RedlandError.new("Failed to create a new stream") unless @rdf_stream
+      ObjectSpace.define_finalizer(@rdf_stream, proc { Redland.librdf_free_stream(@rdf_stream) })
+    end
+
+    # Add a statement to the model.
+    # It must be a complete statement - all of subject, predicate, object parts must be present.
+    # Only statements that are legal RDF can be added.
+    # If the statement already exists in the model, it is not added.
+    #
+    # Returns true on success or false on failure.
+    def add(statement)
+      statement.model = @model
+    end
+
+    # Create a statement and add it to the model.
+    #
+    # Options are:
+    #   :subject, :predicate, :object,
+    # (see Statement.new for option explanations).
+    #
+    # Returns an instance of Statement on success,
+    # or nil if the statement could not be added.
+    def create(options = {})
+      statement = Statement.new(options)
+      add(statement) && statement
+    end
+
+    def empty?
+      size.zero?
+    end
+
+    def size
+      s = Redland.librdf_model_size(@model.rdf_model)
+      if s < 0
+        raise RedlandError.new("Attempt to get size when using non-countable storage")
+      else
+        s
+      end
+    end
+
+    # Find statements satisfying the given criteria.
+    # Scope can be:
+    #   :all
+    #   :first
+    def find(scope, options = {})
+      statement = Statement.new(options)
+      rdf_stream = Redland.librdf_model_find_statements(@model.rdf_model, statement.rdf_statement)
+      proxy = self.class.new(@model, rdf_stream)
+
+      case scope
+      when :first
+        proxy.first
+      when :all
+        if block_given?
+          proxy.each
+        else
+          proxy
+        end
+      else
+        raise RedlandError.new("Invalid search scope '#{scope}' specified.")
+      end
+    end
+
+    def all(options = {})
+      find(:all, options)
+    end
+
+  end
+
+end

data/lib/redlander/node.rb

@@ -0,0 +1,90 @@
+module Redlander
+
+  class Node
+
+    attr_reader :rdf_node
+
+    # Create a RDF node.
+    # Argument can be:
+    #   - an instance of URI - to create a RDF "resource",
+    #   - an instance of Node - to create a copy of the node,
+    #   - nil (or absent) - to create a "blank" node,
+    #   - any other Ruby object, which can be coerced into a literal.
+    # If nothing else, a RedlandError is thrown.
+    #
+    # Note, that you cannot create a resource node from an URI string,
+    # it must be an instance of URI. Otherwise it is treated as a string literal.
+    def initialize(arg = nil)
+      @rdf_node = if arg.nil?
+                    Redland.librdf_new_node_from_blank_identifier(Redlander.rdf_world, nil)
+                  elsif arg.is_a?(URI)
+                    Redland.librdf_new_node_from_uri_string(Redlander.rdf_world, arg.to_s)
+                  elsif arg.is_a?(SWIG::TYPE_p_librdf_node_s)
+                    # A special case, where you can pass an instance of SWIG::TYPE_p_librdf_node_s
+                    # in order to create a Node from an internal RDF node representation.
+                    arg
+                  elsif arg.is_a?(Node)
+                    Redland.librdf_new_node_from_node(arg.rdf_node)
+                  else
+                    value = arg.respond_to?(:xmlschema) ? arg.xmlschema : arg.to_s
+                    datatype = Redlander.to_rdf_uri(XmlSchema.datatype_of(arg))
+                    Redland.librdf_new_node_from_typed_literal(Redlander.rdf_world, value, nil, datatype)
+                  end
+
+      raise RedlandError.new("Failed to create a new node") unless @rdf_node
+      ObjectSpace.define_finalizer(@rdf_node, proc { Redland.librdf_free_node(@rdf_node) })
+    end
+
+    def resource?
+      !Redland.librdf_node_is_resource(@rdf_node).zero?
+    end
+
+    # Return true if node is a literal.
+    def literal?
+      !Redland.librdf_node_is_literal(@rdf_node).zero?
+    end
+
+    # Return true if node is a blank node.
+    def blank?
+      !Redland.librdf_node_is_blank(@rdf_node).zero?
+    end
+
+    # Return the datatype URI of the node.
+    # Returns nil if the node is not a literal, or has no datatype URI.
+    def datatype
+      if rdf_uri = Redland.librdf_node_get_literal_value_datatype_uri(@rdf_node)
+        ObjectSpace.define_finalizer(rdf_uri, proc { Redland.librdf_free_uri(rdf_uri) })
+        Redland.librdf_uri_to_string(rdf_uri)
+      end
+    end
+
+    # Equivalency. Only works for comparing two Nodes.
+    def eql?(other_node)
+      !Redland.librdf_node_equals(@rdf_node, other_node.rdf_node).zero?
+    end
+    alias_method :==, :eql?
+
+    def hash
+      self.class.hash + to_s.hash
+    end
+
+    # Convert this node to a string (with a datatype suffix).
+    def to_s
+      Redland.librdf_node_to_string(@rdf_node)
+    end
+
+    # Value of the literal node as a Ruby object instance.
+    def value
+      if resource?
+        if rdf_uri = Redland.librdf_node_get_uri(@rdf_node)
+          ObjectSpace.define_finalizer(rdf_uri, proc { Redland.librdf_free_uri(rdf_uri) })
+          URI.parse(Redland.librdf_uri_to_string(rdf_uri))
+        end
+      else
+        XmlSchema.instantiate(to_s)
+      end
+    end
+
+  end
+
+end

data/lib/redlander/parser.rb

@@ -0,0 +1,92 @@
+require 'redlander/parser_proxy'
+
+module Redlander
+
+  class Parser
+
+    attr_reader :rdf_parser
+
+    # Create a new parser.
+    # Name can be either of [:rdfxml, :ntriples, :turtle],
+    # or nil, which defaults to :rdfxml.
+    #
+    # TODO: Only a small subset of parsers is implemented,
+    # because the rest seem to be very buggy.
+    def initialize(name = :rdfxml)
+      # name, mime-type and syntax uri can all be nil, which defaults to :rdfxml parser
+      @rdf_parser = Redland.librdf_new_parser(Redlander.rdf_world, name.to_s, nil, nil)
+      raise RedlandError.new("Failed to create a new parser") unless @rdf_parser
+      ObjectSpace.define_finalizer(@rdf_parser, proc { Redland.librdf_free_parser(@rdf_parser) })
+    end
+
+    # Parse the content (String) into the model.
+    #
+    # Options are:
+    #   :base_uri   base URI (String or URI)
+    #
+    # Returns true on success, or false.
+    def from_string(model, content, options = {})
+      # FIXME: A bug (?) in Redland breaks NTriples parser if its input is not terminated with "\n"
+      content.concat("\n") unless content.end_with?("\n")
+      Redland.librdf_parser_parse_string_into_model(@rdf_parser, content, Redlander.to_rdf_uri(options[:base_uri]), model.rdf_model).zero?
+    end
+
+    # Parse the content from URI into the model.
+    # (It is possible to use "file:" schema for local files).
+    #
+    # Options are:
+    #   :base_uri   base URI (String or URI)
+    #
+    # Returns true on success, or false.
+    def from_uri(model, uri, options = {})
+      uri = URI.parse(uri)
+      uri = URI.parse("file://#{File.expand_path(uri.to_s)}") if uri.scheme.nil?
+      Redland.librdf_parser_parse_into_model(@rdf_parser, Redlander.to_rdf_uri(uri), Redlander.to_rdf_uri(options[:base_uri]), model.rdf_model).zero?
+    end
+    alias_method :from_file, :from_uri
+
+    def statements(content, options = {})
+      # BUG: Parser accumulates data from consequent runs??? WTF, Redland?!
+      #   When parsing a series of files, parser reported a duplicate entry,
+      #   then seemed to have stopped yielding statements at all.
+
+      # FIXME: A bug (?) in Redland breaks NTriples parser if its input is not terminated with "\n"
+      content.concat("\n") unless content.end_with?("\n")
+      ParserProxy.new(self, content, options)
+    end
+
+  end
+
+
+  module ParsingInstanceMethods
+
+    def from_rdfxml(content, options = {})
+      parser = Parser.new(:rdfxml)
+      parser.from_string(self, content, options)
+    end
+
+    def from_ntriples(content, options = {})
+      parser = Parser.new(:ntriples)
+      parser.from_string(self, content, options)
+    end
+
+    def from_turtle(content, options = {})
+      parser = Parser.new(:turtle)
+      parser.from_string(self, content, options)
+    end
+
+    # Load the model from an URI content.
+    #
+    # Options are:
+    #   :format   - content format [:rdfxml (default), :ntriples, :turtle]
+    #   :base_uri - base URI
+    def from_uri(uri, options = {})
+      parser_options = options.dup
+      parser = Parser.new(parser_options.delete(:format) || :rdfxml)
+      parser.from_uri(self, uri, parser_options)
+    end
+    alias_method :from_file, :from_uri
+
+  end
+
+end

data/lib/redlander/parser_proxy.rb

@@ -0,0 +1,18 @@
+require 'redlander/statement'
+
+module Redlander
+
+  class ParserProxy
+
+    include StatementIterator
+
+    def initialize(parser, content, options = {})
+      @model = nil  # the yielded statements will not be bound to a model
+      @rdf_stream = Redland.librdf_parser_parse_string_as_stream(parser.rdf_parser, content, Redlander.to_rdf_uri(options[:base_uri]))
+      raise RedlandError.new("Failed to create a new stream") unless @rdf_stream
+      ObjectSpace.define_finalizer(@rdf_stream, proc { Redland.librdf_free_stream(@rdf_stream) })
+    end
+
+  end
+
+end

data/lib/redlander/serializer.rb

@@ -0,0 +1,80 @@
+module Redlander
+
+  class Serializer
+
+    # Create a new serializer.
+    # Name can be either of [:rdfxml, :ntriples, :turtle, :json, :dot],
+    # or nil, which defaults to :rdfxml.
+    #
+    # TODO: Only a small subset of parsers is implemented,
+    # because the rest seem to be very buggy.
+    def initialize(name = :rdfxml)
+      @rdf_serializer = Redland.librdf_new_serializer(Redlander.rdf_world, name.to_s, nil, nil)
+      raise RedlandError.new("Failed to create a new serializer") unless @rdf_serializer
+      ObjectSpace.define_finalizer(@rdf_serializer, proc { Redland.librdf_free_serializer(@rdf_serializer) })
+    end
+
+    # Serialize a model into a string.
+    #
+    # Options are:
+    #   :base_uri   base URI (String or URI)
+    def to_string(model, options = {})
+      Redland.librdf_serializer_serialize_model_to_string(@rdf_serializer, Redlander.to_rdf_uri(options[:base_uri]), model.rdf_model)
+    end
+
+    # Serializes a model and stores it in a file
+    # filename  -  the name of the file to serialize to
+    # model     -  model instance
+    #
+    # Options are:
+    #   :base_uri   base URI (String or URI)
+    #
+    # Returns true on success, or false.
+    def to_file(model, filename, options = {})
+      Redland.librdf_serializer_serialize_model_to_file(@rdf_serializer, filename, Redlander.to_rdf_uri(options[:base_uri]), model.rdf_model).zero?
+    end
+
+  end
+
+
+  module SerializingInstanceMethods
+
+    def to_rdfxml(options = {})
+      serializer = Serializer.new(:rdfxml)
+      serializer.to_string(self, options)
+    end
+
+    def to_ntriples(options = {})
+      serializer = Serializer.new(:ntriples)
+      serializer.to_string(self, options)
+    end
+
+    def to_turtle(options = {})
+      serializer = Serializer.new(:turtle)
+      serializer.to_string(self, options)
+    end
+
+    def to_json(options = {})
+      serializer = Serializer.new(:json)
+      serializer.to_string(self, options)
+    end
+
+    def to_dot(options = {})
+      serializer = Serializer.new(:dot)
+      serializer.to_string(self, options)
+    end
+
+    # Serialize the model into a file.
+    #
+    # Options are:
+    #   :format   - output format [:rdfxml (default), :ntriples, :turtle, :json, :dot]
+    #   :base_uri - base URI
+    def to_file(filename, options = {})
+      serializer_options = options.dup
+      serializer = Serializer.new(serializer_options.delete(:format) || :rdfxml)
+      serializer.to_file(self, filename, serializer_options)
+    end
+
+  end
+
+end