openlogic-rdf 0.3.6

data/lib/rdf/query/solutions.rb

@@ -0,0 +1,237 @@
+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 or proc
+  #   solutions.order_by(:updated)
+  #   solutions.order_by(:updated, :created)
+  #   solutions.order_by(:updated, lambda {|a, b| b <=> a})
+  #
+  # @example Selecting/Projecting particular variables only
+  #   solutions.select(:title)
+  #   solutions.select(:title, :description)
+  #   solutions.project(:title)
+  #
+  # @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
+
+    ##
+    # Returns hash of bindings from each solution. Each bound variable will have
+    # an array of bound values representing those from each solution, where a given
+    # solution will have just a single value for each bound variable
+    # @return [Hash{Symbol => Array<RDF::Term>}]
+    def bindings
+      bindings = {}
+      each do |solution|
+        solution.each do |key, value|
+          bindings[key] ||= []
+          bindings[key] << value
+        end
+      end
+      bindings
+    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`.
+    #
+    # Variables may be symbols or {Query::Variable} instances.
+    # A variable may also be a Procedure/Lambda, compatible with {::Enumerable#sort}.
+    # This takes two arguments (solutions) and returns -1, 0, or 1 equivalently to <=>.
+    #
+    # If called with a block, variables are ignored, and the block is invoked with
+    # pairs of solutions. The block is expected to return -1, 0, or 1 equivalently to <=>.
+    #
+    # @param  [Array<Proc, Query::Variable, Symbol, #to_sym>] variables
+    # @yield  [solution]
+    # @yieldparam  [RDF::Query::Solution] q
+    # @yieldparam  [RDF::Query::Solution] b
+    # @yieldreturn [Integer] -1, 0, or 1 depending on value of comparator
+    # @return [void] `self`
+    def order(*variables, &block)
+      if variables.empty? && !block_given?
+        raise ArgumentError, "wrong number of arguments (0 for 1)"
+      else
+        self.sort! do |a, b|
+          if block_given?
+            block.call((a.is_a?(Solution) ? a : Solution.new(a)), (b.is_a?(Solution) ? b : Solution.new(b)))
+          else
+            # Try each variable until a difference is found.
+            variables.inject(nil) do |memo, v|
+              memo || begin
+                comp = v.is_a?(Proc) ? v.call(a, b) : (v = v.to_sym; a[v] <=> b[v])
+                comp == 0 ? false : comp
+              end
+            end || 0
+          end
+        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

data/lib/rdf/query/variable.rb

@@ -0,0 +1,221 @@
+class RDF::Query
+  ##
+  # An RDF query variable.
+  #
+  # @example Creating a named unbound variable
+  #   var = RDF::Query::Variable.new(:x)
+  #   var.unbound?   #=> true
+  #   var.value      #=> nil
+  #
+  # @example Creating an anonymous unbound variable
+  #   var = RDF::Query::Variable.new
+  #   var.name       #=> :g2166151240
+  #
+  # @example Unbound variables match any value
+  #   var === 42     #=> true
+  #
+  # @example Creating a bound variable
+  #   var = RDF::Query::Variable.new(:y, 123)
+  #   var.bound?     #=> true
+  #   var.value      #=> 123
+  #
+  # @example Bound variables match only their actual value
+  #   var === 42     #=> false
+  #   var === 123    #=> true
+  #
+  # @example Getting the variable name
+  #   var.named?     #=> true
+  #   var.name       #=> :y
+  #   var.to_sym     #=> :y
+  #
+  # @example Rebinding a variable returns the previous value
+  #   var.bind!(456) #=> 123
+  #   var.value      #=> 456
+  #
+  # @example Unbinding a previously bound variable
+  #   var.unbind!
+  #   var.unbound?   #=> true
+  #
+  # @example Getting the string representation of a variable
+  #   var = RDF::Query::Variable.new(:x)
+  #   var.to_s       #=> "?x"
+  #   var = RDF::Query::Variable.new(:y, 123)
+  #   var.to_s       #=> "?y=123"
+  #
+  class Variable
+    include RDF::Term
+
+    ##
+    # The variable's name.
+    #
+    # @return [Symbol]
+    attr_accessor :name
+    alias_method :to_sym, :name
+
+    ##
+    # The variable's value.
+    #
+    # @return [RDF::Term]
+    attr_accessor :value
+
+    ##
+    # @param  [Symbol, #to_sym] name
+    #   the variable name
+    # @param  [RDF::Term] value
+    #   an optional variable value
+    def initialize(name = nil, value = nil)
+      @name  = (name || "g#{__id__.to_i.abs}").to_sym
+      @value = value
+    end
+
+    ##
+    # Returns `true`.
+    #
+    # @return [Boolean]
+    # @see    RDF::Term#variable?
+    # @since  0.1.7
+    def variable? 
+      true
+    end
+
+    ##
+    # Returns `true` if this variable has a name.
+    #
+    # @return [Boolean]
+    def named?
+      true
+    end
+
+    ##
+    # Returns `true` if this variable is bound.
+    #
+    # @return [Boolean]
+    def bound?
+      !unbound?
+    end
+
+    ##
+    # Returns `true` if this variable is unbound.
+    #
+    # @return [Boolean]
+    def unbound?
+      value.nil?
+    end
+
+    ##
+    # Returns `true` if this variable is distinguished.
+    #
+    # @return [Boolean]
+    def distinguished?
+      @distinguished.nil? || @distinguished
+    end
+
+    ##
+    # Sets if variable is distinguished or non-distinguished.
+    # By default, variables are distinguished
+    #
+    # @return [Boolean]
+    def distinguished=(value)
+      @distinguished = value
+    end
+
+    ##
+    # Rebinds this variable to the given `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
+    end
+    alias_method :bind!, :bind
+
+    ##
+    # Unbinds this variable, discarding any currently bound value.
+    #
+    # @return [RDF::Term] 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 => RDF::Query::Variable}]
+    def variables
+      {name => self}
+    end
+    alias_method :to_hash, :variables
+
+    ##
+    # Returns this variable's bindings (if any) as a `Hash`.
+    #
+    # @return [Hash{Symbol => RDF::Term}]
+    def bindings
+      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. Or, to another Term if bound, or to any other Term
+    #
+    # @param  [Object] other
+    # @return [Boolean] `true` or `false`
+    # @since  0.3.0
+    def eql?(other)
+      if unbound?
+        other.is_a?(RDF::Term) # match any Term when unbound
+      elsif other.is_a?(RDF::Query::Variable)
+        @name.eql?(other.name)
+      else
+        value.eql?(other)
+      end
+    end
+    alias_method :==, :eql?
+
+    ##
+    # Compares this variable with the given value.
+    #
+    # @param  [RDF::Term] other
+    # @return [Boolean]
+    def ===(other)
+      if unbound?
+        other.is_a?(RDF::Term) # match any Term when unbound
+      else
+        value === other
+      end
+    end
+
+    ##
+    # Returns a string representation of this variable.
+    #
+    # Distinguished variables are indicated with a single `?`.
+    #
+    # Non-distinguished variables are indicated with a double `??`
+    #
+    # @example
+    #   v = Variable.new("a")
+    #   v.to_s => '?a'
+    #   v.distinguished = false
+    #   v.to_s => '??a'
+    #
+    # @return [String]
+    def to_s
+      prefix = distinguished? ? '?' : "??"
+      unbound? ? "#{prefix}#{name}" : "#{prefix}#{name}=#{value}"
+    end
+  end # Variable
+end # RDF::Query