sparql 3.1.8 → 3.2.3

data/lib/sparql/algebra/operator.rb

@@ -49,17 +49,20 @@ 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 :Triple,             'sparql/algebra/operator/triple'
     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 :Adjust,             'sparql/algebra/operator/adjust'
     autoload :And,                'sparql/algebra/operator/and'
     autoload :Compare,            'sparql/algebra/operator/compare'
     autoload :Concat,             'sparql/algebra/operator/concat'
@@ -94,7 +97,9 @@ module SPARQL; module Algebra
     autoload :NotOneOf,           'sparql/algebra/operator/notoneof'
     autoload :PathOpt,            'sparql/algebra/operator/path_opt'
     autoload :PathPlus,           'sparql/algebra/operator/path_plus'
+    autoload :PathRange,          'sparql/algebra/operator/path_range'
     autoload :PathStar,           'sparql/algebra/operator/path_star'
+    autoload :PathZero,            'sparql/algebra/operator/path_zero'
     autoload :Path,               'sparql/algebra/operator/path'
     autoload :Reverse,            'sparql/algebra/operator/reverse'
     autoload :Seq,                'sparql/algebra/operator/seq'
@@ -105,6 +110,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 +177,7 @@ module SPARQL; module Algebra
         when :>               then GreaterThan
         when :>=              then GreaterThanOrEqual
         when :abs             then Abs
-        when :add             then Add
+        when :adjust          then Adjust
         when :alt             then Alt
         when :and, :'&&'      then And
         when :avg             then Avg
@@ -204,7 +210,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
@@ -215,9 +220,11 @@ module SPARQL; module Algebra
         when :now             then Now
         when :or, :'||'       then Or
         when :path            then Path
+        when :path0           then PathZero
         when :path?           then PathOpt
-        when :"path*"         then PathStar
         when :"path+"         then PathPlus
+        when :"path*"         then PathStar
+        when :pathrange       then PathRange
         when :plus            then Plus
         when :rand            then Rand
         when :regex           then Regex
@@ -231,6 +238,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 +262,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 +287,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
@@ -302,6 +310,8 @@ module SPARQL; module Algebra
         # RDF-star
         when :istriple        then IsTriple
         when :triple          then Triple
+        when :qtriple         then RDF::Query::Pattern
+        when :quad            then RDF::Query::Pattern
         when :subject         then Subject
         when :predicate       then Predicate
         when :object          then Object
@@ -333,6 +343,119 @@ 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{String => 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.to_s)
+            v = expr.to_sparql(**options)
+            pp = RDF::Query::Variable.new(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(**options)
+        pp = RDF::Query::Variable.new(as).to_sparql(**options)
+        content << "\nBIND (" << v << " AS " << pp << ") ."
+      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 +681,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 +700,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
-      to_sxp_bin.to_sxp
+    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_sparql(**options)
+      raise NotImplementedError, "#{self.class}#to_sparql(#{operands.map(&:class).join(', ')})"
     end
 
     ##
@@ -672,6 +801,15 @@ module SPARQL; module Algebra
       operands.each {|op| op.validate! if op.respond_to?(:validate!)}
       self
     end
+
+    ##
+    # The variables used in this query.
+    #
+    # @return [Hash{Symbol => RDF::Query::Variable}]
+    def variables
+      operands.inject({}) {|hash, o| o.respond_to?(:variables) ? hash.merge(o.variables) : hash}
+    end
+
   protected
 
     ##

data/lib/sparql/algebra/query.rb

@@ -16,13 +16,13 @@ module SPARQL; module Algebra
       @operands.unshift(query)
       self
     end
-    
+
     ##
     # The variables used in this query.
     #
     # @return [Hash{Symbol => RDF::Query::Variable}]
     def variables
-      operands.inject({}) {|hash, o| o.executable? ? hash.merge(o.variables) : hash}
+      operands.inject({}) {|hash, o| o.respond_to?(:variables) ? hash.merge(o.variables) : hash}
     end
 
     ##
@@ -38,7 +38,9 @@ module SPARQL; module Algebra
     #   the graph or repository to query
     # @param  [Hash{Symbol => Object}] options
     #   any additional keyword options
-    # @option options [Boolean] debug
+    # @option options  [RDF::Query::Solution] :bindings
+    #   a query solution containing zero or more variable bindings
+    # @option options [Boolean] :debug
     #   Query execution debugging
     # @option options [RDF::Term, RDF::Query::Variable] :graph_name
     # @yield  [solution]

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'
@@ -215,7 +233,7 @@ module SPARQL
   # scarcity.
   # 
   # [memoization]:      http://en.wikipedia.org/wiki/Memoization
-  # [RDF::Util::Cache]: http://www.rubydoc.info/github/ruby-rdf/rdf/RDF/Util/Cache
+  # [RDF::Util::Cache]: https://ruby-rdf.github.io/rdf/RDF/Util/Cache
   # 
   # ## Documentation
   # 
@@ -228,12 +246,15 @@ module SPARQL
   #   * {SPARQL::Algebra::Operator}
   #     * {SPARQL::Algebra::Operator::Abs}
   #     * {SPARQL::Algebra::Operator::Add}
+  #     * {SPARQL::Algebra::Operator::Adjust}
+  #     * {SPARQL::Algebra::Operator::Alt}
   #     * {SPARQL::Algebra::Operator::And}
   #     * {SPARQL::Algebra::Operator::Asc}
   #     * {SPARQL::Algebra::Operator::Ask}
   #     * {SPARQL::Algebra::Operator::Avg}
   #     * {SPARQL::Algebra::Operator::Base}
   #     * {SPARQL::Algebra::Operator::BGP}
+  #     * {SPARQL::Algebra::Operator::Bnode}
   #     * {SPARQL::Algebra::Operator::Bound}
   #     * {SPARQL::Algebra::Operator::Ceil}
   #     * {SPARQL::Algebra::Operator::Clear}
@@ -248,9 +269,9 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::Dataset}
   #     * {SPARQL::Algebra::Operator::Datatype}
   #     * {SPARQL::Algebra::Operator::Day}
