rdf 3.1.1 → 3.1.6

data/lib/rdf/ntriples/reader.rb

@@ -1,4 +1,7 @@
 # -*- encoding: utf-8 -*-
+
+require 'strscan'
+
 module RDF::NTriples
   ##
   # N-Triples parser.
@@ -25,6 +28,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 +77,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 +213,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 +229,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 +245,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

@@ -247,15 +247,22 @@ module RDF
     # Optimizes this query by reordering its constituent triple patterns
     # according to their cost estimates.
     #
+    # Optional patterns have greater cost than non-optional patterns so they will always come after non-optional patterns
+    #
     # @param  [Hash{Symbol => Object}] options
     #   any additional options for optimization
     # @return [self]
     # @see    RDF::Query::Pattern#cost
     # @since  0.3.0
     def optimize!(**options)
-      @patterns.sort! do |a, b|
+      optional, required = @patterns.partition(&:optional?)
+      required.sort! do |a, b|
+        (a.cost || 0) <=> (b.cost || 0)
+      end
+      optional.sort! do |a, b|
         (a.cost || 0) <=> (b.cost || 0)
       end
+      @patterns = required + optional
       self
     end
 
@@ -289,6 +296,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 +320,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 +515,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`.
     #
@@ -159,16 +181,10 @@ module RDF; class Query
 
       # No, some terms actually refer to the same variable...
       else
-        # Figure out which terms refer to the same variable:
-        terms = variables.each_key.find do |name|
-          terms = variable_terms(name)
-          break terms if terms.size > 1
-        end
+        # Considering embedding, figure out if variables that may appear more than once resolve to the same value.
+        vars = variables.keys
         queryable.query(query).select do |statement|
-          # Only yield those matching statements where the variable
-          # constraint is also satisfied:
-          # FIXME: `Array#uniq` uses `#eql?` and `#hash`, not `#==`
-          if terms.map { |term| statement.send(term) }.uniq.size.equal?(1)
+          if vars.all? {|var| self.var_values(var, statement).uniq.size == 1}
             yield statement if block_given?
             true
           end
@@ -198,6 +214,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.respond_to?(:solution)
+        solution.merge!(object.solution(statement.object)) if object.respond_to?(:solution)
       end
     end
 
@@ -210,8 +228,11 @@ module RDF; class Query
     # @param  [Symbol, #to_sym] name
     #   an optional variable name
     # @return [Array<Symbol>]
+    # @deprecated use {#var_values} instead
     # @since  0.3.0
     def variable_terms(name = nil)
+      warn "[DEPRECATION] RDF::Query::Pattern#variable_terms is deprecated and will be removed in a future version.\n" +
+           "Called from #{Gem.location_of_caller.join(':')}"
       terms = []
       terms << :subject    if subject.is_a?(Variable)    && (!name || name.eql?(subject.name))
       terms << :predicate  if predicate.is_a?(Variable)  && (!name || name.eql?(predicate.name))
@@ -220,6 +241,20 @@ module RDF; class Query
       terms
     end
 
+    ##
+    # Returns all values the statement in the same pattern position
+    #
+    # @param [Symbol] var
+    # @param [RDF::Statement] statement
+    # @return [Array<RDF::Term>]
+    def var_values(var, statement)
+      [:subject, :predicate, :object, :graph_name].map do |position|
+        po = self.send(position)
+        so = statement.send(position)
+        po.var_values(var, so) if po.respond_to?(:var_values)
+      end.flatten.compact
+    end
+
     ##
     # Returns the number of variables in this pattern.
     #
@@ -229,7 +264,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.respond_to?(:variable_count) ? term.variable_count : 0))
       end
     end
     alias_method :cardinality, :variable_count
@@ -243,7 +279,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 +290,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,10 +321,10 @@ module RDF; class Query
     # @return [Hash{Symbol => RDF::Term}]
     def bindings
       bindings = {}
-      bindings.merge!(subject.bindings)    if subject.is_a?(Variable)
-      bindings.merge!(predicate.bindings)  if predicate.is_a?(Variable)
-      bindings.merge!(object.bindings)     if object.is_a?(Variable)
-      bindings.merge!(graph_name.bindings) if graph_name.is_a?(Variable)
+      bindings.merge!(subject.bindings)    if subject && subject.variable?
+      bindings.merge!(predicate.bindings)  if predicate && predicate.variable?
+      bindings.merge!(object.bindings)     if object && object.variable?
+      bindings.merge!(graph_name.bindings) if graph_name && graph_name.variable?
       bindings
     end
 
@@ -327,18 +365,7 @@ module RDF; class Query
     #
     # @return [String]
     def to_s
-      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)
-        end.join(" ")
-        buffer << case graph_name
-          when nil, false then " ."
-          when Variable then " #{graph_name.to_s} ."
-          else " #{RDF::NTriples.serialize(graph_name)} ."
-        end
-        buffer.string
-      end
+      (optional? ? 'OPTIONAL ' : '') + super
     end
   end # Pattern
 end; end # RDF::Query

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

@@ -65,7 +65,7 @@ class RDF::Query
     #   the variable name
     # @param  [RDF::Term] value
     #   an optional variable value
-    # @param [Boolean] distinguished (true) Also interpreted by leading '??' or '$$' in name.
+    # @param [Boolean] distinguished (true) Also interpreted by leading '?' or '$' in name. If non-distinguished, '??' or '$$'.
     # @param [Boolean] existential (true) Also interpreted by leading '$' in name
     def initialize(name = nil, value = nil, distinguished: nil, existential: nil)
       name = (name || "g#{__id__.to_i.abs}").to_s
@@ -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
 
@@ -234,6 +246,16 @@ class RDF::Query
       end
     end
 
+    ##
+    # Returns term if var is the same as this variable.
+    #
+    # @param [Symbol] var
+    # @param [RDF::Term] term
+    # @return [RDF::Term]
+    def var_values(var, term)
+      term if var == name
+    end
+
     ##
     # Returns a string representation of this variable.
     #
@@ -253,5 +275,6 @@ class RDF::Query
       prefix = distinguished? ? (existential? ? '$' : '?') : (existential? ? '$$' : '??')
       unbound? ? "#{prefix}#{name}" : "#{prefix}#{name}=#{value}"
     end
+    alias_method :to_base, :to_s
   end # Variable
 end # RDF::Query