redlander 0.3.6 → 0.4.0

data/lib/redlander/node.rb

@@ -1,86 +1,69 @@
 module Redlander
+  # RDF node (usually, a part of an RDF statement)
   class Node
+    # @api private
     attr_reader :rdf_node
 
+    # Datatype URI for the literal node, or nil
+    attr_reader :datatype
+
     # Create a RDF node.
-    # Argument can be:
+    #
+    # @param [Any] arg
     #   - 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.
+    #     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.
+    #   - 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, role = :subject)
-      @bound = false
+    # @param [Hash] options
+    # @option options [String] :blank_id optional ID to use for a blank node.
+    # @raise [RedlandError] if it fails to create a node from the given args.
+    def initialize(arg = nil, options = {})
       @rdf_node = case arg
+                  when FFI::Pointer
+                    unless Redland.librdf_node_is_literal(arg).zero?
+                      rdf_uri = Redland.librdf_node_get_literal_value_datatype_uri(arg)
+                      @datatype = rdf_uri.null? ? XmlSchema.datatype_of("") : URI(Redland.librdf_uri_to_string(rdf_uri))
+                    end
+                    wrap(arg)
                   when NilClass
-                    Redland.librdf_new_node_from_blank_identifier(Redlander.rdf_world, nil)
+                    Redland.librdf_new_node_from_blank_identifier(Redlander.rdf_world, options[:blank_id])
                   when URI
                     Redland.librdf_new_node_from_uri_string(Redlander.rdf_world, arg.to_s)