-  #     * {SPARQL::Algebra::Operator::Delete}
   #     * {SPARQL::Algebra::Operator::DeleteData}
   #     * {SPARQL::Algebra::Operator::DeleteWhere}
+  #     * {SPARQL::Algebra::Operator::Delete}
   #     * {SPARQL::Algebra::Operator::Desc}
   #     * {SPARQL::Algebra::Operator::Describe}
   #     * {SPARQL::Algebra::Operator::Distinct}
@@ -258,10 +279,12 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::Drop}
   #     * {SPARQL::Algebra::Operator::EncodeForURI}
   #     * {SPARQL::Algebra::Operator::Equal}
+  #     * {SPARQL::Algebra::Operator::Exists}
   #     * {SPARQL::Algebra::Operator::Exprlist}
   #     * {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}
@@ -277,9 +300,11 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::IsIRI}
   #     * {SPARQL::Algebra::Operator::IsLiteral}
   #     * {SPARQL::Algebra::Operator::IsNumeric}
+  #     * {SPARQL::Algebra::Operator::IsTriple}
   #     * {SPARQL::Algebra::Operator::Join}
   #     * {SPARQL::Algebra::Operator::Lang}
   #     * {SPARQL::Algebra::Operator::LangMatches}
+  #     * {SPARQL::Algebra::Operator::LCase}
   #     * {SPARQL::Algebra::Operator::LeftJoin}
   #     * {SPARQL::Algebra::Operator::LessThan}
   #     * {SPARQL::Algebra::Operator::LessThanOrEqual}
@@ -297,20 +322,32 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::NotEqual}
   #     * {SPARQL::Algebra::Operator::NotExists}
   #     * {SPARQL::Algebra::Operator::NotIn}
+  #     * {SPARQL::Algebra::Operator::NotOneOf}
   #     * {SPARQL::Algebra::Operator::Now}
+  #     * {SPARQL::Algebra::Operator::Object}
   #     * {SPARQL::Algebra::Operator::Or}
   #     * {SPARQL::Algebra::Operator::Order}
+  #     * {SPARQL::Algebra::Operator::Path}
+  #     * {SPARQL::Algebra::Operator::PathOpt}
+  #     * {SPARQL::Algebra::Operator::PathPlus}
+  #     * {SPARQL::Algebra::Operator::PathRange}
+  #     * {SPARQL::Algebra::Operator::PathStar}
+  #     * {SPARQL::Algebra::Operator::PathZero}
   #     * {SPARQL::Algebra::Operator::Plus}
+  #     * {SPARQL::Algebra::Operator::Predicate}
   #     * {SPARQL::Algebra::Operator::Prefix}
   #     * {SPARQL::Algebra::Operator::Project}
   #     * {SPARQL::Algebra::Operator::Rand}
   #     * {SPARQL::Algebra::Operator::Reduced}
   #     * {SPARQL::Algebra::Operator::Regex}
   #     * {SPARQL::Algebra::Operator::Replace}
+  #     * {SPARQL::Algebra::Operator::Reverse}
   #     * {SPARQL::Algebra::Operator::Round}
   #     * {SPARQL::Algebra::Operator::SameTerm}
   #     * {SPARQL::Algebra::Operator::Sample}
   #     * {SPARQL::Algebra::Operator::Seconds}
+  #     * {SPARQL::Algebra::Operator::Seq}
+  #     * {SPARQL::Algebra::Operator::Sequence}
   #     * {SPARQL::Algebra::Operator::SHA1}
   #     * {SPARQL::Algebra::Operator::SHA256}
   #     * {SPARQL::Algebra::Operator::SHA384}
@@ -330,6 +367,7 @@ module SPARQL
   #     * {SPARQL::Algebra::Operator::Sum}
   #     * {SPARQL::Algebra::Operator::Table}
   #     * {SPARQL::Algebra::Operator::Timezone}
+  #     * {SPARQL::Algebra::Operator::Triple}
   #     * {SPARQL::Algebra::Operator::TZ}
   #     * {SPARQL::Algebra::Operator::Ucase}
   #     * {SPARQL::Algebra::Operator::Union}
@@ -339,11 +377,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
 
@@ -419,7 +455,7 @@ module SPARQL
     #
     # @param  [Symbol, #to_sym] name
     # @return [Variable]
-    # @see    http://www.rubydoc.info/github/ruby-rdf/rdf/RDF/Query/Variable
+    # @see    https://ruby-rdf.github.io/rdf/RDF/Query/Variable
     def Variable(name)
       Variable.new(name)
     end