sparql 3.1.8 → 3.2.3

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

@@ -5,12 +5,23 @@ 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
-    #                 (filter (notexists (bgp (triple ?s ?p ex:o2)))
-    #                   (bgp (triple ?s ?p ex:o1))))
-    #        (bgp (triple ?s ?p ex:o))))
+    # [126] NotExistsFunc           ::= 'NOT' 'EXISTS' GroupGraphPattern
+    #
+    # @example SPARQL Grammar
+    #   PREFIX ex: <http://www.w3.org/2009/sparql/docs/tests/data-sparql11/negation#>
+    #   SELECT ?animal { 
+    #     ?animal a ex:Animal 
+    #     FILTER NOT EXISTS { ?animal a ex:Insect } 
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((ex: <http://www.w3.org/2009/sparql/docs/tests/data-sparql11/negation#>))
+    #    (project (?animal)
+    #     (filter
+    #      (notexists
+    #       (bgp (triple ?animal a ex:Insect)))
+    #      (bgp (triple ?animal a ex:Animal)))) )
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-abs
     # @see https://www.w3.org/TR/xpath-functions/#func-abs
@@ -34,6 +45,19 @@ module SPARQL; module Algebra
         queryable = options[:queryable]
         operand(0).execute(queryable, solutions: solutions, **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)
+        "NOT EXISTS {\n" +
+          operands.last.to_sparql(top_level: false, **options) +
+          "\n}"
+      end
     end # NotExists
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,8 +5,13 @@ module SPARQL; module Algebra
     #
     # Used for filters with more than one expression.
     #
-    # @example
-    #   (ask (filter (notin ?o 1 2) (bgp)))
+    # [114] RelationalExpression    ::= NumericExpression ('NOT' 'IN' ExpressionList)?
+    #
+    # @example SPARQL Grammar
+    #   ASK { FILTER(2 NOT IN ()) }
+    #
+    # @example SSE
+    #   (ask (filter (notin 2) (bgp)))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-notin
     class NotIn < Operator
@@ -58,6 +63,18 @@ module SPARQL; module Algebra
         else RDF::Literal::TRUE
         end
       end
-    end # Exprlist
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "(" + operands.first.to_sparql(**options) +
+        " NOT IN (" +
+        operands[1..-1].map {|e| e.to_sparql(**options)}.join(", ") +
+        "))"
+      end
+    end # NotIn
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,18 @@ module SPARQL; module Algebra
     ##
     # The SPARQL Property Path `notoneof` (NegatedPropertySet) operator.
     #
-    # @example
-    #   (notoneof ex:p1 ex:p2)
+    # [96]  PathOneInPropertySet ::= iri | 'a' | '^' ( iri | 'a' )
+    #
+    # @example SPARQL Grammar
+    #   PREFIX ex:	<http://www.example.org/schema#>
+    #   PREFIX in:	<http://www.example.org/instance#>
+    #   ASK { in:a !(ex:p1|ex:p2) ?x }
+    #
+    # @example SSE
+    #   (prefix ((ex: <http://www.example.org/schema#>)
+    #           (in: <http://www.example.org/instance#>))
+    #    (ask
+    #     (path in:a (notoneof ex:p1 ex:p2) ?x)))
     #
     # @see https://www.w3.org/TR/sparql11-query/#eval_negatedPropertySet
     class NotOneOf < Operator
@@ -46,6 +56,15 @@ module SPARQL; module Algebra
           block.call(solution)
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "!(" + operands.to_sparql(delimiter: ' | ', **options) + ')'
+      end
     end # NotOneOf
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -7,11 +7,21 @@ module SPARQL; module Algebra
     #
     # Returns an XSD dateTime value for the current query execution. All calls to this function in any one query execution must return the same value. The exact moment returned is not specified.
     #
-    # @example
-    #     (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>))
-    #       (ask (filter (= (datatype ?n) xsd:dateTime)
-    #         (extend ((?n (now)))
-    #           (bgp)))))
+    # [121] BuiltInCall ::= ... | 'NOW' NIL 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   ASK {
+    #     BIND(NOW() AS ?n)
+    #     FILTER(DATATYPE(?n) = xsd:dateTime)
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (ask
+    #     (filter (= (datatype ?n) xsd:dateTime)
+    #      (extend ((?n (now)))
+    #       (bgp)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-now
     class Now < Operator::Nullary
@@ -26,6 +36,15 @@ module SPARQL; module Algebra
       def apply(**options)
         RDF::Literal(DateTime.now)
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "NOW()"
+      end
     end # Now
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,6 +5,29 @@ module SPARQL; module Algebra
     #
     # If triple is an RDF-star triple, the function returns the object of this triple. Passing anything other than an RDF-star triple is an error.
     #
+    # [121] BuiltInCall ::= ... | 'OBJECT' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.com/ns#>
+    #   SELECT * {
+    #     ?t :source :g
+    #     FILTER(isTriple(?t))
+    #     FILTER(SUBJECT(?t) = :s)
+    #     FILTER(PREDICATE(?t) = :p)
+    #     FILTER(OBJECT(?t) = :o)
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.com/ns#>))
+    #    (filter
+    #     (exprlist
+    #      (isTRIPLE ?t)
+    #      (= (subject ?t) :s)
+    #      (= (predicate ?t) :p)
+    #      (= (object ?t) :o))
+    #     (bgp (triple ?t :source :g))) )
+    #
     # @see https://w3c.github.io/rdf-star/rdf-star-cg-spec.html#object
     class Object < Operator::Unary
       include Evaluatable
@@ -22,6 +45,15 @@ module SPARQL; module Algebra
         raise TypeError, "expected an RDF::Statement, but got #{operand.inspect}" unless operand.is_a?(RDF::Statement)
         operand.object
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "OBJECT(" + operands.last.to_sparql(**options) + ")"
+      end
     end # Object
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,9 +3,23 @@ module SPARQL; module Algebra
     ##
     # The SPARQL logical `or` operator.
     #
-    # @example
-    #   (|| ?x ?y)
-    #   (or ?x ?y)
+    # [111] ConditionalOrExpression ::= ConditionalAndExpression ( '||' ConditionalAndExpression )*
+    #
+    # @example SPARQL Grammar
+    #   PREFIX  xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   PREFIX  : <http://example.org/ns#>
+    #   SELECT  ?a
+    #   WHERE {
+    #     ?a :p ?v . 
+    #     FILTER ("false"^^xsd:boolean || ?v) .
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
+    #            (: <http://example.org/ns#>))
+    #    (project (?a)
+    #     (filter (|| false ?v)
+    #      (bgp (triple ?a :p ?v)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-logical-or
     # @see https://www.w3.org/TR/sparql11-query/#evaluation
@@ -63,6 +77,15 @@ module SPARQL; module Algebra
         else                              RDF::Literal(left || right)
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "(#{operands.first.to_sparql(**options)} || #{operands.last.to_sparql(**options)})"
+      end
     end # Or
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,12 +3,64 @@ module SPARQL; module Algebra
     ##
     # The SPARQL GraphPattern `order` operator.
     #
-    # @example
+    # [23]  OrderClause             ::= 'ORDER' 'BY' OrderCondition+
+    #
+    # @example SPARQL Grammar
+    #   PREFIX foaf:    <http://xmlns.com/foaf/0.1/>
+    #   SELECT ?name
+    #   WHERE { ?x foaf:name ?name }
+    #   ORDER BY ASC(?name)
+    #
+    # @example SSE
     #   (prefix ((foaf: <http://xmlns.com/foaf/0.1/>))
     #     (project (?name)
     #       (order ((asc ?name))
     #         (bgp (triple ?x foaf:name ?name)))))
     #
+    # @example SPARQL Grammar (with builtin)
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s WHERE {
+    #     ?s :p ?o .
+    #   }
+    #   ORDER BY str(?o)
+    #
+    # @example SSE (with builtin)
+    #   (prefix ((: <http://example.org/>))
+    #    (project (?s)
+    #     (order ((str ?o))
+    #      (bgp (triple ?s :p ?o)))))
+    #
+    # @example SPARQL Grammar (with bracketed expression)
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s WHERE {
+    #     ?s :p ?o1 ; :q ?o2 .
+    #   } ORDER BY (?o1 + ?o2)
+    #
+    # @example SSE (with bracketed expression)
+    #   (prefix
+    #    ((: <http://example.org/>))
+    #    (project (?s)
+    #     (order ((+ ?o1 ?o2))
+    #      (bgp
+    #       (triple ?s :p ?o1)
+    #       (triple ?s :q ?o2)))))
+    #
+    # @example SPARQL Grammar (with function call)
+    #   PREFIX :      <http://example.org/ns#>
+    #   PREFIX xsd:   <http://www.w3.org/2001/XMLSchema#>
+    #   SELECT *
+    #   { ?s ?p ?o }
+    #   ORDER BY 
+    #     DESC(?o+57) xsd:string(?o) ASC(?s)
+    #
+    # @example SSE (with function call)
+    #   (prefix ((: <http://example.org/ns#>)
+    #            (xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (order ((desc (+ ?o 57))
+    #            (xsd:string ?o)
+    #            (asc ?s))
+    #     (bgp (triple ?s ?p ?o))))
+    #
     # @see https://www.w3.org/TR/sparql11-query/#modOrderBy
     class Order < Operator::Binary
       include Query
@@ -56,6 +108,17 @@ module SPARQL; module Algebra
         @solutions.each(&block) if block_given?
         @solutions
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # Provides order to descendant query.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        operands.last.to_sparql(order_ops: operands.first, **options)
+      end
     end # Order
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,23 @@ module SPARQL; module Algebra
     ##
     # The SPARQL Property Path `path` operator.
     #
-    # @example
-    #   (path :a (path+ :p) ?z)
+    # [88]  Path ::= PathAlternative
+    #
+    # @example SPARQL Grammar
+    #   PREFIX :  <http://www.example.org/>
+    #   SELECT ?t
+    #   WHERE {
+    #     :a :p1|:p2/:p3|:p4 ?t
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://www.example.org/>))
+    #    (project (?t)
+    #     (path :a
+    #      (alt
+    #       (alt :p1 (seq :p2 :p3))
+    #       :p4)
+    #      ?t)))
     #
     # @see https://www.w3.org/TR/sparql11-query/#sparqlTranslatePathExpressions
     class Path < Operator::Ternary
@@ -45,6 +60,18 @@ module SPARQL; module Algebra
         @solutions.each(&block) if block_given?
         @solutions
       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)
+        str = operands.to_sparql(top_level: false, **options) + " ."
+        top_level ? Operator.to_sparql(str, **options) : str
+      end
     end # Path
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,18 @@ module SPARQL; module Algebra
     ##
     # The SPARQL Property Path `path?` (ZeroOrOnePath) operator.
     #
-    # @example
-    #   (path? :p)
+    # [91]  PathElt ::= PathPrimary PathMod?
+    # [93]  PathMod ::= '*' | '?' | '+' | '{' INTEGER? (',' INTEGER?)? '}'
+    
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example/> 
+    #   SELECT * WHERE {
+    #     :a (:p/:p)? ?t
+    #   } 
+    #
+    # @example SSE
+    #   (prefix ((: <http://example/>))
+    #    (path :a (path? (seq :p :p)) ?t))
     #
     # @see https://www.w3.org/TR/sparql11-query/#defn_evalPP_ZeroOrOnePath
     class PathOpt < Operator::Unary
@@ -13,11 +23,10 @@ module SPARQL; module Algebra
       NAME = :path?
 
       ##
-      # Equivalent to:
+      # Optional path:
       #
       #    (path x (path? :p) y)
-      #     => (union (bgp ((x :p y))) (filter (x = x) (solution x y)))
-      #        
+      #     => (union (bgp ((x :p y))) (filter (x = y) (solution x y)))
       #
       # @param  [RDF::Queryable] queryable
       #   the graph or repository to query
@@ -34,79 +43,33 @@ module SPARQL; module Algebra
         subject, object = options[:subject], options[:object]
         debug(options) {"Path? #{[subject, operands, object].to_sse}"}
 
-        solutions = RDF::Query::Solutions.new
-        # Solutions where subject == object with no predicate
-        case
-        when subject.variable? && object.variable?
-          # Nodes is the set of all subjects and objects in queryable
-          # FIXME: should this be Queryable#enum_nodes?
-          # All subjects which are `object`
-          query = RDF::Query.new {|q| q.pattern({subject: subject})}
-          queryable.query(query, **options) do |solution|
-            solution.merge!(object.to_sym => solution[subject])
-            debug(options) {"(solution-s0)-> #{solution.to_h.to_sse}"}
-            solutions << solution
-          end if query.valid?
-
-          # All objects which are `object`
-          query = RDF::Query.new {|q| q.pattern({object: object})}
-          queryable.query(query, **options) do |solution|
-            solution.merge!(subject.to_sym => solution[object])
-            debug(options) {"(solution-o0)-> #{solution.to_h.to_sse}"}
-            solutions << solution
-          end if query.valid?
-        when subject.variable?
-          # All subjects which are `object`
-          query = RDF::Query.new {|q| q.pattern({subject: object})}
-          queryable.query(query, **options) do |solution|
-            solution.merge!(subject.to_sym => object)
-            debug(options) {"(solution-s0)-> #{solution.to_h.to_sse}"}
-            solutions << solution
-          end if query.valid?
-
-          # All objects which are `object`
-          query = RDF::Query.new {|q| q.pattern({object: object})}
-          queryable.query(query, **options) do |solution|
-            solution.merge!(subject.to_sym => object)
-            debug(options) {"(solution-o0)-> #{solution.to_h.to_sse}"}
-            solutions << solution
-          end if query.valid?
-        when object.variable?
-          # All subjects which are `subject`
-          query = RDF::Query.new {|q| q.pattern({subject: subject})}
-          queryable.query(query, **options) do |solution|
-            solution.merge!(object.to_sym => subject)
-            debug(options) {"(solution-s0)-> #{solution.to_h.to_sse}"}
-            solutions << solution
-          end if query.valid?
-
-          # All objects which are `subject
-          query = RDF::Query.new {|q| q.pattern({object: subject})}
-          queryable.query(query, **options) do |solution|
-            solution.merge!(object.to_sym => subject)
-            debug(options) {"(solution-o0)-> #{solution.to_h.to_sse}"}
-            solutions << solution
-          end if query.valid?
-        else
-          # Otherwise, if subject == object, an empty solution
-          solutions << RDF::Query::Solution.new if subject == object
-        end
+        query = PathZero.new(operand)
+        solutions = query.execute(queryable, **options.merge(depth: options[:depth].to_i + 1))
 
         # Solutions where predicate exists
         query = if operand.is_a?(RDF::Term)
           RDF::Query.new do |q|
             q.pattern [subject, operand, object]
           end
-        else
+        else # path
           operand
         end
 
         # Recurse into query
-        solutions += 
-        queryable.query(query, depth: options[:depth].to_i + 1, **options)
+        solutions += query.execute(queryable, **options.merge(depth: options[:depth].to_i + 1))
+        debug(options) {"(path?)=> #{solutions.to_sxp}"}
         solutions.each(&block) if block_given?
         solutions
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "(#{operands.first.to_sparql(**options)})?"
+      end
     end # PathOpt
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,18 @@ module SPARQL; module Algebra
     ##
     # The SPARQL Property Path `path+` (OneOrMorePath) operator.
     #
-    # @example
-    #   (path+ :p)
+    # [91]  PathElt ::= PathPrimary PathMod?
+    # [93]  PathMod ::= '*' | '?' | '+' | '{' INTEGER? (',' INTEGER?)? '}'
+    
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example/> 
+    #   SELECT * WHERE {
+    #     :a :p+ ?z
+    #   } 
+    #
+    # @example SSE
+    #   (prefix ((: <http://example/>))
+    #    (path :a (path+ :p) ?z))
     #
     # @see https://www.w3.org/TR/sparql11-query/#defn_evalPP_OneOrMorePath
     class PathPlus < Operator::Unary
@@ -15,6 +25,16 @@ module SPARQL; module Algebra
       ##
       # Match on simple relation of subject to object, and then recurse on solutions
       #
+      # Path including at least one:
+      #
+      #    (path :a (path+ :p) :b)
+      #
+      # into
+      #
+      #    (union
+      #     (bgp (triple :a :p :b))
+      #     (path :a (path* :p) :b))
+      #
       # @param  [RDF::Queryable] queryable
       #   the graph or repository to query
       # @param  [Hash{Symbol => Object}] options
@@ -52,10 +72,8 @@ module SPARQL; module Algebra
 
         # Keep track of solutions
         # Recurse into query
-        immediate_solutions = []
-        queryable.query(query, depth: options[:depth].to_i + 1, **options) do |solution|
-          immediate_solutions << solution
-        end
+        immediate_solutions = 
+          query.execute(queryable, depth: options[:depth].to_i + 1, **options)
 
         # For all solutions, if they are not in the accumulator, add them and recurse, otherwise skip
         recursive_solutions = RDF::Query::Solutions.new
@@ -66,23 +84,23 @@ module SPARQL; module Algebra
           case
           when subject.variable? && object.variable?
             # Query starting with bound object as subject, but replace result with subject
-            rs = queryable.query(self, **options.merge(
+            rs = self.execute(queryable, **options.merge(
               subject: solution[object],
               accumulator: (cumulative_solutions + immediate_solutions),
               depth: options[:depth].to_i + 1)).map {|s| s.merge(subject.to_sym => solution[subject])}
             # Query starting with bound subject as object, but replace result with subject
-            ro = queryable.query(self, **options.merge(
+            ro = self.execute(queryable, **options.merge(
               object: solution[subject],
               accumulator: (cumulative_solutions + immediate_solutions),
               depth: options[:depth].to_i + 1)).map {|s| s.merge(object.to_sym => solution[object])}
             recursive_solutions += (rs + ro).uniq
           when subject.variable?
-            recursive_solutions += queryable.query(self, **options.merge(
+            recursive_solutions += self.execute(queryable, **options.merge(
               object: solution[subject],
               accumulator: (cumulative_solutions + immediate_solutions),
               depth: options[:depth].to_i + 1)).uniq
           when object.variable?
-            recursive_solutions += queryable.query(self, **options.merge(
+            recursive_solutions += self.execute(queryable, **options.merge(
               subject: solution[object],
               accumulator: (cumulative_solutions + immediate_solutions),
               depth: options[:depth].to_i + 1)).uniq
@@ -94,6 +112,15 @@ module SPARQL; module Algebra
         solutions.each(&block) if block_given? # Only at top-level
         solutions
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "(#{operands.first.to_sparql(**options)})+"
+      end
     end # PathPlus
   end # Operator
 end; end # SPARQL::Algebra