rdf 0.3.0.pre → 0.3.0

data/lib/rdf/query/pattern.rb

@@ -7,30 +7,27 @@ module RDF; class Query
     # @since 0.2.2
     def self.from(pattern, options = {})
       case pattern
-        when Pattern   then pattern
-        when Statement then self.new(options.merge(pattern.to_hash))
-        when Hash      then self.new(options.merge(pattern))
-        when Array     then self.new(pattern[0], pattern[1], pattern[2], options.merge(:context => pattern[3]))
-        else raise ArgumentError.new("expected RDF::Query::Pattern, RDF::Statement, Hash, or Array, but got #{pattern.inspect}")
+        when Pattern then pattern
+        when Array, Statement
+          self.new(pattern[0], pattern[1], pattern[2], options.merge(:context => pattern[3]))
+        when Hash    then self.new(options.merge(pattern))
+        else raise ArgumentError, "expected RDF::Query::Pattern, RDF::Statement, Hash, or Array, but got #{pattern.inspect}"
       end
     end
 
-    # @return [Hash{Symbol => Object}]
-    attr_reader :options
-
     ##
     # @overload initialize(options = {})
     #   @param  [Hash{Symbol => Object}]     options
     #   @option options [Variable, Resource] :subject   (nil)
     #   @option options [Variable, URI]      :predicate (nil)
-    #   @option options [Variable, Value]    :object    (nil)
+    #   @option options [Variable, Term]     :object    (nil)
     #   @option options [Variable, Resource] :context   (nil)
     #   @option options [Boolean]            :optional  (false)
     #
     # @overload initialize(subject, predicate, object, options = {})
     #   @param  [Variable, Resource]         subject
     #   @param  [Variable, URI]              predicate
-    #   @param  [Variable, Value]            object
+    #   @param  [Variable, Term]             object
     #   @param  [Hash{Symbol => Object}]     options
     #   @option options [Variable, Resource] :context   (nil)
     #   @option options [Boolean]            :optional  (false)
@@ -48,6 +45,63 @@ module RDF; class Query
       super
     end
 
+    ##
+    # Any additional options for this pattern.
+    #
+    # @return [Hash]
+    attr_reader :options
+
+    ##
+    # The estimated cost of this pattern (for query optimization).
+    #
+    # @return [Numeric]
+    attr_accessor :cost
+
+    ##
+    # Returns `true` if this is a blank pattern, with all terms being `nil`.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def blank?
+      subject.nil? && predicate.nil? && object.nil? && context.nil?
+    end
+
+    ##
+    # Returns `true` if this is a constant pattern, with all terms being
+    # either URIs, blank nodes, or literals.
+    #
+    # A constant pattern is structurally and functionally equivalent to an
+    # RDF statement.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def constant?
+      !(variable?)
+    end
+
+    ##
+    # Returns `true` if this is a variable pattern, with any term being
+    # `nil` or a variable.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def variable?
+      subject.nil? || predicate.nil? || object.nil? || context.nil? || has_variables?
+    end
+
+    ##
+    # Returns `true` if this pattern contains any variables.
+    #
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def has_variables?
+      subject.is_a?(Variable) ||
+        predicate.is_a?(Variable) ||
+        object.is_a?(Variable) ||
+        context.is_a?(Variable)
+    end
+    alias_method :variables?, :has_variables?
+
     ##
     # Returns `true` if this is an optional pattern.
     #
