sparql 3.1.8 → 3.2.3

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

@@ -5,11 +5,20 @@ module SPARQL; module Algebra
     #
     # Returns the timezone part of `arg` as an xsd:dayTimeDuration. Raises an error if there is no timezone.
     #
-    # @example
-    #     (prefix ((: <http://example.org/>))
-    #       (project (?s ?x)
-    #         (extend ((?x (timezone ?date)))
-    #           (bgp (triple ?s :date ?date)))))
+    # [121] BuiltInCall ::= ... | 'TIMEZONE' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s (TIMEZONE(?date) AS ?x) WHERE {
+    #     ?s :date ?date
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>))
+    #    (project (?s ?x)
+    #     (extend ((?x (timezone ?date)))
+    #      (bgp (triple ?s :date ?date)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-timezone
     class Timezone < Operator::Unary
@@ -24,13 +33,22 @@ module SPARQL; module Algebra
       #
       # @param  [RDF::Literal] operand
       #   the operand
-      # @return [RDF::Literal]
+      # @return [RDF::Literal::Temporal]
       # @raise  [TypeError] if the operand is not a simple literal
       def apply(operand, **options)
-        raise TypeError, "expected an RDF::Literal::DateTime, but got #{operand.inspect}" unless operand.is_a?(RDF::Literal::DateTime)
+        raise TypeError, "expected an RDF::Literal::Temporal, but got #{operand.inspect}" unless operand.is_a?(RDF::Literal::Temporal)
         raise TypeError, "literal has no timezone" unless res = operand.timezone
         res
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "TIMEZONE(" + operands.to_sparql(**options) + ")"
+      end
     end # Timezone
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,6 +5,21 @@ module SPARQL; module Algebra
     #
     # If the 3-tuple (term1, term2, term3) is an RDF-star triple, the function returns this triple. If the 3-tuple is not an RDF-star triple, then the function raises an error.
     #
+    # [121] BuiltInCall ::= ... | 'TRIPLE' '(' Expression ',' Expression ',' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.com/ns#>
+    #   SELECT * {
+    #     ?s ?p ?o .
+    #     BIND(TRIPLE(?s, ?p, ?o) AS ?t1)
+    #   }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.com/ns#>))
+    #    (extend ((?t1 (triple ?s ?p ?o)))
+    #     (bgp (triple ?s ?p ?o))))
+    #
+    # @note This operator overlaps with RDF::Query::Pattern as used as an operand to a BGP.
     # @see https://w3c.github.io/rdf-star/rdf-star-cg-spec.html#triple
     class Triple < Operator::Ternary
       include Evaluatable
@@ -22,6 +37,15 @@ module SPARQL; module Algebra
         raise TypeError, "valid components, but got #{triple.inspect}" unless triple.valid?
         triple
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "TRIPLE(#{operands.to_sparql(delimiter: ', ', **options)})"
+      end
     end # Triple
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,11 +5,20 @@ module SPARQL; module Algebra
     #
     # Returns the timezone part of `arg` as a simple literal. Returns the empty string if there is no timezone.
     #
-    # @example
-    #     (prefix ((: <http://example.org/>))
-    #       (project (?s ?x)
-    #         (extend ((?x (tz ?date)))
-    #           (bgp (triple ?s :date ?date)))))
+    # [121] BuiltInCall ::= ... | 'TZ' '(' Expression ')' 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   SELECT ?s (TZ(?date) AS ?x) WHERE {
+    #     ?s :date ?date
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>))
+    #    (project (?s ?x)
+    #     (extend ((?x (tz ?date)))
+    #      (bgp (triple ?s :date ?date)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-tz
     class TZ < Operator::Unary
@@ -20,14 +29,22 @@ module SPARQL; module Algebra
       ##
       # Returns the timezone part of arg as a simple literal. Returns the empty string if there is no timezone.
       #
-      # @param  [RDF::Literal] operand
+      # @param  [RDF::Literal::Temporal] operand
       #   the operand
       # @return [RDF::Literal]
       # @raise  [TypeError] if the operand is not a simple literal
       def apply(operand, **options)
-        raise TypeError, "expected an RDF::Literal::DateTime, but got #{operand.inspect}" unless operand.is_a?(RDF::Literal::DateTime)
+        raise TypeError, "expected an RDF::Literal::Temporal, but got #{operand.inspect}" unless operand.is_a?(RDF::Literal::Temporal)
         operand.tz
       end
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "TZ(" + operands.to_sparql(**options) + ")"
+      end
     end # TZ
   end # Operator
 end; end # SPARQL::Algebra

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

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

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

@@ -3,12 +3,19 @@ module SPARQL; module Algebra
     ##
     # The SPARQL GraphPattern `union` operator.
     #
