sparql 3.1.5 → 3.2.0

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

@@ -5,11 +5,19 @@ 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/p> ?o
+    #     BIND(?o+1 AS ?z)
+    #   }
+    #
+    # @example SSE
+    #   (project (?z)
+    #     (extend ((?z (+ ?o 10)))
+    #       (bgp (triple ?s <http://example/p> ?o))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#evaluation
     class Extend < Operator::Binary
@@ -28,12 +36,6 @@ module SPARQL; module Algebra
       # 
       # Extend(Ω, var, expr) = { Extend(μ, var, expr) | μ in Ω }
       #
-      # For SPARQL*, expr may be an embedded tiple pattern
-      #
-      #    (extend
-      #     ((?t (triple ?bob foaf:age ?age)))
-      #     (bgp (triple ?t dct:source ?src)))
-      #
       # @param  [RDF::Queryable] queryable
       #   the graph or repository to query
       # @param  [Hash{Symbol => Object}] options
@@ -56,12 +58,8 @@ module SPARQL; module Algebra
                                             depth: options[:depth].to_i + 1,
                                             **options)
               debug(options) {"===> + #{var} => #{val.inspect}"}
-              solution.bindings[var.to_sym] = if val.is_a?(RDF::Query::Pattern)
-                # Variable is bound to the solution
-                val.bind(solution)
-              else
-                val
-              end
+              val = val.dup.bind(solution) if val.is_a?(RDF::Query::Pattern)
+              solution.bindings[var.to_sym] = val
             rescue TypeError => e
               # Evaluates to error, ignore
               debug(options) {"===> #{var} error: #{e.message}"}
@@ -83,6 +81,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]
+        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/graph.rb

@@ -5,6 +5,19 @@ module SPARQL; module Algebra
     #
     # This is a wrapper to add a `graph_name` to the query, or an array of statements.
     #
+    # [58]  GraphGraphPattern       ::= 'GRAPH' VarOrIri GroupGraphPattern
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example/> 
+    #   SELECT * { 
+    #       GRAPH ?g { ?s ?p ?o }
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example/>))
+    #    (graph ?g
+    #     (bgp (triple ?s ?p ?o))))
+    #
     # @example of a query
     #   (prefix ((: <http://example/>))
     #     (graph ?g

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,22 @@ 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))))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#sparqlAlgebra
     class Group < Operator
@@ -122,6 +130,24 @@ module SPARQL; module Algebra
         end
         super
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @param [Hash{Symbol => Operator}] extensions
+      #   Variable bindings
+      # @return [String]
+      def to_sparql(extensions: {}, **options)
+        if operands.length > 2
+          # Replace extensions from temporary bindings
+          operands[1].each do |var, op|
+            ext_var = extensions.invert.fetch(var)
+            extensions[ext_var] = op
+          end
+        end
+        operands.last.to_sparql(extensions: extensions, group_ops: operands.first, **options)
+      end
     end # Group
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,13 +5,16 @@ module SPARQL; module Algebra
     #
     # GroupConcat is a set function which performs a string concatenation across the values of an expression with a group. The order of the strings is not specified. The separator character used in the concatenation may be given with the scalar argument SEPARATOR.
     #
-    # @example
-    #    (prefix ((: <http://www.example.org/>))
-    #      (filter (|| (= ?g "1 22") (= ?g "22 1"))
-    #        (project (?g)
-    #          (extend ((?g ??.0))
-    #            (group () ((??.0 (group_concat ?o)))
-    #              (bgp (triple ??.0 :p1 ?o)))))))
+    # [127] Aggregate::= ... | 'GROUP_CONCAT' '(' 'DISTINCT'? Expression ( ';' 'SEPARATOR' '=' String )? ')'
+    #
+    # @example SPARQL Grammar
+    #   SELECT (GROUP_CONCAT(?x) AS ?y) {}
+    #
+    # @example SSE
+    #   (project (?y)
+    #    (extend ((?y ??.0))
+    #     (group () ((??.0 (group_concat ?x)))
+    #      (bgp))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#defn_aggGroupConcat
     class GroupConcat < Operator
