rdf 0.2.3 → 0.3.0.pre

data/lib/rdf/query/pattern.rb

@@ -5,12 +5,12 @@ module RDF; class Query
     ##
     # @private
     # @since 0.2.2
-    def self.from(pattern)
+    def self.from(pattern, options = {})
       case pattern
         when Pattern   then pattern
-        when Statement then self.new(pattern.to_hash)
-        when Hash      then self.new(pattern)
-        when Array     then self.new(*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}")
       end
     end
@@ -49,36 +49,151 @@ module RDF; class Query
     end
 
     ##
-    # @param  [Graph, Repository] graph
+    # Returns `true` if this is an optional pattern.
+    #
+    # @example
+    #   Pattern.new(:s, :p, :o).optional?                     #=> false
+    #   Pattern.new(:s, :p, :o, :optional => true).optional?  #=> true
+    #
+    # @return [Boolean]
+    # @since  0.3.0
+    def optional?
+      !!options[:optional]
+    end
+
+    ##
+    # Executes this query pattern on the given `queryable` object.
+    #
+    # By default any variable terms in this pattern will be treated as `nil`
+    # wildcards when executing the query. If the optional `bindings` are
+    # given, variables will be substituted with their values when executing
+    # the query.
+    #
+    # @example
+    #   Pattern.new(:s, :p, :o).execute(RDF::Repository.load('data.nt'))
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Symbol => RDF::Value}] bindings
+    #   optional variable bindings to use
+    # @yield  [statement]
+    #   each matching statement
+    # @yieldparam [RDF::Statement] statement
+    #   an RDF statement matching this pattern
     # @return [Enumerator]
-    def execute(graph, &block)
-      graph.query(self) # FIXME
+    #   an enumerator yielding matching statements
+    # @see    RDF::Queryable#query
+    def execute(queryable, bindings = {}, &block)
+      variables = self.variables
+
+      # 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)
+
+      # Yes, this pattern uses at least one 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
+          end
+        end
+      end
     end
 
     ##
-    # Returns `true` if this pattern contains variables.
+    # Returns a query solution constructed by binding any variables in this
+    # pattern with the corresponding terms in the given `statement`.
     #
-    # @return [Boolean]
+    # @example
+    #   pattern.solution(statement)
+    #
+    # @param  [RDF::Statement] statement
+    #   an RDF statement to bind terms from
+    # @return [RDF::Query::Solution]
+    def solution(statement)
+      RDF::Query::Solution.new do |solution|
+        solution[subject.to_sym]   = statement.subject   if subject.variable?
+        solution[predicate.to_sym] = statement.predicate if predicate.variable?
+        solution[object.to_sym]    = statement.object    if object.variable?
+      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.
+    #
+    # @example
+    #   Pattern.new(RDF::Node.new, :p, 123).variable_terms    #=> [:predicate]
+    #
+    # @param  [Symbol, #to_sym] name
+    #   an optional variable name
+    # @return [Array<Symbol>]
+    # @since  0.3.0
+    def variable_terms(name = nil)
+      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))
+      terms << :object    if object.is_a?(Variable)    && (!name || name.eql?(object.name))
+      terms
+    end
+
     ##
     # Returns the number of variables in this pattern.
     #
+    # Note: this does not count distinct variables, and will therefore e.g.
+    # return 3 even if two terms are actually the same variable.
+    #
     # @return [Integer] (0..3)
     def variable_count
-      variables.size
+      count = 0
+      count += 1 if subject.is_a?(Variable)
+      count += 1 if predicate.is_a?(Variable)
+      count += 1 if object.is_a?(Variable)
+      count
     end
-
     alias_method :cardinality, :variable_count
     alias_method :arity,       :variable_count
 
     ##
     # Returns all variables in this pattern.
     #
+    # Note: this returns a hash containing distinct variables only.
+    #
     # @return [Hash{Symbol => Variable}]
     def variables
       variables = {}
@@ -91,7 +206,7 @@ module RDF; class Query
     ##
     # Returns `true` if this pattern contains bindings.
     #
-    # @return [Boolean]
+    # @return [Boolean] `true` or `false`
     def bindings?
       !bindings.empty?
     end
@@ -149,16 +264,17 @@ module RDF; class Query
     end
 
     ##
