sparql 3.1.6 → 3.2.1

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
@@ -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,6 +49,7 @@ 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'
@@ -105,6 +106,7 @@ module SPARQL; module Algebra
     autoload :Coalesce,           'sparql/algebra/operator/coalesce'
     autoload :Desc,               'sparql/algebra/operator/desc'
     autoload :Exprlist,           'sparql/algebra/operator/exprlist'
+    autoload :FunctionCall,       'sparql/algebra/operator/function_call'
     autoload :GroupConcat,        'sparql/algebra/operator/group_concat'
     autoload :In,                 'sparql/algebra/operator/in'
     autoload :NotIn,              'sparql/algebra/operator/notin'
@@ -171,7 +173,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
@@ -204,7 +205,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
@@ -231,6 +231,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
@@ -254,6 +255,7 @@ module SPARQL; module Algebra
         when :asc             then Asc
         when :desc            then Desc
         when :exprlist        then Exprlist
+        when :function_call   then FunctionCall
 
         # Datasets
         when :dataset         then Dataset
@@ -278,7 +280,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
@@ -301,7 +302,7 @@ module SPARQL; module Algebra
 
         # RDF-star
         when :istriple        then IsTriple
-        when :triple          then Triple
+        when :triple          then RDF::Query::Pattern
         when :subject         then Subject
         when :predicate       then Predicate
         when :object          then Object
@@ -314,8 +315,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
 
     ##
@@ -333,6 +334,120 @@ module SPARQL; module Algebra
       self.const_get(:ARITY)
     end
 
+    ##
+    # Generate a top-level Grammar, using collected options
+    #
+    # @param [String] content
+    # @param [Operator] datasets ([])
+    # @param [Operator] distinct (false)
+    # @param [Hash{Symbol => Operator}] extensions
+    #   Variable bindings
+    # @param [Array<Operator>] filter_ops ([])
+    #   Filter Operations
+    # @param [Integer] limit (nil)
+    # @param [Array<Operator>] group_ops ([])
+    # @param [Array<Operator>] having_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 [Operator] values_clause (nil)
+    #   Top-level Values clause
+    # @param [Operator] where_clause (true)
+    #   Emit 'WHERE' before GroupGraphPattern
+    # @param [Hash{Symbol => Object}] options
+    # @return [String]
+    def self.to_sparql(content,
+                       datasets: [],
+                       distinct: false,
+                       extensions: {},
+                       filter_ops: [],
+                       group_ops: [],
+                       having_ops: [],
+                       limit: nil,
+                       offset: nil,
+                       order_ops: [],
+                       project: %i(*),
+                       reduced: false,
+                       values_clause: nil,
+                       where_clause: true,
+                       **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)
+            v = expr.to_sparql(as_statement: true, **options)
+            v = "<< #{v} >>" if expr.is_a?(RDF::Statement)
+            pp = p.to_sparql(**options)
+            # Replace projected variables with their extension, if any
+            '(' + v + ' AS ' + pp + ')'
+          else
+            p.to_sparql(**options)
+          end
+        end.join(" ") + "\n"
+      end
+
+      # DatasetClause
+      datasets.each do |ds|
+        str << "FROM #{ds.to_sparql(**options)}\n"
+      end
+
+      # Bind
+      extensions.each do |as, expression|
+        v = expression.to_sparql(as_statement: true, **options)
+        v = "<< #{v} >>" if expression.is_a?(RDF::Statement)
+        content << "\nBIND (" << v << " AS " << as.to_sparql(**options) << ") ."
+      end
+
+      # Filter
+      filter_ops.each do |f|
+        content << "\nFILTER (#{f.to_sparql(**options)}) ."
+      end
+
+      # WhereClause / GroupGraphPattern
+      str << (where_clause ? "WHERE {\n#{content}\n}\n" : "{\n#{content}\n}\n")
+
+      ##
+      # SolutionModifier
+      #
+      # GroupClause
+      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
+
+      # HavingClause
+      unless having_ops.empty?
+        str << "HAVING #{having_ops.to_sparql(**options)}"
+      end
+
+      # OrderClause
+      unless order_ops.empty?
+        str << "ORDER BY #{order_ops.to_sparql(**options)}\n"
+      end
+
+      # LimitOffsetClauses
+      str << "OFFSET #{offset}\n" unless offset.nil?
+      str << "LIMIT #{limit}\n" unless limit.nil?
+
+      # Values Clause
+      str << values_clause.to_sparql(top_level: false, **options) if values_clause
+      str
+    end
+
     ARITY = -1 # variable arity
 
     ##
