redlander 0.3.6 → 0.4.0

data/.gitignore

@@ -0,0 +1,20 @@
+*~
+.*~
+*.rbc
+ext/*.o
+ext/*.so
+ext/*.bundle
+ext/Makefile
+lib/*.o
+lib/*.so
+lib/*.bundle
+pkg/
+tmtags
+*.gem
+TAGS
+vendor/
+tmp/
+.rbx
+.bundle
+.yardoc/
+doc/

data/ChangeLog

@@ -0,0 +1,19 @@
+redlander (0.4.0)
+
+  * deprecated Parser, Serializer, Storage, Stream and related classes and modules
+  * moved parsing and serialization methods to Model instance
+  * renamed parsing/serialization option :name to :format
+  * Redlander::Uri now explicitly belongs to private (internal) API
+  * ModelProxy (model.statements) is now Enumerable, with all benefits thereof
+  * Statement no longer has "valid?" method and "errors" container
+  * blank Nodes can be created with a given ID (:blank_id option)
+  * public methods for handling transactions
+  * URI is preferred over Redlander::Uri as method arguments or output,
+    e.g., Node#datatype, Node#uri and others return an instance of URI
+  * updated gem dependencies
+  * updated README and YARD documentation
+  * added LICENSE (MIT)
+
+redlander (0.3.6)
+
+  ... the dark ages ...

data/Gemfile

@@ -0,0 +1,4 @@
+source "http://rubygems.org"
+gemspec
+
+gem "rake"

data/Gemfile.lock

@@ -0,0 +1,30 @@
+PATH
+  remote: .
+  specs:
+    redlander (0.4.0)
+      ffi (~> 1.1)
+      xml_schema (~> 0.1.0)
+
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.3)
+    ffi (1.1.0)
+    rake (0.9.2.2)
+    rspec (2.11.0)
+      rspec-core (~> 2.11.0)
+      rspec-expectations (~> 2.11.0)
+      rspec-mocks (~> 2.11.0)
+    rspec-core (2.11.1)
+    rspec-expectations (2.11.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.11.1)
+    xml_schema (0.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  rake
+  redlander!
+  rspec (~> 2)

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2012 Slava Kravchenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -1,6 +1,6 @@
-= Description
+= Redlander
 
-Redlander is Ruby bindings to Redland library (see http://librdf.org). This is an alternative implementation of the bindings, aiming to be more intuitive, lightweight and less buggy.
+Redlander is Ruby bindings to Redland library (see http://librdf.org) written in C, which is used to manipulate RDF graphs. This is an alternative implementation of Ruby bindings (as opposed to the official bindings), aiming to be more intuitive, lightweight, high-performing and as bug-free as possible.
 
 = Installing
 
@@ -8,17 +8,21 @@ Installing Redlander is simple:
 
   $ gem install redlander
 
-Note, that you will have to install Redlander (librdf) for Redlander to work.
+Note, that you will have to install Redland runtime library (librdf) for Redlander to work.
 
 = Usage
 
+This README outlines most obvious use cases. For more details please refer to YARD documentation of Redlander.
+
 To start doing anything useful with Redlander, you need to initialize a model first:
 
   $ m = Redlander::Model.new
 
-This creates a model where all RDF statements are stored in the memory. Depending on the selected storage you may need to supply extra parameters like :user or :password. Look-up the options for Storage.initialize_storage method for the list of storage options.
+This creates a model where all RDF statements are stored in the memory. Depending on the selected storage you may need to supply extra parameters like :user or :password. Look-up the options for Model.initialize for the list of available options.
 Naturally, you don't need to create a model if you just want to play around with independent statements, nodes and the like.
 
+== RDF Statements
+
 Now that you have created a model, you can access its RDF statements:
 
   $ m.statements
@@ -41,21 +45,90 @@ Most of Redlander functionality is accessable via these statements. The API is a
 
 Finding statements:
 
-  m.statements.find(:first, :object => "subject!")
-  m.statements.all(:object => "another label")
-  m.statements.find(:all, :object => "subject!").each { |statement|
-    puts statement.subject
-  }
+  $ m.statements.find(:first, :object => "subject!")
+  $ m.statements.all(:object => "another label")
+  $ m.statements.each(:object => "subject!") { |statement|
+      puts statement.subject
+    }
+
+Note that "m.statements.each" is "lazy", while "m.statements.all" (and other finders) is not.
+
+You can access the subject, predicate or object of a statement:
+
+  $ m.statements.first.subject  # => (Redlander::Node)
+
+Please refer to Redlander::Node API doc for details.
+
+== Parsing Input
+
+You can fill your model with statements by parsing some external sources like plain or streamed data.
+
+  $ data = File.read("data.xml")
+  $ m.from(data, :format => "rdfxml")
+
+If the input is too large, you may prefer streaming it:
+
+  $ source = URI("http://example.com/data.nt")
+  $ m.from(source, :format => "ntriples")
+
+If you want to get the data from a local file, you can use "file://" schema for your URI
+(or Redlander::Uri) or use "from_file" method with a local file name (without schema):
+
+  $ m.from_file("../data.ttl", :format => "turtle")
+
+Most frequently used parsing methods are aliased to save you some typing:
+"from_rdfxml", "from_ntriples", "from_turtle", "from_uri/from_file".
+
+Finally, you can filter the parsed input to prevent certain statements from getting into your model:
+
+  $ m.from_turtle(data) do |statement|
+      statement.object.value == "good"
+    end
+
+If the block returns "false", the statement will not be added to the model.
+The above example will add only statements having "literal" objects with a value of "good".
+
+== Serializing Model
+
+Naturally, you can convert your model into a portable syntax:
+
+  $ m.to(:format => "rdfxml") # => RDF/XML output
+
+There are aliases as well: "to_rdfxml", "to_dot", etc.
+
+You can also dump the output directly into a local file:
+
+  $ m.to_file("data.nt", :format => "ntriples")
+
+== Transactions
+
+It is possible to wrap all changes you perform on a model in a transaction,
+if transactions are supported by the backend storage. If they are not supported,
+all changes will be instantaneous.
+
+  $ m.transaction { m.statements.delete_all }
+
+There are also dedicated methods to start, commit and rollback a transaction,
+should you not be able to explicitly wrap your changes in a block:
+
+  $ m.transaction_start
+  $ m.delete_all
+  $ if lucky?
+      m.transaction_commit
+    else
+      m.transaction_rollback
+    end
 
-Note that "m.statements.each" is "lazy", while "m.statements.all" (and other finders) are not.
+All the above methods have their "banged" counterparts ("transaction_start!",
+"transaction_commit!" and "transaction_rollback!") that would raise RedlandError
+in case of an error.
 
-For more details refer to the documentation of Model, Statement, Storage and other classes of Redlander.
 
 = Exceptions
 
 If anything unexpected happens, Redlander raises RedlandError.
 
-= Authors
+= Authors and Contributors
 
 Slava Kravchenko <slava.kravchenko@gmail.com>
 

data/Rakefile

@@ -1,5 +1,6 @@
-require 'spec/rake/spectask'
-require 'bundler'
+#!/usr/bin/env rake
 
-Bundler::GemHelper.install_tasks
-Spec::Rake::SpecTask.new
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new

data/lib/redland.rb

@@ -1,7 +1,8 @@
+# @api private
 # FFI bindings
-
 module Redland
-  if !defined?(RUBY_ENGINE) || RUBY_ENGINE=='ruby'
+  # Handling FFI difference between MRI and Rubinius
+  if !defined?(RUBY_ENGINE) || RUBY_ENGINE == 'ruby'
     require 'ffi'
     extend FFI::Library
     ffi_lib "rdf.so.0"
@@ -52,6 +53,7 @@ module Redland
   attach_function :librdf_node_is_resource, [:pointer], :int
   attach_function :librdf_node_is_literal, [:pointer], :int
   attach_function :librdf_node_is_blank, [:pointer], :int
+  attach_function :librdf_node_get_literal_value, [:pointer], :string
   attach_function :librdf_node_get_literal_value_datatype_uri, [:pointer], :pointer
   attach_function :librdf_node_equals, [:pointer, :pointer], :int
   attach_function :librdf_node_to_string, [:pointer], :string
@@ -74,6 +76,7 @@ module Redland
   attach_function :librdf_free_parser, [:pointer], :void
   attach_function :librdf_parser_parse_into_model, [:pointer, :pointer, :pointer, :pointer], :int
   attach_function :librdf_parser_parse_string_into_model, [:pointer, :string, :pointer, :pointer], :int
+  attach_function :librdf_parser_parse_as_stream, [:pointer, :pointer, :pointer], :pointer
   attach_function :librdf_parser_parse_string_as_stream, [:pointer, :string, :pointer], :pointer
 
   # URI
@@ -81,4 +84,5 @@ module Redland
   attach_function :librdf_new_uri_from_uri, [:pointer], :pointer
   attach_function :librdf_free_uri, [:pointer], :void
   attach_function :librdf_uri_to_string, [:pointer], :string
+  attach_function :librdf_uri_equals, [:pointer, :pointer], :int
 end

data/lib/redlander.rb

@@ -9,26 +9,28 @@ require 'redlander/node'
 require 'redlander/model'
 require 'redlander/statement'
 
+# Main Redlander namespace
 module Redlander
-
   class << self
+    # @api private
     def rdf_world
       unless @rdf_world
         @rdf_world = Redland.librdf_new_world
-        raise RedlandError.new("Could not create a new RDF world") if @rdf_world.null?
+        raise RedlandError, "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
     end
 
+    # @api private
     # 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
     #
-    # E.g.:
+    # @example
     #   to_rdf_options {:key => true, "key_board" => 3}
     #   # => "key='yes',key-board='3'"
     def to_rdf_options(options = {})

data/lib/redlander/model.rb

@@ -1,22 +1,58 @@
-require 'redlander/storage'
-require 'redlander/parser'
-require 'redlander/serializer'
+require 'redlander/parsing'
+require 'redlander/serializing'
 require 'redlander/model_proxy'
 
 module Redlander
+  # The core object incorporating the repository of RDF statements.
   class Model
-    include Redlander::ParsingInstanceMethods
-    include Redlander::SerializingInstanceMethods
+    include Redlander::Parsing
+    include Redlander::Serializing
 
+    # @api private
     attr_reader :rdf_model
 
     # Create a new RDF model.
-    # For explanation of options, read Storage.initialize
+    # (For available storage options see http://librdf.org/docs/api/redland-storage-modules.html)
+    #
+    # @param [Hash] options
+    # @option options [String] :storage
+    #   - "memory"     - default, if :storage option is omitted,
+    #   - "hashes"
+    #   - "file"       - memory model initialized from RDF/XML file,
+    #   - "uri"        - read-only memory model with URI provided in 'name' arg,
+    #   - "mysql"
+    #   - "sqlite"
+    #   - "postgresql"
+    #   - "tstore"
+    #   - "virtuoso"
+    #   - ... anything else that Redland can handle.
+    # @option options [String] :name storage identifier (DB file name or database name),
+    # @option options [String] :host database host name (for store types: :postgres, :mysql, :tstore),
+    # @option options [String] :port database host port (for store types: :postgres, :mysql, :tstore),
+    # @option options [String] :database database name (for store types: :postgres, :mysql, :tstore),
+    # @option options [String] :user database user name (for store types: :postgres, :mysql, :tstore),
+    # @option options [String] :password database user password (for store types: :postgres, :mysql, :tstore),
+    # @option options [String] :hash_type hash type (for store types: :bdb), can be either 'memory' or 'bdb',
+    # @option options [String] :new force creation of a new store,
+    # @option options [String] :dir directory path (for store types: :hashes),
+    # @option options [String] :contexts support contexts (for store types: :hashes, :memory),
+    # @option options [String] :write allow writing data to the store (for store types: :hashes),
+    # @option options [...] ... other storage-specific options.
+    # @raise [RedlandError] if it fails to create a storage or a model.
     def initialize(options = {})
-      @storage = Storage.new(options)
+      options = options.dup
+      storage_type = options.delete(:storage) || "memory"
+      storage_name = options.delete(:name)
+
+      @rdf_storage = Redland.librdf_new_storage(Redlander.rdf_world,
+                                                storage_type.to_s,
+                                                storage_name.to_s,
+                                                Redlander.to_rdf_options(options))
+      raise RedlandError, "Failed to initialize '#{storage_name}' storage (type: #{storage_type})" if @rdf_storage.null?
+      ObjectSpace.define_finalizer(self, proc { Redland.librdf_free_storage(@rdf_storage) })
 
-      @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?
+      @rdf_model = Redland.librdf_new_model(Redlander.rdf_world, @rdf_storage, "")
+      raise RedlandError, "Failed to create a new model" if @rdf_model.null?
       ObjectSpace.define_finalizer(self, proc { Redland.librdf_free_model(@rdf_model) })
     end
 
@@ -24,27 +60,73 @@ module Redlander
     #
     # Similar to Ruby on Rails, a proxy object is actually returned,
     # which delegates methods to Statement class.
+    #
+    # @return [ModelProxy]
     def statements
       ModelProxy.new(self)
     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).
+    #
+    # @note Does not work for all storages, in which case the changes are instanteous
+    #
+    # @yieldparam [void]
+    # @return [void]
     def transaction
       if block_given?
-        Redland.librdf_model_transaction_start(@rdf_model).zero? || raise(RedlandError, "Failed to initialize a transaction")
+        transaction_start
         yield
-        Redland.librdf_model_transaction_commit(@rdf_model).zero? || raise(RedlandError, "Failed to commit the transaction")
+        transaction_commit
       end
     rescue
-      rollback
+      transaction_rollback
       raise
     end
 
-    # Rollback the transaction
-    def rollback
-      Redland.librdf_model_transaction_rollback(@rdf_model).zero? || raise(RedlandError, "Failed to rollback the latest transaction")
+    # Start a transaction, if it is supported by the backend storage.
+    #
+    # @return [Boolean]
+    def transaction_start
+      Redland.librdf_model_transaction_start(@rdf_model).zero?
+    end
+
+    # Start a transaction.
+    #
+    # @raise [RedlandError] if it is not supported by the backend storage
+    # @return [true]
+    def transaction_start!
+      raise RedlandError, "Failed to initialize a transaction" unless transaction_start
+    end
+
+    # Commit a transaction, if it is supported by the backend storage.
+    #
+    # @return [Boolean]
+    def transaction_commit
+      Redland.librdf_model_transaction_commit(@rdf_model).zero?
+    end
+
+    # Commit a transaction.
+    #
+    # @raise [RedlandError] if it is not supported by the backend storage
+    # @return [true]
+    def transaction_commit!
+      raise RedlandError, "Failed to commit the transaction" unless transaction_commit
+    end
+
+    # Rollback a transaction, if it is supported by the backend storage.
+    #
+    # @return [Boolean]
+    def transaction_rollback
+      Redland.librdf_model_transaction_rollback(@rdf_model).zero?
+    end
+
+    # Rollback a transaction.
+    #
+    # @raise [RedlandError] if it is not supported by the backend storage
+    # @return [true]
+    def transaction_rollback!
+      raise RedlandError, "Failed to rollback the latest transaction" unless transaction_rollback
     end
   end
 end

data/lib/redlander/model_proxy.rb

@@ -1,104 +1,161 @@
-require 'redlander/stream'
-require 'redlander/stream_enumerator'
-
 module Redlander
+  # Proxy between model and its statements,
+  # allowing to scope actions on statements
+  # within a certain model.
+  #
+  # @example
+  #   model = Redlander::Model.new
+  #   model.statements
+  #   # => ModelProxy
+  #   model.statements.add(...)
+  #   model.statements.each(...)
+  #   model.statements.find(...)
+  #   # etc...
   class ModelProxy
-    include StreamEnumerator
+    include Enumerable
 
+    # @param [Redlander::Model] model
     def initialize(model)
       @model = model
     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.
+    # @note
+    #   All of subject, predicate, object nodes of the statement must be present.
+    #   Only statements that are legal RDF can be added.
+    #   If the statement already exists in the model, it is not added.
+    #
+    # @param [Statement] statement
+    # @return [Boolean]
     def add(statement)
-      if statement.valid?
-        Redland.librdf_model_add_statement(@model.rdf_model, statement.rdf_statement).zero?
-      end
+      Redland.librdf_model_add_statement(@model.rdf_model, statement.rdf_statement).zero?
     end
+    alias_method :<<, :add
 
-    # 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
+    # Delete a statement from the model.
+    #
+    # @note
+    #   All of subject, predicate, object nodes of the statement must be present.
+    #
+    # @param [Statement] statement
+    # @return [Boolean]
+    def delete(statement)
       Redland.librdf_model_remove_statement(@model.rdf_model, statement.rdf_statement).zero?
     end
 
-    # Create a statement and add it to the model.
+    # Delete all statements from the model.
     #
-    # Options are:
-    #   :subject, :predicate, :object,
-    # (see Statement.new for option explanations).
+    # @todo Fix this extremely ineffective (slow) implementation
+    # @return [Boolean]
+    def delete_all
+      each { |st| delete(st) }
+    end
+
+    # Create a statement and add it to the model.
     #
-    # 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
+    # @param [Hash] source subject, predicate and object nodes
+    #   of the statement to be created (see Statement#initialize).
+    # @option source [Node, URI, String, nil] :subject
+    # @option source [Node, URI, String, nil] :predicate
+    # @option source [Node, URI, String, nil] :object
+    # @return [Statement, nil]
+    def create(source)
+      statement = Statement.new(source)
+      add(statement) ? statement : nil
     end
 
+    # Checks whether there are no statements in the model.
+    #
+    # @return [Boolean]
     def empty?
       size.zero?
     end
 
+    # Size of the model in statements.
+    #
+    # @note
+    #   While #count must iterate across all statements in the model,
+    #   {#size} tries to use a more efficient C implementation.
+    #   So {#size} should be preferred to #count in terms of performance.
+    #   However, for non-countable storages, {#size} falls back to
+    #   using #count. Also, {#size} is not available for enumerables
+    #   (e.g. produced from {#each} (without a block) or otherwise) and
+    #   thus cannot be used to count "filtered" results.
+    #
+    # @return [Fixnum]
     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")
+      s < 0 ? count : s
+    end
+
+    # Enumerate (and filter) model statements.
+    # If given no block, returns Enumerator.
+    #
+    # @param [Statement, Hash, void] args
+    #   if given Statement or Hash, filter the model statements
+    #   according to the specified pattern (see {#find} options).
+    # @yieldparam [Statement]
+    # @return [void]
+    def each(*args)
+      if block_given?
+        rdf_stream =
+          if args.empty?
+            Redland.librdf_model_as_stream(@model.rdf_model)
+          else
+            pattern = args.first.is_a?(Statement) ? args.first.rdf_statement : Statement.new(args.first)
+            Redland.librdf_model_find_statements(@model.rdf_model, pattern.rdf_statement)
+          end
+        raise RedlandError, "Failed to create a new stream" if rdf_stream.null?
+
+        begin
+          while Redland.librdf_stream_end(rdf_stream).zero?
+            statement = Statement.new(Redland.librdf_stream_get_object(rdf_stream))
+            yield statement
+            Redland.librdf_stream_next(rdf_stream)
+          end
+        ensure
+          Redland.librdf_free_stream(rdf_stream)
+        end
       else
-        s
+        enum_for(:each, *args)
       end
     end
 
     # Find statements satisfying the given criteria.
-    # Scope can be:
-    #   :all
-    #   :first
-    def find(scope, options = {}, &block)
-      stream = Stream.new(@model, Statement.new(options))
-
+    #
+    # @param [:first, :all] scope find just one or all matches
+    # @param [Hash, Statement] options matching pattern made of:
+    #   - Hash with :subject, :predicate or :object nodes, or
+    #   - "patternized" Statement (nil nodes are matching anything).
+    # @return [Statement, Array, nil]
+    def find(scope, options = {})
       case scope
       when :first
-        stream.current
+        each(options).first
       when :all
-        stream.tail
+        each(options).to_a
       else
-        raise RedlandError.new("Invalid search scope '#{scope}' specified.")
+        raise RedlandError, "Invalid search scope '#{scope}' specified."
       end
     end
 
+    # Find a first statement matching the given criteria.
+    # (Shortcut for {#find}(:first, options)).
+    #
+    # @param [Hash] options (see {#find})
+    # @return [Statement, nil]
     def first(options = {})
       find(:first, options)
     end
 
+    # Find all statements matching the given criteria.
+    # (Shortcut for {#find}(:all, options)).
+    #
+    # @param [Hash] options (see {#find})
+    # @return [Array<Statement>]
     def all(options = {})
       find(:all, options)
     end
-
-
-    private
-
-    def reset_stream
-      @stream = Stream.new(@model)
-    end
   end
 end