-    # Returns the string representation of this pattern.
+    # Returns a string representation of this pattern.
     #
     # @return [String]
     def to_s
       StringIO.open do |buffer| # FIXME in RDF::Statement
+        buffer << 'OPTIONAL ' if optional?
         buffer << (subject.is_a?(Variable)   ? subject.to_s :   "<#{subject}>") << ' '
         buffer << (predicate.is_a?(Variable) ? predicate.to_s : "<#{predicate}>") << ' '
         buffer << (object.is_a?(Variable)    ? object.to_s :    "<#{object}>") << ' .'
         buffer.string
       end
     end
-  end # class Pattern
-end; end # module RDF class Query
+  end # Pattern
+end; end # RDF::Query

data/lib/rdf/query/solution.rb

@@ -22,50 +22,76 @@ class RDF::Query
   #
   class Solution
     # Undefine all superfluous instance methods:
-    undef_method(*(instance_methods.map(&:to_sym) - [:__id__, :__send__, :__class__, :__eval__, :object_id, :instance_eval, :inspect, :class, :is_a?]))
+    undef_method(*(instance_methods.map(&:to_sym) - [:__id__, :__send__, :__class__, :__eval__,
+      :object_id, :dup, :instance_eval, :inspect, :to_s,
+      :class, :is_a?, :respond_to?, :respond_to_missing?]))
 
     include Enumerable
 
     ##
-    # @param  [Hash{Symbol => Value}] bindings
-    def initialize(bindings = {})
+    # Initializes the query solution.
+    #
+    # @param  [Hash{Symbol => RDF::Value}] bindings
+    # @yield  [solution]
+    def initialize(bindings = {}, &block)
       @bindings = bindings.to_hash
+
+      if block_given?
+        case block.arity
+          when 1 then block.call(self)
+          else instance_eval(&block)
+        end
+      end
     end
 
+    # @private
+    attr_reader :bindings
+
     ##
     # Enumerates over every variable binding in this solution.
     #
     # @yield  [name, value]
-    # @yieldparam [Symbol, Value]
+    # @yieldparam [Symbol] name
+    # @yieldparam [RDF::Value] value
     # @return [Enumerator]
     def each_binding(&block)
       @bindings.each(&block)
     end
-
     alias_method :each, :each_binding
 
     ##
     # Enumerates over every variable name in this solution.
     #
     # @yield  [name]
-    # @yieldparam [Symbol]
+    # @yieldparam [Symbol] name
     # @return [Enumerator]
     def each_name(&block)
       @bindings.each_key(&block)
     end
-
     alias_method :each_key, :each_name
 
     ##
     # Enumerates over every variable value in this solution.
     #
     # @yield  [value]
-    # @yieldparam [Value]
+    # @yieldparam [RDF::Value] value
     # @return [Enumerator]
     def each_value(&block)
       @bindings.each_value(&block)
     end
 
+    ##
+    # Returns `true` if this solution contains bindings for any of the given
+    # `variables`.
+    #
+    # @param  [Array<Symbol, #to_sym>] variables
+    #   an array of variables to check
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def has_variables?(variables)
+      variables.any? { |variable| bound?(variable) }
+    end
+
     ##
     # Enumerates over every variable in this solution.
     #
@@ -81,8 +107,9 @@ class RDF::Query
     ##
     # Returns `true` if the variable `name` is bound in this solution.
     #
-    # @param  [Symbol] name
-    # @return [Boolean]
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @return [Boolean] `true` or `false`
     def bound?(name)
       !unbound?(name)
     end
@@ -90,8 +117,9 @@ class RDF::Query
     ##
     # Returns `true` if the variable `name` is unbound in this solution.
     #
-    # @param  [Symbol] name
-    # @return [Boolean]
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @return [Boolean] `true` or `false`
     def unbound?(name)
       @bindings[name.to_sym].nil?
     end
@@ -99,20 +127,58 @@ class RDF::Query
     ##
     # Returns the value of the variable `name`.
     #
-    # @param  [Symbol] name
-    # @return [Value]
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @return [RDF::Value]
     def [](name)
       @bindings[name.to_sym]
     end
 
     ##