@@ -558,12 +673,8 @@ module SPARQL; module Algebra
     # @return [SPARQL::Algebra::Expression] `self`
     def rewrite(&block)
       @operands = @operands.map do |op|
-        # Rewrite the operand
-        unless new_op = block.call(op)
-          # Not re-written, rewrite
-          new_op = op.respond_to?(:rewrite) ? op.rewrite(&block) : op
-        end
-        new_op
+        new_op = block.call(op)
+        new_op.respond_to?(:rewrite) ? new_op.rewrite(&block) : new_op
       end
       self
     end
@@ -581,9 +692,19 @@ 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

data/lib/sparql/algebra.rb

@@ -19,6 +19,24 @@ module SPARQL
   #
   # {RDF::Query} and {RDF::Query::Pattern} are used as primitives for `bgp` and `triple` expressions.
   #
+  # # Background
+  #
+  # The SPARQL Algebra, and the S-Expressions used to represent it, are based on those of [Jena](https://jena.apache.org/documentation/notes/sse.html). Generally, an S-Expression generated by this Gem can be used as an SSE input to Jena, or an SSE output from Jena can also be used as input to this Gem.
+  #
+  # S-Expressions generally follow a standardized nesting resulting from parsing the original SPARQL Grammar. The individual operators map to SPARQL Grammar productions, and in most cases, the SPARQL Grammar can be reproduced by turning the S-Expression back into SPARQL (see {SPARQL::Algebra::Operator#to_sparql}). The order of operations will typically be as follows:
+  #
+  #  * {SPARQL::Algebra::Operator::Base}
+  #  * {SPARQL::Algebra::Operator::Prefix}
+  #  * {SPARQL::Algebra::Operator::Slice}
+  #  * {SPARQL::Algebra::Operator::Distinct}
+  #  * {SPARQL::Algebra::Operator::Reduced}
+  #  * {SPARQL::Algebra::Operator::Project}
+  #  * {SPARQL::Algebra::Operator::Order}
+  #  * {SPARQL::Algebra::Operator::Filter}
+  #  * {SPARQL::Algebra::Operator::Extend}
+  #  * {SPARQL::Algebra::Operator::Group}
+  #  * {SPARQL::Algebra::Query} (many classes implement Query)
+  #
   # # Queries
   # 
   #     require 'sparql/algebra'
@@ -262,6 +280,7 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::Extend}
   #     * {SPARQL::Algebra::Operator::Filter}
   #     * {SPARQL::Algebra::Operator::Floor}
+  #     * {SPARQL::Algebra::Operator::FunctionCall}
   #     * {SPARQL::Algebra::Operator::Graph}
   #     * {SPARQL::Algebra::Operator::GreaterThan}
   #     * {SPARQL::Algebra::Operator::GreaterThanOrEqual}
@@ -339,11 +358,9 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::With}
   #     * {SPARQL::Algebra::Operator::Year}
   # 
-  # TODO
-  # ====
-  # * Operator#optimize needs to be completed and tested.
   # 
   # @see http://www.w3.org/TR/sparql11-query/#sparqlAlgebra
+  # @see https://jena.apache.org/documentation/notes/sse.html
   module Algebra
     include RDF