sparql 3.1.8 → 3.2.3

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

@@ -3,7 +3,14 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `avg` set function.
     #
-    # @example
+    # [127] Aggregate::= ... | 'AVG' '(' 'DISTINCT'? Expression ')' 
+    #
+    # @example SPARQL Query
+    #   PREFIX : <http://www.example.org/>
+    #   SELECT (AVG(?o) AS ?avg)
+    #   WHERE { ?s :dec ?o }
+    #
+    # @example SSE
     #    (prefix ((: <http://www.example.org/>))
     #      (project (?avg)
     #        (extend ((?avg ??.0))
@@ -40,6 +47,17 @@ module SPARQL; module Algebra
           raise TypeError, "Averaging non-numeric types: #{enum.flatten}"
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        distinct = operands.first == :distinct
+        args = distinct ? operands[1..-1] : operands
+        "AVG(#{'DISTINCT ' if distinct}#{args.to_sparql(**options)})"
+      end
     end # Avg
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,7 +3,13 @@ module SPARQL; module Algebra
     ##
     # The SPARQL GraphPattern `base` operator.
     #
-    # @example
+    # [5]   BaseDecl                ::= 'BASE' IRIREF
+    #
+    # @example SPARQL Grammar
+    #   BASE <http://example.org/>
+    #   SELECT * { <a> <b> 123.0 }
+    #
+    # @example SSE
     #   (base <http://example.org/>
     #     (bgp (triple <a> <b> 123.0)))
     #
@@ -56,6 +62,17 @@ module SPARQL; module Algebra
       def query_yields_statements?
         operands.last.query_yields_statements?
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this term.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        str = "BASE #{operands.first.to_sparql}\n"
+
+        str << operands.last.to_sparql(base_uri: operands.first, **options)
+      end
     end # Base
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,10 +5,22 @@ module SPARQL; module Algebra
     #
     # Query with `graph_name` set to false.
     #
-    # @example
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example/>
+    #   SELECT * { ?s ?p ?o }
+    #
+    # @example SSE
     #   (prefix ((: <http://example/>))
     #     (bgp (triple ?s ?p ?o)))
     #
+    # @example SPARQL Grammar (sparql-star)
+    #   PREFIX : <http://example.com/ns#>
+    #   SELECT * {<< :a :b :c >> :p1 :o1.}
+    #
+    # @example SSE (sparql-star)
+    #   (prefix ((: <http://example.com/ns#>))
+    #    (bgp (triple (qtriple :a :b :c) :p1 :o1)))
+    #
     # @see https://www.w3.org/TR/sparql11-query/#sparqlAlgebra
     class BGP < Operator
       NAME = [:bgp]

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

@@ -5,16 +5,30 @@ module SPARQL; module Algebra
     #
     # The BNODE function constructs a blank node that is distinct from all blank nodes in the dataset being queried and distinct from all blank nodes created by calls to this constructor for other query solutions. If the no argument form is used, every call results in a distinct blank node. If the form with a simple literal is used, every call results in distinct blank nodes for different simple literals, and the same blank node for calls with the same simple literal within expressions for one solution mapping.
     #
