redlander 0.2.2 → 0.3.1

data/README.rdoc

@@ -8,7 +8,7 @@ Installing Redlander is simple:
 
   $ gem install redlander
 
-Note, that in order to install Redlander you need the development libraries of Redland project (tested with redland-1.0.12 in Ubuntu 11.04).
+Note, that you will have to install Redlander (librdf) for Redlander to work.
 
 = Usage
 
@@ -34,17 +34,21 @@ Most of Redlander functionality is accessable via these statements. The API is a
   $ st = Redlander::Statement.new(:subject => s, :predicate => p, :object => "another label")
   $ m.statements.add(st)
 
-  m.statements.size    # => 2
+  $ m.statements.size    # => 2
+
+  $ m.statements.each { |st| puts st }
 
 Finding statements:
 
   m.statements.find(:first, :object => "subject!")
   m.statements.all(:object => "another label")
-  m.statements.find(:all, :object => "subject!") { |statement|
+  m.statements.find(:all, :object => "subject!").each { |statement|
     puts statement.subject
   }
 
-For more detail refer to the documentation of Model, Statement, Storage and other classes of Redlander.
+Note that "m.statements.each" is "lazy", while "m.statements.all" (and other finders) are not.
+
+For more details refer to the documentation of Model, Statement, Storage and other classes of Redlander.
 
 = Exceptions
 

data/lib/redlander.rb

@@ -10,13 +10,27 @@ module Redlander
 
   class RedlandError < RuntimeError; end
 
-  class << self
+  autoload :ErrorContainer, 'redlander/error_container'
+  autoload :Uri, 'redlander/uri'
+  autoload :Parser, 'redlander/parser'
+  autoload :ParserProxy, 'redlander/parser_proxy'
+  autoload :Serializer, 'redlander/serializer'
+  autoload :Model, 'redlander/model'
+  autoload :ModelProxy, 'redlander/model_proxy'
+  autoload :Node, 'redlander/node'
+  autoload :Stream, 'redlander/stream'
+  autoload :Storage, 'redlander/storage'
+  autoload :ParsingInstanceMethods, 'redlander/parser'
+  autoload :SerializingInstanceMethods, 'redlander/serializer'
+  autoload :StreamEnumerator, 'redlander/stream_enumerator'
+  autoload :Statement, 'redlander/statement'
 
+  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) })
+        raise RedlandError.new("Could not create a new RDF world") if @rdf_world.null?
+        ObjectSpace.define_finalizer(self, proc { Redland.librdf_free_world(@rdf_world) })
         Redland.librdf_world_open(@rdf_world)
       end
       @rdf_world
@@ -38,24 +52,5 @@ module Redlander
         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

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

data/lib/redlander/model.rb

@@ -1,23 +1,18 @@
-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
+    # For explanation of options, read Storage.initialize
     def initialize(options = {})
-      @rdf_storage = Storage.initialize_storage(options)
+      @storage = Storage.new(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) })
+      @rdf_model = Redland.librdf_new_model(Redlander.rdf_world, @storage.rdf_storage, "")
+      raise RedlandError.new("Failed to create a new model") if @rdf_model.null?
+      ObjectSpace.define_finalizer(self, proc { Redland.librdf_free_model(@rdf_model) })
     end
 
     # Statements contained in the model.
@@ -28,6 +23,23 @@ module Redlander
       ModelProxy.new(self)
     end
 
-  end
+    # Wrap changes to the given model in a transaction.
+    # If an exception is raised in the block, the transaction is rolled back.
+    # (Does not work for all storages, in which case the changes are instanteous).
+    def transaction
+      if block_given?
+        Redland.librdf_model_transaction_start(@rdf_model).zero? || RedlandError.new("Failed to initialize a transaction")
+        yield
+        Redland.librdf_model_transaction_commit(@rdf_model).zero? || RedlandError.new("Failed to commit the transaction")
+      end
+    rescue
+      rollback
+      raise
+    end
 
+    # Rollback the transaction
+    def rollback
+      Redland.librdf_model_transaction_rollback(@rdf_model).zero? || RedlandError.new("Failed to rollback the latest transaction")
+    end
+  end
 end

data/lib/redlander/model_proxy.rb

@@ -1,20 +1,9 @@
-require 'redlander/statement'
-
 module Redlander
-
   class ModelProxy
+    include StreamEnumerator
 
-    include StatementIterator
-
-    def initialize(model, rdf_stream = nil)
+    def initialize(model)
       @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.
@@ -24,7 +13,31 @@ module Redlander
     #
     # Returns true on success or false on failure.
     def add(statement)
-      statement.model = @model
+      if statement.valid?
+        Redland.librdf_model_add_statement(@model.rdf_model, statement.rdf_statement).zero?
+      end
+    end
+
+    # Delete a statement from the model,
+    # or delete all statements matching the given criteria.
+    # Source can be either
+    #   Statement
+    # or
+    #   Hash (all keys are optional)
+    #     :subject
+    #     :predicate
+    #     :object
+    def delete(source)
+      statement = case source
+                  when Statement
+                    source
+                  when Hash
+                    Statement.new(source)
+                  else
+                    # TODO
+                    raise NotImplementedError.new
+                  end
+      Redland.librdf_model_remove_statement(@model.rdf_model, statement.rdf_statement).zero?
     end
 
     # Create a statement and add it to the model.
@@ -58,32 +71,31 @@ module Redlander
     #   :all
     #   :first
     def find(scope, options = {}, &block)
