rdf 3.1.1 → 3.1.2

data/lib/rdf/model/uri.rb

@@ -400,7 +400,7 @@ module RDF
     # @example Joining two URIs
     #     RDF::URI.new('http://example.org/foo/bar').join('/foo')
     #     #=> RDF::URI('http://example.org/foo')
-    # @see <http://github.com/ruby-rdf/rdf-spec/blob/master/lib/rdf/spec/uri.rb>
+    # @see <https://github.com/ruby-rdf/rdf-spec/blob/master/lib/rdf/spec/uri.rb>
     # @see <http://tools.ietf.org/html/rfc3986#section-5.2>
     # @see RDF::URI#/
     # @see RDF::URI#+
@@ -471,7 +471,7 @@ module RDF
     # @see RDF::URI#+
     # @see RDF::URI#join
     # @see <http://tools.ietf.org/html/rfc3986#section-5.2>
-    # @see <http://github.com/ruby-rdf/rdf-spec/blob/master/lib/rdf/spec/uri.rb>
+    # @see <https://github.com/ruby-rdf/rdf-spec/blob/master/lib/rdf/spec/uri.rb>
     # @example Building a HTTP URL
     #     RDF::URI.new('http://example.org') / 'jhacker' / 'foaf.ttl'
     #     #=> RDF::URI('http://example.org/jhacker/foaf.ttl')

data/lib/rdf/nquads.rb

@@ -69,9 +69,9 @@ module RDF
 
           begin
             unless blank? || read_comment
-              subject   = read_uriref || read_node || fail_subject
+              subject   = read_uriref || read_node || read_rdfstar || fail_subject
               predicate = read_uriref(intern: true) || fail_predicate
-              object    = read_uriref || read_node || read_literal || fail_object
+              object    = read_uriref || read_node || read_literal || read_rdfstar || fail_object
               graph_name    = read_uriref || read_node
               if validate? && !read_eos
                 log_error("Expected end of statement (found: #{current_line.inspect})", lineno: lineno, exception: RDF::ReaderError)

data/lib/rdf/ntriples.rb

@@ -15,15 +15,17 @@ module RDF
   #
   #     <https://rubygems.org/gems/rdf> <http://purl.org/dc/terms/title> "rdf" .
   #
-  # Installation
-  # ------------
+  # ## RDFStar (RDF*)
+  #
+  # Supports statements as resources using `<<s p o>>`.
+  #
+  # ## Installation
   #
   # This is the only RDF serialization format that is directly supported by
   # RDF.rb. Support for other formats is available in the form of add-on
   # gems, e.g. 'rdf-xml' or 'rdf-json'.
   #
-  # Documentation
-  # -------------
+  # ## Documentation
   #
   # * {RDF::NTriples::Format}
   # * {RDF::NTriples::Reader}

data/lib/rdf/ntriples/reader.rb

@@ -25,6 +25,10 @@ module RDF::NTriples
   #     end
   #   end
   #
+  # ** RDFStar (RDF*)
+  #
+  # Supports statements as resources using `<<s p o>>`.
+  #
   # @see http://www.w3.org/TR/rdf-testcases/#ntriples
   # @see http://www.w3.org/TR/n-triples/
   class Reader < RDF::Reader
@@ -70,6 +74,10 @@ module RDF::NTriples
     # 22
     STRING_LITERAL_QUOTE = /"((?:[^\"\\\n\r]|#{ECHAR}|#{UCHAR})*)"/.freeze
 
+    # RDF*
+    ST_START              = /^<</.freeze
+    ST_END                = /^\s*>>/.freeze
+
     # @see http://www.w3.org/TR/rdf-testcases/#ntrip_grammar
     COMMENT               = /^#\s*(.*)$/.freeze
     NODEID                = /^#{BLANK_NODE_LABEL}/.freeze
@@ -202,7 +210,7 @@ module RDF::NTriples
       begin
         read_statement
       rescue RDF::ReaderError
