sparql 0.0.1 → 0.0.2

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

@@ -0,0 +1,28 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `graph` operator.
+    #
+    # This is a wrapper to add a `context` to the query.
+    #
+    # @example
+    #   (prefix ((: <http://example/>))
+    #     (graph ?g
+    #       (bgp (triple ?s ?p ?o))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    class Graph < Operator::Binary
+      NAME = [:graph]
+      ##
+      # A `graph` is an RDF::Query with a context.
+      #
+      # @param [RDF::URI, RDF::Query::Variable] context
+      # @param [RDF::Query] bgp
+      # @return [RDF::Query]
+      def self.new(context, bgp)
+        bgp.context = context
+        bgp
+      end
+    end # Graph
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,32 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL relational `>` (greater than) comparison operator.
+    #
+    # @example
+    #   (> ?x ?y)
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#OperatorMapping
+    # @see http://www.w3.org/TR/xpath-functions/#func-compare
+    # @see http://www.w3.org/TR/xpath-functions/#func-numeric-greater-than
+    # @see http://www.w3.org/TR/xpath-functions/#func-boolean-greater-than
+    # @see http://www.w3.org/TR/xpath-functions/#func-dateTime-greater-than
+    class GreaterThan < Compare
+      NAME = :>
+
+      ##
+      # Returns `true` if the first operand is greater than the second
+      # operand; returns `false` otherwise.
+      #
+      # @param  [RDF::Literal] left
+      #   a literal
+      # @param  [RDF::Literal] right
+      #   a literal
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if either operand is not a literal
+      def apply(left, right)
+        super
+      end
+    end # GreaterThan
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,33 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL relational `>=` (greater than or equal) comparison
+    # operator.
+    #
+    # @example
+    #   (>= ?x ?y)
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#OperatorMapping
+    # @see http://www.w3.org/TR/xpath-functions/#func-compare
+    # @see http://www.w3.org/TR/xpath-functions/#func-numeric-greater-than
+    # @see http://www.w3.org/TR/xpath-functions/#func-boolean-greater-than
+    # @see http://www.w3.org/TR/xpath-functions/#func-dateTime-greater-than
+    class GreaterThanOrEqual < Compare
+      NAME = :>=
+
+      ##
+      # Returns `true` if the first operand is greater than or equal to the
+      # second operand; returns `false` otherwise.
+      #
+      # @param  [RDF::Literal] left
+      #   a literal
+      # @param  [RDF::Literal] right
+      #   a literal
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if either operand is not a literal
+      def apply(left, right)
+        super
+      end
+    end # GreaterThanOrEqual
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,35 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `isBlank` operator.
+    #
+    # @example
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
+    #            (: <http://example.org/things#>))
+    #     (project (?x ?v)
+    #       (filter (isBlank ?v)
+    #         (bgp (triple ?x :p ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-isBlank
+    class IsBlank < Operator::Unary
+      include Evaluatable
+
+      NAME = :isBlank
+
+      ##
+      # Returns `true` if the operand is an `RDF::Node`, `false` otherwise.
+      #
+      # @param  [RDF::Term] term
+      #   an RDF term
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if the operand is not an RDF term
+      def apply(term)
+        case term
+          when RDF::Node then RDF::Literal::TRUE
+          when RDF::Term then RDF::Literal::FALSE
+          else raise TypeError, "expected an RDF::Term, but got #{term.inspect}"
+        end
+      end
+    end # IsBlank
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,37 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `isIRI`/`isURI` operator.
+    #
+    # @example
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
+    #            (: <http://example.org/things#>))
+    #     (project (?x ?v)
+    #       (filter (isIRI ?v)
+    #         (bgp (triple ?x :p ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-isIRI
+    class IsIRI < Operator::Unary
+      include Evaluatable
+
+      NAME = [:isIRI, :isURI]
+
+      ##
+      # Returns `true` if the operand is an `RDF::URI`, `false` otherwise.
+      #
+      # @param  [RDF::Term] term
+      #   an RDF term
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if the operand is not an RDF term
+      def apply(term)
+        case term
+          when RDF::URI  then RDF::Literal::TRUE
+          when RDF::Term then RDF::Literal::FALSE
+          else raise TypeError, "expected an RDF::Term, but got #{term.inspect}"
+        end
+      end
+
+      Operator::IsURI = IsIRI
+    end # IsIRI
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,36 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `isLiteral` operator.
+    #
+    # @example
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
+    #            (: <http://example.org/things#>))
+    #     (project (?x ?v)
+    #       (filter (isLiteral ?v)
+    #         (bgp (triple ?x :p ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-isLiteral
+    class IsLiteral < Operator::Unary
+      include Evaluatable
+
+      NAME = :isLiteral
+
+      ##
+      # Returns `true` if the operand is an `RDF::Literal`, `false`
+      # otherwise.
+      #
+      # @param  [RDF::Term] term
+      #   an RDF term
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if the operand is not an RDF term
+      def apply(term)
+        case term
+          when RDF::Literal then RDF::Literal::TRUE
+          when RDF::Term    then RDF::Literal::FALSE
+          else raise TypeError, "expected an RDF::Term, but got #{term.inspect}"
+        end
+      end
+    end # IsLiteral
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,67 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `join` operator.
+    #
+    # @example
+    #   (prefix ((: <http://example/>))
+    #     (join
+    #       (bgp (triple ?s ?p ?o))
+    #       (graph ?g
+    #         (bgp (triple ?s ?q ?v)))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    class Join < Operator::Binary
+      include Query
+      
+      NAME = [:join]
+
+      ##
+      # Executes each operand with `queryable` and performs the `join` operation
+      # by creating a new solution set containing the `merge` of all solutions
+      # from each set that are `compatible` with each other.
+      #
+      # @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
+      # @see    http://rdf.rubyforge.org/RDF/Query/Solution.html#merge-instance_method
+      # @see    http://rdf.rubyforge.org/RDF/Query/Solution.html#compatible%3F-instance_method
+      def execute(queryable, options = {})
+        # Join(Ω1, Ω2) = { merge(μ1, μ2) | μ1 in Ω1 and μ2 in Ω2, and μ1 and μ2 are compatible }
+        # eval(D(G), Join(P1, P2)) = Join(eval(D(G), P1), eval(D(G), P2))
+        #
+        # Generate solutions independently, merge based on solution compatibility
+        debug(options) {"Join"}
+        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 = solutions1.map do |s1|
+          solutions2.map { |s2| s2.merge(s1) if s2.compatible?(s1) }
+        end.flatten.compact
+        @solutions = RDF::Query::Solutions.new(@solutions)
+        debug(options) {"=> #{@solutions.inspect}"}
+        @solutions
+      end
+      
+      ##
+      # Returns an optimized version of this query.
+      #
+      # Groups of one graph pattern (not a filter) become join(Z, A) and can be replaced by A.
+      # The empty graph pattern Z is the identity for join:
+      #   Replace join(Z, A) by A
+      #   Replace join(A, Z) by A
+      #
+      # @return [Join, RDF::Query] `self`
+      def optimize
+        ops = operands.map {|o| o.optimize }.select {|o| o.respond_to?(:empty?) && !o.empty?}
+        @operands = ops
+        self
+      end
+    end # Join
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,29 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `lang` operator.
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-lang
+    class Lang < Operator::Unary
+      include Evaluatable
+
+      NAME = :lang
+
+      ##
+      # Returns the language tag of the operand, if it has one.
+      #
+      # If the operand has no language tag, returns `""`.
+      #
+      # @param  [RDF::Literal] literal
+      #   a literal
+      # @return [RDF::Literal] a simple literal
+      # @raise  [TypeError] if the operand is not a literal
+      def apply(literal)
+        case literal
+          when RDF::Literal then RDF::Literal(literal.language.to_s)
+          else raise TypeError, "expected an RDF::Literal, but got #{literal.inspect}"
+        end
+      end
+    end # Lang
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,53 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `langMatches` operator.
+    #
+    # @example
+    #   (prefix ((: <http://example.org/#>))
+    #     (filter (langMatches (lang ?v) "en-GB")
+    #       (bgp (triple :x ?p ?v))))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#func-langMatches
+    # @see http://tools.ietf.org/html/rfc4647#section-3.3.1
+    class LangMatches < Operator::Binary
+      include Evaluatable
+
+      NAME = :langMatches
+
+      ##
+      # Returns `true` if the language tag (the first operand) matches the
+      # language range (the second operand).
+      #
+      # @param  [RDF::Literal] language_tag
+      #   a simple literal containing a language tag
+      # @param  [RDF::Literal] language_range
+      #   a simple literal containing a language range, per
+      #   [RFC 4647 section 2.1](http://tools.ietf.org/html/rfc4647#section-2.1)
+      # @return [RDF::Literal::Boolean] `true` or `false`
+      # @raise  [TypeError] if either operand is unbound
+      # @raise  [TypeError] if either operand is not a simple literal
+      def apply(language_tag, language_range)
+        raise TypeError, "expected a plain RDF::Literal for language_tag, but got #{language_tag.inspect}" unless language_tag.is_a?(RDF::Literal) && language_tag.plain?
+        language_tag = language_tag.to_s.downcase
+
+        raise TypeError, "expected a plain RDF::Literal for language_range, but got #{language_range.inspect}" unless language_range.is_a?(RDF::Literal) && language_range.plain?
+        language_range = language_range.to_s.downcase
+
+        case
+          # A language range of "*" matches any non-empty language tag.
+          when language_range.eql?('*')
+            RDF::Literal(!(language_tag.empty?))
+          # A language range matches a particular language tag if, in a
+          # case-insensitive comparison, it exactly equals the tag, ...
+          when language_tag.eql?(language_range)
+            RDF::Literal::TRUE
+          # ... or if it exactly equals a prefix of the tag such that the
+          # first character following the prefix is "-".
+          else
+            RDF::Literal(language_tag.start_with?(language_range + '-'))
+        end
+      end
+    end # LangMatches
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -0,0 +1,95 @@
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL GraphPattern `leftjoin` operator.
+    #
+    # @example
+    #   (prefix ((: <http://example/>))
+    #     (leftjoin
+    #       (bgp (triple ?x :p ?v))
+    #       (bgp (triple ?y :q ?w))
+    #       (= ?v 2)))
+    #
+    # @see http://www.w3.org/TR/rdf-sparql-query/#sparqlAlgebra
+    class LeftJoin < Operator
+      include Query
+      
+      NAME = [:leftjoin]
+
+      ##
+      # Executes each operand with `queryable` and performs the `leftjoin` operation
+      # by adding every solution from the left, merging compatible solutions from the right
+      # that match an optional filter.
+      #
+      # @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
+      # @see    http://rdf.rubyforge.org/RDF/Query/Solution.html#merge-instance_method
+      # @see    http://rdf.rubyforge.org/RDF/Query/Solution.html#compatible%3F-instance_method
+      def execute(queryable, options = {})
+        filter = operand(2)
+
+        
+        debug(options) {"LeftJoin"}
+        left = operand(0).execute(queryable, options.merge(:depth => options[:depth].to_i + 1)) || {}
+        debug(options) {"=>(left) #{left.inspect}"}
+        right = operand(1).execute(queryable, options.merge(:depth => options[:depth].to_i + 1)) || {}
+        debug(options) {"=>(right) #{right.inspect}"}
+        
+        # LeftJoin(Ω1, Ω2, expr) =
+        solutions = []
+        left.each do |s1|
+          load_left = true
+          right.each do |s2|
+            s = s2.merge(s1)
+            expr = filter ? boolean(filter.evaluate(s)).true? : true rescue false
+            debug(options) {"===>(evaluate) #{s.inspect}"} if filter
+
+            if expr && s1.compatible?(s2)
+              # { merge(μ1, μ2) | μ1 in Ω1 and μ2 in Ω2, and μ1 and μ2 are compatible and expr(merge(μ1, μ2)) is true }
+              debug(options) {"=>(merge s1 s2) #{s.inspect}"}
+              solutions << s
+              load_left = false   # Left solution added one or more times due to merge
+            end
+          end
+          if load_left
+            debug(options) {"=>(add) #{s1.inspect}"}
+            solutions << s1
+          end
+        end
+        
+        @solutions = RDF::Query::Solutions.new(solutions)
+        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?}
+        expr = ops.pop unless ops.last.executable?
+        expr = nil if expr.respond_to?(:true?) && expr.true?
+        
+        # ops now is one or two executable operators
+        # expr is a filter expression, which may have been optimized to 'true'
+        case ops.length
+        when 0
+          RDF::Query.new  # Empty query, expr doesn't matter
+        when 1
+          expr ? Filter.new(expr, ops.first) : ops.first
+        else
+          expr ? LeftJoin(ops[0], ops[1], expr) : LeftJoin(ops[0], ops[1])
+        end
+      end
+    end # LeftJoin
+  end # Operator
+end; end # SPARQL::Algebra