-      statement = Statement.new(options)
-      rdf_stream = Redland.librdf_model_find_statements(@model.rdf_model, statement.rdf_statement)
-      proxy = self.class.new(@model, rdf_stream)
+      stream = Stream.new(@model, Statement.new(options))
 
       case scope
       when :first
-        proxy.first
+        stream.current
       when :all
-        if block_given?
-          proxy.each(&block)
-        else
-          proxy
-        end
+        stream.tail
       else
         raise RedlandError.new("Invalid search scope '#{scope}' specified.")
       end
     end
 
+    def first(options = {})
+      find(:first, options)
+    end
+
     def all(options = {})
-      [].tap do |st|
-        find(:all, options) do |fs|
-          st << fs
-        end
-      end
+      find(:all, options)
     end
 
-  end
 
+    private
+
+    def reset_stream
+      @stream = Stream.new(@model)
+    end
+  end
 end

data/lib/redlander/node.rb

@@ -1,7 +1,5 @@
 module Redlander
-
   class Node
-
     attr_reader :rdf_node
 
     # Create a RDF node.
@@ -9,58 +7,72 @@ module Redlander
     #   - 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,
+    #   - an instance of Statement ("role" must be supplied then) -
+    #     to create a node from subject, predicate or object
+    #     (determined by "role" parameter) of the statement.
     #   - 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?
+    def initialize(arg = nil, role = :subject)
+      bound = false
+      @rdf_node = case arg
+                  when NilClass
                     Redland.librdf_new_node_from_blank_identifier(Redlander.rdf_world, nil)
-                  elsif arg.is_a?(URI)
+                  when 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)
+                  when Node
                     Redland.librdf_new_node_from_node(arg.rdf_node)
+                  when Statement
+                    bound = true
+                    case role
+                    when :subject
+                      Redland.librdf_statement_get_subject(arg.rdf_statement)
+                    when :object
+                      Redland.librdf_statement_get_object(arg.rdf_statement)
+                    when :predicate
+                      Redland.librdf_statement_get_predicate(arg.rdf_statement)
+                    else
+                      raise RedlandError.new("Invalid role specified")
+                    end
                   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)
+                    datatype = Uri.new(XmlSchema.datatype_of(arg))
+                    Redland.librdf_new_node_from_typed_literal(Redlander.rdf_world, value, nil, datatype.rdf_uri)
                   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) })
+      if @rdf_node.null?
+        raise RedlandError.new("Failed to create a new node") unless bound
+      else
+        ObjectSpace.define_finalizer(self, proc { Redland.librdf_free_node(@rdf_node) })
+        # bound nodes cannot be added to (other) statements
+        freeze if bound
+      end
     end
 
     def resource?
-      !Redland.librdf_node_is_resource(@rdf_node).zero?
+      Redland.librdf_node_is_resource(@rdf_node) != 0
     end
 
     # Return true if node is a literal.
     def literal?
-      !Redland.librdf_node_is_literal(@rdf_node).zero?
+      Redland.librdf_node_is_literal(@rdf_node) != 0
     end
 
     # Return true if node is a blank node.
     def blank?
-      !Redland.librdf_node_is_blank(@rdf_node).zero?
+      Redland.librdf_node_is_blank(@rdf_node) != 0
     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
+      Uri.new(self).to_s if literal?
     end
 
     # Equivalency. Only works for comparing two Nodes.
     def eql?(other_node)
-      !Redland.librdf_node_equals(@rdf_node, other_node.rdf_node).zero?
+      Redland.librdf_node_equals(@rdf_node, other_node.rdf_node) != 0
     end
     alias_method :==, :eql?
 
@@ -76,15 +88,10 @@ module Redlander
     # 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
+        URI.parse(Uri.new(self).to_s)
       else
         XmlSchema.instantiate(to_s)
       end
     end
-
   end
-
 end

data/lib/redlander/parser.rb

@@ -1,9 +1,5 @@
-require 'redlander/parser_proxy'
-
 module Redlander
-
   class Parser
-
     attr_reader :rdf_parser
 
     # Create a new parser.
@@ -15,8 +11,8 @@ module Redlander
     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) })
+      raise RedlandError.new("Failed to create a new parser") if @rdf_parser.null?
+      ObjectSpace.define_finalizer(self, proc { Redland.librdf_free_parser(@rdf_parser) })
     end
 
     # Parse the content (String) into the model.
@@ -28,7 +24,12 @@ module Redlander
     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?
+      base_uri = if options.has_key?(:base_uri)
+                   Uri.new(options[:base_uri]).rdf_uri
+                 else
+                   nil
+                 end
+      Redland.librdf_parser_parse_string_into_model(@rdf_parser, content, base_uri, model.rdf_model).zero?
     end
 
     # Parse the content from URI into the model.
@@ -41,25 +42,24 @@ module Redlander
     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?
+      base_uri = if options.has_key?(:base_uri)
+                   Uri.new(options[:base_uri]).rdf_uri
+                 else
+                   nil
+                 end
+      Redland.librdf_parser_parse_into_model(@rdf_parser, Uri.new(uri).rdf_uri, 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
 
-
+  # Applied to Model
   module ParsingInstanceMethods
-
     def from_rdfxml(content, options = {})
       parser = Parser.new(:rdfxml)
       parser.from_string(self, content, options)
@@ -86,7 +86,5 @@ module Redlander
       parser.from_uri(self, uri, parser_options)
     end
     alias_method :from_file, :from_uri
-
   end
-
 end