-        value = read_uriref || read_node || read_literal
+        value = read_uriref || read_node || read_literal || read_rdfstar
         log_recover
         value
       end
@@ -218,9 +226,9 @@ module RDF::NTriples
 
         begin
           unless blank? || read_comment
-            subject   = read_uriref || read_node || fail_subject
+            subject   = read_uriref || read_node || read_rdfstar || fail_subject
             predicate = read_uriref(intern: true) || fail_predicate
-            object    = read_uriref || read_node || read_literal || fail_object
+            object    = read_uriref || read_node || read_literal || read_rdfstar || fail_object
 
             if validate? && !read_eos
               log_error("Expected end of statement (found: #{current_line.inspect})", lineno: lineno, exception: RDF::ReaderError)
@@ -234,6 +242,20 @@ module RDF::NTriples
       end
     end
 
+    ##
+    # @return [RDF::Statement]
+    def read_rdfstar
+      if @options[:rdfstar] && match(ST_START)
+        subject   = read_uriref || read_node || read_rdfstar || fail_subject
+        predicate = read_uriref(intern: true) || fail_predicate
+        object    = read_uriref || read_node || read_literal || read_rdfstar || fail_object
+        if !match(ST_END)
+          log_error("Expected end of statement (found: #{current_line.inspect})", lineno: lineno, exception: RDF::ReaderError)
+        end
+        RDF::Statement.new(subject, predicate, object)
+      end
+    end
+
     ##
     # @return [Boolean]
     # @see    http://www.w3.org/TR/rdf-testcases/#ntrip_grammar (comment)

data/lib/rdf/ntriples/writer.rb

@@ -221,6 +221,15 @@ module RDF::NTriples
       format_triple(*statement.to_triple, **options)
     end
 
+    ##
+    # Returns the N-Triples representation of an RDF* reified statement.
+    #
+    # @param  [RDF::Statement] statement
+    # @param  [Hash{Symbol => Object}] options ({})
+    # @return [String]
+    def format_rdfstar(statement, **options)
+      "<<%s %s %s>>" % statement.to_a.map { |value| format_term(value, **options) }
+    end
     ##
     # Returns the N-Triples representation of a triple.
     #

data/lib/rdf/query.rb

@@ -289,6 +289,8 @@ module RDF
     #   any additional keyword options
     # @option options [Hash{Symbol => RDF::Term}] bindings
     #   optional variable bindings to use
+    # @option options [Boolean] :optimize
+    #   Optimize query before execution.
     # @option options [RDF::Query::Solutions] solutions
     #   optional initial solutions for chained queries
     # @yield  [solution]
@@ -311,6 +313,7 @@ module RDF
         return @solutions
       end
 
+      self.optimize! if options[:optimize]
       patterns = @patterns
       graph_name = name if graph_name.nil?
       @graph_name = graph_name unless graph_name.nil?
@@ -505,7 +508,7 @@ module RDF
     # @return [RDF::Query]
     def dup
       patterns = @patterns.map {|p| p.dup}
-      Query.new(patterns, solutions: @solutions.dup, **options)
+      Query.new(patterns, graph_name: graph_name, solutions: @solutions.dup, **options)
     end
 
     ##

data/lib/rdf/query/hash_pattern_normalizer.rb

@@ -77,14 +77,15 @@ module RDF; class Query
       ##
       # Returns the normalization of the specified `hash_pattern`.
       #
-      # @param [Hash{Symbol => Object}] hash_pattern (Hash.new)
-      #   the query pattern as a hash.
-      # @param [Hash{Symbol => Object}] options (Hash.new)
-      #   any additional normalization options.
-      # @option options [String] :anonymous_subject_format ("__%s__")
-      #   the string format for anonymous subjects.
-      # @return [Hash{Symbol => Object}]
-      #   the resulting query pattern as a normalized hash.
+      # @overload normalize!(hash_pattern, **options)
+      #   @param [Hash{Symbol => Object}] hash_pattern (Hash.new)
+      #     the query pattern as a hash.
+      #   @param [Hash{Symbol => Object}] **options
+      #     any additional normalization options.
+      #   @option options [String] :anonymous_subject_format ("__%s__")
+      #     the string format for anonymous subjects.
+      #   @return [Hash{Symbol => Object}]
+      #     the resulting query pattern as a normalized hash.
       def normalize!(*args)
         hash_pattern = args.shift
         options = args.shift || {}

