sparql 3.1.6 → 3.2.1

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

@@ -3,8 +3,18 @@ module SPARQL; module Algebra
     ##
     # The SPARQL relational `=` (equal) comparison operator.
     #
-    # @example
-    #   (= ?x ?y)
+    # [114] RelationalExpression    ::= NumericExpression ('=' NumericExpression)?
+    #
+    # @example SPARQL Grammar
+    #   PREFIX  xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   PREFIX  : <http://example.org/things#>
+    #   SELECT  ?x
+    #   WHERE { ?x :p ?v . FILTER ( ?v = 1 ) }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((xsd: <http://www.w3.org/2001/XMLSchema#>) (: <http://example.org/things#>))
+    #    (project (?x) (filter (= ?v 1) (bgp (triple ?x :p ?v)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#OperatorMapping
     # @see https://www.w3.org/TR/sparql11-query/#func-RDFterm-equal
@@ -26,7 +36,7 @@ module SPARQL; module Algebra
       # @raise  [TypeError] if either operand is not an RDF term or operands are not comperable
       #
       # @see RDF::Term#==
-      def apply(term1, term2)
+      def apply(term1, term2, **options)
         term1 = term1.dup.extend(RDF::TypeCheck)
         term2 = term2.dup.extend(RDF::TypeCheck)
         RDF::Literal(term1 == term2)

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

@@ -5,10 +5,21 @@ module SPARQL; module Algebra
     #
     # There is a filter operator EXISTS that takes a graph pattern. EXISTS returns `true`/`false` depending on whether the pattern matches the dataset given the bindings in the current group graph pattern, the dataset and the active graph at this point in the query evaluation. No additional binding of variables occurs. The `NOT EXISTS` form translates into `fn:not(EXISTS{...})`.
     #
-    # @example
-    #    (prefix ((ex: <http://www.example.org/>))
-    #      (filter (exists (bgp (triple ?s ?p ex:o)))
-    #      (bgp (triple ?s ?p ?o))))
+    # [125] ExistsFunc              ::= 'EXISTS' GroupGraphPattern
+    #
+    # @example SPARQL Grammar
+    #   PREFIX :    <http://example/>
+    #   SELECT *
+    #   WHERE {
+    #     ?set a :Set .
+    #     FILTER EXISTS { ?set :member 9 }
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example/>))
+    #    (filter
+    #     (exists (bgp (triple ?set :member 9)))
+    #     (bgp (triple ?set a :Set))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-filter-exists
     class Exists < Operator::Unary
@@ -32,6 +43,19 @@ module SPARQL; module Algebra
                                        depth: options[:depth].to_i + 1,
                                        **options).empty?
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @param [Boolean] top_level (true)
+      #   Treat this as a top-level, generating SELECT ... WHERE {}
+      # @return [String]
+      def to_sparql(top_level: true, **options)
+        "EXISTS {\n" +
+          operands.last.to_sparql(top_level: false, **options) +
+          "\n}"
+      end
     end # Exists
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,8 +5,21 @@ module SPARQL; module Algebra
     #
     # Used for filters with more than one expression.
     #
-    # @example
-    #   (prefix ((: <http://example/>))
+    # [72]  ExpressionList ::= NIL | '(' Expression ( ',' Expression )* ')'
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #
+    #   SELECT ?v ?w
+    #   { 
+    #     FILTER (?v = 2)
+    #     FILTER (?w = 3)
+    #     ?s :p ?v . 
+    #     ?s :q ?w .
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.org/>))
     #     (project (?v ?w)
     #       (filter (exprlist (= ?v 2) (= ?w 3))
     #         (bgp

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

@@ -5,11 +5,52 @@ module SPARQL; module Algebra
     #
     # Extends a solution
     #
