rdf 0.2.3 → 0.3.0.pre

data/lib/rdf/query/variable.rb

@@ -45,17 +45,24 @@ class RDF::Query
   class Variable
     include RDF::Value
 
-    # @return [Symbol] The variable's name.
+    ##
+    # The variable's name.
+    #
+    # @return [Symbol]
     attr_accessor :name
-
     alias_method :to_sym, :name
 
-    # @return [Value] The variable's value.
+    ##
+    # The variable's value.
+    #
+    # @return [RDF::Value]
     attr_accessor :value
 
     ##
-    # @param  [Symbol] name
-    # @param  [Value]  value
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @param  [RDF::Value]  value
+    #   an optional variable value
     def initialize(name = nil, value = nil)
       @name  = (name || "g#{__id__.to_i.abs}").to_sym
       @value = value
@@ -98,50 +105,67 @@ class RDF::Query
     ##
     # Rebinds this variable to the given `value`.
     #
-    # @param  [Value] value
-    # @return [Value] The previous value, if any.
+    # @param  [RDF::Value] value
+    # @return [RDF::Value] the previous value, if any.
     def bind(value)
       old_value = self.value
       self.value = value
       old_value
     end
-
     alias_method :bind!, :bind
 
     ##
     # Unbinds this variable, discarding any currently bound value.
     #
-    # @return [Value] The previous value, if any.
+    # @return [RDF::Value] the previous value, if any.
     def unbind
       old_value = self.value
       self.value = nil
       old_value
     end
-
     alias_method :unbind!, :unbind
 
     ##
     # Returns this variable as `Hash`.
     #
-    # @return [Hash{Symbol => Variable}]
+    # @return [Hash{Symbol => RDF::Query::Variable}]
     def variables
-      { name => self }
+      {name => self}
     end
-
     alias_method :to_hash, :variables
 
     ##
     # Returns this variable's bindings (if any) as a `Hash`.
     #
-    # @return [Hash{Symbol => Value}]
+    # @return [Hash{Symbol => RDF::Value}]
     def bindings
-      unbound? ? {} : { name => value }
+      unbound? ? {} : {name => value}
+    end
+
+    ##
+    # Returns a hash code for this variable.
+    #
+    # @return [Fixnum]
+    # @since  0.3.0
+    def hash
+      @name.hash
+    end
+
+    ##
+    # Returns `true` if this variable is equivalent to a given `other`
+    # variable.
+    #
+    # @param  [Object] other
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def eql?(other)
+      other.is_a?(RDF::Query::Variable) && @name.eql?(other.name)
     end
 
     ##
     # Compares this variable with the given value.
     #
-    # @param  [Value] other
+    # @param  [RDF::Value] other
     # @return [Boolean]
     def ===(other)
       if unbound?
@@ -158,5 +182,5 @@ class RDF::Query
     def to_s
       unbound? ? "?#{name}" : "?#{name}=#{value}"
     end
-  end
-end
+  end # Variable
+end # RDF::Query

data/lib/rdf/query.rb

@@ -1,224 +1,274 @@
 module RDF
   ##
-  # An RDF basic graph pattern query.
+  # An RDF basic graph pattern (BGP) query.
   #
-  # @example Filtering solutions using a hash
-  #   query.filter(:author  => RDF::URI.new("http://ar.to/#self"))
-  #   query.filter(:author  => "Arto Bendiken")
-  #   query.filter(:author  => [RDF::URI.new("http://ar.to/#self"), "Arto Bendiken"])
-  #   query.filter(:updated => RDF::Literal.new(Date.today))
+  # @example Constructing a basic graph pattern query (1)
+  #   query = RDF::Query.new do
+  #     pattern [:person, RDF.type,  FOAF.Person]
+  #     pattern [:person, FOAF.name, :name]
+  #     pattern [:person, FOAF.mbox, :email]
+  #   end
   #
-  # @example Filtering solutions using a block
-  #   query.filter { |solution| solution.author.literal? }
-  #   query.filter { |solution| solution.title =~ /^SPARQL/ }
-  #   query.filter { |solution| solution.price < 30.5 }
-  #   query.filter { |solution| solution.bound?(:date) }
-  #   query.filter { |solution| solution.age.datatype == RDF::XSD.integer }
-  #   query.filter { |solution| solution.name.language == :es }
+  # @example Constructing a basic graph pattern query (2)
+  #   query = RDF::Query.new({
+  #     :person => {
+  #       RDF.type  => FOAF.Person,
+  #       FOAF.name => :name,
+  #       FOAF.mbox => :email,
+  #     }
+  #   })
   #
-  # @example Reordering solutions based on a variable
-  #   query.order_by(:updated)
-  #   query.order_by(:updated, :created)
+  # @example Executing a basic graph pattern query
+  #   graph = RDF::Graph.load('etc/doap.nt')
+  #   query.execute(graph).each do |solution|
+  #     solution.inspect
+  #   end
   #
-  # @example Selecting particular variables only
-  #   query.select(:title)
-  #   query.select(:title, :description)
+  # @example Constructing and executing a query in one go (1)
+  #   solutions = RDF::Query.execute(graph) do
+  #     pattern [:person, RDF.type, FOAF.Person]
+  #   end
   #