-    # @example
-    #     (prefix ((: <http://example.org/>)
-    #              (xsd: <http://www.w3.org/2001/XMLSchema#>))
-    #       (project (?s1 ?s2 ?b1 ?b2)
-    #         (extend ((?b1 (bnode ?s1)) (?b2 (bnode ?s2)))
-    #           (filter (exprlist (|| (= ?a :s1) (= ?a :s3)) (|| (= ?b :s1) (= ?b :s3)))
-    #             (bgp
-    #               (triple ?a :str ?s1)
-    #               (triple ?b :str ?s2)
-    #             )))))
+    # [121] BuiltInCall ::= ... | 'BNODE' ( '(' Expression ')' | NIL ) 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   SELECT ?s1 ?s2 (BNODE(?s1) AS ?b1) (BNODE(?s2) AS ?b2)
+    #   WHERE {
+    #     ?a :str ?s1 .
+    #     ?b :str ?s2 .
+    #     FILTER (?a = :s1 || ?a = :s3)
+    #     FILTER (?b = :s1 || ?b = :s3)
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>) (xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (project (?s1 ?s2 ?b1 ?b2)
+    #     (extend
+    #      ((?b1 (bnode ?s1)) (?b2 (bnode ?s2)))
+    #      (filter
+    #       (exprlist
+    #        (|| (= ?a :s1) (= ?a :s3))
+    #        (|| (= ?b :s1) (= ?b :s3)))
+    #       (bgp (triple ?a :str ?s1) (triple ?b :str ?s2))) )) )
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-bnode
     class BNode < Operator::Unary
@@ -86,6 +100,15 @@ module SPARQL; module Algebra
       def to_sxp_bin
         [NAME] + operands.reject {|o| o == false}
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "BNODE(#{operands.last.to_sparql(**options)})"
+      end
     end # BNode
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,7 +3,19 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `bound` operator.
     #
-    # @example
+    # [121] BuiltInCall ::= ... | 'BOUND' '(' Var ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX  : <http://example.org/ns#>
+    #   SELECT  ?a ?c
+    #   WHERE
+    #       { ?a :b ?c . 
+    #         OPTIONAL
+    #           { ?c :d ?e } . 
+    #         FILTER (! bound(?e)) 
+    #       }
+    #
+    # @example SSE
     #   (prefix ((: <http://example.org/ns#>))
     #     (project (?a ?c)
     #       (filter (! (bound ?e))
@@ -46,6 +58,15 @@ module SPARQL; module Algebra
           else raise TypeError, "expected an RDF::Query::Variable, but got #{var.inspect}"
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "bound(" + operands.first.to_sparql(**options) + ")"
+      end
     end # Bound
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,22 @@ module SPARQL; module Algebra
     ##
     # The SPARQL logical `ceil` operator.
     #
-    # @example
-    #   (ceil ?x)
+    # [121] BuiltInCall ::= ... 'CEIL' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   SELECT ?s ?num (CEIL(?num) AS ?ceil) WHERE {
+    #    ?s :num ?num
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>)
+    #     (xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (project (?s ?num ?ceil)
+    #     (extend ((?ceil (ceil ?num)))
+    #      (bgp (triple ?s :num ?num)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-ceil
     # @see https://www.w3.org/TR/xpath-functions/#func-ceil
@@ -26,6 +40,15 @@ module SPARQL; module Algebra
           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)
+        "CEIL(#{operands.to_sparql(**options)})"
+      end
     end # Ceil
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,8 +6,19 @@ module SPARQL; module Algebra
     #
     # The CLEAR operation removes all the triples in the specified graph(s) in the Graph Store.
     #
-    # @example
-    #   (clear silent default)
+    # [32]  Clear                   ::= 'CLEAR' 'SILENT'? GraphRefAll
+    #
+    # @example SPARQL Grammar (SILENT DEFAULT)
+    #   CLEAR SILENT DEFAULT
+    #
+    # @example SSE (SILENT DEFAULT)
+    #   (update (clear silent default))
+    #
+    # @example SPARQL Grammar (IRI)
+    #   CLEAR GRAPH <http://example.com/>
+    #
+    # @example SSE (IRI)
+    #   (update (clear <http://example.com/>))
     #
     # @see https://www.w3.org/TR/sparql11-update/#clear
     class Clear < Operator
@@ -58,6 +69,19 @@ module SPARQL; module Algebra
 
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        silent = operands.first == :silent
+        str = "CLEAR "
+        str << "SILENT " if operands.first == :silent
+        str << "GRAPH " if operands.last.is_a?(RDF::URI)
+        str << operands.last.to_sparql(**options)
+      end
     end # Clear
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,17 +3,30 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `coalesce` function.
     #