-    # @example
-    #   (select (?z)
-    #     (project (?z)
-    #       (extend ((?z (+ ?o 10)))
-    #         (bgp (triple ?s <http://example/p> ?o)))))
+    # [60]  Bind ::= 'BIND' '(' Expression 'AS' Var ')'
+    #
+    # @example SPARQL Grammar
+    #   SELECT ?z
+    #   { 
+    #     ?x <http://example.org/p> ?o
+    #     BIND(?o+10 AS ?z)
+    #   }
+    #
+    # @example SSE
+    #   (project (?z)
+    #     (extend ((?z (+ ?o 10)))
+    #       (bgp (triple ?x <http://example.org/p> ?o))))
+    #
+    # @example SPARQL Grammar (cast as boolean)
+    #   PREFIX : <http://example.org/>
+    #   PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+    #   PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   SELECT ?a ?v (xsd:boolean(?v) AS ?boolean)
+    #   WHERE { ?a :p ?v . }
+    #
+    # @example SSE (cast as boolean)
+    #   (prefix ((: <http://example.org/>)
+    #            (rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>)
+    #            (xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (project (?a ?v ?boolean)
+    #     (extend ((?boolean (xsd:boolean ?v)))
+    #      (bgp (triple ?a :p ?v)))))
+    #
+    # @example SPARQL Grammar (inner bind)
+    #   PREFIX : <http://example.org/> 
+    #   
+    #   SELECT ?z ?s1
+    #   {
+    #     ?s ?p ?o .
+    #     BIND(?o+1 AS ?z)
+    #     ?s1 ?p1 ?z
+    #   }
+    #
+    # @example SSE (inner bind)
+    #   (prefix ((: <http://example.org/>))
+    #    (project (?z ?s1)
+    #     (join
+    #      (extend ((?z (+ ?o 1)))
+    #       (bgp (triple ?s ?p ?o)))
+    #     (bgp (triple ?s1 ?p1 ?z)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#evaluation
     class Extend < Operator::Binary
@@ -73,6 +114,23 @@ module SPARQL; module Algebra
         end
         super
       end
-    end # Filter
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # Extracts bindings.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        extensions = operands.first.inject({}) do |memo, (as, expression)|
+          memo.merge(as => expression)
+        end
+
+        # Merge any inherited extensions from options
+        extensions = options.delete(:extensions).merge(extensions) if options.key?(:extensions)
+        operands.last.to_sparql(extensions: extensions, **options)
+      end
+    end # Extend
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,11 +3,19 @@ module SPARQL; module Algebra
     ##
     # The SPARQL GraphPattern `filter` operator.
     #
-    # @example
-    #   (select (?v)
-    #     (project (?v)
-    #       (filter (= ?v 2)
-    #         (bgp (triple ?s <http://example/p> ?v)))))
+    # [68]  Filter ::= 'FILTER' Constraint
+    #
+    # @example SPARQL Grammar
+    #   SELECT ?v
+    #   { 
+    #     ?s <http://example/p> ?v
+    #     FILTER(?v = 2)
+    #   }
+    #
+    # @example SSE
+    #    (project (?v)
+    #      (filter (= ?v 2)
+    #        (bgp (triple ?s <http://example/p> ?v))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#evaluation
     class Filter < Operator::Binary
@@ -69,6 +77,20 @@ module SPARQL; module Algebra
         end
         self
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # Provides filters to descendant query.
+      #
+      # If filter operation is an Exprlist, then separate into multiple filter ops.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        filter_ops = operands.first.is_a?(Operator::Exprlist) ? operands.first.operands : [operands.first]
+        str = operands.last.to_sparql(filter_ops: filter_ops, **options)
+      end
     end # Filter
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,22 @@ module SPARQL; module Algebra
     ##
     # The SPARQL logical `floor` operator.
     #
-    # @example
-    #   (floor ?x)
+    # [121] BuiltInCall ::= ... 'FLOOR' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   SELECT ?s ?num (FLOOR(?num) AS ?floor) WHERE {
+    #    ?s :num ?num
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>)
+    #     (xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (project (?s ?num ?floor)
+    #     (extend ((?floor (floor ?num)))
+    #      (bgp (triple ?s :num ?num)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-floor
     # @see https://www.w3.org/TR/xpath-functions/#func-floor
@@ -24,12 +38,21 @@ module SPARQL; module Algebra
       #   the operand
       # @return [RDF::Literal] literal of same type
       # @raise  [TypeError] if the operand is not a numeric value