-    # @return [Array<Array(Symbol, Value)>}
+    # Binds or rebinds the variable `name` to the given `value`.
+    #
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @param  [RDF::Value] value
+    # @return [RDF::Value]
+    # @since  0.3.0
+    def []=(name, value)
+      @bindings[name.to_sym] = value
+    end
+
+    ##
+    # Merges the bindings from the given `other` query solution into this
+    # one, overwriting any existing ones having the same name.
+    #
+    # @param  [RDF::Query::Solution, #to_hash] other
+    #   another query solution or hash bindings
+    # @return [void] self
+    # @since  0.3.0
+    def merge!(other)
+      @bindings.merge!(other.to_hash)
+      self
+    end
+
+    ##
+    # Merges the bindings from the given `other` query solution with a copy
+    # of this one.
+    #
+    # @param  [RDF::Query::Solution, #to_hash] other
+    #   another query solution or hash bindings
+    # @return [RDF::Query::Solution]
+    # @since  0.3.0
+    def merge(other)
+      self.class.new(@bindings.dup).merge!(other)
+    end
+
+    ##
+    # @return [Array<Array(Symbol, RDF::Value)>}
     def to_a
       @bindings.to_a
     end
 
     ##
-    # @return [Hash{Symbol => Value}}
+    # @return [Hash{Symbol => RDF::Value}}
     def to_hash
       @bindings.dup
     end
@@ -123,18 +189,17 @@ class RDF::Query
       sprintf("#<%s:%#0x(%s)>", self.class.name, __id__, @bindings.inspect)
     end
 
-    protected
+  protected
 
-      ##
-      # @param  [Symbol] name
-      # @return [Value]
-      def method_missing(name, *args, &block)
-        if args.empty? && @bindings.has_key?(name.to_sym)
-          @bindings[name.to_sym]
-        else
-          super
-        end
+    ##
+    # @param  [Symbol] name
+    # @return [RDF::Value]
+    def method_missing(name, *args, &block)
+      if args.empty? && @bindings.has_key?(name.to_sym)
+        @bindings[name.to_sym]
+      else
+        super # raises NoMethodError
       end
-
-  end
-end
+    end
+  end # Solution
+end # RDF::Query

data/lib/rdf/query/solutions.rb