data/lib/rdf/query/pattern.rb

@@ -50,10 +50,12 @@ module RDF; class Query
 
       # Estmate cost positionally, with variables being least expensive as objects, then predicates, then subjects, then graph_names.
       # XXX does not consider bound variables, which would need to be dynamically calculated.
-      @cost = (@object.nil?     || @object.is_a?(Variable)      ? 1 : 0) +
-              (@predicate.nil?  || @predicate.is_a?(Variable)   ? 2 : 0) +
-              (@subject.nil?    || @subject.is_a?(Variable)     ? 4 : 0) +
-              (@graph_name.is_a?(Variable)                      ? 8 : 0)
+      @cost = (@object.nil?     || @object.is_a?(Variable)      ? 8 : 0) +
+              (@predicate.nil?  || @predicate.is_a?(Variable)   ? 4 : 0) +
+              (@subject.nil?    || @subject.is_a?(Variable)     ? 2 : 0) +
+              (@graph_name.is_a?(Variable)                      ? 1 : 0) +
+              (@object.is_a?(Pattern)                           ? (@object.cost * 4) : 0) +
+              (@subject.is_a?(Pattern)                          ? (@subject.cost * 2) : 0)
       super
     end
 
@@ -84,10 +86,10 @@ module RDF; class Query
     # @return [Boolean] `true` or `false`
     # @since  0.3.0
     def has_variables?
-      subject.is_a?(Variable) ||
-        predicate.is_a?(Variable) ||
-        object.is_a?(Variable) ||
-        graph_name.is_a?(Variable)
+      subject    && subject.variable? ||
+      predicate  && predicate.variable? ||
+      object     && object.variable? ||
+      graph_name && graph_name.variable?
     end
     alias_method :variables?, :has_variables?
 
@@ -117,13 +119,33 @@ module RDF; class Query
       false
     end
 
+    ##
+    # Checks pattern equality against a statement, considering nesting.
+    #
+    # * A pattern which has a pattern as a subject or an object, matches
+    #   a statement having a statement as a subject or an object using {#eql?}.
+    #
+    # @param  [Statement] other
+    # @return [Boolean]
+    #
+    # @see RDF::URI#==
+    # @see RDF::Node#==
+    # @see RDF::Literal#==
+    # @see RDF::Query::Variable#==
+    def eql?(other)
+      return false unless other.is_a?(Statement) && (self.graph_name || false) == (other.graph_name || false)
+
+      predicate == other.predicate &&
+      (subject.is_a?(Pattern) ? subject.eql?(other.subject) : subject == other.subject) &&
+      (object.is_a?(Pattern) ? object.eql?(other.object) : object == other.object)
+    end
+
     ##
     # Executes this query pattern on the given `queryable` object.
     #
     # Values are matched using using Queryable#query_pattern.
     #
-    # If the optional `bindings` are given, variables will be substituted with their values
-    # when executing the query.
+    # If the optional `bindings` are given, variables will be substituted with their values when executing the query.
     #
     # To match triples only in the default graph, set graph_name to `false`.
     #
@@ -198,6 +220,8 @@ module RDF; class Query
         solution[predicate.to_sym]  = statement.predicate  if predicate.is_a?(Variable)
         solution[object.to_sym]     = statement.object     if object.is_a?(Variable)
         solution[graph_name.to_sym] = statement.graph_name if graph_name.is_a?(Variable)
+        solution.merge!(subject.solution(statement.subject)) if subject.is_a?(Pattern)
+        solution.merge!(object.solution(statement.object)) if object.is_a?(Pattern)
       end
     end
 