-    # @example
-    #   (prefix ((: <http://example/>))
-    #     (union
-    #       (bgp (triple ?s ?p ?o))
-    #       (graph ?g
-    #         (bgp (triple ?s ?p ?o)))))
+    # [67]  GroupOrUnionGraphPattern::= GroupGraphPattern ( 'UNION' GroupGraphPattern )*
+    #
+    # @example SPARQL Grammar
+    #   SELECT * {
+    #     { ?s ?p ?o }
+    #     UNION
+    #     { GRAPH ?g { ?s ?p ?o } }}
+    #
+    # @example SSE
+    #   (union
+    #    (bgp (triple ?s ?p ?o))
+    #    (graph ?g
+    #     (bgp (triple ?s ?p ?o))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#sparqlAlgebra
     class Union < Operator::Binary
@@ -66,6 +73,22 @@ module SPARQL; module Algebra
         @operands = ops
         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)
+        str = "{\n"
+        str << operands[0].to_sparql(top_level: false, **options)
+        str << "\n} UNION {\n"
+        str << operands[1].to_sparql(top_level: false, **options)
+        str << "\n}"
+        top_level ? Operator.to_sparql(str, **options) : str
+      end
     end # Union
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -3,11 +3,44 @@ module SPARQL; module Algebra
     ##
     # The SPARQL GraphPattern `prefix` operator.
     #
-    # @example
-    #   (update
+    # [29]  Update                  ::= Prologue ( Update1 ( ';' Update )? )?
+    #
+    # @example SPARQL Grammar
+    #   PREFIX     : <http://example.org/> 
+    #   PREFIX foaf: <http://xmlns.com/foaf/0.1/> 
+    #   DELETE  { ?a foaf:knows ?b }
+    #   INSERT { ?b foaf:knows ?a }
+    #   WHERE { ?a foaf:knows ?b }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example.org/>)
+    #            (foaf: <http://xmlns.com/foaf/0.1/>))
+    #    (update
+    #     (modify
+    #      (bgp (triple ?a foaf:knows ?b))
+    #      (delete ((triple ?a foaf:knows ?b)))
+    #      (insert ((triple ?b foaf:knows ?a)))) ))
+    #
+    # @example SPARQL Grammar (update multiple)
+    #   PREFIX     : <http://example.org/> 
+    #   PREFIX foaf: <http://xmlns.com/foaf/0.1/> 
+    #   
+    #   DELETE { ?a foaf:knows ?b . }
+    #   WHERE { ?a foaf:knows ?b . }
+    #   ;
+    #   INSERT { ?b foaf:knows ?a . }
+    #   WHERE { ?a foaf:knows ?b .}
+    #
+    # @example SSE (update multiple)
+    #   (prefix ((: <http://example.org/>)
+    #            (foaf: <http://xmlns.com/foaf/0.1/>))
+    #    (update
+    #     (modify
+    #      (bgp (triple ?a foaf:knows ?b))
+    #      (delete ((triple ?a foaf:knows ?b))))
     #     (modify
-    #       (bgp (triple ?s ?p ?o))
-    #       (insert ((triple ?s ?p "q")))))
+    #      (bgp (triple ?a foaf:knows ?b))
+    #      (insert ((triple ?b foaf:knows ?a))))))
     #
     # @see https://www.w3.org/TR/sparql11-update/#graphUpdate
     class Update < Operator
@@ -39,6 +72,15 @@ module SPARQL; module Algebra
         end
         queryable
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        str = operands.map { |e| e.to_sparql(**options) }.join(";\n")
+      end
     end # Update
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,8 +6,42 @@ module SPARQL; module Algebra
     #
     # The USING and USING NAMED clauses affect the RDF Dataset used while evaluating the WHERE clause. This describes a dataset in the same way as FROM and FROM NAMED clauses describe RDF Datasets in the SPARQL 1.1 Query Language
     #