-  # @example Eliminating duplicate solutions
-  #   query.distinct!
-  #
-  # @example Limiting the number of solutions
-  #   query.offset(25).limit(10)
-  #
-  # @example Counting the number of solutions
-  #   query.count
-  #
-  # @example Iterating over all found solutions
-  #   query.each_solution { |solution| puts solution.inspect }
+  # @example Constructing and executing a query in one go (2)
+  #   solutions = RDF::Query.execute(graph, {
+  #     :person => {
+  #       RDF.type => FOAF.Person,
+  #     }
+  #   })
   #
+  # @since 0.3.0
   class Query
-    autoload :Pattern,  'rdf/query/pattern'
-    autoload :Solution, 'rdf/query/solution'
-    autoload :Variable, 'rdf/query/variable'
+    autoload :Pattern,   'rdf/query/pattern'
+    autoload :Solution,  'rdf/query/solution'
+    autoload :Solutions, 'rdf/query/solutions'
+    autoload :Variable,  'rdf/query/variable'
 
-    include ::Enumerable
+    ##
+    # Executes a query on the given `queryable` graph or repository.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Object => Object}] patterns
+    #   optional hash patterns to initialize the query with
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional keyword options (see {RDF::Query#initialize})
+    # @yield  [query]
+    # @yieldparam  [RDF::Query] query
+    # @yieldreturn [void] ignored
+    # @return [RDF::Query::Solutions]
+    #   the resulting solution sequence
+    # @see    RDF::Query#execute
+    def self.execute(queryable, patterns = nil, options = {}, &block)
+      self.new(patterns, options, &block).execute(queryable, options)
+    end
 
+    ##
+    # The variables used in this query.
+    #
     # @return [Hash{Symbol => RDF::Query::Variable}]
     attr_reader :variables
 
+    ##
+    # The patterns that constitute this query.
+    #
     # @return [Array<RDF::Query::Pattern>]
     attr_reader :patterns
 
-    # @return [Array<Hash{Symbol => RDF::Value}>] An unordered sequence of query solutions.
-    attr_accessor :solutions
+    ##
+    # The solution sequence for this query.
+    #
+    # @return [RDF::Query::Solutions]
+    attr_reader :solutions
 
+    ##
+    # Any additional options for this query.
+    #
     # @return [Hash]
     attr_reader :options
 
     ##
-    # @param  [Hash{Symbol => Object}] options
-    # @yield  [query]
-    # @yieldparam [Query]
-    def initialize(options = {}, &block)
+    # Initializes a new basic graph pattern query.
+    #
+    # @overload initialize(patterns = [], options = {})
+    #   @param  [Array<RDF::Query::Pattern>] patterns
+    #     ...
+    #   @param  [Hash{Symbol => Object}] options
+    #     any additional keyword options
+    #   @option options [RDF::Query::Solutions] :solutions (Solutions.new)
+    #   @yield  [query]
+    #   @yieldparam  [RDF::Query] query
+    #   @yieldreturn [void] ignored
+    #
+    # @overload initialize(patterns, options = {})
+    #   @param  [Hash{Object => Object}] patterns
+    #     ...
+    #   @param  [Hash{Symbol => Object}] options
+    #     any additional keyword options
+    #   @option options [RDF::Query::Solutions] :solutions (Solutions.new)
+    #   @yield  [query]
+    #   @yieldparam  [RDF::Query] query
+    #   @yieldreturn [void] ignored
+    def initialize(patterns = nil, options = {}, &block)
       @options   = options.dup
-      @variables = @options.delete(:variables) || {}
-      @patterns  = @options.delete(:patterns)  || []
-      @solutions = @options.delete(:solutions) || []
+      @variables = {}
+      @solutions = @options.delete(:solutions) || Solutions.new
+
+      @patterns  = case patterns
+        when Hash  then compile_hash_patterns(patterns.dup)
+        when Array then patterns
+        else []
+      end
 
       if block_given?
         case block.arity
-          when 1 then block.call(self)
-          else instance_eval(&block)
+          when 0 then instance_eval(&block)
+          else block.call(self)
         end
       end
     end
 
     ##
-    # Enumerates over each query solution.
+    # Appends the given query `pattern` to this query.
     #
-    # @yield  [solution]
-    # @yieldparam [Solution] solution
-    # @return [Enumerator]
-    def each_solution(&block)
-      unless block_given?
-        enum_for(:each_solution)
-      else
-        solutions.each do |solution|
-          block.call(solution.is_a?(Solution) ? solution : Solution.new(solution))
-        end
-      end
+    # @param  [RDF::Query::Pattern] pattern
+    #   a triple query pattern
+    # @return [void] self
+    def <<(pattern)
+      @patterns << Pattern.from(pattern)
+      self
     end
 
-    alias_method :each, :each_solution
-
     ##
-    # Returns the number of query solutions.
+    # Appends the given query `pattern` to this query.
     #
-    # @return [Integer]
-    def count
-      solutions.size
+    # @param  [RDF::Query::Pattern] pattern
+    #   a triple query pattern
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional keyword options
+    # @option options [Boolean] :optional (false)
+    #   whether this is an optional pattern
+    # @return [void] self
+    def pattern(pattern, options = {})
+      @patterns << Pattern.from(pattern, options)
+      self
     end
 
-    alias_method :size, :count
-
     ##
-    # Filters the solution sequence by the given criteria.
+    # Executes this query on the given `queryable` graph or repository.
     #
-    # @param  [Hash{Symbol => Object}] criteria
-    # @yield  [solution]
-    # @yieldparam  [Solution] solution
-    # @yieldreturn [Boolean]
-    # @return [Query]
-    def filter(criteria = {}, &block)
-      if block_given?
-        solutions.reject! do |solution|
-          !block.call(solution.is_a?(Solution) ? solution : Solution.new(solution))
-        end
-      else
-        solutions.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
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional keyword options
+    # @return [RDF::Query::Solutions]
+    #   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
 
-    alias_method :filter!, :filter
+          when 3 # only variables
+            pattern.execute(queryable) do |statement|
+              @solutions << pattern.solution(statement)
+            end
 
-    ##
-    # Reorders the solution sequence based on `variables`.
-    #
-    # @param  [Array<Symbol>] variables
-    # @return [Query]
-    def order(*variables)
-      if variables.empty?
-        raise ArgumentError.new("wrong number of arguments (0 for 1)")
-      else
-        # TODO: support for descending sort, e.g. order(:s => :asc, :p => :desc)
-        variables.map!(&:to_sym)
-        solutions.sort! do |a, b|
-          a = variables.map { |variable| a[variable].to_s }
-          b = variables.map { |variable| b[variable].to_s }
-          a <=> b
-        end
-      end
-      self
-    end
+          else case # 1 or 2 variables
 
-    alias_method :order_by, :order
+            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
 
-    ##
-    # Restricts the the solution sequence to the given `variables` only.
-    #
-    # @param  [Array<Symbol>] variables
-    # @return [Query]
-    def project(*variables)
-      unless variables.empty?
-        variables.map!(&:to_sym)
-        solutions.each do |bindings|
-          bindings.delete_if { |k, v| !variables.include?(k) } # FIXME
+            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?
+              end
+              @solutions.compact! # remove `nil` entries
+          end
         end
       end
-      self
+      @solutions
     end
 
-    alias_method :select, :project
-
     ##
-    # Ensures solutions in the solution sequence are unique.
+    # Returns `true` if this query did not match when last executed.
     #
-    # @return [Query]
-    def distinct
-      solutions.uniq!
-      self
+    # When the solution sequence is empty, this method can be used to
+    # determine whether the query failed to match or not.
+    #
+    # @return [Boolean]
+    # @see    #matched?
+    def failed?
+      @failed
     end
 
-    alias_method :distinct!, :distinct
-    alias_method :reduced,   :distinct
-    alias_method :reduced!,  :distinct
-
     ##
-    # Limits the solution sequence to bindings starting from the `start`
-    # offset in the overall solution sequence.
+    # Returns `true` if this query matched when last executed.
+    #
+    # When the solution sequence is empty, this method can be used to
+    # determine whether the query matched successfully or not.
     #
-    # @param  [Integer, #to_i] start
-    # @return [Query]
-    def offset(start)
-      slice(start, solutions.size - start.to_i)
+    # @return [Boolean]
+    # @see    #failed?
+    def matched?
+      !@failed
     end
 
-    alias_method :offset!, :offset
-
     ##
-    # Limits the number of solutions to `length`.
+    # Enumerates over each matching query solution.
     #
-    # @param  [Integer, #to_i] length
-    # @return [Query]
-    def limit(length)
-      slice(0, length)
+    # @yield  [solution]
+    # @yieldparam [RDF::Query::Solution] solution
+    # @return [Enumerator]
+    def each_solution(&block)
+      @solutions.each(&block)
     end
+    alias_method :each, :each_solution
 
-    alias_method :limit!, :limit
+  protected
 
     ##
-    # Limits the solution sequence to `length` bindings starting from the
-    # `start` offset in the overall solution sequence.
-    #
-    # @param  [Integer, #to_i] start
-    # @param  [Integer, #to_i] length
-    # @return [Query]
-    def slice(start, length)
-      if (start = start.to_i) < solutions.size
-        solutions.slice!(start, length.to_i)
-      else
-        solutions = []
+    # @private
+    def compile_hash_patterns(hash_patterns)
+      patterns = []
+      hash_patterns.each do |s, pos|
+        raise ArgumentError, "invalid hash pattern: #{hash_patterns.inspect}" unless pos.is_a?(Hash)
+        pos.each do |p, os|
+          case os
+            when Hash
+              patterns += os.keys.map { |o| [s, p, o] }
+              patterns += compile_hash_patterns(os)
+            when Array
+              patterns += os.map { |o| [s, p, o] }
+            else
+              patterns << [s, p, os]
+          end
+        end
       end
-      self
+      patterns.map { |pattern| Pattern.from(pattern) }
     end
-
-    alias_method :slice!, :slice
-  end
-end
+  end # Query
+end # RDF