@@ -55,7 +109,7 @@ module RDF; class Query
     #   Pattern.new(:s, :p, :o).optional?                     #=> false
     #   Pattern.new(:s, :p, :o, :optional => true).optional?  #=> true
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` or `false`
     # @since  0.3.0
     def optional?
       !!options[:optional]
@@ -74,7 +128,7 @@ module RDF; class Query
     #
     # @param  [RDF::Queryable] queryable
     #   the graph or repository to query
-    # @param  [Hash{Symbol => RDF::Value}] bindings
+    # @param  [Hash{Symbol => RDF::Term}] bindings
     #   optional variable bindings to use
     # @yield  [statement]
     #   each matching statement
@@ -83,44 +137,35 @@ module RDF; class Query
     # @return [Enumerator]
     #   an enumerator yielding matching statements
     # @see    RDF::Queryable#query
+    # @since  0.3.0
     def execute(queryable, bindings = {}, &block)
-      variables = self.variables
+      query = {
+        :subject   => subject   && subject.variable?   ? bindings[subject.to_sym]   : subject,
+        :predicate => predicate && predicate.variable? ? bindings[predicate.to_sym] : predicate,
+        :object    => object    && object.variable?    ? bindings[object.to_sym]    : object,
+        # TODO: context handling?
+      }
 
-      # Does this pattern contain any variables?
-      if variables.empty?
-        # With no variables to worry about, we will let the repository
-        # implementation yield matching statements directly:
-        queryable.query(self, &block)
+      # Do all the variable terms refer to distinct variables?
+      variables = self.variables
+      if variable_count == variables.size
+        # If so, we can just let the repository implementation handle
+        # everything and yield matching statements directly:
+        queryable.query(query, &block)
 
-      # Yes, this pattern uses at least one variable...
+      # No, some terms actually refer to the same variable...
       else
-        query = {
-          :subject   => subject   && subject.variable?   ? bindings[subject.to_sym]   : subject,
-          :predicate => predicate && predicate.variable? ? bindings[predicate.to_sym] : predicate,
-          :object    => object    && object.variable?    ? bindings[object.to_sym]    : object,
-          # TODO: context handling?
-        }
-
-        # Do all the variable terms refer to distinct variables?
-        if variable_count == variables.size
-          # If so, we can just let the repository implementation handle
-          # everything and yield matching statements directly:
-          queryable.query(query, &block)
-
-        # 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
-          queryable.query(query) do |statement|
-            # Only yield those matching statements where the variable
-            # constraint is also satisfied:
-            # FIXME: `Array#uniq` uses `#eql?` and `#hash`, not `#==`
-            if matches = terms.map { |term| statement.send(term) }.uniq.size.equal?(1)
-              block.call(statement)
-            end
+        # 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
+        queryable.query(query) do |statement|
+          # Only yield those matching statements where the variable
+          # constraint is also satisfied:
+          # FIXME: `Array#uniq` uses `#eql?` and `#hash`, not `#==`
+          if matches = terms.map { |term| statement.send(term) }.uniq.size.equal?(1)
+            block.call(statement)
           end
         end
       end
@@ -136,6 +181,7 @@ module RDF; class Query
     # @param  [RDF::Statement] statement
     #   an RDF statement to bind terms from
     # @return [RDF::Query::Solution]
+    # @since  0.3.0
     def solution(statement)
       RDF::Query::Solution.new do |solution|
         solution[subject.to_sym]   = statement.subject   if subject.variable?
@@ -144,16 +190,6 @@ module RDF; class Query
       end
     end
 
-    ##
-    # Returns `true` if this pattern contains any variables.
-    #
-    # @return [Boolean] `true` or `false`
-    def variables?
-      subject.is_a?(Variable) ||
-        predicate.is_a?(Variable) ||
-        object.is_a?(Variable)
-    end
-
     ##
     # Returns the variable terms in this pattern.
     #
@@ -222,7 +258,7 @@ module RDF; class Query
     ##
     # Returns all bindings in this pattern.
     #
-    # @return [Hash{Symbol => Value}]
+    # @return [Hash{Symbol => RDF::Term}]
     def bindings
       bindings = {}
       bindings.merge!(subject.bindings)   if subject.is_a?(Variable)
@@ -234,7 +270,7 @@ module RDF; class Query
     ##
     # Returns `true` if all variables in this pattern are bound.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` or `false`
     def bound?
       !variables.empty? && variables.values.all?(&:bound?)
     end
@@ -250,7 +286,7 @@ module RDF; class Query
     ##
     # Returns `true` if all variables in this pattern are unbound.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` or `false`
     def unbound?
       !variables.empty? && variables.values.all?(&:unbound?)
     end

data/lib/rdf/query/solution.rb

@@ -31,7 +31,7 @@ class RDF::Query
     ##
     # Initializes the query solution.
     #
-    # @param  [Hash{Symbol => RDF::Value}] bindings
+    # @param  [Hash{Symbol => RDF::Term}] bindings
     # @yield  [solution]
     def initialize(bindings = {}, &block)
       @bindings = bindings.to_hash
@@ -52,7 +52,7 @@ class RDF::Query
     #
     # @yield  [name, value]
     # @yieldparam [Symbol] name
-    # @yieldparam [RDF::Value] value
+    # @yieldparam [RDF::Term] value
     # @return [Enumerator]
     def each_binding(&block)
       @bindings.each(&block)
@@ -74,7 +74,7 @@ class RDF::Query
     # Enumerates over every variable value in this solution.
     #
     # @yield  [value]
-    # @yieldparam [RDF::Value] value
+    # @yieldparam [RDF::Term] value
     # @return [Enumerator]
     def each_value(&block)
       @bindings.each_value(&block)
@@ -129,7 +129,7 @@ class RDF::Query
     #
     # @param  [Symbol, #to_sym] name
     #   the variable name
-    # @return [RDF::Value]
+    # @return [RDF::Term]
     def [](name)
       @bindings[name.to_sym]
     end