@@ -0,0 +1,202 @@
+module RDF; class Query
+  ##
+  # An RDF basic graph pattern (BGP) query solution sequence.
+  #
+  # @example Filtering solutions using a hash
+  #   solutions.filter(:author  => RDF::URI("http://ar.to/#self"))
+  #   solutions.filter(:author  => "Arto Bendiken")
+  #   solutions.filter(:author  => [RDF::URI("http://ar.to/#self"), "Arto Bendiken"])
+  #   solutions.filter(:updated => RDF::Literal(Date.today))
+  #
+  # @example Filtering solutions using a block
+  #   solutions.filter { |solution| solution.author.literal? }
+  #   solutions.filter { |solution| solution.title =~ /^SPARQL/ }
+  #   solutions.filter { |solution| solution.price < 30.5 }
+  #   solutions.filter { |solution| solution.bound?(:date) }
+  #   solutions.filter { |solution| solution.age.datatype == RDF::XSD.integer }
+  #   solutions.filter { |solution| solution.name.language == :es }
+  #
+  # @example Reordering solutions based on a variable
+  #   solutions.order_by(:updated)
+  #   solutions.order_by(:updated, :created)
+  #
+  # @example Selecting particular variables only
+  #   solutions.select(:title)
+  #   solutions.select(:title, :description)
+  #
+  # @example Eliminating duplicate solutions
+  #   solutions.distinct
+  #
+  # @example Limiting the number of solutions
+  #   solutions.offset(20).limit(10)
+  #
+  # @example Counting the number of matching solutions
+  #   solutions.count
+  #   solutions.count { |solution| solution.price < 30.5 }
+  #
+  # @example Iterating over all found solutions
+  #   solutions.each { |solution| puts solution.inspect }
+  #
+  # @since 0.3.0
+  class Solutions < Array
+    alias_method :each_solution, :each
+
+    ##
+    # Returns the number of matching query solutions.
+    #
+    # @overload count
+    #   @return [Integer]
+    #
+    # @overload count { |solution| ... }
+    #   @yield  [solution]
+    #   @yieldparam  [RDF::Query::Solution] solution
+    #   @yieldreturn [Boolean]
+    #   @return [Integer]
+    #
+    # @return [Integer]
+    def count(&block)
+      super
+    end
+
+    ##
+    # Filters this solution sequence by the given `criteria`.
+    #
+    # @param  [Hash{Symbol => Object}] criteria
+    # @yield  [solution]
+    # @yieldparam  [RDF::Query::Solution] solution
+    # @yieldreturn [Boolean]
+    # @return [void] `self`
+    def filter(criteria = {}, &block)
+      if block_given?
+        self.reject! do |solution|
+          !block.call(solution.is_a?(Solution) ? solution : Solution.new(solution))
+        end
+      else
+        self.reject! do |solution|
+          solution = solution.is_a?(Solution) ? solution : Solution.new(solution)
+          results = criteria.map do |name, value|
+            solution[name] == value
+          end
+          !results.all?
+        end
+      end
+      self
+    end
+    alias_method :filter!, :filter
+
+    ##
+    # Reorders this solution sequence by the given `variables`.
+    #
+    # @param  [Array<Symbol, #to_sym>] variables
+    # @return [void] `self`
+    def order(*variables)
+      if variables.empty?
+        raise ArgumentError, "wrong number of arguments (0 for 1)"
+      else
+        # TODO: support for descending sort, e.g. `order(:s => :asc, :p => :desc)`
+        variables.map!(&:to_sym)
+        self.sort! do |a, b|
+          a = variables.map { |variable| a[variable].to_s } # FIXME
+          b = variables.map { |variable| b[variable].to_s } # FIXME
+          a <=> b
+        end
+      end
+      self
+    end
+    alias_method :order_by, :order
+
+    ##
+    # Restricts this solution sequence to the given `variables` only.
+    #
+    # @param  [Array<Symbol, #to_sym>] variables
+    # @return [void] `self`
+    def project(*variables)
+      if variables.empty?
+        raise ArgumentError, "wrong number of arguments (0 for 1)"
+      else
+        variables.map!(&:to_sym)
+        self.each do |solution|
+          solution.bindings.delete_if { |k, v| !variables.include?(k.to_sym) }
+        end
+      end
+      self
+    end
+    alias_method :select, :project
+
+    ##
+    # Ensures that the solutions in this solution sequence are unique.
+    #
+    # @return [void] `self`
+    def distinct
+      self.uniq!
+      self
+    end
+    alias_method :distinct!, :distinct
+    alias_method :reduced,   :distinct
+    alias_method :reduced!,  :distinct
+
+    ##
+    # Limits this solution sequence to bindings starting from the `start`
+    # offset in the overall solution sequence.
+    #
+    # @param  [Integer, #to_i] start
+    #   zero or a positive or negative integer
+    # @return [void] `self`
+    def offset(start)
+      case start = start.to_i
+        when 0 then nil
+        else self.slice!(0...start)
+      end
+      self
+    end
+    alias_method :offset!, :offset
+
+    ##
+    # Limits the number of solutions in this solution sequence to a maximum
+    # of `length`.
+    #
+    # @param  [Integer, #to_i] length
+    #   zero or a positive integer
+    # @return [void] `self`
+    # @raise  [ArgumentError] if `length` is negative
+    def limit(length)
+      length = length.to_i
+      raise ArgumentError, "expected zero or a positive integer, got #{length}" if length < 0
+      case length
+        when 0 then self.clear
+        else self.slice!(length..-1) if length < self.size
+      end
+      self
+    end
+    alias_method :limit!, :limit
+
+    ##
+    # Returns an array of the distinct variable names used in this solution
+    # sequence.
+    #
+    # @return [Array<Symbol>]
+    def variable_names
+      variables = self.inject({}) do |result, solution|
+        solution.each_name do |name|
+          result[name] ||= true
+        end
+        result
+      end
+      variables.keys
+    end
+
+    ##
+    # Returns `true` if this solution sequence contains bindings for any of
+    # the given `variables`.
+    #
+    # @param  [Array<Symbol, #to_sym>] variables
+    #   an array of variables to check
+    # @return [Boolean] `true` or `false`
+    # @see    RDF::Query::Solution#has_variables?
+    # @see    RDF::Query#execute
+    def have_variables?(variables)
+      self.any? { |solution| solution.has_variables?(variables) }
+    end
+    alias_method :has_variables?, :have_variables?
+  end # Solutions
+end; end # RDF::Query