-    # @example
-    #   (using (:g1) (bgp (triple ?s ?p ?o)))
+    # [44]  UsingClause             ::= 'USING' ( iri | 'NAMED' iri )
+    #
+    # @example SPARQL Grammar
+    #   PREFIX     : <http://example.org/> 
+    #   PREFIX foaf: <http://xmlns.com/foaf/0.1/> 
+    #   
+    #   DELETE { ?s ?p ?o }
+    #   USING <http://example.org/g2>
+    #   WHERE {
+    #     :a foaf:knows ?s .
+    #     ?s ?p ?o 
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>) (foaf: <http://xmlns.com/foaf/0.1/>))
+    #    (update
+    #     (modify
+    #      (using (:g2)
+    #       (bgp (triple :a foaf:knows ?s) (triple ?s ?p ?o)))
+    #      (delete ((triple ?s ?p ?o)))) ))
+    #
+    # @example SPARQL Grammar (multiple clauses)
+    #   PREFIX     : <http://example.org/> 
+    #   
+    #   INSERT { ?s ?p "q" }
+    #   USING :g1
+    #   USING :g2
+    #   WHERE { ?s ?p ?o }
+    #
+    # @example SSE (multiple clauses)
+    #   (prefix ((: <http://example.org/>))
+    #    (update
+    #     (modify
+    #      (using (:g1 :g2) (bgp (triple ?s ?p ?o)))
+    #      (insert ((triple ?s ?p "q"))))))
     #
     # @see https://www.w3.org/TR/sparql11-update/#add
     class Using < Operator
@@ -35,6 +69,19 @@ module SPARQL; module Algebra
         debug(options) {"Using"}
         Dataset.new(*operands).execute(queryable, depth: options[:depth].to_i + 1, **options, &block)
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        str = "\n" + operands.first.map do |op|
+          "USING #{op.to_sparql(**options)}\n"
+        end.join("")
+        content = operands.last.to_sparql(top_level: false, **options)
+        str << Operator.to_sparql(content, project: nil, **options)
+      end
     end # Using
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -5,14 +5,24 @@ module SPARQL; module Algebra
     ##
     # The SPARQL `uuid` function.
     #
-    # @example
-    #     (prefix ((: <http://example.org/>)
-    #              (xsd: <http://www.w3.org/2001/XMLSchema#>))
-    #       (project (?length)
-    #         (extend ((?length (strlen (str ?uuid))))
-    #           (filter (&& (isIRI ?uuid) (regex (str ?uuid) "^urn:uuid:[0-9A-F]{8}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{4}-[0-9A-F]{12}$" "i"))
-    #             (extend ((?uuid (uuid)))
-    #               (bgp))))))
+    # [121] BuiltInCall ::= ... | 'UUID' NIL 
+    #
+    # @example SPARQL Grammar
+    #   PREFIX : <http://example.org/>
+    #   PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
+    #   ASK {
+    #     BIND(UUID() AS ?u1)
+    #     BIND(UUID() AS ?u2)
+    #     FILTER(?u1 != ?u2)
+    #   }
+    #
+    # @example SSE
+    #   (prefix
+    #    ((: <http://example.org/>) (xsd: <http://www.w3.org/2001/XMLSchema#>))
+    #    (ask
+    #     (filter (!= ?u1 ?u2)
+    #      (extend ((?u1 (uuid)) (?u2 (uuid)))
+    #       (bgp)))))
     #
     # @see https://www.w3.org/TR/sparql11-query/#func-uuid
     class UUID < Operator::Nullary
@@ -27,6 +37,15 @@ module SPARQL; module Algebra
       def apply(**options)
         RDF::URI("urn:uuid:#{SecureRandom.uuid}")
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        "UUID(" + operands.to_sparql(delimiter: ', ', **options) + ")"
+      end
     end # UUID
   end # Operator
 end; end # SPARQL::Algebra

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

@@ -6,10 +6,21 @@ module SPARQL; module Algebra
     #
     # The WITH clause provides a convenience for when an operation primarily refers to a single graph.
     #
-    # @example
-    #   (with :g1
-    #     (bgp (triple ?s ?p ?o))
-    #     (insert ((triple ?s ?p "z"))))
+    # [41]  Modify ::= ( 'WITH' iri )? ( DeleteClause InsertClause? | InsertClause ) UsingClause* 'WHERE' GroupGraphPattern
+    #
+    # @example SPARQL Grammar
+    #   PREFIX  :     <http://example/>
+    #   WITH :g
+    #   DELETE { <base:s> ?p ?o . }
+    #   WHERE { ?s ?p ?o }
+    #
+    # @example SSE
+    #   (prefix ((: <http://example/>))
+    #    (update
+    #     (modify
+    #      (with :g
+    #       (bgp (triple ?s ?p ?o))
+    #       (delete ((triple <base:s> ?p ?o)))))))
     #
     # @see https://www.w3.org/TR/sparql11-update/#deleteInsert
     class With < Operator
@@ -67,6 +78,29 @@ module SPARQL; module Algebra
           end
         end
       end
+
+      ##
+      #
+      # Returns a partial SPARQL grammar for this operator.
+      #
+      # @return [String]
+      def to_sparql(**options)
+        with, where, *ops = operands
+        str = "WITH #{with.to_sparql(**options)}\n"
+
+        # The content of the WHERE clause, may be USING
+        content = where.to_sparql(top_level: false, **options)
+
+        # DELETE | INSERT | DELETE INSERT
+        str << ops.to_sparql(top_level: false, delimiter: "\n", **options) + "\n"
+
+        # Append the WHERE or USING clause
+        str << if where.is_a?(Using)
+          content
+        else
+          Operator.to_sparql(content, project: nil, **options)
+        end
+      end
     end # With
   end # Operator
 end; end # SPARQL::Algebra

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

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