-    # @example
-    #     (prefix ((: <http://example.org/>)
-    #              (xsd: <http://www.w3.org/2001/XMLSchema#>))
-    #       (project (?cx ?div ?def ?err)
-    #         (extend ((?cx (coalesce ?x -1))
-    #                  (?div (coalesce (/ ?o ?x) -2))
-    #                  (?def (coalesce ?z -3))
-    #                  (?err (coalesce ?z)))
-    #           (leftjoin
-    #             (bgp (triple ?s :p ?o))
-    #             (bgp (triple ?s :q ?x))))))
+    # [121] BuiltInCall ::= ... | 'COALESCE' ExpressionList 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX :        <http://example/>
+    #   PREFIX xsd:     <http://www.w3.org/2001/XMLSchema#>
+    #   
+    #   SELECT ?X (SAMPLE(?v) AS ?S)
+    #   {
+    #     ?s :p ?v .
+    #     OPTIONAL { ?s :q ?w }
+    #   }
+    #   GROUP BY (COALESCE(?w, "1605-11-05"^^xsd:date) AS ?X) 
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example/>) (xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (project (?X ?S)
+    #     (extend ((?S ??.0))
+    #      (group
+    #       ((?X (coalesce ?w "1605-11-05"^^xsd:date)))
+    #       ((??.0 (sample ?v)))
+    #       (leftjoin
+    #        (bgp (triple ?s :p ?v))
+    #        (bgp (triple ?s :q ?w)))))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-coalesce
     class Coalesce < Operator
@@ -50,6 +63,15 @@ module SPARQL; module Algebra
         end
         raise TypeError, "None of the operands evaluated"
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "COALESCE(#{operands.to_sparql(delimiter: ', ', **options)})"
+      end
     end # Coalesce
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -35,6 +35,15 @@ module SPARQL; module Algebra
         RDF::Literal(spaceship(left, right, **options))
       end
 
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "(#{operands.first.to_sparql(**options)} #{self.class.const_get(:NAME)} #{operands.last.to_sparql(**options)})"
+      end
+
     private
       # Define <=> as private for recursive statements
       def spaceship(left, right, **options)

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

@@ -5,8 +5,23 @@ module SPARQL; module Algebra
     #
     # The CONCAT function corresponds to the XPath fn:concat function. The function accepts string literals as arguments.
     #
-    # @example
-    #   (concat ?a ?b ...)
+    # [121] BuiltInCall ::= ... 'CONCAT' ExpressionList 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   SELECT (CONCAT(?str1,?str2) AS ?str) WHERE {
+    #     :s6 :str ?str1 .
+    #     :s7 :str ?str2 .
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>))
+    #    (project (?str)
+    #     (extend ((?str (concat ?str1 ?str2)))
+    #      (bgp
+    #       (triple :s6 :str ?str1)
+    #       (triple :s7 :str ?str2)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-concat
     # @see https://www.w3.org/TR/xpath-functions/#func-concat
@@ -48,6 +63,15 @@ module SPARQL; module Algebra
           end
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "CONCAT(#{operands.to_sparql(delimiter: ', ', **options)})"
+      end
     end # Concat
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,12 +5,22 @@ module SPARQL; module Algebra
     #
     # The CONSTRUCT query form returns a single RDF graph specified by a graph template. The result is an RDF graph formed by taking each query solution in the solution sequence, substituting for the variables in the graph template, and combining the triples into a single RDF graph by set union.
     #
-    # @example
-    #   (prefix ((rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>)
-    #            (foaf: <http://xmlns.com/foaf/0.1/>))
-    #     (construct ((triple ?s ?p ?o))
-    #       (project (?s ?p ?o)
-    #         (bgp (triple ?s ?p ?o)))))
+    # [10]  ConstructQuery          ::= 'CONSTRUCT' ( ConstructTemplate DatasetClause* WhereClause SolutionModifier | DatasetClause* 'WHERE' '{' TriplesTemplate? '}' SolutionModifier ) ValuesClause
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example/> 
+    #   CONSTRUCT { ?x :p2 ?v }
+    #   WHERE {
+    #     ?x :p ?o .
+    #     OPTIONAL {?o :q ?v }
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example/>))
+    #    (construct ((triple ?x :p2 ?v))
+    #     (leftjoin
+    #      (bgp (triple ?x :p ?o))
+    #      (bgp (triple ?o :q ?v)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#construct
     class Construct < Operator::Binary
@@ -81,6 +91,19 @@ module SPARQL; module Algebra
       def query_yields_statements?
         true
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this term.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        str = "CONSTRUCT {\n" +
+        operands[0].map { |e| e.to_sparql(top_level: false, **options) }.join(". \n") +
+        "\n}\n"
+
+        str << operands[1].to_sparql(top_level: true, project: nil, **options)
+      end
     end # Construct
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,8 +3,21 @@ module SPARQL; module Algebra
     ##
     # A SPARQL `contains` operator.
     #
-    # @example
-    #   (contains ?x ?y)
+    # [121] BuiltInCall ::= ... | 'CONTAINS' '(' Expression ',' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s ?str WHERE {
+    #     ?s :str ?str
+    #     FILTER CONTAINS(?str, "a")
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>))
+    #    (project (?s ?str)
+    #     (filter (contains ?str "a")
+    #      (bgp (triple ?s :str ?str)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-contains
     # @see https://www.w3.org/TR/xpath-functions/#func-contains