@@ -139,8 +139,8 @@ class RDF::Query
     #
     # @param  [Symbol, #to_sym] name
     #   the variable name
-    # @param  [RDF::Value] value
-    # @return [RDF::Value]
+    # @param  [RDF::Term] value
+    # @return [RDF::Term]
     # @since  0.3.0
     def []=(name, value)
       @bindings[name.to_sym] = value
@@ -172,13 +172,13 @@ class RDF::Query
     end
 
     ##
-    # @return [Array<Array(Symbol, RDF::Value)>}
+    # @return [Array<Array(Symbol, RDF::Term)>}
     def to_a
       @bindings.to_a
     end
 
     ##
-    # @return [Hash{Symbol => RDF::Value}}
+    # @return [Hash{Symbol => RDF::Term}}
     def to_hash
       @bindings.dup
     end
@@ -193,7 +193,7 @@ class RDF::Query
 
     ##
     # @param  [Symbol] name
-    # @return [RDF::Value]
+    # @return [RDF::Term]
     def method_missing(name, *args, &block)
       if args.empty? && @bindings.has_key?(name.to_sym)
         @bindings[name.to_sym]

data/lib/rdf/query/variable.rb

@@ -43,7 +43,7 @@ class RDF::Query
   #   var.to_s       #=> "?y=123"
   #
   class Variable
-    include RDF::Value
+    include RDF::Term
 
     ##
     # The variable's name.
@@ -55,13 +55,13 @@ class RDF::Query
     ##
     # The variable's value.
     #
-    # @return [RDF::Value]
+    # @return [RDF::Term]
     attr_accessor :value
 
     ##
     # @param  [Symbol, #to_sym] name
     #   the variable name
-    # @param  [RDF::Value]  value
+    # @param  [RDF::Term] value
     #   an optional variable value
     def initialize(name = nil, value = nil)
       @name  = (name || "g#{__id__.to_i.abs}").to_sym
@@ -72,7 +72,7 @@ class RDF::Query
     # Returns `true`.
     #
     # @return [Boolean]
-    # @see    RDF::Value#variable?
+    # @see    RDF::Term#variable?
     # @since  0.1.7
     def variable? 
       true
@@ -105,8 +105,8 @@ class RDF::Query
     ##
     # Rebinds this variable to the given `value`.
     #
-    # @param  [RDF::Value] value
-    # @return [RDF::Value] the previous value, if any.
+    # @param  [RDF::Term] value
+    # @return [RDF::Term] the previous value, if any.
     def bind(value)
       old_value = self.value
       self.value = value
@@ -117,7 +117,7 @@ class RDF::Query
     ##
     # Unbinds this variable, discarding any currently bound value.
     #
-    # @return [RDF::Value] the previous value, if any.
+    # @return [RDF::Term] the previous value, if any.
     def unbind
       old_value = self.value
       self.value = nil
@@ -137,7 +137,7 @@ class RDF::Query
     ##
     # Returns this variable's bindings (if any) as a `Hash`.
     #
-    # @return [Hash{Symbol => RDF::Value}]
+    # @return [Hash{Symbol => RDF::Term}]
     def bindings
       unbound? ? {} : {name => value}
     end
@@ -165,7 +165,7 @@ class RDF::Query
     ##
     # Compares this variable with the given value.
     #
-    # @param  [RDF::Value] other
+    # @param  [RDF::Term] other
     # @return [Boolean]
     def ===(other)
       if unbound?

data/lib/rdf/query.rb

@@ -21,7 +21,7 @@ module RDF
   # @example Executing a basic graph pattern query
   #   graph = RDF::Graph.load('etc/doap.nt')
   #   query.execute(graph).each do |solution|
-  #     solution.inspect
+  #     puts solution.inspect
   #   end
   #
   # @example Constructing and executing a query in one go (1)
@@ -153,6 +153,33 @@ module RDF
       self
     end
 
+    ##
+    # Returns an optimized copy of this query.
+    #
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for optimization
+    # @return [RDF::Query] a copy of `self`
+    # @since  0.3.0
+    def optimize(options = {})
+      self.dup.optimize!(options)
+    end
+
+    ##
+    # Optimizes this query by reordering its constituent triple patterns
+    # according to their cost estimates.
+    #
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional options for optimization
+    # @return [void] `self`
+    # @see    RDF::Query::Pattern#cost
+    # @since  0.3.0
+    def optimize!(options = {})
+      @patterns.sort! do |a, b|
+        (a.cost || 0) <=> (b.cost || 0)
+      end
+      self
+    end
+
     ##
     # Executes this query on the given `queryable` graph or repository.
     #