-                  when Node
-                    Redland.librdf_new_node_from_node(arg.rdf_node)
-                  when Statement
-                    # TODO: Bound nodes should better be produced
-                    # using an explicit "factory" like Node.from_statement
-                    # to keep the clutter in the constructor at minimum.
-                    # (Esp. handling the "bound" stuff)
-                    @bound = true
-                    case role
-                    when :subject
-                      copy_rdf_node_on_initialize(Redland.librdf_statement_get_subject(arg.rdf_statement))
-                    when :object
-                      copy_rdf_node_on_initialize(Redland.librdf_statement_get_object(arg.rdf_statement))
-                    when :predicate
-                      copy_rdf_node_on_initialize(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 = Uri.new(XmlSchema.datatype_of(arg))
-                    Redland.librdf_new_node_from_typed_literal(Redlander.rdf_world, value, nil, datatype.rdf_uri)
+                    @datatype = XmlSchema.datatype_of(arg)
+                    Redland.librdf_new_node_from_typed_literal(Redlander.rdf_world, value, nil, Uri.new(@datatype).rdf_uri)
                   end
-      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
-
-    # Bound nodes are those belonging to a statement
-    # (bound nodes cannot be modified or added to other statements).
-    def bound?
-      @bound
+      raise RedlandError, "Failed to create a new node" if @rdf_node.null?
+      ObjectSpace.define_finalizer(self, proc { Redland.librdf_free_node(@rdf_node) })
     end
 
+    # Check whether the node is a resource (identified by a URI)
+    #
+    # @return [Boolean]
     def resource?
       Redland.librdf_node_is_resource(@rdf_node) != 0
     end
 
     # Return true if node is a literal.
+    #
+    # @return [Boolean]
     def literal?
       Redland.librdf_node_is_literal(@rdf_node) != 0
     end
 
     # Return true if node is a blank node.
+    #
+    # @return [Boolean]
     def blank?
       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
-      Uri.new(self).to_s if literal?
-    end
-
     # Equivalency. Only works for comparing two Nodes.
+    #
+    # @param [Node] other_node Node to be compared with.
+    # @return [Boolean]
     def eql?(other_node)
       Redland.librdf_node_equals(@rdf_node, other_node.rdf_node) != 0
     end
@@ -91,14 +74,37 @@ module Redlander
     end
 
     # Convert this node to a string (with a datatype suffix).
+    #
+    # @return [String]
     def to_s
       Redland.librdf_node_to_string(@rdf_node)
     end
 
+    # Internal URI of the Node.
+    #
+    # Returns the datatype URI for literal nodes,
+    # nil for blank nodes.
+    #
+    # @return [URI, nil]
+    def uri
+      if resource?
+        URI(to_s[1..-2])
+      elsif literal?
+        datatype
+      else
+        nil
+      end
+    end
+
     # Value of the literal node as a Ruby object instance.
+    #
+    # Returns an instance of URI for resource nodes,
+    # "blank identifier" for blank nodes.
+    #
+    # @return [URI, Any]
     def value
       if resource?
-        URI.parse(Uri.new(self).to_s)
+        uri
       else
         XmlSchema.instantiate(to_s)
       end
@@ -107,13 +113,10 @@ module Redlander
 
     private
 
-    def copy_rdf_node_on_initialize(n)
+    # @api private
+    def wrap(n)
       if n.null?
-        if bound?
-          n
-        else
-          raise RedlandError.new("Failed to create a new node")
-        end
+        raise RedlandError, "Failed to create a new node"
       else
         Redland.librdf_new_node_from_node(n)
       end

data/lib/redlander/parsing.rb

@@ -0,0 +1,123 @@
+module Redlander
+  # Syntax parsing methods.
+  # "self" is assumed to be an instance of Redlander::Model
+  module Parsing
+    # Core parsing method for non-streams
+    #
+    # @note
+    #   If a block is given, the extracted statements will be yielded into
+    #   the block and inserted into the model depending on the output
+    #   of the block (if true, the statement will be added,
+    #   if false, the statement will not be added).
+    #
+    # @param [String, URI] content
+    #   - Can be a String,
+    #     causing the statements to be extracted
+    #     directly from it, or
+    #   - URI
+    #     causing the content to be first pulled
+    #     from the specified URI (or a local file,
+    #     if URI schema == "file:")
+    # @param [Hash] options
+    # @option options [String] :format name of the parser to use,
+    # @option options [String] :mime_type MIME type of the syntax, if applicable,
+    # @option options [String, URI] :type_uri URI of syntax, if applicable,
+    # @option options [String, URI] :base_uri base URI,
+    #   to be applied to the nodes with relative URIs.
+    # @yieldparam [Statement]
+    # @raise [RedlandError] if it fails to create a parser or stream
+    # @return [Model]
+    def from(content, options = {})
+      format = options[:format].to_s
+      mime_type = options[:mime_type] && options[:mime_type].to_s
+      type_uri = options[:type_uri] && options[:type_uri].to_s
+      base_uri = options[:base_uri] && options[:base_uri].to_s
+      content = Uri.new(content) if content.is_a?(URI)
+
+      # FIXME: to be fixed in librdf:
+      # ntriples parser absolutely needs "\n" at the end of the input
+      if format == "ntriples" && !content.is_a?(Uri) && !content.end_with?("\n")
+        content << "\n"
+      end
+
+      rdf_parser = Redland.librdf_new_parser(Redlander.rdf_world, format, mime_type, type_uri)
+      raise RedlandError, "Failed to create a new '#{format}' parser" if rdf_parser.null?
+
+      begin
+        if block_given?
+          rdf_stream =
+            if content.is_a?(Uri)
+              Redland.librdf_parser_parse_as_stream(rdf_parser, content.rdf_uri, base_uri)
+            else
+              Redland.librdf_parser_parse_string_as_stream(rdf_parser, content, base_uri)
+            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))
+              statements.add(statement) if yield statement
+              Redland.librdf_stream_next(rdf_stream)
+            end
+          ensure
+            Redland.librdf_free_stream(rdf_stream)
+          end
+        else
+          if content.is_a?(Uri)
+            Redland.librdf_parser_parse_into_model(rdf_parser, content.rdf_uri, base_uri, @rdf_model).zero?
+          else
+            Redland.librdf_parser_parse_string_into_model(rdf_parser, content, base_uri, @rdf_model).zero?
+          end
+        end
+      ensure
+        Redland.librdf_free_parser(rdf_parser)
+      end
+      self
+    end
+
+    # Parse input in RDF/XML format.
+    # Shortcut for {#from}(content, :format => "rdfxml").
+    #
+    # @param (see #from)
+    # @yieldparam [Statement]
+    # @return [void]
+    def from_rdfxml(content, options = {}, &block)
+      from(content, options.merge(:format => "rdfxml"), &block)
+    end
+
+    # Parse input in NTriples format.
+    # Shortcut for {#from}(content, :format => "ntriples").
+    #
+    # @param (see #from)
+    # @yieldparam [Statement]
+    # @return [void]
+    def from_ntriples(content, options = {}, &block)
+      from(content, options.merge(:format => "ntriples"), &block)
+    end
+
+    # Parse input in Turtls format.
+    # Shortcut for {#from}(content, :format => "turtle").
+    #
+    # @param (see #from)
+    # @yieldparam [Statement]
+    # @return [void]
+    def from_turtle(content, options = {}, &block)
+      from(content, options.merge(:format => "turtle"), &block)
+    end
+
+    # Parse input as stream from URI (or File)
+    #
+    # @param [URI, String] uri URI of the endpoint or file path
+    # @param [Hash] options (see {#from})
+    # @yieldparam [Statement]
+    # @return [void]
+    def from_uri(uri, options = {}, &block)
+      if uri.is_a?(String)
+        uri = URI.parse(uri)
+        uri = URI.parse("file://#{File.expand_path(uri.to_s)}") if uri.scheme.nil?
+      end
+      from(uri, options, &block)
+    end
+    alias_method :from_file, :from_uri
+  end
+end

