sparql 0.0.1 → 0.0.2

data/lib/sparql/algebra/operator/reduced.rb

@@ -0,0 +1,47 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `reduced` operator.
+    #
+    # @example
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
+    #            (: <http://example/>))
+    #     (reduced
+    #       (project (?v)
+    #         (bgp (triple ?x ?p ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    class Reduced < Operator::Unary
+      include Query
+      
+      NAME = [:reduced]
+
+      ##
+      # Executes this query on the given `queryable` graph or repository.
+      # Removes duplicate solutions from the solution set.
+      #
+      # @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.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+      def execute(queryable, options = {})
+        @solutions = operands.last.
+          execute(queryable, options.merge(:depth => options[:depth].to_i + 1)).
+          reduced
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Return optimized query
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands = operands.map(&:optimize)
+      end
+    end # Reduced
+  end # Operator
+end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/regex.rb

@@ -0,0 +1,70 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `regex` operator.
+    #
+    # @example
+    #   (prefix ((ex: <http://example.com/#>)
+    #            (rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>))
+    #     (project (?val)
+    #       (filter (regex ?val "GHI")
+    #         (bgp (triple ex:foo rdf:value ?val)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#funcex-regex
+    # @see http://www.w3.org/TR/xpath-functions/#func-matches
+    class Regex < Operator::Ternary
+      include Evaluatable
+
+      NAME = :regex
+
+      ##
+      # Initializes a new operator instance.
+      #
+      # @param  [RDF::Term] text
+      # @param  [RDF::Term] pattern
+      # @param  [RDF::Term] flags
+      # @param  [Hash{Symbol => Object}] options
+      #   any additional options (see {Operator#initialize})
+      # @raise  [TypeError] if any operand is invalid
+      def initialize(text, pattern, flags = RDF::Literal(''), options = {})
+        super
+      end
+
+      ##
+      # Matches `text` against a regular expression `pattern`.
+      #
+      # @param  [RDF::Literal] text
+      #   a simple literal
+      # @param  [RDF::Literal] pattern
+      #   a simple literal
+      # @param  [RDF::Literal] flags
+      #   a simple literal (defaults to an empty string)
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if any operand is unbound
+      # @raise  [TypeError] if any operand is not a simple literal
+      def apply(text, pattern, flags = RDF::Literal(''))
+        # @see http://www.w3.org/TR/xpath-functions/#regex-syntax
+        raise TypeError, "expected a plain RDF::Literal, but got #{text.inspect}" unless text.is_a?(RDF::Literal) && text.plain?
+        text = text.to_s
+        # TODO: validate text syntax
+
+        # @see http://www.w3.org/TR/xpath-functions/#regex-syntax
+        raise TypeError, "expected a plain RDF::Literal, but got #{pattern.inspect}" unless pattern.is_a?(RDF::Literal) && pattern.plain?
+        pattern = pattern.to_s
+        # TODO: validate pattern syntax
+
+        # @see http://www.w3.org/TR/xpath-functions/#flags
+        raise TypeError, "expected a plain RDF::Literal, but got #{flags.inspect}" unless flags.is_a?(RDF::Literal) && flags.plain?
+        flags = flags.to_s
+        # TODO: validate flag syntax
+
+        options = 0
+        raise NotImplementedError, "unsupported regular expression flag: /s" if flags.include?(?s) # FIXME
+        options |= Regexp::MULTILINE  if flags.include?(?m)
+        options |= Regexp::IGNORECASE if flags.include?(?i)
+        options |= Regexp::EXTENDED   if flags.include?(?x)
+        RDF::Literal(Regexp.new(pattern, options) === text)
+      end
+    end # Regex
+  end # Operator
+end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/same_term.rb

@@ -0,0 +1,46 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `sameTerm` operator.
+    #
+    # @example
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
+    #            (: <http://example.org/things#>))
+    #     (project (?x ?v)
+    #       (filter (sameTerm ?v)
+    #         (bgp (triple ?x :p ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-sameTerm
+    class SameTerm < Operator::Binary
+      include Evaluatable
+
+      NAME = :sameTerm
+
+      ##
+      # Returns `true` if the operands are the same RDF term; returns
+      # `false` otherwise.
+      #
+      # @param  [RDF::Term] term1
+      #   an RDF term
+      # @param  [RDF::Term] term2
+      #   an RDF term
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if either operand is unbound
+      def apply(term1, term2)
+        RDF::Literal(term1.eql?(term2))
+      end
+
+      ##
+      # Returns an optimized version of this expression.
+      #
+      # @return [SPARQL::Algebra::Expression]
+      def optimize
+        if operand(0).is_a?(Variable) && operand(0).eql?(operand(1))
+          RDF::Literal::TRUE
+        else
+          super # @see Operator#optimize
+        end
+      end
+    end # SameTerm
+  end # Operator
+end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/slice.rb