@@ -164,51 +191,46 @@ module RDF
     #   the resulting solution sequence
     # @see    http://www.holygoat.co.uk/blog/entry/2005-10-25-1
     def execute(queryable, options = {})
-      @solutions = Solutions.new
-      @failed = false
-      @patterns.each do |pattern|
-        case pattern.variable_count
-          when 0 # no variables
-            if pattern.execute(queryable).empty?
-              # return an empty solution sequence:
-              @solutions.clear
-              @failed = true
-              break
-            end
+      options = options.dup
 
-          when 3 # only variables
-            pattern.execute(queryable) do |statement|
-              @solutions << pattern.solution(statement)
-            end
+      # just so we can call #keys below without worrying
+      options[:bindings] ||= {}
 
-          else case # 1 or 2 variables
+      @solutions = Solutions.new
+      # A quick empty solution simplifies the logic below; no special case for
+      # the first pattern
+      @solutions << RDF::Query::Solution.new({})
 
-            when !@solutions.have_variables?(pattern.variables.values)
-              if @solutions.empty?
-                pattern.execute(queryable) do |statement|
-                  @solutions << pattern.solution(statement)
-                end
-              else # union
-                old_solutions, @solutions = @solutions, Solutions.new
-                old_solutions.each do |solution|
-                  pattern.execute(queryable) do |statement|
-                    @solutions << solution.merge(pattern.solution(statement))
-                  end
-                end
-              end
+      @patterns.each do |pattern|
+        
+        old_solutions, @solutions = @solutions, Solutions.new
 
-            else # intersection
-              @solutions.each_with_index do |solution, index|
-                failed = true
-                pattern.execute(queryable, solution) do |statement|
-                  failed = false
-                  solution.merge!(pattern.solution(statement))
-                end
-                @solutions[index] = nil if failed && !pattern.optional?
+        options[:bindings].keys.each do |variable|
+          if pattern.variables.include?(variable)
+            unbound_solutions, old_solutions = old_solutions, Solutions.new
+            options[:bindings][variable].each do |binding|
+              unbound_solutions.each do |solution|
+                old_solutions << solution.merge(variable => binding)
               end
-              @solutions.compact! # remove `nil` entries
+            end
+            options[:bindings].delete(variable)
+          end
+        end
+
+        old_solutions.each do |solution|
+          pattern.execute(queryable, solution) do |statement|
+            @solutions << solution.merge(pattern.solution(statement))
           end
         end
+
+        # It's important to abort failed queries quickly because later patterns
+        # that can have constraints are often broad without them.
+        # We have no solutions at all:
+        return @solutions if @solutions.empty?
+        # We have no solutions for variables we should have solutions for:
+        if !pattern.optional? && pattern.variables.keys.any? { |variable| !@solutions.variable_names.include?(variable) }
+          return Solutions.new
+        end
       end
       @solutions
     end
@@ -222,7 +244,7 @@ module RDF
     # @return [Boolean]
     # @see    #matched?
     def failed?
-      @failed
+      @solutions.empty?
     end
 
     ##

data/lib/rdf/reader.rb

@@ -221,8 +221,8 @@ module RDF
     #
     # @return [RDF::URI]
     def prefix(name, uri = nil)
-      name = name.respond_to?(:to_sym) ? name.to_sym : name.to_s.to_sym
-      uri.nil? ? prefixes[name] : prefixes[name] = RDF::URI(uri)
+      name = name.to_s.empty? ? nil : (name.respond_to?(:to_sym) ? name.to_sym : name.to_s.to_sym)
+      uri.nil? ? prefixes[name] : prefixes[name] = uri
     end
     alias_method :prefix!, :prefix
 
@@ -271,7 +271,7 @@ module RDF
     #     each triple
     #   @yieldparam  [RDF::Resource] subject
     #   @yieldparam  [RDF::URI]      predicate
-    #   @yieldparam  [RDF::Value]    object
+    #   @yieldparam  [RDF::Term]     object
     #   @yieldreturn [void] ignored
     #   @return [void]
     #
@@ -331,7 +331,7 @@ module RDF
     ##
     # Reads a triple from the input stream.
     #
-    # @return [Array(RDF::Value)] a triple
+    # @return [Array(RDF::Term)] a triple
     # @raise  [NotImplementedError] unless implemented in subclass
     # @abstract
     def read_triple
@@ -423,7 +423,8 @@ module RDF
     ##
     # @return [String]
     def readline
-      @line = @input.readline.chomp
+      @line = @input.readline
+      @line.chomp!
       @line.force_encoding(encoding) if @line.respond_to?(:force_encoding) # for Ruby 1.9+
       @line
     end