@@ -229,7 +253,8 @@ module RDF; class Query
     # @return [Integer] (0..3)
     def variable_count
       [subject, predicate, object, graph_name].inject(0) do |memo, term|
-        memo += (term.is_a?(Variable) ? 1 : 0)
+        memo += (term.is_a?(Variable) ? 1 :
+                 (term.is_a?(Pattern) ? term.variable_count : 0))
       end
     end
     alias_method :cardinality, :variable_count
@@ -243,7 +268,7 @@ module RDF; class Query
     # @return [Hash{Symbol => Variable}]
     def variables
       [subject, predicate, object, graph_name].inject({}) do |memo, term|
-        term.is_a?(Variable) ? memo.merge(term.variables) : memo
+        term && term.variable? ? memo.merge(term.variables) : memo
       end
     end
 
@@ -254,8 +279,10 @@ module RDF; class Query
     # @return [self]
     def bind(solution)
       self.to_quad.each_with_index do |term, index|
-        if term && term.variable? && solution[term]
+        if term.is_a?(Variable) && solution[term]
           self[index] = solution[term] 
+        elsif term.is_a?(Pattern)
+          term.bind(solution)
         end
       end
       self
@@ -283,9 +310,9 @@ module RDF; class Query
     # @return [Hash{Symbol => RDF::Term}]
     def bindings
       bindings = {}
-      bindings.merge!(subject.bindings)    if subject.is_a?(Variable)
+      bindings.merge!(subject.bindings)    if subject && subject.variable?
       bindings.merge!(predicate.bindings)  if predicate.is_a?(Variable)
-      bindings.merge!(object.bindings)     if object.is_a?(Variable)
+      bindings.merge!(object.bindings)     if object && object.variable?
       bindings.merge!(graph_name.bindings) if graph_name.is_a?(Variable)
       bindings
     end
@@ -330,7 +357,13 @@ module RDF; class Query
       StringIO.open do |buffer| # FIXME in RDF::Statement
         buffer << 'OPTIONAL ' if optional?
         buffer << [subject, predicate, object].map do |r|
-          r.is_a?(RDF::Query::Variable) ? r.to_s : RDF::NTriples.serialize(r)
+          if r.is_a?(RDF::Query::Variable)
+            r.to_s
+          elsif r.is_a?(RDF::Query::Pattern)
+            "<<#{r.to_s[0..-3]}>>"
+          else
+            RDF::NTriples.serialize(r)
+          end
         end.join(" ")
         buffer << case graph_name
           when nil, false then " ."

data/lib/rdf/query/solution.rb

@@ -195,12 +195,31 @@ class RDF::Query
     # Merges the bindings from the given `other` query solution into this
     # one, overwriting any existing ones having the same name.
     #
+    # ## RDFStar (RDF*)
+    #
+    # If merging a binding for a statement to a pattern,
+    # merge their embedded solutions.
+    #
     # @param  [RDF::Query::Solution, #to_h] other
     #   another query solution or hash bindings
     # @return [void] self
     # @since  0.3.0
     def merge!(other)
-      @bindings.merge!(other.to_h)
+      @bindings.merge!(other.to_h) do |key, v1, v2|
+        # Don't merge a pattern over a statement
+        # This happens because JOIN does a reverse merge,
+        # and a pattern is set in v2.
+        v2.is_a?(Pattern) ? v1 : v2
+      end
+      # Merge bindings from patterns
+      embedded_solutions = []
+      @bindings.each do |k, v|
+        if v.is_a?(Pattern) && other[k].is_a?(RDF::Statement)
+          embedded_solutions << v.solution(other[k])
+        end
+      end
+      # Merge embedded solutions
+      embedded_solutions.each {|soln| merge!(soln)}
       self
     end
 

data/lib/rdf/query/solutions.rb

@@ -66,13 +66,15 @@ module RDF; class Query
     #
     # @return [Array<Symbol>]
     def variable_names