@@ -0,0 +1,60 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `slice` operator.
+    #
+    # @example
+    #   (prefix ((: <http://example.org/ns#>))
+    #     (slice 1 1
+    #       (project (?v)
+    #         (order (?v)
+    #           (bgp (triple ??0 :num ?v))))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    class Slice < Operator::Ternary
+      include Query
+      
+      NAME = [:slice]
+
+      ##
+      # Executes this query on the given `queryable` graph or repository.
+      # Returns a subset of the solutions resulting from executing
+      # the third operand, an RDF::Queryable object by indexing in to the
+      # result set by the amount specified in the first operand and limiting
+      # the total number of solutions returned by the amount specified in the
+      # second operand.
+      #
+      # If either the first or second operands are `:_`, they are not considered.
+      #
+      # @example
+      #
+      #   (slice 1 2 (bgp (triple ?s ?p ?o)))   # Returns at most two solutions starting with the second solution.
+      #   (slice _ 2 (bgp (triple ?s ?p ?o)))   # Returns at most two solutions starting with the first solution.
+      #   (slice 1 _ (bgp (triple ?s ?p ?o)))   # Returns all solution after the first.
+      #
+      # @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.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+      def execute(queryable, options = {})
+        @solutions = operands.last. execute(queryable, options.merge(:depth => options[:depth].to_i + 1))
+        @solutions.offset(operands[0]) unless operands[0] == :_
+        @solutions.limit(operands[1]) unless operands[1] == :_
+        @solutions
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Return optimized query
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        operands = operands.map(&:optimize)
+      end
+    end # Slice
+  end # Operator
+end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/str.rb

@@ -0,0 +1,35 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `str` operator.
+    #
+    # @example
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
+    #            (: <http://example.org/things#>))
+    #     (project (?x ?v)
+    #       (filter (= (str ?v) "1")
+    #         (bgp (triple ?x :p ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-str
+    class Str < Operator::Unary
+      include Evaluatable
+
+      NAME = :str
+
+      ##
+      # Returns the string form of the operand.
+      #
+      # @param  [RDF::Literal, RDF::URI] term
+      #   a literal or IRI
+      # @return [RDF::Literal] a simple literal
+      # @raise  [TypeError] if the operand is not a literal or IRI
+      def apply(term)
+        case term
+          when RDF::Literal then RDF::Literal(term.value)
+          when RDF::URI     then RDF::Literal(term.to_s)
+          else raise TypeError, "expected an RDF::Literal or RDF::URI, but got #{term.inspect}"
+        end
+      end
+    end # Str
+  end # Operator
+end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/subtract.rb

@@ -0,0 +1,32 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL numeric `subtract` operator.
+    #   (- ?x ?y)
+    #   (subtract ?x ?y)
+    #
+    # @see http://www.w3.org/TR/xpath-functions/#func-numeric-subtract
+    class Subtract < Operator::Binary
+      include Evaluatable
+
+      NAME = [:-, :subtract]
+
+      ##
+      # Returns the arithmetic difference of the operands.
+      #
+      # @param  [RDF::Literal::Numeric] left
+      #   a numeric literal
+      # @param  [RDF::Literal::Numeric] right
+      #   a numeric literal
+      # @return [RDF::Literal::Numeric]
+      # @raise  [TypeError] if either operand is not a numeric literal
+      def apply(left, right)
+        case
+          when left.is_a?(RDF::Literal::Numeric) && right.is_a?(RDF::Literal::Numeric)
+            left - right
+          else raise TypeError, "expected two RDF::Literal::Numeric operands, but got #{left.inspect} and #{right.inspect}"
+        end
+      end
+    end # Subtract
+  end # Operator
+end; end # SPARQL::Algebra