@@ -39,6 +52,15 @@ module SPARQL; module Algebra
         else RDF::Literal::FALSE
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "contains(" + operands.to_sparql(delimiter: ', ', **options) + ")"
+      end
     end # Contains
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,8 +6,13 @@ module SPARQL; module Algebra
     #
     # The COPY operation is a shortcut for inserting all data from an input graph into a destination graph. Data from the input graph is not affected, but data from the destination graph, if any, is removed before insertion.
     #
-    # @example
-    #   (copy silent <iri> to default)
+    # [37]  Copy                    ::= 'COPY' 'SILENT'? GraphOrDefault 'TO' GraphOrDefault
+    #
+    # @example SPARQL Grammar
+    #   COPY SILENT GRAPH <http://www.example.com/g1> TO DEFAULT
+    #
+    # @example SSE
+    #   (update (copy silent <http://www.example.com/g1> default))
     #
     # @see https://www.w3.org/TR/sparql11-update/#copy
     class Copy < Operator
@@ -59,6 +64,18 @@ module SPARQL; module Algebra
         end
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        *args, last = operands.dup
+        args += [:TO, last]
+        
+        "COPY " + args.to_sparql(**options)
+      end
     end # Copy
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,12 +3,47 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `count` set function.
     #
-    # @example
-    #    (prefix ((: <http://www.example.org>))
-    #      (project (?C)
-    #        (extend ((?C ??.0))
-    #          (group () ((??.0 (count ?O)))
-    #            (bgp (triple ?S ?P ?O))))))
+    # [127] Aggregate::= 'COUNT' '(' 'DISTINCT'? ( '*' | Expression ) ')' ...
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://www.example.org/>
+    #   SELECT (COUNT(?O) AS ?C)
+    #   WHERE { ?S ?P ?O }
+    #
+    # @example SSE
+    #   (prefix ((: <http://www.example.org/>))
+    #     (project (?C)
+    #       (extend ((?C ??.0))
+    #         (group () ((??.0 (count ?O)))
+    #           (bgp (triple ?S ?P ?O))))))
+    #
+    # @example SPARQL Grammar (count(*))
+    #   PREFIX : <http://www.example.org>
+    #   
+    #   SELECT (COUNT(*) AS ?C)
+    #   WHERE { ?S ?P ?O }
+    #
+    # @example SSE (count(*))
+    #   (prefix
+    #    ((: <http://www.example.org>))
+    #    (project (?C)
+    #     (extend ((?C ??.0))
+    #      (group () ((??.0 (count)))
+    #       (bgp (triple ?S ?P ?O))))))
+    #
+    # @example SPARQL Grammar (count(distinct *))
+    #   PREFIX : <http://www.example.org>
+    #   
+    #   SELECT (COUNT(DISTINCT *) AS ?C)
+    #   WHERE { ?S ?P ?O }
+    #
+    # @example SSE (count(distinct *))
+    #   (prefix
+    #    ((: <http://www.example.org>))
+    #    (project (?C)
+    #     (extend ((?C ??.0))
+    #      (group () ((??.0 (count distinct)))
+    #       (bgp (triple ?S ?P ?O))))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#defn_aggCount
     class Count < Operator
@@ -25,6 +60,17 @@ module SPARQL; module Algebra
       def apply(enum, **options)
         RDF::Literal(enum.length)
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        distinct = operands.first == :distinct
+        args = distinct ? operands[1..-1] : operands
+        "COUNT(#{'DISTINCT ' if distinct}#{args.empty? ? '*' : args.to_sparql(**options)})"
+      end
     end # Count
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -8,8 +8,13 @@ module SPARQL; module Algebra
     #
     # This is a no-op for RDF.rb implementations, unless the graph exists
     #
-    # @example
-    #   (create silent <graph>)
+    # [34]  Create                  ::= 'CREATE' 'SILENT'? GraphRef
+    #
+    # @example SPARQL Grammar
+    #   CREATE SILENT GRAPH <http://example.org/g1>
+    #
+    # @example SSE
+    #   (update (create silent <http://example.org/g1>))
     #
     # @see https://www.w3.org/TR/sparql11-update/#create
     class Create < Operator
@@ -43,6 +48,19 @@ module SPARQL; module Algebra
         end
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        silent = operands.first == :silent
+        str = "CREATE "
+        str << "SILENT " if operands.first == :silent
+        str << "GRAPH " if operands.last.is_a?(RDF::URI)
+        str << operands.last.to_sparql(**options)
+      end
     end # Create
   end # Operator
 end; end # SPARQL::Algebra