-      variables = self.inject({}) do |result, solution|
-        solution.each_name do |name|
-          result[name] ||= true
+      @variable_names ||= begin
+        variables = self.inject({}) do |result, solution|
+          solution.each_name do |name|
+            result[name] ||= true
+          end
+          result
         end
-        result
+        variables.keys
       end
-      variables.keys
     end
 
     ##
@@ -136,6 +138,7 @@ module RDF; class Query
     # @yieldreturn [Boolean]
     # @return [self]
     def filter(criteria = {})
+      @variable_names = nil
       if block_given?
         self.reject! do |solution|
           !yield(solution.is_a?(Solution) ? solution : Solution.new(solution))
@@ -223,6 +226,13 @@ module RDF; class Query
           solution.bindings.delete_if { |k, v| !variables.include?(k.to_sym) }
         end
       end
+
+      # Make sure variable_names are ordered by projected variables
+      projected_vars, vars = variables.map(&:to_sym), variable_names
+      vars = variable_names
+
+      # Maintain projected order, and add any non-projected variables
+      @variable_names = (projected_vars & vars) + (vars - projected_vars)
       self
     end
     alias_method :select, :project

data/lib/rdf/query/variable.rb

@@ -157,12 +157,24 @@ class RDF::Query
     ##
     # Rebinds this variable to the given `value`.
     #
-    # @param  [RDF::Term] value
-    # @return [RDF::Term] the previous value, if any.
+    # @overload bind(value)
+    #   @param [RDF::Query::Solution] value
+    #   @return [self] the bound variable
+    #
+    # @overload bind(value)
+    #   @param [RDF::Term] value
+    #   @return [RDF::Term] the previous value, if any.
     def bind(value)
-      old_value = self.value
-      self.value = value
-      old_value
+      if value.is_a?(RDF::Query::Solution)
+        self.value = value.to_h.fetch(name, self.value)
+        self
+      else
+        warn "[DEPRECATION] RDF::Query::Variable#bind should be used with a solution, not a term.\n" +
+             "Called from #{Gem.location_of_caller.join(':')}"
+        old_value = self.value
+        self.value = value
+        old_value
+      end
     end
     alias_method :bind!, :bind
 

data/lib/rdf/reader.rb