data/lib/sparql/algebra/operator/union.rb

@@ -0,0 +1,55 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `union` operator.
+    #
+    # @example
+    #   (prefix ((: <http://example/>))
+    #     (union
+    #       (bgp (triple ?s ?p ?o))
+    #       (graph ?g
+    #         (bgp (triple ?s ?p ?o)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    class Union < Operator::Binary
+      include Query
+      
+      NAME = [:union]
+
+      ##
+      # Executes each operand with `queryable` and performs the `union` operation
+      # by creating a new solution set consiting of all solutions from both operands.
+      #
+      # @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.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+      def execute(queryable, options = {})
+        debug(options) {"Union"}
+        solutions1 = operand(0).execute(queryable, options.merge(:depth => options[:depth].to_i + 1))
+        debug(options) {"=>(left) #{solutions1.inspect}"}
+        solutions2 = operand(1).execute(queryable, options.merge(:depth => options[:depth].to_i + 1))
+        debug(options) {"=>(right) #{solutions2.inspect}"}
+        @solutions = RDF::Query::Solutions.new(solutions1 + solutions2)
+        debug(options) {"=> #{@solutions.inspect}"}
+        @solutions
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # If optimize operands, and if the first two operands are both Queries, replace
+      # with the unique sum of the query elements
+      #
+      # @return [Union, RDF::Query] `self`
+      def optimize
+        ops = operands.map {|o| o.optimize }.select {|o| o.respond_to?(:empty?) && !o.empty?}
+        @operands = ops
+        self
+      end
+    end # Union
+  end # Operator
+end; end # SPARQL::Algebra

data/lib/sparql/algebra/query.rb

@@ -0,0 +1,99 @@
+module SPARQL; module Algebra
+  ##
+  # A SPARQL algebra query, may be duck-typed as RDF::Query.
+  #
+  # Mixin with SPARQL::Algebra::Operator to provide query-like operations on graphs and filters
+  #
+  # @abstract
+  module Query
+    ##
+    # Prepends an operator.
+    #
+    # @param  [RDF::Query] query
+    #   a query
+    # @return [void] self
+    def unshift(query)
+      @operands.unshift(query)
+      self
+    end
+    
+    ##
+    # The variables used in this query.
+    #
+    # @return [Hash{Symbol => RDF::Query::Variable}]
+    def variables
+      operands.inject({}) {|hash, o| o.executable? ? hash.merge!(o.variables) : hash}
+    end
+
+    ##
+    # The solution sequence for this query.
+    #
+    # @return [RDF::Query::Solutions]
+    attr_reader :solutions
+
+    ##
+    # Executes this query on the given `queryable` graph or repository.
+    #
+    # @param  [RDF::Queryable] queryable
+    #   the graph or repository to query
+    # @param  [Hash{Symbol => Object}] options
+    #   any additional keyword options
+    # @option options [Boolean] debug
+    #   Query execution debugging
+    # @return [RDF::Query::Solutions]
+    #   the resulting solution sequence
+    # @raise [TypeError]
+    #   TypeError raised if any operands are invalid
+    # @raise [NotImplementedError]
+    #   If an attempt is made to perform an unsupported operation
+    # @see    http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    def execute(queryable, options = {})
+      raise NotImplementedError, "#{self.class}#execute(#{queryable})"
+    end
+
+    # Add context to sub-items, unless they already have a context
+    # @param [RDF::URI, RDF::Query::Variable] value
+    # @return [RDF::URI, RDF::Query::Variable]
+    def context=(value)
+      operands.each do |operand|
+        operand.context = value if operand.respond_to?(:context) && operand.context != false
+      end
+      value
+    end
+
+    ##
+    # Returns `true` if this query did not match when last executed.
+    #
+    # 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?
+      solutions.empty?
+    end
+
+    ##
+    # 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.
+    #
+    # @return [Boolean]
+    # @see    #failed?
+    def matched?
+      !failed?
+    end
+
+    ##
+    # Enumerates over each matching query solution.
+    #
+    # @yield  [solution]
+    # @yieldparam [RDF::Query::Solution] solution
+    # @return [Enumerator]
+    def each_solution(&block)
+      solutions.each(&block)
+    end
+    alias_method :each, :each_solution
+  end # Query
+end; end # SPARQL::Algebra