@@ -50,9 +53,18 @@ module SPARQL; module Algebra
       #   enum of evaluated operand
       # @return [RDF::Term] An arbitrary term
       # @raise  [TypeError] If enum is empty
-      def apply(enum, separator)
+      def apply(enum, separator, **options)
         RDF::Literal(enum.flatten.map(&:to_s).join(separator.to_s))
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "GROUP_CONCAT(#{operands.to_sparql(delimiter: ', ', **options)})"
+      end
     end # GroupConcat
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,11 +3,20 @@ module SPARQL; module Algebra
     ##
     # The SPARQL logical `hours` operator.
     #
-    # @example
-    #     (prefix ((: <http://example.org/>))
-    #       (project (?s ?x)
-    #         (extend ((?x (hours ?date)))
-    #           (bgp (triple ?s :date ?date)))))
+    # [121] BuiltInCall ::= ... | 'HOURS' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s (HOURS(?date) AS ?x) WHERE {
+    #     ?s :date ?date
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>))
+    #    (project (?s ?x)
+    #     (extend ((?x (hours ?date)))
+    #      (bgp (triple ?s :date ?date)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-hours
     class Hours < Operator::Unary
@@ -22,10 +31,19 @@ module SPARQL; module Algebra
       #   the operand
       # @return [RDF::Literal]
       # @raise  [TypeError] if the operand is not a simple literal
-      def apply(operand)
+      def apply(operand, **options)
         raise TypeError, "expected an RDF::Literal::DateTime, but got #{operand.inspect}" unless operand.is_a?(RDF::Literal::DateTime)
         RDF::Literal(operand.object.hour)
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "HOURS(#{operands.last.to_sparql(**options)})"
+      end
     end # Hours
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,7 +3,15 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `if` function.
     #
-    # @example
+    # [121] BuiltInCall ::= ... | 'IF' '(' Expression ',' Expression ',' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   BASE <http://example.org/>
+    #   PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   SELECT ?o (IF(lang(?o) = "ja", true, false) AS ?integer)
+    #   WHERE { ?s ?p ?o }
+    #
+    # @example SSE
     #     (base <http://example.org/>
     #       (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>))
     #         (project (?o ?integer)
@@ -37,9 +45,18 @@ module SPARQL; module Algebra
         operand(0).evaluate(bindings, depth: options[:depth].to_i + 1, **options) == RDF::Literal::TRUE ?
           operand(1).evaluate(bindings, depth: options[:depth].to_i + 1, **options) :
           operand(2).evaluate(bindings, depth: options[:depth].to_i + 1, **options)
-        rescue
-          raise TypeError
+      rescue
+        raise TypeError
       end
     end # If
-  end # Operator
+
+    ##
+    #
+    # Returns a partial SPARQL grammar for this operator.
+    #
+    # @return [String]
+    def to_sparql(**options)
+      "IF(" + operands.to_sparql(delimiter: ', ', **options) + ")"
+    end
+  end # If
 end; end # SPARQL::Algebra

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

@@ -3,7 +3,12 @@ module SPARQL; module Algebra
     ##
     # The SPARQL GraphPattern `in` operator.
     #
-    # @example
+    # [114] RelationalExpression    ::= NumericExpression ('IN' ExpressionList)?
+    #
+    # @example SPARQL Grammar
+    #   ASK { FILTER(2 IN (1, 2, 3)) }
+    #
+    # @example SSE
     #   (ask (filter (in 2 1 2 3) (bgp)))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-in
@@ -54,6 +59,18 @@ module SPARQL; module Algebra
         else RDF::Literal::FALSE
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "(" + operands.first.to_sparql(**options) +
+        " IN (" +
+        operands[1..-1].map {|e| e.to_sparql(**options)}.join(", ") +
+        "))"
+      end
     end # In
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,8 +6,19 @@ module SPARQL; module Algebra
     #
     # The INSERT operation is a form of the DELETE/INSERT operation having no DELETE section
     #
