sparql 3.1.5 → 3.2.0

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 (?str ?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
@@ -20,12 +32,21 @@ module SPARQL; module Algebra
       #   the operand
       # @return [RDF::Literal] literal of same type
       # @raise  [TypeError] if the operand is not a literal value
-      def apply(operand)
+      def apply(operand, **options)
         case operand
           when RDF::Literal then RDF::Literal(operand.to_s.upcase, datatype: operand.datatype, language: operand.language)
           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,23 @@ 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 ?s ?p ?o))
-    #       (insert ((triple ?s ?p "q")))))
+    #      (bgp (triple ?a foaf:knows ?b))
+    #      (delete ((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 +51,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,27 @@ 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)))) ))
     #
     # @see https://www.w3.org/TR/sparql11-update/#add
     class Using < Operator
@@ -35,6 +54,17 @@ 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 = "USING #{operands.first.to_sparql(**options)}\n"
+        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
@@ -24,9 +34,18 @@ module SPARQL; module Algebra
       # Return a fresh IRI from the UUID URN scheme. Each call of UUID() returns a different UUID. It must not be the "nil" UUID (all zeroes). The variant and version of the UUID is implementation dependent.
       #
       # @return [RDF::URI]
-      def apply
+      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
@@ -24,10 +33,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.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

data/lib/sparql/algebra/operator.rb

@@ -49,11 +49,16 @@ module SPARQL; module Algebra
     autoload :Sum,                'sparql/algebra/operator/sum'
     autoload :SHA1,               'sparql/algebra/operator/sha1'
     autoload :SHA256,             'sparql/algebra/operator/sha256'
+    autoload :SHA384,             'sparql/algebra/operator/sha384'
     autoload :SHA512,             'sparql/algebra/operator/sha512'
     autoload :Str,                'sparql/algebra/operator/str'
     autoload :Timezone,           'sparql/algebra/operator/timezone'
     autoload :TZ,                 'sparql/algebra/operator/tz'
     autoload :Year,               'sparql/algebra/operator/year'
+    autoload :IsTriple,           'sparql/algebra/operator/is_triple'
+    autoload :Subject,            'sparql/algebra/operator/subject'
+    autoload :Predicate,          'sparql/algebra/operator/predicate'
+    autoload :Object,             'sparql/algebra/operator/object'
 
     # Binary operators
     autoload :And,                'sparql/algebra/operator/and'
@@ -167,7 +172,6 @@ module SPARQL; module Algebra
         when :>               then GreaterThan
         when :>=              then GreaterThanOrEqual
         when :abs             then Abs
-        when :add             then Add
         when :alt             then Alt
         when :and, :'&&'      then And
         when :avg             then Avg
@@ -200,7 +204,6 @@ module SPARQL; module Algebra
         when :md5             then MD5
         when :max             then Max
         when :min             then Min
-        when :minus           then Minus
         when :minutes         then Minutes
         when :month           then Month
         when :multiply        then Multiply
@@ -227,6 +230,7 @@ module SPARQL; module Algebra
         when :sequence        then Sequence
         when :sha1            then SHA1
         when :sha256          then SHA256
+        when :sha384          then SHA384
         when :sha512          then SHA512
         when :str             then Str
         when :strafter        then StrAfter
@@ -274,7 +278,6 @@ module SPARQL; module Algebra
         when :reduced         then Reduced
         when :slice           then Slice
         when :table           then Table
-        when :triple          then RDF::Query::Pattern
         when :union           then Union
 
         # Update forms
@@ -294,6 +297,14 @@ module SPARQL; module Algebra
         when :update          then Update
         when :using           then Using
         when :with            then With
+
+        # RDF-star
+        when :istriple        then IsTriple
+        when :triple          then RDF::Query::Pattern
+        when :subject         then Subject
+        when :predicate       then Predicate
+        when :object          then Object
+
         else                       nil # not found
       end
     end
@@ -302,8 +313,8 @@ module SPARQL; module Algebra
     # @param  [Array<RDF::Term>] operands
     # @return [RDF::Term]
     # @see    Operator#evaluate
-    def self.evaluate(*operands)
-      self.new(*operands).evaluate(RDF::Query::Solution.new)
+    def self.evaluate(*operands, **options)
+      self.new(*operands, **options).evaluate(RDF::Query::Solution.new, **options)
     end
 
     ##