-      def apply(operand)
+      def apply(operand, **options)
         case operand
           when RDF::Literal::Numeric then operand.floor
           else raise TypeError, "expected an RDF::Literal::Numeric, but got #{operand.inspect}"
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "FLOOR(#{operands.to_sparql(**options)})"
+      end
     end # Floor
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -0,0 +1,64 @@
+
+module SPARQL; module Algebra
+  class Operator
+    ##
+    # The SPARQL `function_call` operator.
+    #
+    # [70]  FunctionCall ::= iri ArgList
+    #
+    # @example SPARQL Grammar
+    #   PREFIX xsd:   <http://www.w3.org/2001/XMLSchema#>
+    #   SELECT *
+    #   WHERE { ?s ?p ?o . FILTER xsd:integer(?o) }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (filter (xsd:integer ?o)
+    #     (bgp (triple ?s ?p ?o))))
+    #
+    # @see https://www.w3.org/TR/sparql11-query/#funcex-regex
+    # @see https://www.w3.org/TR/xpath-functions/#func-matches
+    class FunctionCall < Operator
+      include Evaluatable
+
+      NAME = :function_call
+
+      ##
+      # Invokes the function with the passed arguments.
+      #
+      # @param  [RDF::IRI] iri
+      #   Identifies the function
+      # @param  [Array<RDF::Term>] args
+      # @return [RDF::Term]
+      def apply(iri, *args, **options)
+        args = RDF.nil == args.last ? args[0..-2] : args
+        SPARQL::Algebra::Expression.extension(iri, *args, **options)
+      end
+
+      ##
+      # Returns the SPARQL S-Expression (SSE) representation of this expression.
+      #
+      # Remove the optional argument.
+      #
+      # @return [Array] `self`
+      # @see    https://openjena.org/wiki/SSE
+      def to_sxp_bin
+        @operands.map(&:to_sxp_bin)
+      end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        iri, args = operands
+        iri.to_sparql(**options) +
+          '(' +
+          args.to_sparql(delimiter: ', ', **options) +
+          ')'
+      end
+    end # FunctionCall
+  end # Operator
+end; end # SPARQL::Algebra

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

@@ -5,15 +5,63 @@ module SPARQL; module Algebra
     #
     # This is a wrapper to add a `graph_name` to the query, or an array of statements.
     #
-    # @example of a query
+    # [58]  GraphGraphPattern       ::= 'GRAPH' VarOrIri GroupGraphPattern
+    #
+    # @example SPARQL Grammar (query)
+    #   PREFIX : <http://example/> 
+    #   SELECT * { 
+    #       GRAPH ?g { ?s ?p ?o }
+    #   }
+    #
+    # @example SSE
     #   (prefix ((: <http://example/>))
-    #     (graph ?g
-    #       (bgp (triple ?s ?p ?o))))
+    #    (graph ?g
+    #     (bgp (triple ?s ?p ?o))))
+    #
+    # @example SPARQL Grammar (named set of statements)
+    #   PREFIX : <http://example/> 
+    #   SELECT * { 
+    #       GRAPH :g { :s :p :o }
+    #   }
     #
-    # @example named set of statements
+    # @example SSE (named set of statements)
     #   (prefix ((: <http://example/>))
-    #     (graph :g
-    #       ((triple :s :p :o))))
+    #    (graph :g
+    #     (bgp (triple :s :p :o))))
+    #
+    # @example SPARQL Grammar (syntax-graph-05.rq)
+    #   PREFIX : <http://example.org/>
+    #   SELECT *
+    #   WHERE
+    #   {
+    #     :x :p :z
+    #     GRAPH ?g { :x :b ?a . GRAPH ?g2 { :x :p ?x } }
+    #   }
+    #
+    # @example SSE (syntax-graph-05.rq)
+    #   (prefix ((: <http://example.org/>))
+    #    (join
+    #     (bgp (triple :x :p :z))
+    #     (graph ?g
+    #      (join
+    #       (bgp (triple :x :b ?a))
+    #       (graph ?g2
+    #        (bgp (triple :x :p ?x)))))))
+    #
+    # @example SPARQL Grammar (pp06.rq)
+    #   prefix ex:	<http://www.example.org/schema#>
+    #   prefix in:	<http://www.example.org/instance#>
+    #   
+    #   select ?x where {
+    #     graph ?g {in:a ex:p1/ex:p2 ?x}
+    #   }
+    #
+    # @example SSE (syntax-graph-05.rq)
+    #   (prefix ((ex: <http://www.example.org/schema#>)
+    #            (in: <http://www.example.org/instance#>))
+    #    (project (?x)
+    #     (graph ?g
+    #      (path in:a (seq ex:p1 ex:p2) ?x))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#sparqlAlgebra
     class Graph < Operator::Binary