-    # @example
-    #   (insert ((triple ?s ?p "q")))
+    # [43]  InsertClause            ::= 'INSERT' QuadPattern
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/> 
+    #   INSERT { ?s ?p "q" }
+    #   WHERE { ?s ?p ?o }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>))
+    #    (update
+    #     (modify (bgp (triple ?s ?p ?o))
+    #      (insert ((triple ?s ?p "q"))))))
     #
     # @see https://www.w3.org/TR/sparql11-update/#insert
     class Insert < Operator::Unary
@@ -51,6 +62,15 @@ module SPARQL; module Algebra
         end
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this term.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "INSERT {\n" + operands.first.to_sparql(as_statement: true, **options) + "\n}"
+      end
     end # Insert
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,8 +6,18 @@ module SPARQL; module Algebra
     #
     # The INSERT DATA operation adds some triples, given inline in the request, into the Graph Store
     #
-    # @example
-    #   (insertData ((graph <http://example.org/g1> ((triple :s :p :o)))))
+    # [38]  InsertData              ::= 'INSERT DATA' QuadData
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/ns#>
+    #   INSERT DATA { GRAPH <http://example.org/g1> { :s :p :o } }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/ns#>))
+    #    (update
+    #     (insertData (
+    #      (graph <http://example.org/g1> ((triple :s :p :o)))))))
     #
     # @see https://www.w3.org/TR/sparql11-update/#insertData
     class InsertData < Operator::Unary
@@ -36,6 +46,17 @@ module SPARQL; module Algebra
         end
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this term.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "INSERT DATA {\n" +
+          operands.first.to_sparql(as_statement: true, top_level: false, delimiter: "\n", **options) +
+          "\n}"
+      end
     end # InsertData
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,10 +3,18 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `iri` operator.
     #
-    # @example
-    #     (base <http://example.org/> (project (?uri ?iri)
-    #       (extend ((?uri (uri "uri")) (?iri (iri "iri")))
-    #         (bgp))))
+    # [121] BuiltInCall ::= ... | 'IRI' '(' Expression ')' | 'URI' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   BASE <http://example.org/>
+    #   SELECT (URI("uri") AS ?uri) (IRI("iri") AS ?iri)
+    #   WHERE {}
+    #
+    # @example SSE
+    #   (base <http://example.org/>
+    #    (project (?uri ?iri)
+    #     (extend ((?uri (iri "uri")) (?iri (iri "iri")))
+    #      (bgp))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-iri
     class IRI < Operator::Unary
@@ -29,12 +37,21 @@ module SPARQL; module Algebra
       #   a simple literal
       # @return [RDF::URI]
       # @raise  [TypeError] if the operand is not a simple literal
-      def apply(literal)
+      def apply(literal, **options)
         raise TypeError, "expected an simple literal, but got #{literal.inspect}" unless literal.literal? && literal.simple?
         base = Operator.base_uri || RDF::URI("")
         base.join(literal.to_s)
       end
 
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "IRI(" + operands.last.to_sparql(**options) + ")"
+      end
+
       Operator::URI = IRI
     end # IRI
   end # Operator

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

@@ -3,7 +3,16 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `isBlank` operator.
     #
-    # @example
+    # [121] BuiltInCall ::= ... | 'isBlank' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX     :    <http://example.org/things#>
+    #   SELECT ?x ?v WHERE {
+    #     ?x :p ?v .
+    #     FILTER isBlank(?v) .
+    #   }
+    #
+    # @example SSE
     #   (prefix ((xsd: <http://www.w3.org/2001/XMLSchema#>)
     #            (: <http://example.org/things#>))
     #     (project (?x ?v)
@@ -23,13 +32,22 @@ module SPARQL; module Algebra
       #   an RDF term
       # @return [RDF::Literal::Boolean] `true` or `false`
       # @raise  [TypeError] if the operand is not an RDF term
-      def apply(term)
+      def apply(term, **options)
         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
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "isBlank(" + operands.first.to_sparql(**options) + ")"
+      end
     end # IsBlank
   end # Operator
 end; end # SPARQL::Algebra