data/lib/redlander/serializing.rb

@@ -0,0 +1,89 @@
+module Redlander
+  # Syntax parsing methods.
+  # "self" is assumed to be an instance of Redlander::Model
+  module Serializing
+    # Serialize model into a string
+    #
+    # @param [Hash] options
+    # @option options [String] :format name of the serializer to use,
+    # @option options [String] :mime_type MIME type of the syntax, if applicable,
+    # @option options [String, URI] :type_uri URI of syntax, if applicable,
+    # @option options [String, URI] :base_uri base URI,
+    #   to be applied to the nodes with relative URIs.
+    # @raise [RedlandError] if it fails to create a serializer
+    def to(options = {})
+      format = options[:format].to_s
+      mime_type = options[:mime_type] && options[:mime_type].to_s
+      type_uri = options[:type_uri] && options[:type_uri].to_s
+      base_uri = options[:base_uri] && options[:base_uri].to_s
+
+      rdf_serializer = Redland.librdf_new_serializer(Redlander.rdf_world, format, mime_type, type_uri)
+      raise RedlandError, "Failed to create a new serializer" if rdf_serializer.null?
+
+      begin
+        if options[:file]
+          Redland.librdf_serializer_serialize_model_to_file(rdf_serializer, options[:file], base_uri, @rdf_model).zero?
+        else
+          Redland.librdf_serializer_serialize_model_to_string(rdf_serializer, base_uri, @rdf_model)
+        end
+      ensure
+        Redland.librdf_free_serializer(rdf_serializer)
+      end
+    end
+
+    # Serialize the model in RDF/XML format.
+    # Shortcut for {#to}(:format => "rdfxml").
+    #
+    # @param (see #to)
+    # @return [String]
+    def to_rdfxml(options = {})
+      to(options.merge(:format => "rdfxml"))
+    end
+
+    # Serialize the model in NTriples format.
+    # Shortcut for {#to}(:format => "ntriples").
+    #
+    # @param (see #to)
+    # @return [String]
+    def to_ntriples(options = {})
+      to(options.merge(:format => "ntriples"))
+    end
+
+    # Serialize the model in Turtle format.
+    # Shortcut for {#to}(:format => "turtle").
+    #
+    # @param (see #to)
+    # @return [String]
+    def to_turtle(options = {})
+      to(options.merge(:format => "turtle"))
+    end
+
+    # Serialize the model in JSON format.
+    # Shortcut for {#to}(:format => "json").
+    #
+    # @param (see #to)
+    # @return [String]
+    def to_json(options = {})
+      to(options.merge(:format => "json"))
+    end
+
+    # Serialize the model in Dot format.
+    # Shortcut for {#to}(:format => "dot").
+    #
+    # @param (see #to)
+    # @return [String]
+    def to_dot(options = {})
+      to(options.merge(:format => "dot"))
+    end
+
+    # Serialize the model to a file.
+    # Shortcut for {#to}(:format => "rdfxml").
+    #
+    # @param [String] filename path to the output file
+    # @param [Hash] options (see {#to} options)
+    # @return [void]
+    def to_file(filename, options = {})
+      to(options.merge(:file => filename))
+    end
+  end
+end

data/lib/redlander/statement.rb

@@ -1,72 +1,80 @@
-require 'redlander/stream'
-require "redlander/error_container"
-
 module Redlander
+  # RDF statement
   class Statement
-    include ErrorContainer
-
+    # @api private
     attr_reader :rdf_statement
 
     # Create an RDF statement.
-    # Source can be:
-    #   Hash, where
-    #     :subject
-    #     :predicate
-    #     :object
-    #   Stream, so that a statement is extracted from its current position
+    #
+    # @param [Hash] source
+    # @option source [Node, String, URI, nil] :subject
+    # @option source [Node, String, URI, nil] :predicate
+    # @option source [Node, String, URI, nil] :object
+    # @raise [NotImplementedError] if cannot create a Statement from the given source.
+    # @raise [RedlandError] if it fails to create a Statement.
     def initialize(source = {})
       @rdf_statement = case source
-                       when Stream
-                         # Pull a (current) statement from the stream
-                         copy_rdf_statement_on_initialize(Redland.librdf_stream_get_object(source.rdf_stream))
+                       when FFI::Pointer
+                         wrap(source)
                        when Hash
                          # Create a new statement from nodes