@@ -321,6 +332,89 @@ module SPARQL; module Algebra
       self.const_get(:ARITY)
     end
 
+    ##
+    # Generate a top-level Grammar, using collected options
+    #
+    # @param [String] content
+    # @param [Hash{Symbol => Operator}] extensions
+    #   Variable bindings
+    # @param [Operator] distinct (false)
+    # @param [Array<Operator>] filter_ops ([])
+    #   Filter Operations
+    # @param [Integer] limit (nil)
+    # @param [Array<Operator>] group_ops ([])
+    # @param [Integer] offset (nil)
+    # @param [Array<Operator>] order_ops ([])
+    #   Order Operations
+    # @param [Array<Symbol,Operator>] project (%i(*))
+    #   Terms to project
+    # @param [Operator] reduced (false)
+    # @param [Hash{Symbol => Object}] options
+    # @return [String]
+    def self.to_sparql(content,
+                       distinct: false,
+                       extensions: {},
+                       filter_ops: [],
+                       group_ops: [],
+                       limit: nil,
+                       offset: nil,
+                       order_ops: [],
+                       project: %i(*),
+                       reduced: false,
+                       **options)
+      str = ""
+
+      # Projections
+      if project
+        str << "SELECT "
+        str << "DISTINCT " if distinct
+        str << "REDUCED " if reduced
+
+        str << project.map do |p|
+          if expr = extensions.delete(p)
+            # Replace projected variables with their extension, if any
+            "(" + [expr, :AS, p].to_sparql(**options) + ")"
+          else
+            p.to_sparql(**options)
+          end
+        end.join(" ") + "\n"
+      end
+
+      # Extensions
+      extensions.each do |as, expression|
+        content << "\nBIND (#{expression.to_sparql(**options)} AS #{as.to_sparql(**options)}) ."
+      end
+
+      # Filters
+      filter_ops.each do |f|
+        content << "\nFILTER #{f.to_sparql(**options)} ."
+      end
+
+      # Where clause
+      str << "WHERE {\n#{content}\n}\n"
+
+      # Group
+      unless group_ops.empty?
+        ops = group_ops.map do |o|
+          # Replace projected variables with their extension, if any
+          o.is_a?(Array) ? 
+            "(" + [o.last, :AS, o.first].to_sparql(**options) + ")" :
+            o.to_sparql(**options)
+        end
+        str << "GROUP BY #{ops.join(' ')}\n"
+      end
+
+      # Order
+      unless order_ops.empty?
+        str << "ORDER BY #{order_ops.to_sparql(**options)}\n"
+      end
+
+      # Offset and Limmit
+      str << "OFFSET #{offset}\n" unless offset.nil?
+      str << "LIMIT #{limit}\n" unless limit.nil?
+      str
+    end
+
     ARITY = -1 # variable arity
 
     ##
@@ -569,9 +663,20 @@ module SPARQL; module Algebra
     ##
     # Returns an S-Expression (SXP) representation of this operator
     #
+    # @param [Hash{Symbol => RDF::URI}] prefixes (nil)
+    # @param [RDF::URI] base_uri (nil)
+    # @return [String]
+    def to_sxp(prefixes: nil, base_uri: nil)
+      to_sxp_bin.to_sxp(prefixes: prefixes, base_uri: base_uri)
+    end
+
+    ##
+    #
+    # Returns a partial SPARQL grammar for the operator.
+    #
     # @return [String]
-    def to_sxp
-      to_sxp_bin.to_sxp
+    def to_sparql(**options)
+      raise NotImplementedError, "#{self.class}#to_sparql(#{operands.map(&:class).join(', ')})"
     end
 
     ##

data/lib/sparql/algebra/sxp_extensions.rb

@@ -5,7 +5,7 @@ class NilClass
   # Returns the SXP representation of this object.
   #
   # @return [String]
-  def to_sxp
+  def to_sxp(**options)
     RDF.nil.to_s
   end
 end
@@ -17,7 +17,7 @@ class FalseClass
   # Returns the SXP representation of this object.
   #
   # @return [String]
-  def to_sxp
+  def to_sxp(**options)
     'false'
   end
 end
@@ -29,7 +29,7 @@ class TrueClass
   # Returns the SXP representation of this object.
   #
   # @return [String]
-  def to_sxp
+  def to_sxp(**options)
     'true'
   end
 end