@@ -76,6 +124,21 @@ module SPARQL; module Algebra
       def rewrite(&block)
         self
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @param [Boolean] top_level (true)
+      #   Treat this as a top-level, generating SELECT ... WHERE {}
+      # @return [String]
+      def to_sparql(top_level: true, **options)
+        query = operands.last.to_sparql(top_level: false, **options)
+        # Paths don't automatically get braces.
+        query = "{\n#{query}\n}" unless query.start_with?('{')
+        str = "GRAPH #{operands.first.to_sparql(**options)} " + query
+        top_level ? Operator.to_sparql(str, **options) : str
+      end
     end # Graph
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,18 @@ module SPARQL; module Algebra
     ##
     # The SPARQL relational `>` (greater than) comparison operator.
     #
-    # @example
-    #   (> ?x ?y)
+    # [114] RelationalExpression    ::= NumericExpression ('>' NumericExpression)?
+    #
+    # @example SPARQL Grammar
+    #   PREFIX  xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   PREFIX  : <http://example.org/things#>
+    #   SELECT  ?x
+    #   WHERE { ?x :p ?v . FILTER ( ?v > 1 ) }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((xsd: <http://www.w3.org/2001/XMLSchema#>) (: <http://example.org/things#>))
+    #    (project (?x) (filter (> ?v 1) (bgp (triple ?x :p ?v)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#OperatorMapping
     # @see https://www.w3.org/TR/xpath-functions/#func-compare
@@ -24,8 +34,8 @@ module SPARQL; module Algebra
       #   a literal
       # @return [RDF::Literal::Boolean] `true` or `false`
       # @raise  [TypeError] if either operand is not a literal
-      def apply(left, right)
-        super
+      def apply(left, right, **options)
+        RDF::Literal(super == RDF::Literal(1))
       end
     end # GreaterThan
   end # Operator

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

@@ -4,8 +4,18 @@ module SPARQL; module Algebra
     # The SPARQL relational `>=` (greater than or equal) comparison
     # operator.
     #
-    # @example
-    #   (>= ?x ?y)
+    # [114] RelationalExpression    ::= NumericExpression ('>=' NumericExpression)?
+    #
+    # @example SPARQL Grammar
+    #   PREFIX  xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   PREFIX  : <http://example.org/things#>
+    #   SELECT  ?x
+    #   WHERE { ?x :p ?v . FILTER ( ?v >= 1 ) }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((xsd: <http://www.w3.org/2001/XMLSchema#>) (: <http://example.org/things#>))
+    #    (project (?x) (filter (>= ?v 1) (bgp (triple ?x :p ?v)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#OperatorMapping
     # @see https://www.w3.org/TR/xpath-functions/#func-compare
@@ -25,8 +35,8 @@ module SPARQL; module Algebra
       #   a literal
       # @return [RDF::Literal::Boolean] `true` or `false`
       # @raise  [TypeError] if either operand is not a literal
-      def apply(left, right)
-        super
+      def apply(left, right, **options)
+        RDF::Literal(super >= RDF::Literal(0))
       end
     end # GreaterThanOrEqual
   end # Operator

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

@@ -8,14 +8,53 @@ module SPARQL; module Algebra
     # query to be grouped. If three operands are provided,
     # the second is an array of temporary bindings.
     #