-                         s = source[:subject] && Node.new(source[:subject]).rdf_node
-                         p = source[:predicate] && Node.new(source[:predicate]).rdf_node
-                         o = source[:object] && Node.new(source[:object]).rdf_node
+                         s = rdf_node_from(source[:subject])
+                         p = rdf_node_from(source[:predicate])
+                         o = rdf_node_from(source[:object])
                          Redland.librdf_new_statement_from_nodes(Redlander.rdf_world, s, p, o)
                        else
-                         # TODO
-                         raise NotImplementedError.new
+                         raise NotImplementedError, "Cannot create Statement from '#{source.inspect}'"
                        end
-      raise RedlandError.new("Failed to create a new statement") if @rdf_statement.null?
+      raise RedlandError, "Failed to create a new statement" if @rdf_statement.null?
       ObjectSpace.define_finalizer(self, proc { Redland.librdf_free_statement(@rdf_statement) })
     end
 
+    # Subject of the statment.
+    #
+    # @return [Node, nil]
     def subject
-      node = Node.new(self, :subject)
-      node.rdf_node.null? ? nil : node
+      rdf_node = Redland.librdf_statement_get_subject(@rdf_statement)
+      rdf_node.null? ? nil : Node.new(rdf_node)
     end
 
+    # Predicate of the statement.
+    #
+    # @return [Node, nil]
     def predicate
-      node = Node.new(self, :predicate)
-      node.rdf_node.null? ? nil : node
+      rdf_node = Redland.librdf_statement_get_predicate(@rdf_statement)
+      rdf_node.null? ? nil : Node.new(rdf_node)
     end
 
+    # Object of the statement.
+    #
+    # @return [Node, nil]
     def object
-      node = Node.new(self, :object)
-      node.rdf_node.null? ? nil : node
+      rdf_node = Redland.librdf_statement_get_object(@rdf_statement)
+      rdf_node.null? ? nil : Node.new(rdf_node)
     end
 
-    # set the subject of the statement
+    # Set the subject of the statement
+    #
+    # @param [Node, nil] node
+    # @return [void]
     def subject=(node)
-      binding_to_statement(node) {
-        Redland.librdf_statement_set_subject(@rdf_statement, node.rdf_node)
-      }
+      Redland.librdf_statement_set_subject(@rdf_statement, rdf_node_from(node))
     end
 
-    # set the predicate of the statement
+    # Set the predicate of the statement
+    #
+    # @param [Node, nil] node
+    # @return [void]
     def predicate=(node)
-      binding_to_statement(node) {
-        Redland.librdf_statement_set_predicate(@rdf_statement, node.rdf_node)
-      }
+      Redland.librdf_statement_set_predicate(@rdf_statement, rdf_node_from(node))
     end
 
-    # set the object of the statement
+    # Set the object of the statement
+    #
+    # @param [Node, nil] node
+    # @return [void]
     def object=(node)
-      binding_to_statement(node) {
-        Redland.librdf_statement_set_object(@rdf_statement, node.rdf_node)
-      }
+      Redland.librdf_statement_set_object(@rdf_statement, rdf_node_from(node))
     end
 
     def eql?(other_statement)
@@ -84,36 +92,29 @@ module Redlander
       Redland.librdf_statement_to_string(@rdf_statement)
     end
 
-    # A valid statement satisfies the following:
-    # URI or blank subject, URI predicate and URI or blank or literal object (i.e. anything).
-    def valid?
-      attributes_satisfy? ? errors.clear : errors.add("is invalid")
-      errors.empty?
-    end
-
 
     private
 
-    def attributes_satisfy?
-      !subject.nil? && (subject.resource? || subject.blank?) &&
-        !predicate.nil? && predicate.resource? &&
-        !object.nil?
-    end
-
-    def binding_to_statement(node)
-      if node.frozen?
-        raise RedlandError.new("Cannot assign a bound node")
+    # @api private
+    def wrap(s)
+      if s.null?
+        raise RedlandError, "Failed to create a new statement"
       else
-        node.freeze
-        yield
+        Redland.librdf_new_statement_from_statement(s)
       end
     end
 
-    def copy_rdf_statement_on_initialize(s)
-      if s.null?
-        raise RedlandError.new("Failed to create a new statement")
+    # Create a Node from the source
+    # and get its rdf_node, or return nil
+    # @api private
+    def rdf_node_from(source)
+      case source
+      when NilClass
+        nil
+      when Node
+        source.rdf_node
       else
-        Redland.librdf_new_statement_from_statement(s)
+        Node.new(source).rdf_node
       end
     end
   end