@@ -121,6 +121,12 @@ module RDF
     # @return [Array<RDF::CLI::Option>]
     def self.options
       [
+        RDF::CLI::Option.new(
+          symbol: :base_uri,
+          control: :url,
+          datatype: RDF::URI,
+          on: ["--uri URI"],
+          description: "Base URI of input file, defaults to the filename.") {|arg| RDF::URI(arg)},
         RDF::CLI::Option.new(
           symbol: :canonicalize,
           datatype: TrueClass,
@@ -153,11 +159,11 @@ module RDF
             end
         end,
         RDF::CLI::Option.new(
-          symbol: :base_uri,
-          control: :url,
-          datatype: RDF::URI,
-          on: ["--uri URI"],
-          description: "Base URI of input file, defaults to the filename.") {|arg| RDF::URI(arg)},
+          symbol: :rdfstar,
+          control: :select,
+          datatype: [:PG, :SA],
+          on: ["--rdf-star MODE"],
+          description: "Parse RDF*, either in Property Graph mode (PG) or Separate Assertions mode (SA).") {|arg| arg.to_sym},
         RDF::CLI::Option.new(
           symbol: :validate,
           datatype: TrueClass,
@@ -261,42 +267,48 @@ module RDF
     #
     # @param  [IO, File, String] input
     #   the input stream to read
-    # @param [Encoding] encoding     (Encoding::UTF_8)
-    #   the encoding of the input stream
-    # @param [Boolean]  validate     (false)
-    #   whether to validate the parsed statements and values
+    # @param [#to_s]    base_uri     (nil)
+    #   the base URI to use when resolving relative URIs (not supported by
+    #   all readers)
     # @param [Boolean]  canonicalize (false)
     #   whether to canonicalize parsed literals
+    # @param [Encoding] encoding     (Encoding::UTF_8)
+    #   the encoding of the input stream
     # @param [Boolean]  intern       (true)
     #   whether to intern all parsed URIs
+    # @param [:PG, :SA] rdfstar      (nil)
+    #   support parsing RDF* statement resources.
+    #   If `:PG`, referenced statements are also emitted.
+    #   If `:SA`, referenced statements are not emitted.
     # @param [Hash]     prefixes     (Hash.new)
     #   the prefix mappings to use (not supported by all readers)
-    # @param [#to_s]    base_uri     (nil)
-    #   the base URI to use when resolving relative URIs (not supported by
-    #   all readers)
     # @param  [Hash{Symbol => Object}] options
     #   any additional options
+    # @param [Boolean]  validate     (false)
+    #   whether to validate the parsed statements and values
     # @yield  [reader] `self`
     # @yieldparam  [RDF::Reader] reader
     # @yieldreturn [void] ignored
     def initialize(input = $stdin,
-                   encoding:      Encoding::UTF_8,
-                   validate:      false,
+                   base_uri:      nil,
                    canonicalize:  false,
+                   encoding:      Encoding::UTF_8,
                    intern:        true,
                    prefixes:      Hash.new,
-                   base_uri:      nil,
+                   rdfstar:       nil,
+                   validate:      false,
                    **options,
                    &block)
 
       base_uri     ||= input.base_uri if input.respond_to?(:base_uri)
       @options = options.merge({
-        encoding:       encoding,
-        validate:       validate,
+        base_uri:       base_uri,
         canonicalize:   canonicalize,
+        encoding:       encoding,
         intern:         intern,
         prefixes:       prefixes,
-        base_uri:       base_uri
+        rdfstar:        rdfstar,
+        validate:       validate
       })
 
       @input = case input
@@ -389,6 +401,9 @@ module RDF
     # Statements are yielded in the order that they are read from the input
     # stream.
     #
+    # If the `rdfstar` option is `:PG` and triples include
+    # embedded statements, they are also enumerated.
+    #
     # @overload each_statement
     #   @yield  [statement]
     #     each statement
@@ -405,7 +420,11 @@ module RDF
     def each_statement(&block)
       if block_given?
         begin
-          loop { block.call(read_statement) }
+          loop do
+            st = read_statement
+            block.call(st)
+            each_pg_statement(st, &block) if options[:rdfstar] == :PG
+          end
         rescue EOFError
           rewind rescue nil
         end
@@ -422,6 +441,9 @@ module RDF
     # Triples are yielded in the order that they are read from the input
     # stream.
     #
+    # If the `rdfstar` option is `:PG` and triples include
+    # embedded statements, they are also enumerated.
+    #
     # @overload each_triple
     #   @yield  [subject, predicate, object]
     #     each triple
@@ -439,7 +461,14 @@ module RDF
     def each_triple(&block)
       if block_given?
         begin
-          loop { block.call(*read_triple) }
+          loop do
+            triple = read_triple
+            block.call(*triple)
+            if options[:rdfstar] == :PG
+              block.call(*triple[0].to_a) if triple[0].is_a?(Statement)
+              block.call(*triple[2].to_a) if triple[2].is_a?(Statement)
+            end
+          end
         rescue EOFError
           rewind rescue nil
         end
@@ -550,6 +579,22 @@ module RDF
       log_error("Expected object (found: #{current_line.inspect})", lineno: lineno, exception: RDF::ReaderError)
     end
 
+    ##
+    # Recursively emit embedded statements in Property Graph mode
+    #
+    # @param [RDF::Statement] statement
+    def each_pg_statement(statement, &block)
+      if statement.subject.is_a?(Statement)
+        block.call(statement.subject)
+        each_pg_statement(statement.subject, &block)
+      end
+
+      if statement.object.is_a?(Statement)
+        block.call(statement.object)
+        each_pg_statement(statement.object, &block)
+      end
+    end
+
   public
     ##
     # Returns the encoding of the input stream.