-    # @example
-    #     (prefix ((: <http://example/>))
-    #       (project (?w ?S)
-    #         (extend ((?S ??.0))
-    #           (group (?w) ((??.0 (sample ?v)))
-    #             (leftjoin
-    #               (bgp (triple ?s :p ?v))
-    #               (bgp (triple ?s :q ?w)))))))
+    # [19]  GroupClause             ::= 'GROUP' 'BY' GroupCondition+
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://www.example.org>
+    #   
+    #   SELECT ?P (COUNT(?O) AS ?C)
+    #   WHERE { ?S ?P ?O }
+    #   GROUP BY ?P
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://www.example.org>))
+    #    (project (?P ?C)
+    #     (extend ((?C ??.0))
+    #      (group (?P) ((??.0 (count ?O)))
+    #       (bgp (triple ?S ?P ?O))))))
+    #
+    # @example SPARQL Grammar (HAVING aggregate)
+    #   PREFIX : <http://www.example.org/>
+    #   SELECT ?s (AVG(?o) AS ?avg)
+    #   WHERE { ?s ?p ?o }
+    #   GROUP BY ?s
+    #   HAVING (AVG(?o) <= 2.0)
+    #
+    # @example SSE (HAVING aggregate)
+    #   (prefix ((: <http://www.example.org/>))
+    #    (project (?s ?avg)
+    #     (filter (<= ??.0 2.0)
+    #      (extend ((?avg ??.0))
+    #       (group (?s) ((??.0 (avg ?o)))
+    #        (bgp (triple ?s ?p ?o)))))) )
+    #
+    # @example SPARQL Grammar (non-triveal filters)
+    #   PREFIX : <http://example.com/data/#>
+    #   SELECT ?g (AVG(?p) AS ?avg) ((MIN(?p) + MAX(?p)) / 2 AS ?c)
+    #   WHERE { ?g :p ?p . }
+    #   GROUP BY ?g
+    #
+    # @example SSE (non-triveal filters)
+    #   (prefix ((: <http://example.com/data/#>))
+    #    (project (?g ?avg ?c)
+    #     (extend ((?avg ??.0) (?c (/ (+ ??.1 ??.2) 2)))
+    #      (group (?g)
+    #             ((??.0 (avg ?p))
+    #              (??.1 (min ?p))
+    #              (??.2 (max ?p)))
+    #       (bgp (triple ?g :p ?p)))) ))
     #
     # @see https://www.w3.org/TR/sparql11-query/#sparqlAlgebra
     class Group < Operator
@@ -122,6 +161,64 @@ module SPARQL; module Algebra
         end
         super
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @param [Hash{Symbol => Operator}] extensions
+      #   Variable bindings
+      # @param [Array<Operator>] filter_ops ([])
+      #   Filter Operations
+      # @return [String]
+      def to_sparql(extensions: {}, filter_ops: [], **options)
+        having_ops = []
+        if operands.length > 2
+          temp_bindings = operands[1].inject({}) {|memo, (var, op)| memo.merge(var => op)}
+          # Replace extensions from temporary bindings
+          temp_bindings.each do |var, op|
+            # Update extensions using a temporarily bound variable with its binding
+            extensions = extensions.inject({}) do |memo, (ext_var, ext_op)|
+              if ext_op.is_a?(Operator)
+                # Try to recursivley replace variable within operator
+                new_op = ext_op.deep_dup.rewrite do |operand|
+                  if operand.is_a?(Variable) && operand.to_sym == var.to_sym
+                    op.dup
+                  else
+                    operand
+                  end
+                end
+                memo.merge(ext_var => new_op)
+              elsif ext_op.is_a?(Variable) && ext_op.to_sym == var.to_sym
+                memo.merge(ext_var => op)
+              else
+                # Doesn't match this variable, so don't change
+                memo.merge(ext_var => ext_op)
+              end
+            end
+
+            # Filter ops using temporary bindinds are used for HAVING clauses
+            filter_ops.each do |fop|
+              having_ops << fop if fop.descendants.include?(var) && !having_ops.include?(fop)
+            end
+          end
+
+          # If used in a HAVING clause, it's not also a filter
+          filter_ops -= having_ops
+
+          # Replace each operand in having using var with it's corresponding operation
+          having_ops = having_ops.map do |op|
+            op.dup.rewrite do |operand|
+              # Rewrite based on temporary bindings
+              temp_bindings.fetch(operand, operand)
+            end
+          end
+        end
+        operands.last.to_sparql(extensions: extensions,
+                                group_ops: operands.first,
+                                having_ops: having_ops,
+                                **options)
+      end
     end # Group
   end # Operator
 end; end # SPARQL::Algebra